Проектировать, реализовывать и отлаживать кастомные веб-интерфейсы для Wiren Board через MQTT over WebSocket (`/mqtt` через nginx): читать/писать топики `/devices/.../controls/...`, строить UI по MQTT metadata, публиковать страницы в локальной сети, добавлять базовый hardening (ACL/auth/безопасный рендер), и диагностировать проблемы UI↔MQTT↔device. Использовать, когда нужно сделать отдельную страницу мониторинга/управления устройствами WB или доработать существующий веб-интерфейс.
Проектировать, реализовывать и отлаживать кастомные веб-интерфейсы для Wiren Board через MQTT over WebSocket (`/mqtt` через nginx): читать/писать топики `/devices/.../controls/...`, строить UI по MQTT metadata, публиковать страницы в локальной сети, добавлять базовый hardening (ACL/auth/безопасный рендер), и диагностировать проблемы UI↔MQTT↔device. Использовать, когда нужно сделать отдельную страницу мониторинга/управления устройствами WB или доработать существующий веб-интерфейс.
WB WebUI
Создавай решения с опорой на MQTT conventions и runtime metadata, а не на один фиксированный пример страницы. Для небольших прикладных дашбордов допустим и статически описанный список контролов, если он проще и надёжнее.
Основной asset
MQTT-клиент в браузере: локальный assets/paho-mqtt-min.js. Копировать из assets/ скилла в статику проекта. Подключение и API — см. references/js-snippets.md.
Workflow
Preflight
Уточнять цель: мониторинг, управление, гибрид.
Проверять, какие устройства и device_id реально существуют в MQTT.
Проверять, что доступ в MQTT из браузера идет через nginx /mqtt (см. references/nginx-publish.md).
Если задача простая и список контролов известен заранее, не усложнять решение discovery-механикой и полным metadata-driven UI.
Для статически описанного UI держать device_id/control_id в одном источнике правды и не дублировать их независимо в HTML и JS.
Спроектировать контракт UI
Составить список устройств/контролов.
Зафиксировать, какие контролы read-only, какие writable, и какие действия считаются критичными.
Для каждого writable-контрола определить подтверждение результата (ACK по state-топику, meta/error, таймаут).
Построить карту контролов по metadata
Использовать type, title, units, readonly, min, max, order, error.
Собирать runtime-модель контролов и рендерить UI из нее.
Не предполагать, что типы/мета полностью заполнены; предусматривать fallback.
Если интерфейс узкоспециализированный, можно ограничиться частичным использованием metadata: например, брать только title, units, readonly.
Реализовать интерфейс
Подключение клиента, topic helpers, reconnect, парсинг — см. references/js-snippets.md.
Дизайн и структуру страницы определять по запросу пользователя; если нужно предложить варианты компоновки, открывать references/layout-ideas.md и выбирать/собирать направление под конкретный сценарий, а не копировать один preset.
Технические паттерны надёжности (stable DOM / pending+ACK / batched render) брать из references/ui-patterns.md; пример их применения — references/app-template.js (relay+sensor setup, только как технический референс, не как дефолтный UI-шаблон).
Для HTML-скелета (MQTT status, toast, подключение paho) — references/index-template-min.html; использовать как минимальную техническую заготовку и наполнять секциями согласно дизайну пользователя.
Семантика state/on-топиков — см. references/mqtt-topics.md.
Mapping type→widget, безопасный рендер, UX — см. references/ui-patterns.md.
Парсить топики корректно: control-имена могут содержать пробелы (Current Motion, P 1).
Не делать full rerender страницы на каждое MQTT-сообщение: обновлять только затронутые контролы/секции и сохранять стабильные DOM-узлы для интерактивных элементов.
Не ломать кликабельность при частых телеметриях: не пересоздавать writable-кнопки/переключатели на каждый MQTT message; обновлять их состояние точечно, а тяжёлые read-only блоки рендерить батчами (requestAnimationFrame/throttle).
Для writable-контролов использовать pending+ACK-логику: блокировать элемент до ACK по state-топику (или meta/error/таймаут), после чего разблокировать и показать результат.
При публикации статических JS/CSS использовать cache-busting (?v=<rev>) и увеличивать ревизию после изменений.
Опубликовать через nginx — см. references/nginx-publish.md.
Пройти hardening
Ограничивать websocket listener localhost-ом; не публиковать 1883/18883 наружу.
Включать auth/ACL по необходимости; ограничивать запись только в допустимые /on топики.
Проверить и отладить — см. references/troubleshooting.md.
Откат/очистка
Удалять временные route/page-файлы, если они были только для теста.
Откатывать nginx-конфиг к исходному состоянию.
При необходимости чистить stale retained-топики тестовых сущностей.
references/ui-patterns.md: универсальные паттерны рендера по meta/type и правила безопасного UI.
references/js-snippets.md: подключение локального paho-mqtt-min.js, переиспользуемые функции для MQTT-клиента и runtime-модели контролов.
references/app-template.js: готовый каркас app.js с устойчивой интерактивностью (stable DOM + pending/ACK + batched render); открывать, когда нужен технический пример логики, а не готовый дизайн.
references/index-template-min.html: минимальный технический HTML-каркас (нейтральный, без навязанного дизайна); открывать, когда нужен стартовый skeleton страницы.
references/layout-ideas.md: варианты компоновки UI (tiles/plan/mobile/control-room/scene-first) и обязательные инварианты надежности; открывать, когда пользователь просит предложить визуальное направление или несколько layout-вариантов.
references/nginx-publish.md: публикация страницы и проверка маршрута.
references/troubleshooting.md: типовые поломки и диагностика.
references/upstream.md: официальные источники и MQTT conventions.
