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.
| Sentido | Tema | Uso | Página |
|---|---|---|---|
| Subida | v1/telemetry | Telemetría | abajo |
| Subida | v1/attributes | Atributos de cliente | Atributos |
| Subida | v1/attributes/req/{id} | Pedir atributos | Atributos |
| Bajada | v1/attributes/res/{id} | Respuesta a una petición de atributos | Atributos |
| Bajada | v1/attributes/set | Cambios de atributos compartidos, incluidas las ofertas de firmware (fw_*) | Actualizaciones de firmware (OTA) |
| Bajada | v1/rpc/req/{id} | Comando desde la nube | Envío de comandos a dispositivos |
| Subida | v1/rpc/res/{id} | Respuesta a un comando | igual |
| Subida | v1/rpc/up/req/{id} | Petición del dispositivo a la nube | igual |
| Bajada | v1/rpc/up/res/{id} | Respuesta a una petición del dispositivo | igual |
| Subida | v1/provision/req | Petición de aprovisionamiento (solo en una sesión de aprovisionamiento) | Añadir y reclamar dispositivos |
| Bajada | v1/provision/res | Respuesta de aprovisionamiento | igual |
| Subida | v1/hello | La autodescripción del dispositivo (dispositivos con licencia) | Dispositivos con licencia |
| Subida | v1/csr | Solicitud de firma de certificado (dispositivos con licencia) | Certificados de dispositivo |
| Bajada | v1/cert | El certificado emitido | igual |
| Subida | v1/claim | Abrir o cerrar la ventana de reclamación (dispositivos con licencia) | Añadir y reclamar dispositivos |
| Subida | v1/gw/connect, v1/gw/disconnect, v1/gw/telemetry, v1/gw/attributes, v1/gw/attributes/req | Solo gateways: informar de dispositivos hijos y solicitar los atributos de un hijo | Dispositivos detrás de un gateway |
| Bajada | v1/gw/rpc, v1/gw/attributes, v1/gw/attributes/res | Solo gateways: comandos y atributos compartidos para dispositivos hijos, y respuestas a solicitudes de atributos | Comandos a dispositivos detrás de un gateway |
| Subida | v1/gw/rpc | Solo gateways: la respuesta de un hijo a un comando | igual |
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 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 gateway, 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 de compatibilidad heredada
Los perfiles con el esquema Compatible con legado también aceptan:
| Sentido | 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 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/boilerytempdansite1.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
tses 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:abcyABCson dos claves. - No se admiten en telemetría las claves que empiezan por
_,fw_,current_fw_ocfg.. - 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 guarda como | Regla |
|---|---|---|
| Entero | long | Por encima de ±2^53, envíalo como cadena. |
| Decimal | 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 guarda 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 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.

