Протокол взаимодействия хоста с RFID-считывателем по UART
Проводной протокол управления считывателем и получения данных о метках по последовательной шине UART. Поддерживаются два стиля команд — компактный бинарный (Short Protocol) и текстовый JSON. Набор команд и форматы уведомлений едины для приборов SAUK; различается лишь состав полей в зависимости от типа прибора и комплектации.
Содержание
1Общие сведения и физический уровень
Это протокол шины UART прибора: хост (компьютер, контроллер, ПЛК) обменивается с RFID-считывателем короткими кадрами по последовательному интерфейсу.
Физический интерфейс
Базовый интерфейс — UART (логические уровни). Шина UART может быть дополнена преобразователями интерфейсов для согласования с оборудованием хоста:
- USB — подключение к компьютеру как виртуальный COM-порт;
- RS-232 — стандартный последовательный порт;
- RS-485 — промышленная двухпроводная линия, в том числе на большие расстояния и с несколькими устройствами.
Логика протокола одинакова независимо от применённого преобразователя.
Скорость обмена настраивается (см. notify_uart_speed): допустимы 9600, 19200, 38400, 57600, 115200 бод. По умолчанию — 9600 бод (для исполнения с USB — 115200).
1.1Формат кадра
Каждая посылка от хоста начинается с признака типа и завершается парой 0x0D 0x0A (CR LF):
| Признак начала | Тип команды | Завершение |
|---|---|---|
| 0xA0 | Бинарная команда (Short Protocol) | 0x0D 0x0A |
| 0x7B «{» | Текстовая команда JSON | 0x0D 0x0A |
Байты, не начинающиеся с 0xA0 или {, отбрасываются. Максимальный размер посылки — 128 байт (HOST_BUFFERSIZE). Бинарные команды используют префикс 0xA0 0x00.
Modbus на той же шине
Параллельно на шине UART может работать протокол Modbus RTU (функции 03/06, регистры с адреса 1000) — это отдельный протокол, описанный в собственном документе «MODBUS RTU и TCP/IP», не относящийся к Short Protocol / JSON.
2Бинарные команды (Short Protocol)
Формат кадра: A0 00 <CMD> [параметры] 0D 0A. Поддерживаются четыре команды; посылки с иным кодом команды игнорируются.
2.1A0 00 01 — управление непрерывной инвентаризацией
Кадр: A0 00 01 [start] [save] 0D 0A.
| Байт | Поле | Значения |
|---|---|---|
| [3] | start | 0x01 = запустить, 0x00 = остановить |
| [4] | save | 0x01 = сохранить флаг в конфигурацию, 0x00 = не сохранять |
{"result":"ok"} 2.2A0 00 02 — однократная инвентаризация
Кадр: A0 00 02 0D 0A. Запускает один цикл сканирования, если непрерывная инвентаризация не идёт. Результат приходит асинхронно как уведомление о метке (раздел 5). Если метка не обнаружена — прибор шлёт «нет метки»: байтовый ответ A0 00 02 00 0D 0A либо (в JSON-режиме) {"c":"tag","p":"read","w":"no_tag_error"}.
2.3A0 00 FF 01 02 — диагностика UART
Кадр: A0 00 FF 01 02 0D 0A (байты 01 02 фиксированы). Самотест линии: прибор сам передаёт этот кадр и ожидает его обратно (петля). При приёме устанавливает признак успешной проверки; UART-ответа не формирует. Таймаут ожидания петли — 500 мс.
2.4A0 00 BE — статус контроллера рампы (RAMP)
Приём статуса от внешнего контроллера рампы (доступно в соответствующей комплектации). Кадр: A0 00 BE [addr] 01 [—] [sensors] [busy] [light1] [light2] 0D 0A.
| Байт | Поле | Описание |
|---|---|---|
| [3] | addr | Адрес считывателя (должен совпасть с адресом Modbus RTU прибора) |
| [4] | тип | 0x01 = статус (иначе кадр игнорируется) |
| [6] | sensors | Состояние сенсоров рампы |
| [7] | busy | Флаг «рампа занята» |
| [8] | light1 | Состояние светофора 1 |
| [9] | light2 | Состояние светофора 2 |
Прямого ответа нет — прибор обновляет внутренние переменные состояния рампы.
3JSON-команды
Текстовые команды передаются как корректный JSON-объект и завершаются 0x0D 0x0A. Общие ключи — cmd, param, value. При синтаксической ошибке прибор отвечает {"result":"syntax error"}.
3.1Чтение памяти метки — tag / read
Читает выбранный банк памяти метки (EPC, TID, USER). Игнорируется при запущенной непрерывной инвентаризации.
| Параметр | Тип | Описание |
|---|---|---|
| cmd | string | «tag» |
| param | string | «read» |
| bank | int | Банк памяти: 0 = Reserved, 1 = EPC, 2 = TID, 3 = USER |
| block | int | Начальный блок (слово) |
| count | int | Число блоков (макс. 6) |
3.2Однократная инвентаризация — act / inventory_once
3.3Запросы информации — get
| Запрос | Назначение | Ответ |
|---|---|---|
| {"cmd":"get","param":"type"} | Тип устройства | {"cmd":"get","param":"type","value":"DW|D|A"} |
| {"cmd":"get","param":"version"} | Версия и конфигурация | {"result":"ok","version":{…}} |
| {"cmd":"get","param":"datetime"} | Дата и время | {"c":"get","datetime":…} |
| {"cmd":"get","param":"peripheryconfig"} | Конфигурация периферии | JSON конфигурации периферии |
{"cmd":"get","param":"type","value":"D"} 3.4Установка параметров — set
Формат: {"cmd":"set","param":"<имя>","value":<значение>}. При успехе прибор отвечает {"result":"ok"} и помечает конфигурацию к сохранению. Через UART доступна установка параметров идентификации меток и периферии:
| Параметр (param) | Назначение |
|---|---|
| tagidentity.validate_ms | Время «сна» метки перед повторным чтением |
| tagidentity.hold_time_ms | Время удержания метки в списке |
| tagidentity.beep_on_tag | Звуковой сигнал при обнаружении метки |
| tagidentity.rssi_filter_enable / .rssi_filter_value | Фильтр по уровню сигнала и его порог |
| tagidentity.epc_filter_enable / .epc_filter_value | EPC-фильтр и его значение |
| tagidentity.epc_access_password | Пароль доступа к меткам |
| tagidentity.extra_mem_read / .data_start_bytes / .data_len_bytes | Чтение доп. банка памяти и его параметры |
| peripheryconfig.beep_on_start | Звуковой сигнал при старте прибора |
{"result":"ok"} Параметры RFID-модуля — через HTTP-API
Параметры самого RFID-модуля (мощность антенн, частотный план, номер сессии, непрерывная инвентаризация) настраиваются через HTTP-API прибора (документ «API для HTTP через Wi-Fi и Ethernet», запрос /rfidconfig) либо, для запуска/остановки инвентаризации, бинарной командой A0 00 01. Управление непрерывной инвентаризацией по UART выполняйте командой A0 00 01, а не через set.
4Форматы ответов
Формат ответов на команды зависит от настройки notify_uart_json:
| notify_uart_json | Формат ответа | Примеры |
|---|---|---|
| 1 или 2 | JSON-объекты | {"result":"ok"} · {"result":"syntax error"} · {"message":"warning","value":"Can't find command"} |
| 0 или 3 | Простые текстовые строки | OK |
Служебные ответы формируются только при включённых UART-уведомлениях (notify_uart).
5Уведомления считывателя на хост
При включённых UART-уведомлениях (notify_uart=true) считыватель сам отправляет на хост посылку по каждой обнаруженной метке, удовлетворяющей правилам фильтрации. Формат посылки выбирается настройкой notify_uart_json:
| notify_uart_json | Формат уведомления |
|---|---|
| 0 | Фиксированная байтовая посылка |
| 1 | Строка JSON (фиксированный набор полей) |
| 2 | Настраиваемая строка (ASCII, конструктор из полей) |
| 3 | Настраиваемая байтовая посылка (конструктор из полей) |
Все примеры ниже соответствуют реальной метке, считанной прибором: EPC 77770220F73F0AFD00000006, TID E280117020000220F73F0AFD, антенна 1, RSSI −34.
5.1Строка JSON (notify_uart_json = 1)
Фиксированный набор ключей, посылка завершается }\r\n. Поля BANK/DATA/DATALEN добавляются, только если дополнительные данные были прочитаны.
{"SN":"A1B2C3","RTC":"109.088","ANT":1,"EPC":"77770220F73F0AFD00000006","EPCLEN":12,"RSSI":-34,"BANK":2,"DATA":"E280117020000220F73F0AFD","DATALEN":12} | Поле | Смысл |
|---|---|
| SN | Серийный номер считывателя |
| RTC | Момент обнаружения (время работы, секунды.миллисекунды) |
| ANT | Номер антенны |
| EPC / EPCLEN | Код метки (память EPC) и его длина в байтах |
| RSSI | Уровень сигнала |
| BANK / DATA / DATALEN | Банк, содержимое и длина доп. данных (например, TID) — при наличии |
5.2Байтовая посылка (notify_uart_json = 0)
Фиксированная посылка длиной 31 байт, завершается 0x0D 0x0A. Структура (для EPC и DATA по 12 байт):
| Байты | Поле |
|---|---|
| [0..2] | Заголовок A0 00 02 |
| [3] | Длина EPC = 0x0C (12) |
| [4..15] | EPC (12 байт) |
| [16] | Длина DATA = 0x0C (12) |
| [17..28] | DATA / TID (12 байт) |
| [29] | Номер антенны |
| [30] | RSSI (пересчитанный) |
| + 0x0D 0x0A | Завершение |
A0 00 02 0C 77 77 02 20 F7 3F 0A FD 00 00 00 06 0C E2 80 11 70 20 00 02 20 F7 3F 0A FD 01 22 0D 0A
5.3Настраиваемая строка и байты (notify_uart_json = 2 и 3)
Состав посылки собирается «конструктором» из включаемых полей. Поля идут строго в фиксированном порядке и склеиваются встык; роль разделителей выполняют префикс и суффикс:
| Флаг | Что добавляет |
|---|---|
| add_prefix | Строку-префикс в начале (по умолчанию «[») |
| add_epcl | Длину EPC |
| add_epc | Код EPC |
| add_tidl | Длину доп. данных (TID/DATA) |
| add_tid | Доп. данные (TID/DATA) |
| add_ant | Номер антенны |
| add_rssi | Уровень RSSI |
| add_suffix | Строку-суффикс в конце (по умолчанию «]») |
| add_crlf | Завершение \r\n |
Режим 2 (ASCII): длины и RSSI — в шестнадцатеричном виде текстом, EPC/TID — hex-строки, номер антенны — два символа. Режим 3 (байты): те же поля сырыми байтами, при этом длины EPC/TID указываются в битах (байты × 8), а префикс/суффикс передаются побайтно.
[0C777702 20F73F0A FD000000 060CE280 11702000 0220F73F 0AFD0122]
Здесь 0C — длина EPC (12 байт), далее EPC; 0C — длина TID, далее TID; 01 — антенна; 22 — RSSI (0x22 = 34). Пробелы приведены только для читаемости — в посылке их нет.
5.4Keep-alive
Если включён notify_uart_alive (по умолчанию включён), считыватель периодически (примерно раз в 5 секунд) отправляет посылку «жив», позволяющую хосту убедиться в наличии связи. При включённой непрерывной инвентаризации keep-alive шлётся только в моменты простоя (когда меток нет); при выключенной — регулярно.
{"SN":"A1B2C3","cmd":"act","param":"inventory","warning":"no_tag_alive","scan":false} A0 00 02 00 0D 0A
Поле scan (и байт [3] в байтовом режиме) отражает состояние непрерывного сканирования: true/0x01 — включено, false/0x00 — выключено.
6Примечания и ограничения
Синтаксис
Все команды должны быть корректно сформированы и завершаться 0x0D 0x0A. Некорректный JSON приводит к ответу {"result":"syntax error"}, неизвестная команда — к предупреждению {"message":"warning","value":"…"}.
Размер посылки
Максимальный размер одной посылки — 128 байт (HOST_BUFFERSIZE). Убедитесь, что команды не превышают этот лимит.
Условия выполнения
Отдельные команды выполняются только при определённых условиях: например, чтение памяти метки (tag/read) невозможно при запущенной непрерывной инвентаризации.
Сохранение конфигурации
Изменение параметров командой set помечает конфигурацию к сохранению в постоянную память прибора.