wb-mqtt

name

wb-mqtt

description

Разворачивать, подключать и диагностировать существующие шаблоны `wb-mqtt-serial` на контроллере Wiren Board: рендерить `.json.jinja` в `.json`, деплоить в `/etc/wb-mqtt-serial.conf.d/templates`, добавлять устройство в `/etc/wb-mqtt-serial.conf`, проверять логи и MQTT retained-топики, сверять каналы/регистры с документацией, а также разбирать несовместимость шаблона с устройством по `hw.signature`, минимальной версии прошивки и конфликтам системного/пользовательского шаблона. Использовать, когда нужно проверить работу шаблона на живом стенде, подобрать совместимый шаблон или разобрать ошибки опроса/публикации. Содержит справочник Modbus-регистров устройств Wiren Board.

WB MQTT-Serial Templates

Проверяй шаблоны wb-mqtt-serial на контроллере: от рендера/деплоя шаблона до валидации публикаций в MQTT. Используй встроенный справочник регистров WB из references/modbus-register-maps.md как источник для сверки адресов/типов/масштабов. Если задача про выбор совместимого шаблона или причины ошибки incompatible, см. references/template-matching.md, где отдельно разведены device_signature устройства и hw.signature шаблона.

Когда читать references

• references/modbus-register-maps.md: когда нужно сверить адреса, типы, scale, units и различия по версиям устройства.
• references/template-matching.md: когда нужно понять, какой шаблон подходит устройству, почему шаблон incompatible, как сравниваются device_signature и hw.signature, или какой шаблон реально победит при одинаковом device_type.
• references/upstream.md: когда нужны upstream-практики по tpl<N>_, deprecated и versioning шаблонов.

Что нужно чтобы установить шаблон

• Локальный файл(ы) шаблона: .json или .json.jinja (и способ сборки/рендера для .jinja).
• Параметры устройства для wb-mqtt-serial: ports[].path (например /dev/ttyRS485-1), скорость/параметры линии, slave_id.
• Какой "тестовый" device_type будет использоваться (чтобы избежать коллизий с прод-шаблонами).

Важно (безопасность и коллизии)

• Пользовательские шаблоны нужно класть в /etc/wb-mqtt-serial.conf.d/templates. Они имеют приоритет над встроенными из /usr/share/wb-mqtt-serial/templates (не правь встроенные).
• Не перезаписывай существующие файлы в /etc/wb-mqtt-serial.conf.d/templates без явного подтверждения.
• Для тестов предпочитай уникальный device_type (например с префиксом tpl1_...). В upstream также рекомендуют подход с префиксом tpl<N>_ для новых версий шаблонов и полем deprecated для старых.

Workflow

Ниже даны шаги, которые дополняют (а не заменяют) wb-devs. Все команды про SSH/systemctl/journalctl/mosquitto_sub/mosquitto_pub бери оттуда. Если проблема выглядит как несовместимость шаблона, сначала проверь matching через references/template-matching.md, а потом деплой и MQTT.

0) Preflight: окружение и зависимости

• Проверь Python-зависимости для helper-скриптов:
  • python3 -c "import jinja2" для scripts/render_jinja.py
  • python3 -c "import paho.mqtt.client" для scripts/describe_device.py
• Если зависимость отсутствует, явно сообщи пользователю и предложи установить (через pip3)

1) Подготовь шаблон .json

• Для создания шаблона по карте регистров используй skill wb-mqtt-tmpl.
• Если у тебя .json.jinja, срендери его в чистый .json:
  • python3 scripts/render_jinja.py <template.json.jinja> -o <template.json>
• Быстро посмотреть, что внутри получилось: python3 scripts/template_summary.py <template.json> (покажет device_type, базовый device.id и список channels).
• Если template_summary.py показывает device_type: null, считай шаблон "нестандартным/legacy" и не пытайся автоматически генерировать devices[] только по этому файлу.
  • В таком случае опирайся на уже рабочий пример устройства в текущем /etc/wb-mqtt-serial.conf и адаптируй его поля под тест.
  • Отдельно зафиксируй в отчете, что для этого шаблона автогенерация сниппета (gen_device_config_snippet.py) неприменима.
• Если нужно понять, подходит ли шаблон устройству по device_signature, hw.signature и минимальной версии прошивки, открой references/template-matching.md.

2) Задеплой шаблон на контроллер

• Проверь содержимое /etc/wb-mqtt-serial.conf.d/templates и заранее договорись, можно ли перезаписывать.
• Скопируй .json в /etc/wb-mqtt-serial.conf.d/templates.

3) Подключи устройство в wb-mqtt-serial.conf

Два рабочих пути:

1. Пользователем через веб-интерфейс "Serial devices": выбрать/добавить устройство и указать device_type, slave_id, параметры порта.
2. Правкой /etc/wb-mqtt-serial.conf: найти нужный элемент в ports[] и добавить в devices[] новый девайс, где:
   • device_type совпадает со строкой device_type из шаблона
   • slave_id это Modbus адрес
   • name опционально (если не задано, обычно формируется из имени в шаблоне + slave_id)
   • channels: включи нужные каналы по name (как они называются в шаблоне). Если нужно быстро включить все каналы, сгенерируй заготовку: python3 scripts/gen_device_config_snippet.py <template.json> --slave-id <N>
   • При необходимости переопредели параметры канала в channels[] локально (для диагностики/временных правок), не меняя сам шаблон.
   • Если у шаблона нет device_type, используй ручной путь: копируй структуру рабочего устройства из того же конфига и меняй только необходимые поля для теста.

Если не уверен в формате channels в вашем конфиге (проекты/версии могли отличаться): скопируй структуру devices[]/channels[] из уже работающего устройства в этом же /etc/wb-mqtt-serial.conf и адаптируй только имена каналов.

4) Перезапусти драйвер и проверь ошибки

• Перезапусти wb-mqtt-serial.
• Проверь логи на ошибки уровня template/config/parse.
• Отдельно ищи признаки проблем линии и опроса: ILLEGAL_*, CRC, timeout, unsupported_value.

5) Проверь результат в MQTT (retained)

Как получить device_id в MQTT (частая путаница)

• В шаблоне есть device.id (базовая часть).
• По документации wb-mqtt-serial templates, при обычной работе device_id формируется как <device.id>_<slave_id> (если device.id не содержит %).
• Дальше проверяй /devices/<device_id>/... (meta, controls, ошибки).

describe_device (проверка "как видит HA/WB UI")

Используй scripts/describe_device.py чтобы собрать полный описывающий JSON со всех retained-топиков устройства:

python3 scripts/describe_device.py --broker <controller_ip> <device_id>

Если ругается на paho-mqtt: установи зависимость на хосте pip3 install paho-mqtt.

Сверь:

• список controls с ожидаемыми каналами в шаблоне
• meta (название, производитель/модель, и т.п., если шаблон их публикует)
• meta/type и meta/error для проблемных контролов

Быстрая проверка MQTT-конвенций (из практики WB)

• Для управляющих каналов различай топики:
  • команда пишется в /devices/<device_id>/controls/<control>/on
  • фактическое состояние читается из /devices/<device_id>/controls/<control>
• Проверь служебные топики:
  • /devices/<device_id>/controls/<control>/meta/type для типа контрола
  • /devices/<device_id>/controls/<control>/meta/error для ошибок (r чтение, w запись)
• При подписке учитывай retained: после mosquitto_sub можно увидеть старые значения до нового опроса.

Сверка регистров с официальной документацией (WB устройства)

Если шаблон описывает устройство Wiren Board (или совместимое устройство, где критичны адреса/типы регистров), сверяй:

• адреса регистров
• типы данных/масштабы/единицы измерения
• различия по версиям устройства/прошивки

Точка входа: references/modbus-register-maps.md.

6) Откат/очистка

• Удали тестовый шаблон из /etc/wb-mqtt-serial.conf.d/templates если он был только для проверки.
• Верни /etc/wb-mqtt-serial.conf к исходному состоянию (бэкап).
• Если в UI остались "призрачные" устройства/каналы, очисти stale retained-топики через mqtt-delete-retained по префиксу /devices/<device_id>/.
• Перезапусти wb-mqtt-serial и убедись, что основной стенд работает.

Типовые причины, почему "не завелось"

• Шаблон: device_type в конфиге не совпадает с device_type в шаблоне.
• Шаблон: твой тестовый шаблон переопределил встроенный или другой пользовательский (поэтому нужен уникальный device_type и проверка содержимого /etc/wb-mqtt-serial.conf.d/templates).
• Линия связи: тайминги RS-485 (в т.ч. guard_interval_us, frame_timeout_ms) и неверные параметры порта приводят к таймаутам/CRC в логах.
• MQTT/retained: видны старые/неактуальные значения, и кажется, что шаблон "не работает", хотя драйвер уже публикует новое состояние.
• Runtime: драйвер автоматически выключил опрос части регистров/каналов (например, из-за ILLEGAL_*, unsupported_value или sporadic), и ожидаемые значения больше не обновляются.
• Runtime: после пропадания/возврата устройства setup не применился как ожидалось; проверь device_timeout_ms и device_max_fail_cycles (эти параметры влияют на повторную инициализацию устройства).

Навигация

• Генерация/нормализация шаблона из карты регистров: skill wb-mqtt-tmpl
• Полезные upstream-материалы и конвенции: references/upstream.md
• Документация по Modbus-регистрам устройств WB (для сверки шаблонов): references/modbus-register-maps.md
• Подбор совместимого шаблона по сигнатуре/прошивке: references/template-matching.md
• Работа с физическими устройствами: skill wb-devs