Novedad: el cortafuegos de IA supervisa toda la plataforma y explica cada incidente con palabras sencillas. Vea cómo funciona

Referencia de temas y payloads de MQTT

Todos los temas MQTT: telemetría, atributos, comandos, aprovisionamiento, certificados, reclamación y gateway; las formas de payload y las reglas de claves y valores.

Esta es la referencia de lo que un dispositivo publica y a lo que se suscribe. Las reglas de conexión, inicio de sesión y sesión están en MQTT. Los dispositivos HTTP usan los mismos payloads; véase Device HTTP API.

Temas del esquema por defecto

Todos los temas empiezan por v1/. Usa QoS 1.

SentidoTemaUsoPágina
Subidav1/telemetryTelemetríaabajo
Subidav1/attributesAtributos de clienteAtributos
Subidav1/attributes/req/{id}Pedir atributosAtributos
Bajadav1/attributes/res/{id}Respuesta a una petición de atributosAtributos
Bajadav1/attributes/setCambios de atributos compartidos, incluidas las ofertas de firmware (fw_*)Actualizaciones de firmware (OTA)
Bajadav1/rpc/req/{id}Comando desde la nubeEnvío de comandos a dispositivos
Subidav1/rpc/res/{id}Respuesta a un comandoigual
Subidav1/rpc/up/req/{id}Petición del dispositivo a la nubeigual
Bajadav1/rpc/up/res/{id}Respuesta a una petición del dispositivoigual
Subidav1/provision/reqPetición de aprovisionamiento (solo en una sesión de aprovisionamiento)Añadir y reclamar dispositivos
Bajadav1/provision/resRespuesta de aprovisionamientoigual
Subidav1/helloLa autodescripción del dispositivo (dispositivos con licencia)Dispositivos con licencia
Subidav1/csrSolicitud de firma de certificado (dispositivos con licencia)Certificados de dispositivo
Bajadav1/certEl certificado emitidoigual
Subidav1/claimAbrir o cerrar la ventana de reclamación (dispositivos con licencia)Añadir y reclamar dispositivos
Subidav1/gw/connect, v1/gw/disconnect, v1/gw/telemetry, v1/gw/attributes, v1/gw/attributes/reqSolo gateways: informar de dispositivos hijos y solicitar los atributos de un hijoDispositivos detrás de un gateway
Bajadav1/gw/rpc, v1/gw/attributes, v1/gw/attributes/resSolo gateways: comandos y atributos compartidos para dispositivos hijos, y respuestas a solicitudes de atributosComandos a dispositivos detrás de un gateway
Subidav1/gw/rpcSolo gateways: la respuesta de un hijo a un comandoigual

Un dispositivo puede suscribirse solo a sus temas de bajada: v1/attributes/set, v1/attributes/res/+, v1/rpc/req/+, v1/rpc/up/res/+ y v1/cert, además de v1/gw/attributes, v1/gw/rpc y v1/gw/attributes/res para gateways. Un dispositivo nunca recibe los mensajes de otro dispositivo.

Temas rechazados

Publicado enResultado
Un tema desconocido bajo v1/Rechazado como unknown_reserved_topic, nunca se almacena.
Un tema de bajada, v1/gw/* desde un dispositivo que no es gateway, o v1/provision/req fuera de una sesión de aprovisionamientoRechazado como forbidden_topic.

Ambos se confirman y se descartan. Tres temas rechazados en un minuto cierran la sesión.

Secuencia de conexión

CONNECT
SUBSCRIBE v1/attributes/set      (QoS 1)
SUBSCRIBE v1/attributes/res/+    (QoS 1)
SUBSCRIBE v1/rpc/req/+           (QoS 1)
SUBSCRIBE v1/rpc/up/res/+        (QoS 1, only if the device sends requests)
PUBLISH   v1/attributes/req/1    {}          catch-up: all shared attributes
PUBLISH   v1/attributes          current state
PUBLISH   v1/telemetry           buffered data first, then live data

Temas de compatibilidad heredada

Los perfiles con el esquema Compatible con legado también aceptan:

SentidoTema
Subidav1/devices/me/telemetry
Subida y bajadav1/devices/me/attributes
Subidav1/devices/me/attributes/request/{id}
Bajadav1/devices/me/attributes/response/{id}

No transportan comandos, reclamación, aprovisionamiento ni temas de gateway.

Temas personalizados

Los perfiles con Temas personalizados aceptan cualquier tema fuera de v1/ como telemetría del dispositivo:

  • Un objeto JSON se convierte en claves. Cualquier otra cosa (un número, un array, texto, binario) se convierte en la única clave raw, como su texto, hasta el Max raw payload (bytes) del perfil (4,096 por defecto).
  • El tema debe quedar dentro de la Max topic depth (8), la Max topic length (128) y los Distinct topics per device (50) del perfil.
  • Con Anteponer el tema a las claves, cada clave se almacena como <topic>.<key>: los / del tema se convierten en ., y otros caracteres fuera de la regla de claves se convierten en _. Por ejemplo, site1/boiler y temp dan site1.boiler.temp. Una clave combinada de más de 64 caracteres se descarta. Sin el prefijo, la misma clave de dos temas se sobrescribe a sí misma.

Formas del payload de telemetría

La telemetría es JSON, UTF-8.

Forma A, un objeto plano. Un registro, marcado con la hora en que Hermetry lo recibió:

{"temperature": 21.5, "humidity": 40, "door_open": false}

Forma B, un objeto con exactamente ts y values. Un registro en ts:

{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}

Forma C, un array de objetos de forma A y forma B. Un registro por elemento, en orden:

[
  {"ts": 1759572000000, "values": {"sys.cpu_load": 0.42}},
  {"ts": 1759572060000, "values": {"sys.cpu_load": 0.38}},
  {"net.wan.up": true}
]

No es JSON. Un cuerpo que no es JSON se guarda como una clave raw en el tema de telemetría por defecto. Un escalar JSON (42, "on") en v1/telemetry se rechaza (bad_form).

Un objeto con ts y values más cualquier otro miembro es forma A, no forma B: todos sus miembros se convierten en claves.

Marcas de tiempo

  • ts es un entero: milisegundos desde la época Unix, UTC.
  • Un dispositivo sin reloj sincronizado debe usar la forma A. No debe inventar una marca de tiempo.
  • Los registros con más de 10 minutos de adelanto, o más antiguos que su retención de telemetría, se descartan. Nunca se trasladan a otro momento.
  • Los duplicados del mismo dispositivo, clave y momento se guardan una sola vez.

Véase Marcas de tiempo, lecturas tardías y duplicadas.

Claves

  • Patrón: ^[A-Za-z0-9_.\-]{1,64}$. Las claves distinguen mayúsculas: abc y ABC son dos claves.
  • No se admiten en telemetría las claves que empiezan por _, fw_, current_fw_ o cfg..
  • Consejo: usa nombres en minúsculas separados por puntos, por ejemplo net.wan.up.

Una clave incorrecta descarta solo esa clave; el resto del registro se conserva.

Valores

Valor JSONSe guarda comoRegla
EnterolongPor encima de ±2^53, envíalo como cadena.
DecimaldoubleNaN e Infinity no son JSON y se rechazan.
true / falsebooleanLos gráficos leen números: envía 0/1 si quieres un historial.
CadenastringHasta 1.024 caracteres. Se muestra como el último valor, no se grafica.
Objeto o arrayJSONHasta 4 KiB, se guarda tal cual.
nullnadaSignifica «sin lectura». No borra nada.

Un valor incorrecto descarta solo esa clave.

Tamaño

  • Un mensaje: hasta 64 KiB y hasta 1.000 puntos clave-valor. Más puntos descartan el mensaje completo; un mensaje más grande se descarta entero. La conexión se mantiene.
  • Profundidad de anidamiento: hasta 8 niveles.
  • Agrupa tus mensajes cuando envíes más de una muestra por segundo.

Atributos de cliente

PUBLISH v1/attributes
{"current_fw_title": "boiler-fw", "current_fw_version": "26.10.2", "lan.ip": "192.168.1.1"}

Las claves de atributo pueden tener hasta 128 caracteres. Véase Atributos.

Comandos

PUBLISH v1/rpc/req/42                              (down)
{"method": "sys.ping", "params": {"host": "8.8.8.8", "count": 3}}

PUBLISH v1/rpc/res/42                              (up)
{"ok": true, "result": {"sent": 3, "received": 3, "avg_ms": 18.2}}

PUBLISH v1/rpc/up/req/5                            (up)
{"method": "app.request", "params": {}}

Aprovisionamiento

username: provision, password: empty
SUBSCRIBE v1/provision/res
PUBLISH   v1/provision/req
{"deviceName": "boiler-07", "provisionDeviceKey": "pk_…", "provisionDeviceSecret": "ps_…"}

Qué cuenta como mensaje

Cada publicación de telemetría o de atributos aceptada cuenta una vez hacia tu cuota mensual de mensajes, independientemente de su contenido. Las respuestas a comandos, los eventos de conexión y las alarmas no cuentan. Un mensaje con 50 lecturas cuesta lo mismo que uno con una sola lectura, así que agrupar ahorra cuota.

Relacionado