Esta página es para personas que escriben firmware de dispositivos o software de pasarelas para Hermetry. Explica cómo se versiona el protocolo de dispositivos y las reglas que sigue un dispositivo para seguir funcionando a medida que Hermetry cambia. Los temas y los payloads están en MQTT topics and payload reference; las reglas de conexión e inicio de sesión están en MQTT.
Dos marcas de versión
| Marca | Dónde | Significado |
|---|---|---|
v1/ | El inicio de cada tema del esquema predeterminado | La versión de los nombres de los temas. Un cambio que rompa los temas usaría temas nuevos bajo v2/; los temas v1/ no se renombran. |
roltek-device-protocol/1 | El campo protocol del mensaje hello del dispositivo | La versión mayor del protocolo que habla el dispositivo. Hermetry almacena la versión mayor en el dispositivo. |
Las dos marcas son independientes: una nueva versión mayor del protocolo no implica por sí sola nuevos nombres de temas.
El mensaje hello
Un dispositivo que se describe a sí mismo (lo hacen los dispositivos con licencia) publica en v1/hello una vez por conexión, con QoS 1. Los dispositivos que no envían hello siguen funcionando con los temas predeterminados.
| Campo | Qué contiene |
|---|---|
model | El modelo del dispositivo |
serial | El número de serie. Debe coincidir con el número de serie registrado del dispositivo; de lo contrario, el mensaje se rechaza con hello_serial_mismatch. |
fw | La versión del firmware |
hw | La revisión de hardware |
profile_hash | Un hash del perfil de ajustes del dispositivo |
capabilities | Las funciones que soporta el dispositivo (abajo) |
protocol | roltek-device-protocol/1 |
Capacidades
Un dispositivo solo lista lo que soporta.
| Capacidad | Significado |
|---|---|
telemetry | Envía lecturas |
attributes | Envía atributos de cliente y recibe atributos compartidos |
rpc | Recibe comandos |
rpc.persistent | Recibe comandos que se mantienen hasta que el dispositivo vuelve a estar en línea |
ota | Recibe actualizaciones de firmware |
cfg | Recibe configuración mediante atributos compartidos cfg.* (requiere cfg_hash) |
claim | Puede ser reclamado con una ventana de reclamación |
csr | Solicita un certificado de dispositivo |
store_forward | Almacena lecturas mientras está sin conexión y las envía después |
gateway | Informa de dispositivos hijos |
La lista de capacidades del protocolo 1 está fija desde el 23 de octubre de 2026.
Cambios compatibles y que rompen compatibilidad
Los cambios compatibles mantienen la versión del protocolo. Hermetry puede añadir en cualquier momento nuevos campos opcionales, valores de capacidad, métodos de comando, claves de atributos, códigos de error y claves de telemetría. Por tanto, un dispositivo debe ignorar lo que no conoce: un campo desconocido, una clave de atributo compartido desconocida, un código de error desconocido.
Los cambios que rompen compatibilidad necesitan una nueva versión mayor: renombrar o eliminar un tema, campo, clave de atributo o estado; cambiar el tipo o el significado de un campo; o hacer un límite más estricto de lo que podría superar un dispositivo correcto de la versión actual.
Cuando se rechaza un mensaje
El protocolo 1 no tiene tema de errores. Un mensaje que Hermetry no puede aceptar se descarta pero se confirma igualmente (PUBACK), así que un dispositivo no lo reenvía. Hermetry registra el motivo; no se envía al dispositivo.
| Qué ocurrió | Qué hace Hermetry |
|---|---|
| JSON anidado a más de 8 niveles | Lo descarta (invalid_payload) |
Atributos de cliente o hello que no son un objeto JSON | Lo descarta (invalid_payload) |
| Telemetría que no es JSON en absoluto (texto, binario) | La conserva como la única clave raw, hasta el tamaño raw del perfil (raw_too_large por encima) |
Un tema bajo v1/ que no existe | Lo descarta (unknown_reserved_topic) |
| Un tema en el que el dispositivo no puede publicar | Lo descarta (forbidden_topic) |
| Tres temas rechazados en un minuto | Cierra la sesión |
| Un SUBSCRIBE a un tema que el dispositivo no puede leer | Responde SUBACK 0x80 |
| Mensajes que superan los límites de tasa del perfil | Descarta los mensajes sobrantes; más de tres veces el límite en 60 segundos cierra la sesión (rate_limit) |
Por HTTP, la API del dispositivo responde con un estado:
| Estado | Código |
|---|---|
| 400 | invalid_payload, hello_serial_mismatch |
| 413 | payload_too_large, raw_too_large |
| 429 | rate_limited, con una cabecera Retry-After |
Los códigos que Hermetry registra para las lecturas almacenadas (key_invalid, bad_ts y otros) aparecen en Error messages.
Códigos de error de comando
Los comandos en ambas direcciones (de la nube al dispositivo en v1/rpc/req/{id}, del dispositivo a la nube en v1/rpc/up/req/{id}) responden los errores como {"ok": false, "error": "<code>"} con uno de estos códigos:
| Código | Significado |
|---|---|
unsupported_method | El receptor no conoce el método |
bad_params | Los parámetros faltan o son incorrectos |
busy | El receptor no puede ejecutarlo ahora |
timeout | La operación agotó el tiempo en el receptor |
expired | El expirationTime de la solicitud ya ha pasado |
forbidden | El método está desactivado por una política local |
payload_too_large | La solicitud es mayor de lo que admite el receptor |
internal | Cualquier otro caso |
Un receptor trata **cualquier otro código como internal**.
Una solicitud del dispositivo a la nube la responden tus flujos. Si ningún flujo responde en 5 segundos, Hermetry responde unsupported_method. Hermetry responde siempre por sí mismo a dos métodos:
| Método | Respuesta |
|---|---|
getCurrentTime | {"ok": true, "result": {"ts": <server time in ms>}} |
getSessionLimits | Los límites efectivos por dispositivo del perfil del dispositivo |
Reglas para el dispositivo
- Ignora lo que no entiendas: mensajes downlink mal formados, claves de atributos compartidos desconocidas y campos desconocidos.
- Responde a un comando desconocido con
unsupported_method; trata un código de error desconocido comointernal. - Ejecuta un id de comando una sola vez. Un comando puede llegar dos veces; consulta Sending commands to devices.
- Reenvía cuando no hay confirmación. Sin PUBACK en 20 segundos, reenvía el mensaje con el flag DUP; tras tres reenvíos, reconecta.
- Reintenta una respuesta agotada una vez. Si una solicitud de atributos o una solicitud del dispositivo no recibe respuesta, pregunta una vez más.
- Retrocede ante conexiones rechazadas. Con CONNACK 1 (versión de protocolo no soportada) deja de reintentar; con CONNACK 3 retrocede normalmente; con CONNACK 4 o 5 retrocede durante mucho tiempo. Los códigos están en MQTT.
- Mantente por debajo de tus límites. Pídelos con
getSessionLimitstras conectar y mantente por debajo del 80 % de cada uno. Los valores predeterminados están en Limits and quotas.

