MQTT

Hermetry habla MQTT 3.1.1. Esta página es la referencia de conexión para desarrolladores de dispositivos: cómo llegar al broker, cómo iniciar sesión, cómo se comportan las sesiones, qué se confirma y cuándo, y qué hacer cuando se rechaza una conexión. Los topics y los payloads están en MQTT topics and payload reference.

Conexión

Elemento	Valor
Protocolo	MQTT 3.1.1 (nivel de protocolo 4). Un CONNECT para MQTT 5 se rechaza con CONNACK 1.
Puerto, TLS	8883
Puerto, sin cifrar	1883, solo para dispositivos de un perfil que permite MQTT sin cifrar
Host	El host del broker en la tarjeta Connection details del dispositivo. Usa el host de la región de tu organización.
Clean session	Envía true. Un CONNECT con false se atiende como clean session.
Keepalive	Usa el keepalive de MQTT. Un keepalive de 0, o superior al máximo del broker (300 segundos en una instalación por defecto), se atiende con el máximo.
Will message	Permitido, pero ignorado. Hermetry decide por sí mismo el estado de la conexión.
Retain flag	Ignorado. El mensaje se procesa, no se retiene.
Tiempo de conexión	Desde la conexión TCP hasta un CONNECT aceptado (incluidos el handshake TLS y el inicio de sesión), el dispositivo dispone de unos pocos segundos (5 por defecto).

Mientras un dispositivo está desconectado no se encola nada para él, salvo los comandos marcados como persistentes. Tras cada conexión, el dispositivo vuelve a suscribirse y solicita sus atributos compartidos, lo que le proporciona los valores actuales.

TLS

• TLS 1.2 como mínimo, TLS 1.3 preferido.
• Suites TLS 1.2: ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-CHACHA20-POLY1305. Sin intercambio de claves RSA, sin CBC.
• Se requiere SNI. Conéctate por nombre de host, no por dirección IP.
• Para dispositivos de terceros, el certificado del servidor es público. Verifícalo con tu paquete de CA habitual y con el nombre de host.
• El servidor pide un certificado de cliente pero no lo exige, de modo que un solo puerto atiende todos los tipos de inicio de sesión.
• Los dispositivos pequeños pueden pedir registros TLS de 4 KB (max_fragment_length).

Un perfil decide si sus dispositivos pueden usar el puerto sin cifrar (Plain MQTT en la pestaña Transport & auth del perfil). TLS únicamente es el valor por defecto. Consulta Device transport security.

Inicio de sesión

Credencial	Client ID	Username	Password
Access token	cualquier ID válido	el access token	vacío
MQTT básico	cualquiera, o el client ID fijado	el username	la password
Certificado X.509	el número de serie del dispositivo (debe ser igual al CN del certificado)	el número de serie (ignorado)	vacío

• Un client ID tiene de 1 a 64 caracteres de A–Z a–z 0–9 . _ : -. Cualquier otro se rechaza con CONNACK 2.
• Un CONNECT con username pero sin password se interpreta como access token. Un CONNECT sin username se rechaza.
• Cuando se presenta un certificado de cliente, es él quien decide. No hay alternativa con password. Un certificado no confiable termina el handshake TLS.
• El username provision abre una sesión de aprovisionamiento (consulta Adding and claiming devices).
• El perfil debe permitir el tipo de credencial, la red del dispositivo y el puerto (TLS o sin cifrar); en caso contrario, el inicio de sesión se rechaza con CONNACK 5.

Sesiones

• Una sesión por dispositivo. Una segunda conexión del mismo dispositivo toma el control y cierra la primera. Un dispositivo cuya sesión se les quita una y otra vez desde dos redes se retiene durante un tiempo, y tus administradores reciben un aviso («takeover fight»); revisa si dos dispositivos comparten una misma credencial.
• Comprobaciones periódicas. Cada sesión activa se vuelve a comprobar aproximadamente cada 60 segundos. Una credencial rotada o revocada, un dispositivo deshabilitado o eliminado, una organización suspendida o un cambio de perfil que la sesión ya no cumple la finalizan de inmediato.
• Dispositivos en cuarentena se conectan, pero su telemetría y sus atributos se confirman y descartan hasta que un administrador los active.
• Aviso de nueva red. Cuando un dispositivo inicia sesión desde una red distinta a la anterior, tus administradores pueden recibir un aviso (como máximo una vez por hora y dispositivo), para que una credencial robada no pase desapercibida.
• Límite de dispositivos conectados. Si tu plan limita cuántos dispositivos pueden estar conectados a la vez, un CONNECT que supere ese límite se rechaza con CONNACK 5.

Confirmaciones y QoS

• Publica con QoS 1. QoS 0 se acepta; QoS 2 se trata como QoS 1.
• Hermetry envía el PUBACK solo después de que el mensaje esté encolado de forma segura. Los PUBACK salen en el orden en que el dispositivo publicó.
• Si un mensaje no se puede encolar, no recibe PUBACK (ni tampoco nada posterior en esa sesión), y la sesión se cierra al cabo de unos segundos. El dispositivo reenvía los mensajes no confirmados después de reconectarse.
• Un dispositivo puede tener como máximo 20 mensajes QoS 1 no confirmados en vuelo por defecto (el Max unacknowledged messages (MQTT) del perfil, de 1 a 1.000).
• Los duplicados del mismo dispositivo, clave y marca de tiempo se almacenan una sola vez, por lo que reenviar es seguro.

Límites

Límite	Por defecto	Dónde se configura
Mensajes de telemetría	10:1,300:60 (10 por segundo y 300 por minuto)	Limits del perfil
Puntos de datos de telemetría	200:1,6000:60	Limits del perfil
Mensajes de atributos	5:1,60:60	Limits del perfil
Tamaño de mensaje	64 KiB, hasta 1.000 puntos clave-valor	Max message payload (bytes) del perfil
Mensajes hacia el dispositivo	64 KiB (4 KiB para dispositivos con licencia)	Max downlink payload (bytes) del perfil

• Al superar un límite de tasa, el mensaje se confirma y se descarta. Un dispositivo que sigue incumpliendo su límite (más de tres veces su cupo por minuto descartado en un minuto) ve cerrada su sesión. Los propietarios y administradores reciben un aviso por dispositivo y hora.
• Un mensaje demasiado grande se descarta entero; la conexión se mantiene.
• Tu organización en su conjunto también tiene límites de tasa según su plan.
• Las lecturas acumuladas que un dispositivo envía tras una interrupción (cada registro lleva un ts anterior) también deben caber en el Replay messages per second del perfil.
• Los mensajes de telemetría y de atributos cuentan para tu cuota mensual de mensajes; los eventos de conexión, los comandos y las alarmas no. Consulta Message quota and usage.

Códigos CONNACK

Código	Significado	Qué debe hacer el dispositivo
0	Aceptado	Continuar.
1	Versión de protocolo no soportada	Dejar de reintentar; corregir el cliente.
2	Client ID rechazado	Detenerse hasta que cambie la configuración.
3	Servidor no disponible: el servicio está ocupado, arrancando o parándose, o la dirección está bloqueada brevemente	Esperar y reintentar, con jitter.
4	Username o password incorrectos	Esperar al menos 5 minutos (hasta 1 hora).
5	No autorizado: dispositivo deshabilitado, certificado revocado o caducado, organización suspendida o por encima de su límite de dispositivos o de dispositivos conectados, tipo de inicio de sesión, red o puerto no permitidos por el perfil	Esperar con la programación larga.

El motivo del código 5 nunca se envía al dispositivo. Se escribe en la pestaña Log del dispositivo.

Motivos de desconexión

La pestaña Log del dispositivo muestra por qué terminó una sesión:

Motivo	Significado
client_disconnect	El dispositivo cerró la conexión.
keepalive_timeout	No llegó nada dentro del tiempo de keepalive.
takeover	Otra conexión del mismo dispositivo tomó el control.
auth_revoked	La credencial, el dispositivo o la organización ya no están permitidos.
rate_limit	El dispositivo siguió incumpliendo su límite de tasa.
server_shutdown	El nodo del broker se reinició; reconectar.
protocol_error, inflight_exceeded, socket_error	El cliente incumplió el protocolo, envió demasiados mensajes no confirmados, o la red falló.

Comportamiento recomendado del dispositivo

1. Conéctate por TLS usando el nombre de host, con un keepalive entre 30 y 300 segundos.
2. Tras un CONNACK 0, suscríbete a los topics de downlink, solicita los atributos compartidos, informa los atributos de cliente y después envía la telemetría acumulada antes de los datos en vivo.
3. Usa QoS 1 y espera al PUBACK antes de eliminar una lectura almacenada en búfer.
4. Agrupa las lecturas en lotes cuando envíes más de una muestra por segundo.
5. Ante una conexión rechazada, sigue el back-off de la tabla de CONNACK; añade un jitter aleatorio para que una flota no se reconecte a la vez.

Relacionado

• Referencia de temas y payloads de MQTT
• Credenciales del dispositivo
• Perfiles de dispositivo
• Un dispositivo no se conecta