Модуль для работы с RFID-метками HID Prox (125 кГц)

Модуль hid считывает RFID-метки HID Prox на частоте 125 кГц. Одновременно можно использовать до трёх считывателей.

Одновременная работа hid и emmarine доступна на устройствах, прошивка которых поддерживает оба модуля. Набор модулей и назначение выводов зависят от модели устройства.

Все методы можно вызывать и в объектном синтаксисе: reader:read(...), reader:raw(...), reader:close().

Поддерживаются форматы:

Где: P — бит паритета, FC — Facility Code, CN — Card Number.

hid.new([rxpin, txpin, pwm_channel, max_items])

Создаёт объект HID-считывателя.

Аргументы:

• rxpin (необязательно): вывод GPIO для приёма данных, 0..39;
• txpin (необязательно): вывод GPIO для антенны, 0..33; выводы 34–39 работают только как входы;
• pwm_channel (необязательно): канал PWM, 0..15;
• max_items (необязательно): размер буфера захвата, не менее 120.

Если параметры не указаны, используются значения, заданные для модели устройства.

Возвращает объект считывателя или ошибку. При попытке создать четвёртый объект возвращается ошибка Max readers (3) reached.

Методы модуля принимают только объект, созданный функцией hid.new().

-- Параметры по умолчанию для данной платы
local reader = hid.new()

hid.read(reader, [timeout_ms], [result_type], [format_37], [callback, …])

hid.read(reader, callback, …)

hid.read(reader, [timeout_ms], callback, …)

Считать HID-карту: включает поле, захватывает сигнал, выполняет демодуляцию/декодирование и парсит формат карты.

Для защиты от ложных срабатываний используется голосование: карта возвращается только после того, как одни и те же данные были успешно декодированы в двух подряд вызовах read(). На практике это означает, что при опросе в цикле первый успешный вызов вернёт nil, а второй — карту. Неудачное чтение (карта убрана, помеха) сбрасывает счётчик голосования.

Аргументы:

• reader: объект считывателя.
• timeout_ms (необязательно): таймаут в миллисекундах. Значение по умолчанию: 120. Минимум 100 (меньшие значения автоматически приводятся к 100).
• result_type (необязательно): формат результата:
  • 0 (по умолчанию): таблица,
  • 1: строка “fc.cn”,
  • 2: hex-строка “FFCCCCCC”. Внимание: FC усекается до 8 бит, CN — до 24 бит; для широких значений используйте result_type 1 или поле cn таблицы.
• format_37 (необязательно): интерпретация неоднозначного 37-битного кадра — “H10302”, “H10304” или “auto”. Без явной подсказки используется H10304. Для считывателя с картами H10302 передавайте “H10302”; строку можно указать вместо timeout_ms или после result_type.
• callback (необязательно): функция, вызываемая только после успешного чтения HID-карты. Все следующие аргументы передаются в неё перед результатом чтения. Если обработчик передан вторым аргументом вместо timeout_ms, тайм-аут и формат результата остаются значениями по умолчанию.

Возвращает:

• при result_type = 0: таблицу
• при result_type = 1: строку “fc.cn”
• при result_type = 2: hex-строку
• nil: если карта не обнаружена, декодирование не удалось или голосование ещё не подтвердило результат (первое успешное чтение)

Если карта не найдена или не распознана, обработчик не вызывается и read() не возвращает значений. После вызова обработчика функция возвращает true и его результаты либо false, err, если обработчик завершился ошибкой. Ошибки оборудования, аргументов и состояния считывателя по-прежнему вызывают исключение.

Поля таблицы (result_type = 0):

• format: “H10301”, “H10302”, “H10304”, “H10306”, “Corp1000-35”, “Generic”
• bits: число бит формата (26, 34, 35, 37, …)
• fc: Facility Code
• cn: точный Card Number. Пока значение помещается в lua_Integer, это число; более широкое значение (например, H10302 в стандартном 32-битном Lua-профиле) возвращается десятичной строкой.

local reader = hid.new()

-- Опрос в цикле: из-за голосования карта возвращается
-- со второго подряд успешного чтения
while true do
    local card = hid.read(reader, 100, 0)
    if card then
        print("Format:", card.format)
        print("Bits:", card.bits)
        print("FC:", card.fc)
        print("CN:", card.cn)
        break
    end
    tmr.delayms(200)
end

-- H10302 содержит 35-битный CN; format_37 обязателен для этой интерпретации.
-- Большой CN в таблице будет точной десятичной строкой.
local card = hid.read(reader, 120, 0, "H10302")

-- result_type = 1 -> "fc.cn"
local code = hid.read(reader, 100, 1)
if code then
    print("Card code:", code)
end

-- result_type = 2 -> "FFCCCCCC"
local hex = hid.read(reader, 100, 2)
if hex then
    print("Card hex:", hex)
end

-- Callback с hex-строкой результата
local ok, err = hid.read(reader, 100, 2, function(code)
    print("HID:", code)
end)
if ok == false then
    print("Callback error:", err)
end

-- Callback с пользовательскими аргументами перед результатом
hid.read(reader, 100, 1, function(prefix, code)
    print(prefix, code)
end, "HID")

hid.raw(reader, [timeout_ms])

Получить сырые данные захвата для отладки.

Аргументы:

• reader: объект считывателя.
• timeout_ms (необязательно): таймаут в миллисекундах. Значение по умолчанию: 120. Минимум 100 (меньшие значения автоматически приводятся к 100).

Возвращает таблицу:

• count: общее количество захваченных переходов
• overflow: было ли переполнение буфера
• data: массив до 512 элементов (первые захваченные переходы), где каждый элемент содержит:
  • us: длительность в микросекундах
  • edge: уровень линии после перехода (0 = low, 1 = high)

local reader = hid.new(4, 15, 6, 4096)

local raw = hid.raw(reader, 100)
print("Captured:", raw.count)
print("Overflow:", raw.overflow)

for i = 1, math.min(10, #raw.data) do
    print(i, "us:", raw.data[i].us, "edge:", raw.data[i].edge)
end

hid.close(reader)

Закрывает считыватель и освобождает занятые им ресурсы.

Аргументы:

• reader: объект считывателя.

Возвращает: ничего. Повторный вызов close() безопасен.

Закрывайте считыватель явно, чтобы сразу освободить его ресурсы и доступный слот.

hid.close(reader)
-- или
reader:close()