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

Versiones del protocolo y reglas del dispositivo

Cómo se versiona el protocolo de dispositivos, qué anuncia un dispositivo en hello, los códigos de error que usa y cómo debe reaccionar cuando algo sale mal.

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

MarcaDóndeSignificado
v1/El inicio de cada tema del esquema predeterminadoLa 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/1El campo protocol del mensaje hello del dispositivoLa 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.

CampoQué contiene
modelEl modelo del dispositivo
serialEl 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.
fwLa versión del firmware
hwLa revisión de hardware
profile_hashUn hash del perfil de ajustes del dispositivo
capabilitiesLas funciones que soporta el dispositivo (abajo)
protocolroltek-device-protocol/1

Capacidades

Un dispositivo solo lista lo que soporta.

CapacidadSignificado
telemetryEnvía lecturas
attributesEnvía atributos de cliente y recibe atributos compartidos
rpcRecibe comandos
rpc.persistentRecibe comandos que se mantienen hasta que el dispositivo vuelve a estar en línea
otaRecibe actualizaciones de firmware
cfgRecibe configuración mediante atributos compartidos cfg.* (requiere cfg_hash)
claimPuede ser reclamado con una ventana de reclamación
csrSolicita un certificado de dispositivo
store_forwardAlmacena lecturas mientras está sin conexión y las envía después
gatewayInforma 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 nivelesLo descarta (invalid_payload)
Atributos de cliente o hello que no son un objeto JSONLo 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 existeLo descarta (unknown_reserved_topic)
Un tema en el que el dispositivo no puede publicarLo descarta (forbidden_topic)
Tres temas rechazados en un minutoCierra la sesión
Un SUBSCRIBE a un tema que el dispositivo no puede leerResponde SUBACK 0x80
Mensajes que superan los límites de tasa del perfilDescarta 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:

EstadoCódigo
400invalid_payload, hello_serial_mismatch
413payload_too_large, raw_too_large
429rate_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ódigoSignificado
unsupported_methodEl receptor no conoce el método
bad_paramsLos parámetros faltan o son incorrectos
busyEl receptor no puede ejecutarlo ahora
timeoutLa operación agotó el tiempo en el receptor
expiredEl expirationTime de la solicitud ya ha pasado
forbiddenEl método está desactivado por una política local
payload_too_largeLa solicitud es mayor de lo que admite el receptor
internalCualquier 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étodoRespuesta
getCurrentTime{"ok": true, "result": {"ts": <server time in ms>}}
getSessionLimitsLos límites efectivos por dispositivo del perfil del dispositivo

Reglas para el dispositivo

  1. Ignora lo que no entiendas: mensajes downlink mal formados, claves de atributos compartidos desconocidas y campos desconocidos.
  2. Responde a un comando desconocido con unsupported_method; trata un código de error desconocido como internal.
  3. Ejecuta un id de comando una sola vez. Un comando puede llegar dos veces; consulta Sending commands to devices.
  4. 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.
  5. Reintenta una respuesta agotada una vez. Si una solicitud de atributos o una solicitud del dispositivo no recibe respuesta, pregunta una vez más.
  6. 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.
  7. Mantente por debajo de tus límites. Pídelos con getSessionLimits tras conectar y mantente por debajo del 80 % de cada uno. Los valores predeterminados están en Limits and quotas.