Внешние интеграции через MQTT

Подготовить подключение и права

Входящий поток данных и исходящая трансляция модели имеют разные форматы. Входящий пакет USEPI содержит массив документов; исходящий state содержит полный JSON-объект вашей модели без обёртки. Любой внешний MQTT-клиент должен соблюдать эти контракты независимо от языка и оборудования.

Нужны зарегистрированный MQTT-сервер источника, доступ к его данным, права на устройство и трансляцию, а также учётные данные MQTT-клиента с подходящими broker ACL. Разрешение в BlueTraktor не заменяет разрешение брокера. Секреты не включайте в payload, модель или снимки проверки.

1. В «Настройки» → «Серверы» проверьте MQTT-подключение и адрес брокера, к которому будет публиковать внешний источник.
2. Согласуйте отдельный тестовый topic и точное право публикации. Для получения одной модели отдельно разрешите подписку только на её точный state topic.

Входящий пакет: topic и JSON

Опубликуйте приведённый ниже JSON-массив в topic USEPI/demo/line-1 на выбранном брокере. ETL подписывается на USEPI/# и /USEPI/#; регистр важен: префикс USEPI должен быть в верхнем регистре. Произвольный raw topic не становится веткой DataTree.

После удаления префикса путь под выбранным зарегистрированным MQTT-источником будет demo/line-1/temperature/value; для второго документа — demo/line-1/enabled/value. Внутренний server ID выбирается отдельно: hostname брокера не входит в путь.

[
  {"@id":"temperature","@type":"value","value":23.5,"unit":"C"},
  {"@id":"enabled","@type":"value","value":true}
]

Ограничения и неправильные payload

JSON-декодер принимает массив объектов: не более 4096 документов и 1024 ключей в каждом документе. Для попадания в DataTree каждому документу нужен непустой строковый @id; документ без него или с пустым @id игнорируется. @type: value необязателен для runtime, но рекомендуется для отображения листа в интерфейсе.

После USEPI нужен непустой хвост topic: не более 32 сегментов, каждый не более 256 байт UTF-8; весь topic — не более 4096 байт. Сегмент root зарезервирован. Эти пределы не заменяют остальные ограничения установки и брокера.

Типы значений и последнее состояние

Передавайте 23.5 как JSON number, а true как JSON boolean, не как строки. Эти типы сохраняются. Число в кавычках является строкой входного JSON; не полагайтесь на автоматическое распознавание строк и отправляйте нужный JSON-тип явно. Объект или массив внутри value остаётся целым значением одного листа value, а не автоматически разложенной веткой.

Для последнего состояния рекомендуется retain=true: новый подписчик сможет получить сохранённое брокером сообщение. Это не история измерений. QoS 1 подтверждает приём брокером, но не даёт гарантии принятия Core. Не направляйте телеметрию обратно в topic команд оборудованию и не создавайте петлю публикации.

Проверить вход и связать устройство

1. Во внешнем MQTT-клиенте выберите согласованный брокер, topic USEPI/demo/line-1 и JSON-массив из примера; для теста последнего состояния задайте QoS 1 и retain=true.
2. В редакторе модели выберите зарегистрированный MQTT-источник и найдите demo/line-1/temperature/value и demo/line-1/enabled/value. Убедитесь, что фактически видны 23.5 и true, а не только статус подключения.
3. Создайте или откройте тестовое устройство и свяжите его поля с этими точными листьями. Сохраните устройство и исправьте недействующие ссылки.
4. Измените входное значение temperature, например с 23.5 на 24.0, и проверьте изменение связанного поля устройства. Подтверждение публикации брокером само по себе не завершает эту проверку.

Включить трансляцию модели

1. В меню сохранённого устройства выберите «Транслировать» и в окне «Трансляция записи» выберите серверы назначения («Транслировать в»). Внешний получатель должен подключаться к выбранному брокеру назначения, который может отличаться от источника.
2. Подтвердите действие и получите одобрение, если оно требуется вашей ролью и состоянием заявки. Сохранённое устройство и зелёный статус брокера сами по себе не включают трансляцию.
3. Проверьте состояние в «Настройки» → «Выгрузка устройств». После изменений сохранённой модели примените изменения к трансляции, если требуется.
4. У сервера назначения откройте меню «Топики», выберите «Трансляции моделей» и нажмите «Показать топики». Скопируйте полный фактический topic нужной модели; просмотр списка ничего не удаляет.

Подписаться на одну конкретную модель

Канонический формат topic приведён ниже. user_id берётся из device_unloading.user_id, model_id — из unloading._id, то есть _id записи device_unloading. Это не ID исходного устройства, шаблона, имя модели или hostname. Стабильные ID сохраняют MQTT-адрес при переименовании модели.

Вставьте в MQTT-клиент точный topic, скопированный из «Топики» → «Трансляции моделей». Не придумывайте ID и не запрашивайте приватную базу. Для одной конкретной модели не используйте + или #; broker ACL и права на просмотр должны разрешать именно это назначение.

TRAKTOR/v1/users/<user_id>/models/<model_id>/state

Исходящий payload: полная модель

Core публикует полный актуальный JSON snapshot модели без transport envelope: QoS 0, retain=true. Пример ниже показывает модель с полями name, temperature и enabled; ваша структура определяется сохранённым устройством. Это JSON-объект, а не входящий массив документов USEPI и не обёртка с @id.

Числа и boolean остаются типизированными. Сообщение не является delta, историей или гарантией каждой промежуточной перемены. Неизменившееся фактическое значение не требует новой публикации; QoS 0 не подтверждает доставку каждого состояния.

{
  "name": "Line 1",
  "temperature": 23.5,
  "enabled": true
}

Проверить получение и остановку

1. Подпишитесь на точный state topic одной модели на брокере назначения. Сравните полученный полный JSON с фактическими значениями связанного устройства.
2. Измените входное поле в валидном USEPI-пакете и дождитесь полного snapshot с новым значением и остальными полями модели. Не принимайте MQTT ACK источника за результат трансляции.
3. Подключите новый отдельный подписчик к тому же точному topic и проверьте позднее получение retained snapshot. Зафиксируйте фактические topic, JSON и значения без секретов; инструкция не является подтверждением успешного обмена.
4. Для согласованного теста остановки используйте «Отменить трансляцию» у модели. Проверьте, что новый подписчик больше не получает старый retained snapshot.