Referencia de temas y payloads MQTT

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

Temas del esquema por defecto

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

Dirección	Tema	Uso	Página
Subida	`v1/telemetry`	Telemetría	abajo
Subida	`v1/attributes`	Atributos del cliente	Attributes
Subida	`v1/attributes/req/{id}`	Solicitar atributos	Attributes
Bajada	`v1/attributes/res/{id}`	Respuesta a una solicitud de atributos	Attributes
Bajada	`v1/attributes/set`	Cambios de atributos compartidos, incluidas las ofertas de firmware (`fw_*`)	Firmware updates (OTA)
Bajada	`v1/rpc/req/{id}`	Comando desde la nube	Sending commands to devices
Subida	`v1/rpc/res/{id}`	Respuesta a un comando	igual
Subida	`v1/rpc/up/req/{id}`	Solicitud del dispositivo a la nube	igual
Bajada	`v1/rpc/up/res/{id}`	Respuesta a una solicitud del dispositivo	igual
Subida	`v1/provision/req`	Solicitud de aprovisionamiento (solo en una sesión de aprovisionamiento)	Adding and claiming devices
Bajada	`v1/provision/res`	Respuesta de aprovisionamiento	igual
Subida	`v1/hello`	La autodescripción del dispositivo (dispositivos licenciados)	Licensed devices
Subida	`v1/csr`	Solicitud de firma de certificado (dispositivos licenciados)	Device certificates
Bajada	`v1/cert`	El certificado emitido	igual
Subida	`v1/claim`	Abrir o cerrar la ventana de reclamación (dispositivos licenciados)	Adding and claiming devices
Subida	`v1/gw/connect`, `v1/gw/disconnect`, `v1/gw/telemetry`, `v1/gw/attributes`, `v1/gw/attributes/req` (En desarrollo)	Solo pasarelas: informe de los dispositivos hijos	Devices behind a gateway
Bajada	`v1/gw/attributes`, `v1/gw/attributes/res`, `v1/gw/rpc`	Solo pasarelas; En desarrollo (comandos y atributos compartidos a los dispositivos hijos)	igual

Un dispositivo solo puede suscribirse 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 las pasarelas. Un dispositivo nunca recibe los mensajes de otro dispositivo.

Temas rechazados

Publicado en	Resultado
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 pasarela, o `v1/provision/req` fuera de una sesión de aprovisionamiento	Rechazado 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 compatibles heredados

Los perfiles con el esquema Legacy compatible también aceptan:

Dirección	Tema
Subida	`v1/devices/me/telemetry`
Subida y bajada	`v1/devices/me/attributes`
Subida	`v1/devices/me/attributes/request/{id}`
Bajada	`v1/devices/me/attributes/response/{id}`

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

Temas personalizados

Los perfiles con Custom topics 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 mantenerse dentro de la Max topic depth (8), la Max topic length (128) y los Distinct topics per device (50) del perfil.
Con Prefix keys with the topic, cada clave se almacena como <topic>.<key>: las / 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 unida 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 almacena 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 en el futuro, o más antiguos que tu retención de telemetría, se descartan. Nunca se mueven a otro tiempo.
Los duplicados del mismo dispositivo, clave y tiempo se almacenan una sola vez.

Consulta Timestamps, late and duplicate readings.

Claves

Patrón: ^[A-Za-z0-9_.\-]{1,64}$. Las claves distinguen mayúsculas y minú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 JSON	Se almacena como	Regla
Entero	long	Por encima de ±2^53, envíalo como cadena.
Fracción	double	NaN e Infinity no son JSON y se rechazan.
`true` / `false`	boolean	Los gráficos leen números: envía `0`/`1` si quieres un historial.
Cadena	string	Hasta 1.024 caracteres. Se muestra como el último valor, no se grafica.
Objeto o array	JSON	Hasta 4 KiB, se almacena tal cual.
`null`	nada	Significa «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 del cliente

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

Las claves de atributos pueden tener hasta 128 caracteres. Consulta Attributes.

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 atributos aceptada cuenta una vez hacia tu cuota mensual de mensajes, sea cual sea 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.