ODNFC-RS485 OSDP — быстрый старт для интегратора

ODNFC-RS485 OSDP подключается к контроллеру СКУД по двухпроводной линии RS485 и работает в роли Peripheral Device (PD). Контроллер доступа выполняет роль Control Panel (CP): регулярно опрашивает считыватель, принимает события карты и отправляет команды выходу, световой и звуковой индикации.

Это руководство помогает сначала проверить физическую линию и обычный обмен OSDP, а затем включить защищённый канал Secure Channel (SC). Для стендовой проверки дан минимальный Python-клиент CP.

Что даёт OSDP

OSDP — специализированный протокол для связи контроллеров доступа с периферийными устройствами. Он опубликован как международный стандарт IEC 60839-11-5 и поддерживает двусторонний обмен, контроль доступности устройств и защищённый канал с шифрованием и аутентификацией.

В исполнении ODNFC-RS485 доступны:

• события чтения карты в стандартном формате OSDP;
• идентификация PD и объявление его возможностей;
• команды управления выходом, светодиодом и звуковым излучателем;
• отчёты о состоянии входов, выходов, питания и корпуса — конкретный набор зависит от установленной прикладной программы;
• OSDP Secure Channel с шифрованием и аутентификацией AES-128;
• несколько PD с разными адресами на общей линии RS485;
• изменение и расширение поведения на Lua.

OSDP или Modbus RTU

OSDP не становится защищённым автоматически. До настройки Secure Channel обмен идёт без шифрования. Modbus RTU, в свою очередь, не определяет встроенную аутентификацию или шифрование вообще.

Перед началом

Подготовьте:

• ODNFC-RS485 с прикладной программой OSDP;
• источник питания 7–24 В;
• контроллер СКУД с ролью OSDP CP или преобразователь USB–RS485 для стенда;
• витую пару для A/B и общий GND;
• адрес PD, скорость линии и состояние Secure Channel;
• индивидуальный 16-байтный SCBK для штатной защищённой работы.

В примерах ниже используются адрес 101, 9600 бит/с, 8N1 и обычный незащищённый обмен. Это параметры тестового стенда, а не универсальные заводские настройки. Используйте значения, указанные для вашего устройства или согласованные при заказе.

1. Соберите стенд

Для первой проверки подключайте один считыватель и не подключайте замок:

• A считывателя к A преобразователя или контроллера;
• B к B;
• GND к общему GND;
• питание к +12V и GND; допустимый диапазон питания — 7–24 В.

Если обмена нет, один раз поменяйте A/B местами: маркировка встречается инвертированной. На длинной линии используйте шинную топологию без длинных ответвлений и согласование на концах линии. На общей шине должен быть только один CP.

2. Проверьте считыватель с ПК

Скачайте два файла в одну папку:

• osdp_cp_client.py — минимальный OSDP Control Panel;
• osdp_wire.py — формирование и разбор кадров.

Нужен Python 3 и пакет pyserial.

Linux и macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pyserial

Порт обычно называется /dev/ttyUSB0, /dev/ttyACM0 или /dev/cu.usbserial-*. Посмотреть подходящие устройства можно так:

ls /dev | grep -E '^(ttyUSB|ttyACM|cu\.usb)'

Windows PowerShell

py -m venv .venv
.venv\Scripts\python -m pip install pyserial

Имя порта (COM3, COM5 и т. п.) видно в диспетчере устройств Windows.

Запуск теста

Linux/macOS:

python osdp_cp_client.py \
  --port /dev/ttyUSB0 --baud 9600 --address 101 \
  --output --led --polls 200

Windows:

.venv\Scripts\python osdp_cp_client.py `
  --port COM5 --baud 9600 --address 101 `
  --output --led --polls 200

Замените порт, адрес и скорость своими значениями. Во время опроса поднесите карту. Перед использованием --output убедитесь, что к выходу не подключён замок или другая нагрузка, которую нельзя кратковременно переключать.

Ожидаемый результат:

• PDID — считыватель ответил своей идентификацией;
• PDCAP — перечислены поддерживаемые возможности;
• ISTATR или другой status reply — линия и прикладной обработчик работают;
• ACK после команд output и LED — команда принята;
• RAW после поднесения карты — получено событие с данными карты.

Например:

reply PDID ...
pdid vendor=0x...... model=... version=... serial=... fw=...
reply PDCAP ...
cap fc=... level=... items=...
reply ACK
reply RAW ...

Python-клиент намеренно реализует только небольшой незащищённый набор OSDP. Он проверяет UART/RS485, адрес, кадры, CRC и базовые команды, но не проверяет Secure Channel, установку ключа, передачу файлов, несколько PD на общей линии или соответствие всему стандарту OSDP. Его нельзя использовать как CP в рабочей СКУД или как доказательство сертификации.

3. Подключите штатный контроллер СКУД

1. Настройте на CP тот же адрес, скорость и формат линии.
2. Убедитесь, что CP видит PD на связи и читает его идентификатор и заявленные возможности.
3. Поднесите несколько карт разных типов и сверьте длину и порядок байтов идентификатора с требованиями системы.
4. Проверьте команды LED, buzzer и output. ACK означает, что команда принята, но фактическую реакцию также нужно проверить на устройстве.
5. Проверьте восстановление обмена после отключения и включения питания PD.
6. После обычного обмена в контролируемом стенде настройте Secure Channel.

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

4. Включите Secure Channel

Для штатной эксплуатации используйте отдельный случайный SCBK для каждого устройства. Один и тот же бинарный ключ длиной 16 байт должен быть сохранён на PD и CP. Не публикуйте ключ, не храните его в общем примере и не используйте тестовое значение 0123456789ABCDEF на объекте.

Если ключ уже записан

Настройте обе стороны с одинаковым SCBK и включите режим обязательного защищённого обмена. В Lua API это флаг OSDP_FLAG_ENFORCE_SECURE. После запуска проверьте не только наличие PD на связи, но и активное состояние Secure Channel.

Первичная запись нового ключа

Выполняйте ввод в эксплуатацию только на физически контролируемом стенде:

1. Запустите PD без рабочего SCBK с флагом OSDP_FLAG_INSTALL_MODE.
2. На CP укажите желаемый новый 16-байтный SCBK и включите такой же режим установки.
3. CP и PD временно установят канал через стандартный SCBK-D, после чего LibOSDP передаст новый ключ командой KEYSET и повторно установит канал.
4. Дождитесь подтверждения, что Secure Channel активен. Сеанс на SCBK-D не считается защищённым рабочим каналом.
5. Отключите режим установки и перезапустите обе стороны с новым ключом и обязательным Secure Channel.

Не сочетайте режим установки с обязательным защищённым обменом (enforce-secure) в одной конфигурации и не оставляйте режим установки включённым после ввода устройства в эксплуатацию. Минимальный Python-клиент из предыдущего раздела эту процедуру не выполняет — используйте штатный CP либо полноценную реализацию OSDP.

Несколько считывателей на одной линии

• назначьте каждому PD уникальный адрес;
• используйте одинаковую скорость и формат 8N1;
• подключайте устройства общей шиной, а не звездой;
• храните соответствие «адрес — серийный номер — место установки — SCBK»;
• проверяйте связь и Secure Channel отдельно для каждого PD;
• сначала отладьте каждое устройство на короткой одиночной линии, затем собирайте общую линию с несколькими устройствами.

В Lua-конфигурации CP все PD одной физической линии используют одинаковый положительный channel_id, но разные OSDP-адреса. Для независимой линии нужен другой channel_id.

Переключение между Modbus и OSDP

ODNFC-RS485 поддерживает Modbus и OSDP, поэтому протокол можно менять прикладной программой. Но один UART/RS485 нельзя одновременно занимать двумя драйверами. Перед переключением остановите текущий протокол, освободите UART и только затем запускайте другой.

Диагностика

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

• Кнопка, замок, реле, второй считыватель и адресная RGB-лента
• Полный API модуля OSDP в Lua
• ODNFC-RS485 Modbus: подключение и карта регистров
• Программирование ODNFC на Lua
• Описание OSDP от Security Industry Association

Для согласования адресов, SCBK и профиля команд до поставки свяжитесь с инженером UnitX.

История обновлений 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()