# MQTT

Топики брокера MQTT как данные оборудования прямо в чате

Топики брокера MQTT (UNS) через назначенный шлюз, только чтение

## Как агент работает с MQTT

Брокер MQTT обычно стоит в сети объекта, поэтому к нему ходит шлюз: программа, установленная на компьютер в той же сети. Шлюз добавляется на вкладке «Шлюзы» и назначается подключению. В подключении указываются адрес брокера (mqtt:// или mqtts://), при необходимости логин и пароль и фильтры топиков. Пока связи наружу нет, шлюз копит данные на диске и отправляет их, когда она вернётся.

Шлюз подписывается только на названные фильтры, а не на весь брокер, и каждый топик становится тегом. Сообщение читается как JSON или как текст; указатели JSON задают, где в нём значения и где время источника, а объект с несколькими полями даёт несколько тегов. Retained-сообщение без времени шлюз помечает как значение неизвестного возраста. Сессия чистая: то, что брокер копил, пока шлюза не было, не переигрывается.

Шлюз не публикует ни одного сообщения: у него нет ни публикации, ни завещания (will), ни retained-сообщений от своего имени. Поэтому его учётной записи в ACL брокера достаточно права подписки, и только чтение держит сам брокер. Агент читает текущие значения, историю и свежесть, но ничего не отправляет в топики и не управляет оборудованием.

Каталог тегов растёт по мере прихода сообщений и ограничен настройкой «Не больше тегов» (по умолчанию 10000), чтобы слишком широкий фильтр не превратил загруженный брокер в сотни тысяч тегов. Тип тега берётся по первому значению и меняется, только если два значения подряд пришли другого типа. История копится с момента подключения: прошлых значений брокер не хранит.

## Сценарии интеграции

### Текущие значения
Агент найдёт теги по топику или имени и покажет последние значения со временем источника, а устаревшее значение назовёт устаревшим, а не текущим.

### Тренд за смену
Агент соберёт историю тега за период интервалами: минимум, максимум, среднее и последнее значение, с пропусками там, где данных не было.

### Датчики через мосты
Агент читает JSON-сообщения Zigbee2MQTT, ChirpStack, Node-RED и HighByte: каждое поле объекта становится своим тегом со своей историей.

### Сравнение линий
Агент сопоставит один показатель по разным топикам, например температуру на нескольких линиях, и сравнит средние и пики за один период.

### Задача по условию
Агент заведёт задачу «По событию»: она запустится, когда значение тега перейдёт порог и продержится заданное время.

### Связь шлюза
Агент скажет, на связи ли шлюз и подключение к брокеру, а задача по событию узнает, когда шлюз пропал и когда вернулся.

## Как подключить

**Перед подключением**

- Брокер MQTT 5 или 3.1.1, доступный с компьютера шлюза
- Учётная запись брокера с правом подписки на нужные топики
- Компьютер в сети объекта для программы шлюза
- Для mqtts:// сертификат брокера, которому доверяет шлюз

### Создайте пользователя брокера
Шлюз только подписывается и ничего не публикует. Дайте его учётной записи в ACL брокера право подписки на нужные топики, публикация ей не нужна.

### Задайте Client ID, если брокер их проверяет
Если ACL брокера пускает только известные ID клиента, впишите такой ID в дополнительных настройках подключения. Пусто: шлюз назовётся сам.

### Подпишитесь узкими фильтрами
Перечислите фильтры через запятую, например линия/+/температура, а не #. Для Zigbee2MQTT подпишитесь на zigbee2mqtt/+, а не на zigbee2mqtt/#.

### Для TLS положите сертификаты на шлюз
Адрес mqtts:// проверяется по корням системы и PEM из папки данных шлюза pki/mqtt/trusted/. Для mTLS: pki/mqtt/own/cert.pem и key.pem.

## Частые вопросы

### Как подключить MQTT?
Установите шлюз на компьютер в сети объекта и добавьте его на вкладке «Шлюзы». В подключении MQTT укажите адрес брокера, например mqtt://10.0.12.5:1883, логин и пароль, если брокер их требует, и фильтры топиков через запятую.

### Что агент видит в MQTT?
Топики под вашими фильтрами как теги: значения из JSON или текста, время источника, если оно есть в сообщении, историю с момента подключения и свежесть каждого значения. Поля объекта JSON становятся отдельными тегами.

### Отправляет ли агент сообщения в брокер?
Нет. Шлюз только подписывается: публикации, завещания и retained-сообщений от его имени нет. Учётной записи шлюза достаточно права подписки.

### Подключение отвечает отказом доступа. Что проверить?
Брокер принял логин, но отказал в подписке на один из фильтров. Проверьте ACL учётной записи шлюза для каждого фильтра, а если брокер пускает только известные ID клиента, впишите Client ID в дополнительных настройках.