Integración de dispositivos con el protocolo Mqtt

Guía de la página
Entrada de integración y flujo mínimo
- 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, la contraseña y el código de autorización del dispositivo.
- El dispositivo o MQTTX se conecta al servicio MQTT con los valores acordados de
clientId,userNameypassword. - Tras conectarse correctamente, publique primero
/info/posty después/property/posto/event/post. - En el lado de la plataforma, confirme el cierre del ciclo mediante el estado de funcionamiento, el registro de eventos, el registro de comandos y las escenas de reglas de los detalles del dispositivo.
1. Pasos de integración
提示
- Código fuente del SDK de hardware ESP8266 de referencia: FastBee Arduino SDK
- Si el formato de los mensajes Mqtt del dispositivo es fijo, puede reenviarlos mediante el Rule Engine para adaptarlos a la plataforma
- netty-mqtt incluido en el sistema: admite el reenvío de topics y de contenido
- Uso del middleware emqx: admite el reenvío de contenido, y los topics pueden reenviarse mediante el Rule Engine que incorpora emqx
1. Autenticación del dispositivo
- Autenticación cifrada (recomendada)
- Autenticación simple
2. Interacción del dispositivo
- Publicación de topics Mqtt relacionados con el Thing Model, la información del dispositivo y la sincronización de reloj
- Suscripción a topics Mqtt relacionados con el Thing Model, la actualización del dispositivo y la sincronización de reloj
3. Aprovisionamiento de red AP del dispositivo (opcional, solo dispositivos WiFi)
- Interfaz de detección del dispositivo
- Interfaz de configuración del dispositivo
2. Autenticación del dispositivo
提示
- 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. Puede usar de forma unificada la cuenta admin con ID 1 y luego asignar los dispositivos a los distintos usuarios mediante el aprovisionamiento de red o la vinculación por código QR.
- Hay dos formas de obtener el número de dispositivo: 1. utilizar el número de dispositivo generado al crear el dispositivo en el sistema; 2. sin crear el dispositivo en el sistema, generar un código único en el lado del hardware como número de dispositivo y, tras la autenticación, el sistema registrará automáticamente una entidad de dispositivo (cuando hay muchos dispositivos, se recomienda este método)
1. Autenticación cifrada
Obtenga el número de producto, la cuenta Mqtt, la contraseña Mqtt y la clave del producto en los detalles del producto; la contraseña se cifra con la clave del producto mediante AES y se transmite al backend, que la descifra con la clave del producto para realizar la autenticación. Para conectarse al servidor de mensajes Mqtt es necesario proporcionar un ID de cliente, un nombre de usuario y una contraseña únicos, con el formato siguiente:
# El ID de cliente es igual a tipo de autenticación + número de dispositivo + número de producto + ID de usuario
clientId = E & deviceNumber & productId & userId
# Nombre de usuario
userName = fastbee
# Contraseña
password = contraseña mqtt & tiempo de caducidad
password = contraseña mqtt & tiempo de caducidad & código de autorización del dispositivo (formato cuando el producto habilita la autorización de dispositivos)- El ID de cliente es igual a tipo de autenticación + número de dispositivo + número de producto + ID de usuario, unidos con el símbolo
&sin espacios intermedios; - El nombre de usuario es directamente la cuenta Mqtt
- La contraseña es igual a contraseña Mqtt + tiempo de caducidad de la contraseña + código de autorización del dispositivo (opcional), cifrada después con AES. Por seguridad, el tiempo de caducidad de la contraseña debe ser inferior a 24 horas y adoptar el formato de marca de tiempo con precisión de milisegundos.
Ejemplo de información de configuración de la cuenta:
clientId = "E&D68329VL588&2&1"
userName = "fastbee"
password = "/W2A/4MK+9cEGBhyBDgr2K5c62DAjAK4m0b5pvwxX6FFMzI3h1pUmaDY3BH1P2mI"2. Autenticación simple
Obtenga la cuenta Mqtt y la contraseña Mqtt en los detalles del producto; se recomienda usarla en entornos de pruebas. El formato del ID de cliente Mqtt es similar al de la autenticación cifrada, cambiando la E por S.
# El ID de cliente es igual a tipo de autenticación + número de dispositivo + número de producto + ID de usuario
clientId = S & deviceNumber & productId & userId
# Nombre de usuario
userName = fastbee
# Contraseña
password = contraseña mqtt
password = contraseña mqtt & código de autorización del dispositivo (formato cuando el producto habilita la autorización de dispositivos)Ejemplo de información de configuración de la cuenta:
# El ID de cliente es igual a tipo de autenticación + número de dispositivo + número de producto + ID de usuario
clientId = "S&D68329VL588&2&1"
userName = "fastbee"
password = "PHYFED93WSFF1DAS"
password = "PHYFED93WSFF1DAS&ADBFCC8934864B26B55658C66F562AC5" (formato cuando el producto habilita la autorización de dispositivos)3. Obtención de la hora actual por el dispositivo
Para obtener la hora actual, puede llamar a la interfaz de tiempo NTP del sistema: al realizar la solicitud se envía el número de milisegundos de funcionamiento actual del dispositivo y se devuelven la hora de envío del dispositivo, la hora de recepción del servidor y la hora de envío del servidor. A continuación se obtiene de nuevo el número de milisegundos de funcionamiento actual del dispositivo como hora de recepción del dispositivo. Por último, se calcula la hora actual del dispositivo con la fórmula; la hora debe estar en milisegundos. Herramienta de marcas de tiempo en línea
# El valor de deviceSendTime es el número de milisegundos de funcionamiento actual del dispositivo
http://localhost:8080/iot/tool/ntp?deviceSendTime=35768
# Cálculo de la hora
Hora actual del dispositivo = (hora de recepción del servidor + hora de envío del servidor + hora de recepción del dispositivo - hora de envío del dispositivo) / 24. Explicación del cifrado AES
Se utiliza el modo de cifrado CBC de AES, con un offset fijo de wumei-smart-open de 16 caracteres, salida en Base64, y la contraseña utilizada para el cifrado es la clave del producto. Para las pruebas puede utilizar: herramienta de cifrado y descifrado en línea
Modo de cifrado: CBC
Relleno: pkcs5padding
Bloque de datos: 128 bits
Offset: wumei-smart-open
Salida: base64
Contraseña: la clave del producto correspondiente del sistema
Contenido a cifrar: contraseña mqtt & expireTime & código de autorización (opcional)3. Interacción del dispositivo
{productId} representa el ID de producto y {deviceNum} representa el número de dispositivo. Obtenga el ID de producto y el número de dispositivo desde el lado web; si utiliza la adición automática de dispositivos, el número de dispositivo puede ser un código único o la dirección MAC del dispositivo, y una vez superada la autenticación se añadirá automáticamente en el backend la entidad de dispositivo correspondiente.
1. Topics de suscripción
| Topic | Descripción |
|---|---|
| /{productId}/{deviceNum}/function/get | Suscripción a los comandos de la plataforma |
| /{productId}/{deviceNum}/info/get | Suscripción a la información del dispositivo (al suscribirse a este topic se publica la información del dispositivo) |
| /{productId}/{deviceNum}/monitor/get | Suscripción a la señal de monitorización en tiempo real (según el número de monitorizaciones y el intervalo, se publican después los datos de monitorización) |
| /{productId}/{deviceNum}/ntp/get | Suscripción a la sincronización de reloj (opcional, para sincronizar la hora actual del dispositivo) |
| /{deviceNum}/http/upgrade/set | Suscripción a la actualización OTA mediante HTTPS (nueva) |
| /{deviceNum}/fetch/upgrade/set | Suscripción a la actualización OTA mediante paquete binario (nueva) |
| /{productId}/{deviceNum}/ota/get | Suscripción a la actualización del dispositivo (antigua) |
| /{productId}/{deviceNum}/property/get | obsoleto en 2.x Suscripción a propiedades (publicadas por el servidor, suscritas por el dispositivo) |
| /{productId}/{deviceNum}/property-online/get | obsoleto en 2.x Suscripción a propiedades (modo en línea, publicadas por el lado del usuario, suscritas por el dispositivo) |
| /{productId}/{deviceNum}/function-online/get | obsoleto en 2.x Suscripción a funciones (modo en línea, publicadas por el lado del usuario, suscritas por el dispositivo) |
2. Topics de publicación
| Topic | Descripción |
|---|---|
| /{productId}/{deviceNum}/property/post | Publicación de datos (visualización en tiempo real, datos de propiedades/funciones y de monitorización; admite el reporte programado de datos de monitorización) |
| /{productId}/{deviceNum}/info/post | Publicación de información del dispositivo |
| /{productId}/{deviceNum}/event/post | Publicación de eventos |
| /{productId}/{deviceNum}/monitor/post | Publicación de datos de monitorización en tiempo real (solo para la visualización de 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 la actualización OTA mediante HTTPS (nueva) |
| /{deviceNum}/fetch/upgrade/reply | Respuesta a la actualización OTA mediante paquete binario (nueva) |
| /{productId}/{deviceNum}/upgrade/reply | Respuesta a la actualización OTA (antigua) |
| /{productId}/{deviceNum}/function/post | obsoleto en 2.x Publicación de funciones (visualización en tiempo real) |
3. Formato de datos
El dispositivo y el sistema intercambian datos en formato JSON
- Suscripción a la información del dispositivo, topic correspondiente:
/info/get
# Descripción: al recibir la suscripción de información del dispositivo, se publica la información del dispositivo para resolver el problema de sincronización del estado del dispositivo
# El contenido del mensaje del dispositivo está vacío- Publicación de la información del dispositivo, topic correspondiente:
/info/post
# Descripción: 1. el dispositivo publica su información tras el encendido; 2. el dispositivo publica su información tras recibir el comando de información del dispositivo
# rssi señal del dispositivo (señal excelente[-55— 0], señal buena[-70— -55], señal normal[-85— -70], señal mala[-100— -85])
# status estado del dispositivo, fijo en 3, indica en línea
# firmwareVersion versión del firmware
# userId ID del usuario; puede establecerse el ID de usuario 1 (administrador), y durante el aprovisionamiento el dispositivo se asignará al usuario concreto.
# longitude opcional, longitud; debe cargarse cuando se utiliza la localización del dispositivo
# latitude opcional, latitud; debe cargarse cuando se utiliza la localización del dispositivo
# iccid opcional, número ICCID de la tarjeta SIM IoT; se carga cuando el dispositivo utiliza una tarjeta SIM IoT
# cardPlatformId opcional, corresponde al número de plataforma de tarjetas en la gestión de tarjetas SIM IoT; se carga cuando el dispositivo carga el número ICCID; si no se carga, por defecto se recorren todas las plataformas de tarjetas para consultar
# summary opcional, resumen con la información de configuración del dispositivo, etc., en formato json; el objeto puede personalizarse
{
"rssi": -43,
"firmwareVersion": 1.2,
"status": 3,
"userId": 2,
"longitude": 0,
"latitude": 0,
"iccid": 898604293620C0000970,
"cardPlatformId": 0,
"summary": {
"name": "FastBee",
"chip": "ESP8266",
"author": "fastbee",
"deliveryTime": "2023-06-06",
"activeTime": "2022-10-01"
}
}- Suscripción a la monitorización en tiempo real, topic correspondiente:
/monitor/get
# Descripción: al suscribirse al mensaje de monitorización en tiempo real, se publican los datos de monitorización en tiempo real según la cantidad y el intervalo
# count cantidad
# interval intervalo, en milisegundos
{
"count": 60,
"interval": 1000
}- Publicación de la monitorización en tiempo real, topic correspondiente:
/monitor/post
# Descripción: según el mensaje de monitorización en tiempo real suscrito, se publican los datos de monitorización con la cantidad y el intervalo indicados
# id identificador; en la monitorización en tiempo real corresponde a una propiedad del Thing Model; consulte el identificador en los detalles del producto, que corresponde al valor de id
# value valor recogido por el dispositivo; solo puede ser un entero o un decimal y se transmite como tipo cadena
# remark puede estar vacío o usar la hora actual del dispositivo
[{
"id": "temperature",
"value": "27.43",
"remark": ""
}, {
"id": "humidity",
"value": "32.18",
"remark": ""
}]- Suscripción a los comandos de la plataforma, topic correspondiente:
/function/get
# Descripción: las propiedades, las funciones y los eventos pertenecen al Thing Model y su definición Json es la misma. Por ejemplo, si todos reciben el mensaje de encender el interruptor, el procesamiento del dispositivo es encender el interruptor.
# id identificador; consulte el Thing Model en los detalles del producto, corresponde al identificador del Thing Model
# value valor, correspondiente a lo definido en el Thing Model, transmitido como tipo cadena
# remark los comandos enviados por alarmas, Scene Linkage y temporizadores de la plataforma incluyen información de observaciones
[{
"id": "gear",
"value": "1",
"remark": "Temporización del dispositivo"
},{
"id": "switch",
"value": "0",
"remark": "Activado por Scene Linkage"
}]- Publicación de datos y eventos, topics correspondientes:
/property/post,/event/post
# Descripción: las propiedades, las funciones y los eventos pertenecen al Thing Model y su definición Json es la misma. Si el valor de `value` es de tipo booleano, el valor es "0" o "1" y representa encendido/apagado; el tipo enumerado corresponde al valor de la clave del elemento de la enumeración (por ejemplo "1" representa la velocidad media); el tipo array es una cadena separada por comas inglesas.
# id identificador; consulte el Thing Model en los detalles del producto, corresponde al identificador del Thing Model
# value valor, correspondiente a lo definido en el Thing Model, transmitido como tipo cadena
# remark puede usar directamente la información de observaciones suscrita, que puede consultarse en la información de logs del dispositivo
[{
"id": "gear",
"value": "1",
"remark": "Velocidad configurada correctamente"
}, {
"id": "switch",
"value": "0",
"remark": "Interruptor apagado"
}]Descripción del Thing Model relacionado
- Los Id (identificadores) de todos los Thing Models son únicos; evite en lo posible los caracteres especiales y utilice principalmente letras y números.
- El formato del Id (identificador) de un submodelo bajo un Thing Model de tipo objeto es: parentId_childId; en el tipo array de objetos ocurre igual, el Id del submodelo añade el Id del nivel superior separado por un guion bajo, por ejemplo:
# Id del Thing Model de nivel superior: power
# Id del Thing Model de nivel inferior: power_light- Un Thing Model de tipo array (incluido el tipo array de objetos) tiene un solo Id (identificador), y su valor es un array (almacenado como una cadena separada por comas inglesas), por ejemplo la cadena
98,100,50. Por tanto, el reporte de propiedades/funciones/eventos de tipo array es relativamente especial: el Id (identificador) debe comenzar porarray_índice, donde el índice tiene dos dígitos, por ejemplo:shell# Formato de array normal `array_00_RGB` # Formato de array de objetos `array_00_power_switch` # El índice 00 representa el primer elemento del array; 02 / 03 ... 98 / 99 y así sucesivamente; la longitud del array no puede superar 100 [{ "id": "array_01_power_switch", // array_01 como prefijo indica el segundo elemento del array "value": "1", "remark": "" }]
- Publicación de la sincronización de reloj, topic correspondiente:
/ntp/post
# Descripción: opcional; se publica el mensaje de sincronización de reloj y, tras suscribirse a él, el servidor envía el mensaje de sincronización de reloj
# deviceSendTime hora de envío del dispositivo
{
"deviceSendTime": "1592361428000"
}- Suscripción a la sincronización de reloj, topic correspondiente:
/ntp/get
# Descripción: opcional; al suscribirse al mensaje de sincronización de reloj, se calcula la hora actual = (hora de recepción del servidor + hora de envío del servidor + hora de recepción del dispositivo - hora de envío del dispositivo) / 2
# deviceSendTime hora de envío del dispositivo
# serverRecvTime hora de recepción del servidor
# serverSendTime hora de envío del servidor
{
"deviceSendTime": "1592361428000",
"serverSendTime": "1592366463548",
"serverRecvTime": "1592366463548"
}- Suscripción a la actualización OTA, topics correspondientes:
/http/upgrade/seto/fetch/upgrade/set
# Descripción: al suscribirse al mensaje de actualización del dispositivo, se descarga el firmware mediante una solicitud Http según la dirección de descarga del firmware y se realiza la actualización
# version número de versión, puede utilizarse para hacer coincidir la versión del firmware
# downloadUrl dirección de descarga del firmware
{
"taskId": 26,
"url": "/profile/iot/1/2024-0824-001954.bin",
"version": 1.2,
"status": 1
}4. Aprovisionamiento de red del dispositivo (opcional, solo dispositivos WiFi)
提示
- El dispositivo utiliza aprovisionamiento AP: durante el aprovisionamiento, el dispositivo habilita un punto de acceso y ofrece un servicio web. El terminal móvil transmite la información de configuración a través del servicio web proporcionado por el dispositivo.
- La dirección del punto de acceso del dispositivo se establece en: 192.168.4.1
- Puede consultar el SDK del proyecto
1. Interfaz de detección del dispositivo
El lado del dispositivo ofrece una interfaz de detección, y el terminal móvil implementa la función de descubrimiento de dispositivos a través de ella, adecuada para el aprovisionamiento de un solo dispositivo.
# Método de solicitud: Get
# Dirección de la interfaz: http://192.168.4.1/status
# Parámetros: ninguno
# Información devuelta: el código de estado HTTP 200 indica que el dispositivo se ha detectado2. Interfaz de configuración
El lado del dispositivo ofrece una interfaz de configuración para obtener información; el terminal móvil envía la información de configuración y los parámetros se transmiten mediante la Url, donde SSID, password y userId son parámetros obligatorios.
# Método de solicitud: Post
# Dirección de la interfaz: http://192.168.4.1/config
# Parámetros:
SSID # Nombre del Wifi
password # Contraseña del Wifi
userId # Número/ID de usuario
deviceNum # Opcional, número de dispositivo
authCode # Opcional, código de autorización
extra # Opcional, información complementaria
# Información devuelta: el código de estado HTTP 200 indica que el aprovisionamiento se ha realizado correctamente; el código de estado HTTP 500 indica que el aprovisionamiento ha fallado;
# Ejemplos de URL de solicitud: el dispositivo obtiene los parámetros a través de esta Url y los guarda en el dispositivo
http://192.168.4.1/config?SSID=mywifi&password=mywifipassword&userId=1
http://192.168.4.1/config?SSID=mywifi&password=mywifipassword&userId=1&deviceNum=D68329VL588&authCode=6688&extra=open5. Lista de verificación de la integración
Se recomienda verificar la integración de dispositivos MQTT en el orden siguiente, para evitar que solo se vea la conexión correcta pero los datos de negocio no lleguen a la plataforma.
| Paso | Contenido de la verificación | Indicación de éxito |
|---|---|---|
| 1 | Producto publicado | El estado del producto es «publicado» |
| 2 | Conexión de MQTTX o del dispositivo | La consola EMQX muestra la conexión del cliente |
| 3 | Estado del dispositivo | Los detalles del dispositivo muestran «en línea» o se actualiza la hora de la última conexión |
| 4 | /info/post | Se actualizan los campos de información del dispositivo, señal, versión, etc. |
| 5 | /property/post | El estado de funcionamiento muestra los valores de las propiedades del Thing Model |
| 6 | /event/post | El registro de eventos muestra los eventos reportados |
| 7 | /function/get | El lado del dispositivo recibe el comando tras el envío desde la plataforma |
| 8 | Devolución del resultado | El dispositivo devuelve el resultado del envío y la plataforma actualiza el estado |
| 9 | Reglas/escenas | Se activan las reglas, escenas y alarmas correspondientes |
6. Errores frecuentes
Conexión rechazada
Compruebe prioritariamente:
- Si el puerto
1883del servidor está abierto. - Si EMQX o el servicio MQTT integrado están iniciados.
- Si
clientIdse ajusta al formatoS&deviceNumber&productId&userIdo al formato de autenticación cifrada. - Si el producto tiene habilitada la autorización de dispositivos y, en ese caso, si la contraseña incluye el código de autorización.
- Si el dispositivo está deshabilitado.
El dispositivo está en línea pero las propiedades no se actualizan
Compruebe prioritariamente:
- Si el topic de publicación es
/{productId}/{deviceNum}/property/post. - Si
productIdutiliza el ID de producto y no el número de producto. - Si
deviceNumcoincide exactamente con el número de dispositivo. - Si el cuerpo del mensaje es un array.
- Si
idcoincide exactamente con el identificador del Thing Model. - Si
valuese ajusta al tipo de dato.
El dispositivo no recibe los envíos de la plataforma
Compruebe prioritariamente:
- Si el dispositivo está suscrito a
/{productId}/{deviceNum}/function/get. - Si la conexión de MQTTX o del dispositivo sigue en línea.
- Si el Thing Model es una función escribible o una propiedad que admite envío.
- Si el usuario tiene permisos de detalles del dispositivo y de envío de comandos.
- Si la sombra de dispositivo afecta a la valoración actual.
Las reglas o alarmas no se activan
Compruebe prioritariamente:
- Si los datos del dispositivo llegan al estado de funcionamiento de la plataforma.
- Si el producto, el dispositivo y las variables vinculados a la escena o la regla son correctos.
- Si la expresión de condición coincide con el tipo del valor reportado.
- Si la configuración de alarmas está habilitada.
7. Entradas para el desarrollo de extensiones
| Tipo | Ruta o interfaz | Descripción |
|---|---|---|
| Autenticación MQTT | /iot/tool/mqtt/auth, /iot/tool/mqtt/webhook | Entradas de autenticación y Webhook de EMQX |
| Interfaz de dispositivos | /iot/device | Estado en línea, estado y detalles del dispositivo |
| Interfaz del Thing Model | /iot/model | Definición y mapeo del modelo |
| Módulo de protocolos | springboot/fastbee-protocol | Análisis y conversión de mensajes MQTT |
| Módulo de datos | springboot/fastbee-iot-data | Procesamiento de datos de propiedades, eventos y monitorización |
| Páginas del frontend | vue3/src/views/iot/device | Detalles del dispositivo, estado de funcionamiento y depuración de datos |
| API del frontend | vue3/src/api/iot | Encapsulación de las peticiones de dispositivos y del Thing Model |


