Integración MQTT

La edición open source de FastBee incorpora un MQTT Broker desarrollado con Netty, por lo que no es necesario desplegar EMQX. Este documento explica cómo se integran los dispositivos en la plataforma mediante el protocolo MQTT.

Proceso de integración

Cree y publique un producto MQTT en la gestión de productos, y confirme el ID de producto, el número de dispositivo, la cuenta MQTT y la contraseña
El dispositivo o MQTTX se conecta al servicio MQTT con los valores acordados de clientId, userName y password
Tras conectarse correctamente, publique primero /info/post y después /property/post o /event/post
En el lado de la plataforma, confirme el cierre del ciclo mediante el estado de funcionamiento, el registro de eventos y el registro de comandos de los detalles del dispositivo

Información de conexión

Parámetro	Conexión TCP	Conexión WebSocket
Dirección	IP del servidor	`ws://IP-del-servidor:8083/mqtt`
Puerto	1883	8083
Protocolo	MQTT 3.1.1	MQTT over WebSocket

Autenticación de dispositivos

提示

Tipos de autenticación: S = autenticación simple, E = autenticación cifrada
Si el producto tiene habilitado el código de autorización de dispositivos, este no puede estar vacío
El ID de usuario es el ID del usuario que inicia sesión; con ID de usuario distintos, los dispositivos pertenecen a usuarios distintos
El número de dispositivo puede ser el generado por la plataforma o un código único como la MAC/IMEI del dispositivo (la plataforma registra el dispositivo automáticamente)

Autenticación simple (recomendada para pruebas)

clientId = S&deviceNumber&productId&userId
userName = CuentaMQTT
password = ContraseñaMQTT
password = ContraseñaMQTT&códigoDeAutorizaciónDelDispositivo(cuando el producto habilita la autorización de dispositivos)

Ejemplo:

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

Autenticación cifrada (recomendada para producción)

clientId = E&deviceNumber&productId&userId
userName = CuentaMQTT
password = CifradoAES(ContraseñaMQTT&marcaDeTiempoDeCaducidad&códigoDeAutorización(opcional))

La contraseña se cifra con AES-CBC usando la clave del producto (offset wumei-smart-open, salida en Base64)
La marca de tiempo de caducidad tiene precisión de milisegundos; se recomienda un plazo inferior a 24 horas

Ejemplo:

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

Explicación del cifrado AES

Se utiliza el modo de cifrado AES-CBC; para las pruebas puede usar la herramienta de cifrado y descifrado en línea:

Parámetro	Valor
Modo de cifrado	CBC
Relleno	pkcs5padding
Bloque de datos	128 bits
Offset	`wumei-smart-open`
Salida	Base64
Contraseña	Clave del producto
Contenido a cifrar	`ContraseñaMQTT&expireTime&códigoDeAutorización(opcional)`

Topics de suscripción (plataforma → dispositivo)

Topic	Descripción
`/{productId}/{deviceNum}/function/get`	Suscripción a los comandos de la plataforma (configuración de propiedades, llamadas a funciones)
`/{productId}/{deviceNum}/info/get`	Suscripción a solicitudes de información del dispositivo (al recibirla, se publica la información del dispositivo)
`/{productId}/{deviceNum}/monitor/get`	Suscripción a solicitudes de monitorización en tiempo real (devuelve el número de veces y el intervalo)
`/{productId}/{deviceNum}/ntp/get`	Suscripción a la sincronización de reloj (opcional)
`/{deviceNum}/http/upgrade/set`	Suscripción a actualizaciones OTA mediante HTTPS
`/{deviceNum}/fetch/upgrade/set`	Suscripción a actualizaciones OTA mediante paquete binario

Topics de publicación (dispositivo → plataforma)

Topic	Descripción
`/{productId}/{deviceNum}/property/post`	Publicación de datos de propiedades/funciones (se muestran en tiempo real y se almacenan)
`/{productId}/{deviceNum}/event/post`	Publicación de eventos
`/{productId}/{deviceNum}/info/post`	Publicación de información del dispositivo
`/{productId}/{deviceNum}/monitor/post`	Publicación de datos de monitorización en tiempo real (solo gráficos en tiempo real, no se almacenan)
`/{productId}/{deviceNum}/ntp/post`	Publicación de sincronización de reloj (opcional)
`/{deviceNum}/http/upgrade/reply`	Respuesta a actualizaciones OTA mediante HTTPS
`/{deviceNum}/fetch/upgrade/reply`	Respuesta a actualizaciones OTA mediante paquete binario

提示

{productId} es el ID de producto (no el número de producto), que se obtiene en los detalles del producto en la plataforma
{deviceNum} es el número de dispositivo y debe coincidir exactamente con el dispositivo de la plataforma

Formato de datos

El dispositivo y la plataforma intercambian datos en formato JSON.

Publicar propiedades/funciones/eventos — `/property/post`, `/event/post`

json

[{
    "id": "temperature",
    "value": "27.43",
    "remark": "Temperatura normal"
}, {
    "id": "switch",
    "value": "1",
    "remark": "Interruptor encendido"
}]

id: identificador del Thing Model, visible en los detalles del producto y único dentro del producto
value: el valor se transmite como cadena; el tipo booleano usa "0"/"1"; el tipo enumerado corresponde al valor de la clave de la enumeración; el tipo array se separa con comas
remark: información de observaciones, visible en el registro del dispositivo

Suscribirse a comandos de la plataforma — `/function/get`

json

[{
    "id": "gear",
    "value": "1",
    "remark": "Activado por Scene Linkage"
}, {
    "id": "switch",
    "value": "0",
    "remark": "Apagado programado"
}]

Publicar información del dispositivo — `/info/post`

json

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

Campo	Descripción
rssi	Intensidad de la señal (excelente [-55~0], buena [-70~-55], normal [-85~-70], mala [-100~-85])
firmwareVersion	Número de versión del firmware
status	Estado del dispositivo, fijo en 3 (en línea)
userId	ID de usuario
longitude/latitude	Opcional, ubicación del dispositivo
summary	Opcional, información resumida del dispositivo

Monitorización en tiempo real — `/monitor/get`, `/monitor/post`

La plataforma envía la solicitud de monitorización:

json

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

El dispositivo reporta los datos según el número de veces y el intervalo indicados:

json

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

Sincronización de reloj — `/ntp/post`, `/ntp/get`

El dispositivo publica:

json

{
    "deviceSendTime": "1592361428000"
}

La plataforma responde:

json

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

Hora actual del dispositivo = (serverRecvTime + serverSendTime + deviceRecvTime - deviceSendTime) / 2

Reglas para los identificadores del Thing Model

Todos los identificadores son únicos dentro del producto; utilice principalmente letras y números y evite caracteres especiales
El formato del ID de submodelo de tipo objeto es: parentId_childId
Los identificadores de tipo array comienzan por array_índice (el índice tiene dos dígitos, por ejemplo array_00_power_switch), y la longitud del array no puede superar 100

Aprovisionamiento de red AP del dispositivo (opcional, solo dispositivos WiFi)

El dispositivo habilita un punto de acceso (dirección 192.168.4.1) y el terminal móvil transmite la información de configuración a través del servicio web del dispositivo.

Detectar el dispositivo

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

Un HTTP 200 indica que el dispositivo se ha detectado; la respuesta contiene la información del dispositivo y el estado actual de la red.

Interfaz de configuración

POST http://192.168.4.1/api/wifi/config?SSID=NombreWiFi&password=ContraseñaWiFi&userId=userId

Parámetro	Descripción
SSID	Nombre del WiFi (obligatorio, compatible con ssid en minúsculas)
password	Contraseña del WiFi (obligatorio, compatible con el alias pwd)
userId	ID de usuario (obligatorio)
deviceNum	Número de dispositivo (opcional)
extra	Número de producto (opcional)

Un HTTP 200 indica que el aprovisionamiento se ha realizado correctamente (el dispositivo cambia después automáticamente al modo STA), 400 indica que falta un parámetro obligatorio y 500 indica un error al guardar. La descripción detallada de la interfaz está en «Configuración de red · API de aprovisionamiento AP para teléfono/terminal móvil» (简体中文).

Pruebas con MQTTX

Descargue el cliente MQTTX
Cree una nueva conexión:
- Host: mqtt://IP-del-servidor, Port: 1883
- Client ID: S&deviceNumber&productId&1
- Username: Cuenta MQTT
- Password: Contraseña MQTT
Suscríbase a /{productId}/{deviceNum}/function/get
Publique la información del dispositivo en /{productId}/{deviceNum}/info/post
Publique datos de propiedades en /{productId}/{deviceNum}/property/post
Observe el estado en línea del dispositivo y los datos de funcionamiento en la consola de la plataforma

Lista de verificación de la integración

Paso	Contenido de la verificación	Indicación de éxito
1	Producto publicado	El estado del producto es «publicado»
2	Conexión de MQTTX	Los detalles del dispositivo muestran «en línea»
3	`/info/post`	Se actualizan los campos de información del dispositivo, señal y versión
4	`/property/post`	El estado de funcionamiento muestra los valores de las propiedades del Thing Model
5	`/event/post`	El registro de eventos muestra los eventos reportados
6	`/function/get`	El dispositivo recibe el comando tras el envío desde la plataforma
7	Devolución del resultado	El dispositivo devuelve el resultado del envío y la plataforma actualiza el estado
8	Reglas/escenas	Se activan las reglas, escenas y alarmas correspondientes

Errores frecuentes

Conexión rechazada

Compruebe si el puerto 1883 del servidor está abierto
Compruebe si el MQTT Broker integrado está iniciado
Compruebe si el formato de clientId es correcto (S&deviceNumber&productId&userId)
Compruebe si el producto tiene habilitado el código de autorización de dispositivos
Compruebe si el dispositivo está deshabilitado

El dispositivo está en línea pero las propiedades no se actualizan

Compruebe si el topic de publicación es /{productId}/{deviceNum}/property/post
Compruebe si productId utiliza el ID de producto (no el número de producto)
Compruebe si deviceNum coincide exactamente con el número de dispositivo
Compruebe si el cuerpo del mensaje está en formato de array JSON
Compruebe si id coincide exactamente con el identificador del Thing Model
Compruebe si value se ajusta al tipo de dato

El dispositivo no recibe los envíos de la plataforma

Compruebe si el dispositivo está suscrito a /{productId}/{deviceNum}/function/get
Compruebe si el dispositivo sigue en línea
Compruebe si el Thing Model es una función escribible o una propiedad que admite envío
Compruebe si el usuario tiene permisos de detalles del dispositivo y de envío de comandos

Las reglas o alarmas no se activan

Compruebe si los datos del dispositivo llegan al estado de funcionamiento de la plataforma
Compruebe si el producto, el dispositivo y las variables vinculados a la escena o la regla son correctos
Compruebe si la expresión de condición coincide con el tipo del valor reportado
Compruebe si la configuración de alarmas está habilitada

Conversión con scripts de reglas

Si el dispositivo utiliza un formato de datos personalizado, puede escribir la lógica de conversión en los scripts de reglas para transformar los datos originales al formato estándar de la plataforma. Más detalles en Scripts de reglas (简体中文).

Integración MQTT ​

Proceso de integración ​

Información de conexión ​

Autenticación de dispositivos ​

Autenticación simple (recomendada para pruebas) ​

Autenticación cifrada (recomendada para producción) ​

Explicación del cifrado AES ​

Topics de suscripción (plataforma → dispositivo) ​

Topics de publicación (dispositivo → plataforma) ​

Formato de datos ​

Publicar propiedades/funciones/eventos — /property/post, /event/post ​

Suscribirse a comandos de la plataforma — /function/get ​

Publicar información del dispositivo — /info/post ​

Monitorización en tiempo real — /monitor/get, /monitor/post ​

Sincronización de reloj — /ntp/post, /ntp/get ​

Reglas para los identificadores del Thing Model ​

Aprovisionamiento de red AP del dispositivo (opcional, solo dispositivos WiFi) ​

Detectar el dispositivo ​

Interfaz de configuración ​

Pruebas con MQTTX ​

Lista de verificación de la integración ​

Errores frecuentes ​

Conexión rechazada ​

El dispositivo está en línea pero las propiedades no se actualizan ​

El dispositivo no recibe los envíos de la plataforma ​

Las reglas o alarmas no se activan ​

Conversión con scripts de reglas ​

Documentación relacionada ​

Integración MQTT

Proceso de integración

Información de conexión

Autenticación de dispositivos

Autenticación simple (recomendada para pruebas)

Autenticación cifrada (recomendada para producción)

Explicación del cifrado AES

Topics de suscripción (plataforma → dispositivo)

Topics de publicación (dispositivo → plataforma)

Formato de datos

Publicar propiedades/funciones/eventos — `/property/post`, `/event/post`

Suscribirse a comandos de la plataforma — `/function/get`

Publicar información del dispositivo — `/info/post`

Monitorización en tiempo real — `/monitor/get`, `/monitor/post`

Sincronización de reloj — `/ntp/post`, `/ntp/get`

Reglas para los identificadores del Thing Model

Aprovisionamiento de red AP del dispositivo (opcional, solo dispositivos WiFi)

Detectar el dispositivo

Interfaz de configuración

Pruebas con MQTTX

Lista de verificación de la integración

Errores frecuentes

Conexión rechazada

El dispositivo está en línea pero las propiedades no se actualizan

El dispositivo no recibe los envíos de la plataforma

Las reglas o alarmas no se activan

Conversión con scripts de reglas

Documentación relacionada