Esta página te ayuda cuando un dispositivo no puede conectarse a Hermetry, recibe un rechazo al iniciar sesión o pierde la conexión constantemente. Cubre MQTT y la API HTTP del dispositivo. Para dispositivos LoRaWAN, consulta Solución de problemas de uniones; para dispositivos con sondeo, consulta Intervalos de sondeo, retroceso y cuota.
Dónde mirar primero
| Lugar | Muestra |
|---|---|
| La pestaña Log del dispositivo | Cada rechazo de inicio de sesión con su motivo, y cada desconexión con su motivo. El motivo de un rechazo nunca se envía al dispositivo: solo aparece aquí. |
| La tarjeta Connection details del dispositivo | El host del broker y los puertos que tu dispositivo debe usar |
| El log propio del cliente | El código CONNACK o el estado HTTP recibido, o el error de TLS |
Paso 1: ¿Puede el dispositivo alcanzar el broker?
| Síntoma en el dispositivo | Causa | Solución |
|---|---|---|
| La resolución DNS falla o la conexión expira | Host incorrecto, o un cortafuegos bloquea el puerto de salida | Usa el host de la tarjeta Connection details, para la región de tu organización. Permite TCP 8883 de salida (y 443 para HTTPS). |
| El handshake TLS falla | El dispositivo se conecta por dirección IP (se requiere SNI), no tiene un paquete CA, o su reloj va muy desfasado y el certificado parece no válido | Conéctate por nombre de host; usa el almacén de CA del sistema; ajusta el reloj (NTP) |
| TLS falla en un dispositivo muy pequeño | Solo admite suites de cifrado antiguas o TLS 1.0/1.1 | TLS 1.2 es el mínimo, con suites ECDHE y GCM o ChaCha20. Actualiza la biblioteca TLS. |
| El puerto 1883 es rechazado | El perfil es TLS only (port 8883), el valor por defecto | Usa 8883 o, solo en una red privada, permite MQTT sin cifrar en el perfil |
| Un certificado de cliente es rechazado durante el handshake | El certificado no procede de la CA de dispositivos de Hermetry, o fue revocado | Un certificado no confiable termina el handshake; no hay alternativa con contraseña. Consulta Certificados de dispositivo. |
Consulta Seguridad del transporte del dispositivo.
Paso 2: ¿Se acepta el inicio de sesión?
MQTT responde al CONNECT con un código CONNACK:
| CONNACK | Significado | Causas habituales |
|---|---|---|
| 1 | Versión de protocolo no soportada | El cliente envía MQTT 5. Hermetry usa MQTT 3.1.1. |
| 2 | ID de cliente rechazado | El ID de cliente está vacío, tiene más de 64 caracteres o contiene caracteres fuera de A–Z a–z 0–9 . _ : - |
| 3 | Servidor no disponible | El servicio se está iniciando o está ocupado, o tu dirección está bloqueada temporalmente tras varios inicios de sesión fallidos. Espera y reintenta con jitter. |
| 4 | Usuario o contraseña incorrectos | El token o la contraseña son incorrectos, fueron rotados o revocados; un nombre de usuario sin contraseña se interpreta como token de acceso |
| 5 | No autorizado | Consulta la tabla siguiente. El motivo exacto está en la pestaña Log del dispositivo. |
| Motivo del CONNACK 5 | Solución |
|---|---|
| El dispositivo está deshabilitado | Habilítalo en la página del dispositivo |
| El certificado está revocado o caducado | Deja que el dispositivo lo renueve, o recupéralo. Consulta Certificados de dispositivo. |
| El perfil no permite este tipo de inicio de sesión | Allowed authentication en la pestaña Transport & auth del perfil |
| La dirección del dispositivo está fuera de las Allowed networks del perfil | Añade la red, o comprueba qué dirección pública usa realmente tu sede (NAT, operador móvil) |
| MQTT sin cifrar en un perfil solo TLS | Usa el puerto 8883 |
| La organización está suspendida | Pide a un propietario de la organización. Consulta Organizaciones e inquilinos. |
| Se ha alcanzado el límite de dispositivos o de dispositivos conectados del plan | Consulta Planes y el complemento IoT |
Por HTTP, las mismas comprobaciones responden 401 (token ausente o desconocido), 403 (deshabilitado, suspendido, fuera de las redes permitidas, o un sondeo de comandos por HTTP sin cifrar que el perfil no permite: tls_required) o 404 (un token en la URL en un perfil sin Token in the URL). Consulta API HTTP del dispositivo.
Recordatorios de inicio de sesión
| Credencial | ID de cliente | Usuario | Contraseña |
|---|---|---|---|
| Token de acceso | cualquier ID válido | el token | vacío |
| MQTT básico | cualquiera, o el fijado | el nombre de usuario | la contraseña |
| Certificado X.509 | el número de serie del dispositivo, igual al CN del certificado | ignorado | vacío |
El secreto de una credencial se muestra una sola vez, al crearla o rotarla. Si se perdió, rótala y actualiza el dispositivo. Consulta Credenciales de dispositivo.
Paso 3: El dispositivo se conecta y luego se desconecta
La pestaña Log indica el motivo de la desconexión:
| Motivo | Significado | Solución |
|---|---|---|
keepalive_timeout | No llegó nada dentro del tiempo de keepalive | Usa un keepalive de 30 a 300 segundos y envía PINGREQ; revisa el enlace móvil |
takeover | Una segunda conexión del mismo dispositivo tomó el control | Dos dispositivos comparten una credencial, o un cliente se reconecta sin cerrar el socket anterior. Da a cada dispositivo su propia credencial. |
auth_revoked | La credencial, el dispositivo o la organización ya no están permitidos | Las sesiones se revalidan aproximadamente cada 60 segundos; una credencial rotada finaliza la sesión anterior |
rate_limit | El dispositivo superó repetidamente su límite de tasa (más de tres veces su cupo por minuto descartado en un minuto) | Agrupa las lecturas, envía con menos frecuencia o aumenta los límites del perfil |
inflight_exceeded | Demasiados mensajes QoS 1 sin confirmar (20 por defecto) | Espera los PUBACK antes de enviar más |
server_shutdown | Se reinició un nodo del broker | Reconecta; no hay nada que corregir |
uplink_window_expired | Terminó la ventana en línea de Recent message | Esperado en dispositivos que solo se conectan para enviar |
protocol_error, socket_error | El cliente incumplió el protocolo, o la red falló | Actualiza el cliente; revisa el enlace |
Un dispositivo cuya sesión es tomada repetidamente desde dos redes queda retenido durante un tiempo, y tus administradores reciben un aviso de «takeover fight».
Paso 4: El dispositivo se conecta, pero aparece como desconectado
| Causa | Comprobación |
|---|---|
| La regla de estado en línea del perfil | Live connection, Recent message o Last seen only determinan qué significa «en línea». Consulta Estado de conexión y actividad. |
| Cuarentena | Un dispositivo autorregistrado que espera en cuarentena se conecta, pero sus datos se confirman y se descartan hasta que un administrador lo active. Consulta Cuarentena. |
| El dispositivo es hijo de una pasarela | Su estado proviene de los mensajes v1/gw/connect y v1/gw/disconnect de la pasarela. Consulta Dispositivos detrás de una pasarela. |
Un dispositivo mal configurado bloquea a otros
Los inicios de sesión fallidos repetidos desde una dirección bloquean esa dirección durante un breve tiempo, para cada dispositivo detrás de ella. Varios dispositivos tras un mismo NAT o router móvil son entonces rechazados con CONNACK 3 (HTTP 429). Localiza el dispositivo con credenciales incorrectas (su pestaña Log muestra los fallos), corrígelo y deja que los demás reintenten con retroceso.
Comportamiento recomendado del dispositivo
- Conéctate por TLS usando el nombre de host, con un keepalive entre 30 y 300 segundos.
- Tras CONNACK 0, suscríbete a los topics de downlink, pide los atributos compartidos, informa los atributos de cliente y luego envía las lecturas en búfer.
- Ante un rechazo, aplica retroceso: reintenta CONNACK 3 con jitter; espera al menos 5 minutos tras CONNACK 4; deja de reintentar CONNACK 1 y 2 hasta que cambie la configuración.
Consulta MQTT.