ODNFC-LAN на Lua — руководство

ODNFC-LAN и ODNFC-LAN-C — NFC/RFID считыватели-контроллеры с сетевым интерфейсом и прошивкой Lua. Логику работы можно изменить во встроенном редакторе кода: считыватель может хранить локальную базу, управлять замком, записывать события и обмениваться данными с сервером.

Быстрый маршрут

Пример сценария: автономная дверь

1. Считыватель получает UID или данные выбранного блока карты.
2. Lua-программа ищет пользователя в локальной базе.
3. Для разрешённой карты включает зелёную индикацию и выход замка на заданное время; для неизвестной — красную индикацию и звуковой сигнал.
4. Событие сохраняется локально и отправляется на сервер по MQTT, REST или другому выбранному протоколу.
5. Если сеть временно недоступна, локальное правило продолжает работать.

Начинайте внедрение с чтения UID и ручного переключения выхода. Только после проверки электрической части добавляйте базу, сеть и сложные правила.

Ключевые возможности

• Поддерживаемые метки. Метки 13,56 МГц: MIFARE Classic 1K/4K/Mini, MIFARE Ultralight, Ultralight Nano, NTAG 213/215/216, S50/S70 — полная поддержка; MIFARE Ultralight C — только чтение UID. Во встроенной Lua-программе для меток 125 кГц доступны UID EM-Marine EM4100 и HID ProxCard II, распознавание T55xx-копий, а для подготовленных ATA5577 — Trace ID и ротация токена. Устройство может быть собрано с одним интерфейсом или сразу с двумя.
• Работа в локальной сети. Подключается по Ethernet (DHCP или статический адрес) либо Wi-Fi (точка доступа или клиент). Встроенный веб-интерфейс для настройки. Передаёт данные по сети или принимает команды.
• Совместимые бесконтактные карты. Считыватель может использовать идентификатор, который отдаёт физическая карта; это не обязательно её напечатанный номер или платёжный PAN. Мобильный кошелёк может выдавать отдельный и меняющийся идентификатор, а обычный пропуск в Apple Wallet или Google Wallet не становится совместимой NFC-картой автоматически. Ограничения разобраны в статье «Телефон как пропуск».
• Отчёты и логи. Собирает статистику «вход-выход» за период и отправляет на почту. Подробнее — на странице логов и отчётов.
• Telegram. Прямая интеграция с Telegram-ботом без сторонних сервисов: команды на перезагрузку, данные о работе, показания датчиков, статистика. Можно описать собственные реакции на команды.
• Изменяемая логика. Встроенный редактор, онлайн-среда и плагин для VS Code позволяют расширить функционал под вашу задачу.
• Дискретный вход и выход. Один вход можно использовать для кнопки, а выход — для управления замком или другой нагрузкой. Учитывайте предел 1 А, напряжение питания и защиту от выброса напряжения для индуктивной нагрузки.
• Управляемая индикация. Программное управление звуковым излучателем и RGB-светодиодами (ODNFC-LAN). Вместо встроенных диодов можно подключить адресную ленту и создавать световые эффекты. Устройство рассчитано на питание до 64 светодиодов: допустимые количество и яркость определяются током конкретной ленты. При необходимости ленту можно питать от отдельного стабилизированного источника 5 В. ODNFC-LAN-C управляет классической парой «красный-зелёный».
• Локальное хранение данных. Устройство хранит список пользователей локально и работает автономно либо синхронизируется с сервером.

Исполнения корпуса

ODNFC-LAN поставляется в корпусе Тип A, ODNFC-LAN-C — в корпусе Тип B.

Лицевая панель ODNFC-LAN покрыта тонкой защитной транспортировочной плёнкой (это не царапины). Удалите её перед использованием.

Веб-интерфейс

Если интерфейс выглядит иначе, сначала сравните модель и версию прошивки с этой инструкцией. Перед обновлением сохраните пользовательский код и настройки и убедитесь, что образ предназначен для вашего исполнения.

Веб-интерфейс устроен как рабочий стол. Слева расположены разделы «Информация», «Настройки», «Редактор», «Файлы» и «Система». В верхней строке показаны состояние подключения и время, там же находится кнопка перезагрузки. На рабочем столе справа видны время работы, IP-адрес, свободная память и место на диске.

Раздел открывается в компактном окне. Кнопка со стрелкой в правом верхнем углу разворачивает окно почти на весь экран; повторное нажатие возвращает компактный вид.

«Информация». Журнал устройства с сообщениями из пользовательской программы. Нажатие на строку копирует её в буфер обмена.

«Настройки». Параметры собраны в группы RFID, «Сеть» и «Общие». Здесь выбирают формат и ключ карты, способ сетевого подключения, адрес получателя, пароль веб-интерфейса, NTP, HTTPS, Websocket REPL, сторожевой таймер, Telnet и язык. Кнопка «Прочитать» заново получает значения из устройства, а «Записать» сохраняет изменения.

Часть параметров — «Формат», «Тип ключа», «Ключ» и «Получатель» — предназначена для пользовательской программы. Пароль и отключение веб-интерфейса ограничивают доступ к устройству в общей сети: перед сохранением убедитесь, что не закрываете доступ себе. При работе по HTTP пароль передаётся по сети без шифрования. HTTPS-сервер использует самоподписанный сертификат, поэтому браузер потребует ручного подтверждения. Websocket REPL нужен для удалённой разработки: его используют IDE lua.unitx.pro и плагин VS Code.

После перезагрузки устройства обновите и страницу в браузере (примерно через 5 секунд). Иначе открытая вкладка «не знает» о перезагрузке и ведёт себя непредсказуемо из-за кеша и открытых соединений.

«Редактор». Встроенный редактор файла usercode.lua с подсветкой синтаксиса. Кнопка «Прочитать» загружает текущий файл из устройства, «Записать» сохраняет код; Lua-файл также можно перетащить в область редактора. Для больших проектов используйте онлайн-среду или плагин VS Code.

«Файлы». Файловый менеджер каталога /public: загружает вспомогательные файлы, показывает их список и позволяет скачать или удалить выбранный файл. Поддерживается загрузка кнопкой и перетаскиванием в окно.

«Система». Модель устройства, версия прошивки и серийный номер. Здесь же можно локально загрузить прошивку в формате UFL или DFU.

Метки сложнее, чем кажется

Метки MIFARE позволяют не только читать UID, но и работать с пользовательской памятью, счётчиками и защищёнными блоками. Чтобы получать выбранные области карты, задайте строку форматирования. Она определяет состав результата и может переставлять, добавлять или исключать байты до передачи данных из считывателя. Подробнее о ключах, счётчиках и собственной программе — в статье «Защита от клонов меток».

Технические характеристики

1. Работа с метками (в зависимости от исполнения):
   • 13,56 МГц — MIFARE Classic 1K/4K/Mini, MIFARE Ultralight, Ultralight Nano, NTAG 213/215/216, S50/S70: полная поддержка; MIFARE Ultralight C: только чтение UID.
   • 125 кГц — UID EM-Marine EM4100 и HID ProxCard II, распознавание T55xx-копий; подготовленные ATA5577 поддерживают Trace ID и ротацию токена.
   • Устройство собирается с одним интерфейсом или сразу с двумя.
2. Дальность считывания: до 6–10 см (зависит от качества метки).
3. Габариты: 120 × 76 × 22 мм (ODNFC-LAN), 115 × 75 × 20 мм (ODNFC-LAN-C).
4. Интерфейсы: Ethernet/Wi-Fi.
5. Индикация: 2 × RGB-светодиод, звуковой излучатель, подключаемая лента.
6. Вход: один канал (3 В, подтянут к «1»).
7. Выход: один канал (макс. 1 А), напряжение равно напряжению питания.
8. Крепление: четыре отверстия M3.
9. Питание: Passive PoE 7–24 В.

Подключение

Интерфейс — Ethernet. Разъём: IDC381-8-110, клеммная колодка или привычный 8P8C (RJ45). По умолчанию устройство получает IP-адрес от DHCP-сервера; в настройках можно задать статический адрес. Питание — Passive PoE 7–24 В (можно подать постоянным напряжением). Индикация сети: красный — нет соединения, зелёный — соединение установлено.

Распиновка Passive PoE для устройств UnitX ODNFC:

• контакты 1 и 2 — Ethernet, первая пара данных;
• контакты 3 и 6 — Ethernet, вторая пара данных;
• контакты 4 и 5 — «+» питания;
• контакты 7 и 8 — «−» питания.

Нумерация относится к контактам разъёма 8P8C (RJ45) или соответствующим контактам колодки. Passive PoE подаёт постоянное напряжение без согласования с устройством — это не IEEE 802.3af/at. Перед включением убедитесь, что напряжение источника входит в допустимый для устройства диапазон.

Сетевой разъём исполнения ONL-N4-L-R-C — стандартный RJ45. В ONL-N4-L-I-C и ONL-N4-L-K-C используется колодка с той же нумерацией контактов.

Дополнительная колодка:

• OUT+ — «+» исполнительного устройства / замка;
• OUT− — «−» исполнительного устройства / замка;
• GND — «земля»;
• IN — сигнальный входной контакт.

Типы устройств

Последний элемент артикула обозначает корпус: C — устройство в корпусе, B — плату без корпуса. Частотное исполнение выбирается отдельно и в артикул не входит. См. расшифровку артикулов.

PRO-версия имеет больше энергонезависимой и оперативной памяти. Это позволяет: исполнять более сложные алгоритмы, использовать SSH, полноценно работать с библиотекой cURL, использовать FTP, работать с Telegram и отправлять данные по почте.

Шаблоны программ

В каталоге шаблонов программ ODNFC можно сравнить типовые сценарии, посмотреть совместимость, открыть исходный код и скачать отдельный .lua-файл. Доступны варианты:

• Передача по UDP — основной шаблон, отправляющий UID серверу по адресу из Web-настройки net_dest.
• Передача по OSC — упаковывает UID в OSC-сообщение и передаёт его по UDP.
• HTTP-считыватель — передаёт UID карты серверу по HTTP и открывает замок в зависимости от ответа.
• Автономный дверной замок — открывает дверь по UID из локального списка.
• Передача по MQTT — то же по MQTT.
• HTTP с опросом сервером — хранит последний UID до запроса сервера.
• Передача по TCP — отправляет UID на заданный TCP-сервер.

Почему Lua

Мы используем Lua, чтобы вам оставалось написать только скрипт с правилами работы: указать, какие данные читать, как принять решение и куда передать результат. Работу RFID-модулей, интерфейсов, сети, входов, выходов и индикации мы уже реализовали в прошивке — программировать считыватель с нуля не нужно.

Код не нужно отдельно компилировать: его можно изменить в устройстве и сразу проверить. В прошивке работает Lua 5.3. Для проекта из нескольких файлов удобнее консоль или плагин VS Code, чем встроенный редактор одного usercode.lua.

Пример кода в устройстве

Небольшой пример, чтобы понять, как работает устройство. Подробнее — на странице программирования на Lua.

Демо ниже — основной шаблон передачи UID по UDP. Он использует сеть, уже запущенную системным кодом, читает net_dest и sys_wdt из Web-настроек, восстанавливает цикл после сетевой ошибки и не перехватывает прерывание Ctrl-C.

local get, sleepms = Settings.get, thread.sleepms

-- Сеть запускается системным кодом по Web-настройкам.
local host, _, _, port = net.parseUrl(get("net_dest"))
local wdt_on = get("sys_wdt") == "on"

local leds = indication.Leds.new()
local snd = indication.Sound.new()

leds:start()
snd:start()

local function on_uid(uid)
    net.udp.sendto(host, port, uid)
    print("UDP sent:", uid)
    leds:ok()
    snd:ok()
end

local function iteration()
    local ok, err = mfrc522.scan(0, on_uid)
    if ok == false then error(err, 0) end
end

while true do
    if wdt_on then cpu.watchdog.reset() end

    local ok, err = pcall(iteration)
    if not ok then
        local message = tostring(err)
        if message:find("interrupted!", 1, true) then
            error(err, 0)
        end
        eprint("Main loop: " .. message)
        leds:err()
        snd:err()
        sleepms(250)
    else
        sleepms(50)
    end
end

Для этого примера нужен mfrc522.scan(). Если функция недоступна, обновите прошивку перед запуском.

Восстановление устройства

Если вы записали неправильные настройки или код и потеряли доступ к устройству:

1. Выключите устройство.
2. Замкните контакты HARD RESET или RECV на плате (зависит от ревизии).
3. Включите устройство, удерживая контакты замкнутыми.
4. Подождите несколько секунд (затем контакты можно разомкнуть).
5. Устройство создаст Wi-Fi-точку доступа вида OD-[серийный номер] без пароля. С версии 1.6.0 дополнительно поднимет Ethernet с DHCP-клиентом.
6. Устройство запустит веб-сервер и сервер Telnet — через них можно изменить настройки или программу и восстановить доступ. Wi-Fi IP-адрес: 192.168.4.1.

Обновление устройства

1. Откройте вкладку «Настройки». Если включён сторожевой таймер, отключите его и перезагрузите устройство.
2. Откройте вкладку «Система».
3. Скачайте подходящую прошивку, нажмите «Из файла» и выберите её.
4. Нажмите «Загрузить» и дождитесь сообщения о готовности — устройство перезагрузится.
5. Убедитесь, что отображается нужная версия прошивки.

Файл прошивки можно запросить в техподдержке.

История обновлений ODNFC на Lua

Если установлена версия ниже 1.7.0, сначала обновите её до 1.7.0, а затем до более новой версии. Перед обновлением отключите сторожевой таймер и сотрите пользовательскую программу.

net.en.setup(
  net.packip(Settings.get("net_ip")),
  net.packip(Settings.get("net_mask")),
  net.packip(Settings.get("net_gw")),
  net.packip(Settings.get("net_dns"))
)
net.en.start()

Дополнительные материалы

• Кнопка, замок, реле, второй считыватель и адресная RGB-лента
• Строка форматирования — как читать не UID, а данные с карты.
• Bluetooth-маяки — обмен по Bluetooth Low Energy.
• Modbus TCP — Master/Slave (Client/Server).
• Консоль — работа с файловой системой.
• Программирование на Lua — инструкции, примеры и советы.