Подключение по MQTT

Open-source версия FastBee включает встроенный MQTT Broker, разработанный на Netty, — отдельное развёртывание EMQX не требуется. В этой статье описано, как устройства подключаются к платформе по протоколу MQTT.

Процесс подключения

Создайте и опубликуйте MQTT-продукт в управлении продуктами, запишите ID продукта, номер устройства, MQTT-аккаунт и пароль
Устройство или MQTTX подключается к MQTT-сервису с согласованными clientId, userName и password
После успешного подключения сначала опубликуйте /info/post, затем /property/post или /event/post
На стороне платформы подтвердите замкнутость канала через состояние работы, журнал событий и журнал команд на странице деталей устройства

Параметры подключения

Параметр	TCP-подключение	WebSocket-подключение
Адрес	IP сервера	`ws://server-ip:8083/mqtt`
Порт	1883	8083
Протокол	MQTT 3.1.1	MQTT over WebSocket

Аутентификация устройства

提示

Типы аутентификации: S = простая аутентификация, E = шифрованная аутентификация
Если для продукта включён код авторизации устройства, код авторизации не может быть пустым
ID пользователя — это ID вошедшего пользователя; при разных ID пользователя устройства принадлежат разным пользователям
Номер устройства может быть номером, созданным платформой, или уникальным кодом, например MAC/IMEI устройства (платформа автоматически зарегистрирует устройство)

Простая аутентификация (рекомендуется для тестирования)

clientId = S&deviceNumber&productId&userId
userName = MQTT-аккаунт
password = MQTT-пароль
password = MQTT-пароль&код-авторизации-устройства (если для продукта включена авторизация устройств)

Пример:

clientId = "S&D68329VL588&2&1"
userName = "fastbee"
password = "PHYFED93WSFF1DAS"

Шифрованная аутентификация (рекомендуется для производства)

clientId = E&deviceNumber&productId&userId
userName = MQTT-аккаунт
password = AES-шифрование(MQTT-пароль&метка-времени-истечения&код-авторизации(опционально))

Пароль шифруется AES-CBC с использованием секретного ключа продукта (вектор инициализации wumei-smart-open, вывод Base64)
Метка времени истечения задаётся с точностью до миллисекунд, рекомендуется не более 24 часов

Пример:

clientId = "E&D68329VL588&2&1"
userName = "fastbee"
password = "/W2A/4MK+9cEGBhyBDgr2K5c62DAjAK4m0b5pvwxX6FFMzI3h1pUmaDY3BH1P2mI"

Описание AES-шифрования

Используется режим AES-CBC; для тестирования можно воспользоваться онлайн-инструментом шифрования:

Параметр	Значение
Режим шифрования	CBC
Заполнение	pkcs5padding
Блок данных	128 бит
Вектор инициализации	`wumei-smart-open`
Вывод	Base64
Пароль	Секретный ключ продукта
Шифруемое содержимое	`MQTT-пароль&expireTime&код-авторизации(опционально)`

Топики подписки (платформа → устройство)

Топик	Описание
`/{productId}/{deviceNum}/function/get`	Подписка на команды платформы (установка свойств, вызов функций)
`/{productId}/{deviceNum}/info/get`	Подписка на запрос информации об устройстве (после получения публикуется информация об устройстве)
`/{productId}/{deviceNum}/monitor/get`	Подписка на запрос мониторинга в реальном времени (возвращает количество и интервал)
`/{productId}/{deviceNum}/ntp/get`	Подписка на синхронизацию времени (опционально)
`/{deviceNum}/http/upgrade/set`	Подписка на OTA-обновление по HTTPS
`/{deviceNum}/fetch/upgrade/set`	Подписка на OTA-обновление бинарным пакетом

Топики публикации (устройство → платформа)

Топик	Описание
`/{productId}/{deviceNum}/property/post`	Публикация данных свойств/функций (отображаются в реальном времени и сохраняются)
`/{productId}/{deviceNum}/event/post`	Публикация событий
`/{productId}/{deviceNum}/info/post`	Публикация информации об устройстве
`/{productId}/{deviceNum}/monitor/post`	Публикация данных мониторинга в реальном времени (только графики реального времени, без сохранения)
`/{productId}/{deviceNum}/ntp/post`	Публикация синхронизации времени (опционально)
`/{deviceNum}/http/upgrade/reply`	Ответ на OTA-обновление по HTTPS
`/{deviceNum}/fetch/upgrade/reply`	Ответ на OTA-обновление бинарным пакетом

提示

{productId} — это ID продукта (не номер продукта), его можно найти в деталях продукта на платформе
{deviceNum} — номер устройства, должен точно совпадать с устройством на платформе

Формат данных

Взаимодействие устройства и платформы использует формат JSON.

Публикация свойств/функций/событий — `/property/post`, `/event/post`

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": "температура в норме"
}, {
    "id": "switch",
    "value": "1",
    "remark": "переключатель включён"
}]

id: идентификатор модели вещи, смотрите в деталях продукта, уникален в пределах продукта
value: значение передаётся строкой; для булева типа используются "0"/"1"; для перечисления — ключ значения перечисления; для массива — значения через запятую
remark: примечание, отображается в журнале устройства

Подписка на команды платформы — `/function/get`

json

[{
    "id": "gear",
    "value": "1",
    "remark": "сработала сценарная автоматизация"
}, {
    "id": "switch",
    "value": "0",
    "remark": "выключение по таймеру"
}]

Публикация информации об устройстве — `/info/post`

json

{
    "rssi": -43,
    "firmwareVersion": 1.2,
    "status": 3,
    "userId": 1,
    "longitude": 0,
    "latitude": 0,
    "summary": {
        "name": "FastBee",
        "chip": "ESP32"
    }
}

Поле	Описание
rssi	Уровень сигнала (отличный [-55~0], хороший [-70~-55], средний [-85~-70], плохой [-100~-85])
firmwareVersion	Номер версии прошивки
status	Состояние устройства, фиксировано 3 (в сети)
userId	ID пользователя
longitude/latitude	Опционально, геопозиция устройства
summary	Опционально, сводная информация об устройстве

Мониторинг в реальном времени — `/monitor/get`, `/monitor/post`

Платформа отправляет запрос мониторинга:

json

{
    "count": 60,
    "interval": 1000
}

Устройство отправляет данные с указанным количеством и интервалом:

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": ""
}]

Синхронизация времени — `/ntp/post`, `/ntp/get`

Устройство публикует:

json

{
    "deviceSendTime": "1592361428000"
}

Платформа отвечает:

json

{
    "deviceSendTime": "1592361428000",
    "serverRecvTime": "1592366463548",
    "serverSendTime": "1592366463548"
}

Текущее время устройства = (serverRecvTime + serverSendTime + deviceRecvTime - deviceSendTime) / 2

Правила идентификаторов модели вещи

Все идентификаторы уникальны в пределах продукта; используйте преимущественно буквы и цифры, избегайте специальных символов
Формат ID подмодели объектного типа: parentId_childId
Идентификаторы типа массив начинаются с array_индекс (индекс — две цифры, например array_00_power_switch), длина массива не более 100

Настройка сети устройства через AP (опционально, только для WiFi-устройств)

Устройство поднимает точку доступа (адрес 192.168.4.1), мобильное приложение передаёт конфигурацию через Web-сервис устройства.

Обнаружение устройства

GET http://192.168.4.1/api/wifi/status

HTTP 200 означает, что устройство обнаружено; ответ содержит информацию об устройстве и текущее состояние сети.

Интерфейс конфигурации

POST http://192.168.4.1/api/wifi/config?SSID=имя-WiFi&password=пароль-WiFi&userId=ID-пользователя

Параметр	Описание
SSID	Имя WiFi (обязательный, совместим со строчным ssid)
password	Пароль WiFi (обязательный, совместим с псевдонимом pwd)
userId	ID пользователя (обязательный)
deviceNum	Номер устройства (опционально)
extra	Номер продукта (опционально)

HTTP 200 означает успешную настройку сети (устройство затем автоматически переключается в режим STA), 400 — отсутствуют обязательные параметры, 500 — ошибка сохранения. Подробное описание интерфейса см. в документе «Настройка сети · AP-провижионинг API для телефона/мобильного приложения».

Тестирование с MQTTX

Скачайте клиент MQTTX
Создайте подключение:
- Host: mqtt://server-ip, Port: 1883
- Client ID: S&deviceNumber&productId&1
- Username: MQTT-аккаунт
- Password: MQTT-пароль
Подпишитесь на /{productId}/{deviceNum}/function/get
Опубликуйте информацию об устройстве в /{productId}/{deviceNum}/info/post
Опубликуйте данные свойств в /{productId}/{deviceNum}/property/post
Наблюдайте онлайн-статус устройства и рабочие данные в консоли платформы

Контрольный список приёмки интеграции

Шаг	Проверяемое содержимое	Признак успеха
1	Продукт опубликован	Статус продукта — «Опубликован»
2	Подключение MQTTX	В деталях устройства отображается «В сети»
3	`/info/post`	Обновились поля информации об устройстве, сигнала, версии
4	`/property/post`	В состоянии работы отображаются значения свойств модели вещи
5	`/event/post`	В журнале событий появляются отправленные события
6	`/function/get`	Устройство получает команду после отправки платформой
7	Возврат результата	Устройство возвращает результат выполнения, состояние на платформе обновляется
8	Правила/сценарии	Связанные правила, сценарии и оповещения срабатывают

Типичные ошибки

Соединение отклонено

Открыт ли порт 1883 на сервере
Запущен ли встроенный MQTT Broker
Верен ли формат clientId (S&deviceNumber&productId&userId)
Включён ли для продукта код авторизации устройства
Не заблокировано ли устройство

Устройство в сети, но свойства не обновляются

Является ли топик публикации /{productId}/{deviceNum}/property/post
Используется ли в productId ID продукта (а не номер продукта)
Совпадает ли deviceNum точно с номером устройства
Является ли тело сообщения JSON-массивом
Совпадает ли id точно с идентификатором модели вещи
Соответствует ли value типу данных

Платформа отправляет команду, но устройство её не получает

Подписано ли устройство на /{productId}/{deviceNum}/function/get
Находится ли устройство ещё в сети
Является ли элемент модели вещи записываемой функцией или свойством, допускающим отправку
Есть ли у пользователя права на просмотр деталей устройства и отправку команд

Правило или оповещение не срабатывает

Попадают ли данные устройства в состояние работы платформы
Верны ли продукт, устройство и переменные, привязанные к сценарию или правилу
Совпадает ли тип выражения условия с типом отправляемого значения
Включена ли конфигурация оповещений

Преобразование скриптами правил

Если устройство использует собственный формат данных, можно написать логику преобразования в скриптах правил, чтобы привести исходные данные к стандартному формату платформы. Подробнее см. Скрипты правил (на кит.).

Подключение по MQTT ​

Процесс подключения ​

Параметры подключения ​

Аутентификация устройства ​

Простая аутентификация (рекомендуется для тестирования) ​

Шифрованная аутентификация (рекомендуется для производства) ​

Описание AES-шифрования ​

Топики подписки (платформа → устройство) ​

Топики публикации (устройство → платформа) ​

Формат данных ​

Публикация свойств/функций/событий — /property/post, /event/post ​

Подписка на команды платформы — /function/get ​

Публикация информации об устройстве — /info/post ​

Мониторинг в реальном времени — /monitor/get, /monitor/post ​

Синхронизация времени — /ntp/post, /ntp/get ​

Правила идентификаторов модели вещи ​

Настройка сети устройства через AP (опционально, только для WiFi-устройств) ​

Обнаружение устройства ​

Интерфейс конфигурации ​

Тестирование с MQTTX ​

Контрольный список приёмки интеграции ​

Типичные ошибки ​

Соединение отклонено ​

Устройство в сети, но свойства не обновляются ​

Платформа отправляет команду, но устройство её не получает ​

Правило или оповещение не срабатывает ​

Преобразование скриптами правил ​

Связанные документы ​

Подключение по MQTT

Процесс подключения

Параметры подключения

Аутентификация устройства

Простая аутентификация (рекомендуется для тестирования)

Шифрованная аутентификация (рекомендуется для производства)

Описание AES-шифрования

Топики подписки (платформа → устройство)

Топики публикации (устройство → платформа)

Формат данных

Публикация свойств/функций/событий — `/property/post`, `/event/post`

Подписка на команды платформы — `/function/get`

Публикация информации об устройстве — `/info/post`

Мониторинг в реальном времени — `/monitor/get`, `/monitor/post`

Синхронизация времени — `/ntp/post`, `/ntp/get`

Правила идентификаторов модели вещи

Настройка сети устройства через AP (опционально, только для WiFi-устройств)

Обнаружение устройства

Интерфейс конфигурации

Тестирование с MQTTX

Контрольный список приёмки интеграции

Типичные ошибки

Соединение отклонено

Устройство в сети, но свойства не обновляются

Платформа отправляет команду, но устройство её не получает

Правило или оповещение не срабатывает

Преобразование скриптами правил

Связанные документы