MQTT

Интеграция MQTT подключает приложение ONS к вашему MQTT-брокеру: сервер публикует в брокер uplink устройств приложения и принимает из брокера команды downlink. Внешней системе достаточно MQTT-клиента — соединение с WebSocket API для этого не нужно. Интеграцию настраивают на странице приложения в веб-интерфейсе; у приложения может быть одна интеграция MQTT.

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

1. Откройте приложение в разделе «Приложения» веб-интерфейса.
2. В блоке «Интеграции» на карточке MQTT нажмите «Add».
3. Заполните поля, см. таблицу ниже. Обязательные — «MQTT сервер» и «QoS».
4. Включите переключатель «Active». У новой интеграции он выключен, а выключенную интеграцию сервер не запускает.
5. Нажмите «Сохранить».

Сохранённые настройки сервер применяет сразу: перезапускает интеграцию с новой конфигурацией. Изменить настройки можно кнопкой «Edit» на карточке, удалить интеграцию — кнопкой «Удалить».

Значок на карточке показывает состояние подключения к брокеру: Connected — подключено, Disconnected — нет связи с брокером, Error — брокер отказал в подключении, например из-за неверного имени пользователя или пароля. В текущей версии Error держится недолго: после отказа брокер закрывает соединение, и значок переходит в Disconnected. Если значок показывает Disconnected, а брокер доступен, проверьте имя пользователя, пароль и права доступа на брокере, затем сохраните интеграцию заново, см. «Что важно знать».

1. MQTT — карточка интеграции MQTT в блоке «Интеграции».
2. Значок включения — зелёный, если интеграция включена переключателем «Active», серый — если выключена.
3. Значок состояния — подключение к брокеру: Connected, Disconnected или Error.
4. Edit — открыть настройки интеграции. У приложения без интеграции MQTT на этом месте кнопка «Add».
5. Удалить — удалить интеграцию.

Поля интеграции

Поле	Что задаёт
«MQTT сервер»	Адрес брокера: tcp:<хост>:<порт> — без шифрования, tls:<хост>:<порт> или ssl:<хост>:<порт> — по TLS. Например, tcp:broker.example.com:1883 или tls:broker.example.com:8883. Хост — доменное имя или IPv4-адрес
«Имя пользователя», «Пароль»	Учётные данные для брокера, если он их требует
«QoS»	Число от 0 до 2. В текущей версии не действует, см. «Что важно знать»
«ID клиента»	Идентификатор MQTT-клиента интеграции. Если поле пустое, сервер генерирует ID сам — вида ons-mqtt/<случайное число>
«Топик для отправки сообщений»	Шаблон топика, в который сервер публикует uplink. Пустое поле — application/{app_id}/device/{DevEUI}/rx
«Топик для получения сообщений»	Шаблон топика, из которого сервер принимает команды downlink. Пустое поле — application/{app_id}/device/{DevEUI}/tx
«CA сертификат», «TLS сертификат», «TLS ключ»	Файлы для TLS. В текущей версии не действуют, см. «Что важно знать»
«Active»	Включает интеграцию. У новой интеграции выключено

Значок «?» у полей топиков открывает подсказку с плейсхолдерами и примерами.

1. MQTT сервер — адрес брокера, здесь tls:mqtt.example.com:8883. Обязательное поле.
2. Имя пользователя, Пароль — учётные данные для брокера.
3. QoS — обязательное поле; в текущей версии не действует.
4. ID клиента — идентификатор MQTT-клиента интеграции. Пустое поле — сервер сгенерирует ID сам.
5. Топик для отправки сообщений — шаблон топика uplink. Здесь поле пустое: серым показан шаблон по умолчанию, под полем — «Эффективный топик» с App ID приложения.
6. Топик для получения сообщений — шаблон топика команд, в него вписан App ID. Под полем — «Топик подписки»: на него подписывается сервер.
7. CA сертификат, TLS ключ, TLS сертификат — файлы для TLS; в текущей версии не действуют.
8. Active — включает интеграцию.

Uplink: что публикует сервер

Сервер публикует в брокер каждый принятый uplink — подтверждаемый и неподтверждаемый — от устройств своего приложения и приложений из поля «Доступные приложения».

Топик собирается из шаблона «Топик для отправки сообщений» для каждого сообщения:

Плейсхолдер	Что подставляется
{app_id}	App ID приложения, которому принадлежит устройство
{DevEUI}	DevEUI устройства
{fport}	Порт приложения (FPort) кадра
{event}	up

Символы + и # в подставляемых значениях сервер заменяет на _. Шаблон без плейсхолдеров — все сообщения уходят в один топик. Под полем в форме показан итоговый топик с App ID приложения.

С шаблоном по умолчанию uplink устройства 6F1E570FFE14DBFC из приложения 77179F01 уходит в топик application/77179F01/device/6F1E570FFE14DBFC/rx. Чтобы получать uplink всех устройств приложения, подпишитесь на application/77179F01/device/+/rx.

Тело сообщения — JSON того же вида, что сообщение realtime_data WebSocket API: cmd, devEui, devAddr, data (кадр, параметры приёма, результат JS-кодека, теги), battery_level, margin, join_request_time. Поля и пример — в описании сообщения realtime_data.

Downlink: команды через брокер

Сервер подписывается на топик из шаблона «Топик для получения сообщений», где каждый плейсхолдер заменён на +. С шаблоном по умолчанию это application/+/device/+/tx; топик подписки показан под полем в форме. Команда — JSON-объект, поле cmd задаёт действие: tx — поставить кадр в очередь, cancel — отозвать.

Устройство сервер определяет по DevEUI: из поля EUI команды, а без него — из места {DevEUI} в топике. Если заданы оба и не совпадают, команда отбрасывается. Кадр можно поставить устройствам приложения интеграции и приложений из поля «Доступные приложения». Чтобы интеграция принимала команды только своего приложения, впишите App ID в шаблон топика.

Поставить кадр в очередь

Поля без пометки «обязательно» можно не передавать.

Поле	Тип	Описание
cmd	string	Обязательно. tx
port	integer	Обязательно. Порт приложения (FPort), 1–223
data	string	Обязательно одно из двух: data или object. Команда с обоими полями отбрасывается. Полезная нагрузка в hex. Размер — не больше предела частотного плана для скорости из dr, а без dr — для скорости одного из сохранённых uplink устройства: в текущей версии сервер не гарантирует, что это последний uplink, поэтому предел может не совпасть с ответом max_dl_data_req. Чтобы проверка была предсказуемой, передавайте dr
object	object	Обязательно одно из двух: data или object. Команда с обоими полями отбрасывается. Данные в виде объекта. Сервер преобразует их в hex функцией encodeDownlink JS-кодека приложения; кодек может сам выбрать порт
EUI	string	DevEUI устройства. Можно не передавать, если DevEUI есть в топике
confirmed	bool	Подтверждаемый кадр. По умолчанию false. В текущей версии не действует, см. «Что важно знать»
ttl	integer	Сколько секунд кадр может ждать в очереди, больше 0. По умолчанию 3600 (1 час). Не успевший уйти кадр получает статус 8 (Expired)
realTime	bool	Отправить только в ближайшее окно приёма, не позже чем через 2 секунды после того, как сервер принял команду; иначе кадр отбрасывается со статусом 5 (Realtime Late). ttl на такой кадр не действует. По умолчанию false
dr	string	Скорость передачи строкой, например SF7BW125. Номер DR сервер не принимает. Без поля сервер выбирает скорость сам
freq	number	Частота передачи, МГц, в пределах частотного плана устройства. Без поля сервер выбирает частоту сам
gatewayEui	string	EUI шлюза, через который передать кадр
power	integer	Мощность передачи, дБм, больше 0 и не выше максимума частотного плана. В текущей версии не действует, см. «Что важно знать»

Команда в топик application/77179F01/device/6F1E570FFE14DBFC/tx — DevEUI сервер возьмёт из топика:

{
    "cmd": "tx",
    "port": 2,
    "data": "0a1b2c"
}

Команда с DevEUI в теле, скоростью передачи и сроком ожидания в одни сутки:

{
    "cmd": "tx",
    "EUI": "6F1E570FFE14DBFC",
    "port": 2,
    "data": "0a1b2c",
    "dr": "SF7BW125",
    "ttl": 86400
}

Кадр попадает в ту же очередь, что и кадры из WebSocket API. Устройству класса A он уйдёт после его очередного uplink, устройству класса C — сразу, см. Классы устройств.

Отозвать кадр

Отзываются только кадры в статусе 0 (Scheduled) или 4 (Realtime Scheduled), поставленные за последний месяц устройствам своего приложения. Отозванный кадр получает статус 6 (Canceled).

Поле	Тип	Описание
cmd	string	Обязательно. cancel
dataId	integer	Обязательно dataId или EUI с allScheduled. Идентификатор элемента очереди — чтобы отозвать один кадр. Тот же идентификатор, что в cancel_downlink_req. Это не dataId из сообщений о статусе кадра: там идентификатор кадра, и отзыв по нему не сработает. Через MQTT сервер идентификатор элемента очереди не возвращает
EUI	string	DevEUI устройства. Чтобы отозвать все кадры устройства, передайте его в команде: DevEUI из топика для этого не подходит
allScheduled	bool	true — отозвать все запланированные кадры устройства. Команда с EUI, но без allScheduled и без dataId отклоняется

При отзыве одного кадра DevEUI тоже нужен — в топике или в поле EUI.

{
    "cmd": "cancel",
    "EUI": "6F1E570FFE14DBFC",
    "allScheduled": true
}

Статусы кадров downlink

Ответов на команды сервер не публикует. Статусы кадров по умолчанию тоже не публикуются: их включает параметр downlink_status_enabled в конфигурации интеграции. В форме веб-интерфейса этого параметра нет — включить его может администратор сервера ONS.

С включённым параметром сервер публикует сообщение при каждой смене статуса кадра, кроме постановки в очередь (0 и 4) и отзыва (6):

• Топик по умолчанию — application/{app_id}/device/{DevEUI}/tx/status, другой шаблон задаёт параметр topic_msg_down_status.
• Статусы приходят в интеграцию приложения, которому принадлежит устройство.
• Тело — поля сообщения downlink_status WebSocket API без cmd: devEui, devAddr, dataId, downlink_status, downlink_status_text, downlink_status_time, emit_ts. Коды и названия — в разделе Статус кадра. Команда через MQTT dataId не возвращает.
• Неопубликованные статусы сервер хранит 5 минут: если интеграция дольше не подключена к брокеру, они теряются.

Что важно знать

• Ответа на команду нет. Неверную команду — без port, с data не в hex, с data и object одновременно, для неизвестного устройства, с dr не из частотного плана, с данными больше предела — сервер отбрасывает и пишет причину только в свой журнал. Встал ли кадр в очередь, покажет команда WebSocket API get_downlink_data_req.
• Часть настроек пока не действует.
  • «QoS»: uplink и статусы сервер публикует с QoS 0. Брокер не подтверждает приём, и сообщение, отправленное в момент обрыва связи, может потеряться. Пропущенные uplink можно забрать командой get_data_req.
  • «CA сертификат», «TLS сертификат», «TLS ключ»: сервер хранит файлы, но при подключении к брокеру не передаёт. Брокер, который требует клиентский сертификат, через интеграцию не подключить.
  • confirmed: кадр уходит как неподтверждаемый (Unconfirmed Data Down). Итоговый статус 3 (Delivered) — подтверждение от шлюза, а не от устройства.
  • power: шлюз передаёт с мощностью по умолчанию из частотного плана.
• После обрыва связи с брокером интеграция может не восстановиться сама. Пока связи нет, uplink копятся на сервере. После обрыва сервер через несколько секунд пробует переподключиться. Если брокер к этому моменту ещё недоступен, в текущей версии интеграция сама не восстанавливается: она остаётся без связи, а uplink продолжают копиться. То же происходит, если брокер недоступен в момент запуска интеграции. Когда брокер снова доступен, откройте интеграцию кнопкой «Edit» и нажмите «Сохранить»: сервер перезапустит её и после подключения отправит накопленное. По умолчанию очередь удаляется вместе с данными, если её не читают 14 дней.
• Не повторяйте «ID клиента» интеграции. Если ваш клиент подключится к брокеру с тем же ID, брокер будет разрывать одно из соединений, и интеграция станет терять связь.
• Впишите App ID в шаблон топика команд. Чтобы интеграция принимала команды только своего приложения, впишите в «Топик для получения сообщений» App ID вместо {app_id}, например application/77179F01/device/{DevEUI}/tx.

См. также

• Приложения — страница приложения, блок «Интеграции» и поле «Доступные приложения».
• Подписаться на данные в реальном времени — поля сообщения realtime_data.
• Отправка данных на устройство — очередь кадров и их статусы.
• Классы устройств — когда кадр дойдёт до устройства.
• cancel_downlink_req — отзыв кадров и идентификатор элемента очереди.