---
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-топиков устройства:

```bash
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`