Cette page vous aide lorsqu’un appareil ne peut pas se connecter à Hermetry, est refusé à la connexion ou perd sans cesse sa connexion. Elle couvre MQTT et l’API HTTP des appareils. Pour les appareils LoRaWAN, voir Dépannage des joins ; pour les appareils en interrogation (polling), voir Intervalles d’interrogation, temporisation et quota.
Où regarder en premier
| Emplacement | Affiche |
|---|---|
| L’onglet Log de l’appareil | Chaque refus de connexion avec son motif, et chaque déconnexion avec son motif. Le motif d’un refus n’est jamais envoyé à l’appareil : il n’est disponible qu’ici. |
| La carte Connection details de l’appareil | L’hôte du broker et les ports que votre appareil doit utiliser |
| Le journal du client | Le code CONNACK ou le statut HTTP reçu, ou l’erreur TLS |
Étape 1 : l’appareil peut-il atteindre le broker ?
| Symptôme sur l’appareil | Cause | Correctif |
|---|---|---|
| La résolution DNS échoue, ou la connexion expire | Mauvais hôte, ou un pare-feu bloque le port sortant | Utilisez l’hôte indiqué sur la carte Connection details, pour la région de votre organisation. Autorisez le TCP sortant 8883 (et 443 pour HTTPS). |
| La négociation TLS échoue | L’appareil se connecte par adresse IP (SNI est requis), n’a pas de bundle d’autorités de certification, ou son horloge est très décalée, ce qui fait paraître le certificat invalide | Connectez-vous par nom d’hôte ; utilisez le magasin de CA du système ; réglez l’horloge (NTP) |
| TLS échoue sur un appareil très petit | Il ne prend en charge que d’anciennes suites de chiffrement ou TLS 1.0/1.1 | TLS 1.2 est le minimum, avec des suites ECDHE et GCM ou ChaCha20. Mettez à jour la bibliothèque TLS. |
| Le port 1883 est refusé | Le profil est TLS only (port 8883), la valeur par défaut | Utilisez le 8883 ou, uniquement sur un réseau privé, autorisez le MQTT non chiffré sur le profil |
| Un certificat client est rejeté pendant la négociation | Le certificat ne provient pas de la CA d’appareils d’Hermetry, ou il a été révoqué | Un certificat non approuvé met fin à la négociation ; il n’existe aucun repli vers un mot de passe. Voir Certificats des appareils. |
Voir Sécurité du transport des appareils.
Étape 2 : la connexion est-elle acceptée ?
MQTT répond au CONNECT par un code CONNACK :
| CONNACK | Signification | Causes habituelles |
|---|---|---|
| 1 | Version de protocole non prise en charge | Le client envoie MQTT 5. Hermetry parle MQTT 3.1.1. |
| 2 | Identifiant client rejeté | L’identifiant client est vide, dépasse 64 caractères ou contient des caractères hors de A–Z a–z 0–9 . _ : - |
| 3 | Serveur indisponible | Le service démarre ou est occupé, ou votre adresse est temporairement bloquée après des connexions échouées répétées. Patientez et réessayez avec une gigue aléatoire. |
| 4 | Nom d’utilisateur ou mot de passe incorrect | Le jeton ou le mot de passe est erroné, a été renouvelé ou révoqué ; un nom d’utilisateur sans mot de passe est lu comme un jeton d’accès |
| 5 | Non autorisé | Voir le tableau ci-dessous. Le motif exact figure dans l’onglet Log de l’appareil. |
| Motif du CONNACK 5 | Correctif |
|---|---|
| L’appareil est désactivé | Activez-le sur la page de l’appareil |
| Le certificat est révoqué ou expiré | Laissez l’appareil le renouveler, ou récupérez-le. Voir Certificats des appareils. |
| Le profil n’autorise pas ce type de connexion | Allowed authentication dans l’onglet Transport & auth du profil |
| L’adresse de l’appareil est en dehors des Allowed networks du profil | Ajoutez le réseau, ou vérifiez l’adresse publique réellement utilisée par votre site (NAT, opérateur mobile) |
| MQTT non chiffré sur un profil TLS uniquement | Utilisez le port 8883 |
| L’organisation est suspendue | Adressez-vous à un propriétaire de l’organisation. Voir Organisations et locataires. |
| La limite d’appareils ou d’appareils connectés du forfait est atteinte | Voir Forfaits et l’extension IoT |
En HTTP, les mêmes contrôles répondent 401 (jeton absent ou inconnu), 403 (désactivé, suspendu, hors des réseaux autorisés, ou une interrogation de commandes en HTTP non chiffré que le profil n’autorise pas : tls_required) ou 404 (un jeton dans l’URL sur un profil sans Token in the URL). Voir API HTTP des appareils.
Rappels de connexion
| Identifiant | Client ID | Nom d’utilisateur | Mot de passe |
|---|---|---|---|
| Jeton d’accès | tout ID valide | le jeton | vide |
| MQTT basique | au choix, ou celui épinglé | le nom d’utilisateur | le mot de passe |
| Certificat X.509 | le numéro de série de l’appareil, égal au CN du certificat | ignoré | vide |
Le secret d’un identifiant n’est affiché qu’une fois, à sa création ou à son renouvellement. S’il a été perdu, renouvelez-le et mettez à jour l’appareil. Voir Identifiants des appareils.
Étape 3 : l’appareil se connecte, puis se déconnecte
L’onglet Log indique le motif de la déconnexion :
| Motif | Signification | Correctif |
|---|---|---|
keepalive_timeout | Rien n’est arrivé pendant la durée du keepalive | Utilisez un keepalive de 30 à 300 secondes et envoyez des PINGREQ ; vérifiez la liaison mobile |
takeover | Une seconde connexion du même appareil a pris le relais | Deux appareils partagent un même identifiant, ou un client se reconnecte sans fermer l’ancien socket. Donnez à chaque appareil son propre identifiant. |
auth_revoked | L’identifiant, l’appareil ou l’organisation n’est plus autorisé | Les sessions sont revérifiées environ toutes les 60 secondes ; un identifiant renouvelé met fin à l’ancienne session |
rate_limit | L’appareil a continué à dépasser sa limite de débit (plus de trois fois son quota par minute rejetées en une minute) | Regroupez les mesures, envoyez moins souvent, ou augmentez les limites du profil |
inflight_exceeded | Trop de messages QoS 1 non acquittés (20 par défaut) | Attendez les PUBACK avant d’en envoyer d’autres |
server_shutdown | Un nœud du broker a redémarré | Reconnectez-vous ; rien à corriger |
uplink_window_expired | La fenêtre de connexion Recent message est terminée | Attendu pour les appareils qui se connectent uniquement pour émettre |
protocol_error, socket_error | Le client n’a pas respecté le protocole, ou le réseau a échoué | Mettez à jour le client ; vérifiez la liaison |
Un appareil dont la session est repris à plusieurs reprises depuis deux réseaux est temporairement mis en attente, et vos administrateurs reçoivent une notification de « takeover fight ».
Étape 4 : l’appareil se connecte, mais apparaît hors ligne
| Cause | Vérification |
|---|---|
| La règle de connexion du profil | Live connection, Recent message ou Last seen only déterminent ce que signifie « en ligne ». Voir État de connexion et activité. |
| Quarantaine | Un appareil auto-enregistré placé en quarantaine se connecte, mais ses données sont acquittées et rejetées jusqu’à ce qu’un administrateur l’active. Voir Quarantaine. |
| L’appareil est un enfant de passerelle | Son état provient des messages v1/gw/connect et v1/gw/disconnect de la passerelle. Voir Appareils derrière une passerelle. |
Un appareil mal configuré bloque les autres
Des connexions échouées répétées depuis une même adresse bloquent cette adresse pendant un court instant, pour chaque appareil derrière elle. Plusieurs appareils derrière un même NAT ou routeur mobile sont alors tous refusés avec CONNACK 3 (HTTP 429). Repérez l’appareil aux identifiants erronés (son onglet Log affiche les échecs), corrigez-le, et laissez les autres réessayer avec temporisation.
Comportement recommandé de l’appareil
- Connectez-vous en TLS par nom d’hôte, avec un keepalive compris entre 30 et 300 secondes.
- Après CONNACK 0, souscrivez aux topics de descente, demandez les attributs partagés, publiez les attributs client, puis envoyez les mesures mises en mémoire tampon.
- En cas de refus, temporisez : réessayez après CONNACK 3 avec une gigue aléatoire ; attendez au moins 5 minutes après CONNACK 4 ; arrêtez de réessayer après CONNACK 1 et 2 tant que la configuration n’a pas changé.
Voir MQTT.

