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 temas y las cargas útiles 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. Use el host de la región de su organización. |
| Clean session | Envíe true. Un CONNECT con false se atiende como clean session. |
| Keepalive | Use el keepalive de MQTT. Un keepalive de 0, o superior al máximo del broker (300 segundos en una instalación por defecto), se aplica con el máximo. |
| Will message | Permitido, 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 segundos (5 por defecto). |
No se encola nada para un dispositivo mientras está desconectado, salvo los comandos marcados como persistentes. Después de 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 de TLS 1.2:
ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-CHACHA20-POLY1305. Sin intercambio de claves RSA, sin CBC. - SNI es obligatorio. Conecte por nombre de host, no por dirección IP.
- Para dispositivos de terceros el certificado del servidor es público. Verifíquelo con su paquete de CA habitual y con el nombre de host.
- El servidor solicita un certificado de cliente pero no lo exige, por lo que un único puerto atiende todos los tipos de inicio de sesión.
- Los dispositivos pequeños pueden solicitar 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). Solo TLS es el valor por defecto. Consulte 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
provisionabre una sesión de aprovisionamiento (consulte 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 sus administradores reciben un aviso («takeover fight»); compruebe si hay dos dispositivos que comparten una credencial.
- Revisiones. 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.
- Los dispositivos en cuarentena se conectan, pero su telemetría y sus atributos se confirman y se descartan hasta que un administrador los active.
- Aviso de nueva red. Cuando un dispositivo inicia sesión desde una red distinta a la anterior, sus 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 su plan limita cuántos dispositivos pueden estar conectados a la vez, un CONNECT por encima de ese límite se rechaza con CONNACK 5.
Confirmaciones y QoS
- Publique 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 puede encolarse, no recibe PUBACK (ni lo recibe 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 sin confirmar 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 del mensaje | 64 KiB, hasta 1.000 puntos clave-valor | Max message payload (bytes) del perfil |
| Mensajes al dispositivo | 64 KiB (4 KiB para dispositivos con licencia) | Max downlink payload (bytes) del perfil |
- Al superar un límite de frecuencia, el mensaje se confirma y se descarta. Un dispositivo que sigue superando su límite (más de tres veces su cuota del minuto descartada dentro de un minuto) ve cerrada su sesión. Los propietarios y administradores reciben un aviso por dispositivo cada hora.
- Un mensaje demasiado grande se descarta entero; la conexión se mantiene.
- Su organización en conjunto también tiene límites de frecuencia según su plan.
- Las lecturas almacenadas en búfer que un dispositivo envía después de una interrupción (cada registro lleva un
tsanterior) también deben caber en Replay messages per second del perfil. - Los mensajes de telemetría y de atributos cuentan para su cuota mensual de mensajes; los eventos de conexión, los comandos y las alarmas no. Consulte Message quota and usage.
Códigos CONNACK
| Código | Significado | Qué debe hacer el dispositivo |
|---|---|---|
| 0 | Aceptada | Continuar. |
| 1 | Versión de protocolo no soportada | Deje de reintentar; corrija el cliente. |
| 2 | Client ID rechazado | Espere hasta que cambie la configuración. |
| 3 | Servidor no disponible: el servicio está ocupado, arrancando o parando, o la dirección está bloqueada temporalmente | Espere y reintente, con jitter. |
| 4 | Usuario o contraseña incorrectos | Espere 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 conectados, tipo de inicio de sesión, red o puerto no permitidos por el perfil | Espere 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.
Nota
Los inicios de sesión fallidos repetidos desde una misma dirección bloquean esa dirección durante un breve tiempo, para todos los dispositivos tras ella. Un dispositivo mal configurado puede, por tanto, bloquear a sus vecinos detrás del mismo NAT. Corrija cuanto antes las credenciales incorrectas.
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ó superando su límite de frecuencia. |
server_shutdown | El nodo del broker se reinició; reconecte. |
protocol_error, inflight_exceeded, socket_error | El cliente incumplió el protocolo, envió demasiados mensajes sin confirmar o la red falló. |
Comportamiento recomendado del dispositivo
- Conecte por TLS usando el nombre de host, con un keepalive entre 30 y 300 segundos.
- Tras CONNACK 0, suscríbase a los topics de downlink, solicite los atributos compartidos, reporte los atributos de cliente y envíe después la telemetría almacenada antes que los datos en vivo.
- Use QoS 1 y espere el PUBACK antes de borrar una lectura almacenada en búfer.
- Agrupe las lecturas cuando envíe más de una muestra por segundo.
- Ante una conexión rechazada, siga el tiempo de espera de la tabla CONNACK; añada jitter aleatorio para que una flota no se reconecte a la vez.

