Dépannage

Dépannez les intégrations MQTT par phase d’échec — connexion au broker, TLS, authentification, routage des topics, dernière donnée.

Recettes de diagnostic pour les intégrations MQTT sur le serveur Kilo IoT, organisées selon l’endroit où l’échec se manifeste. Parcourez-les dans l’ordre — la plupart des problèmes se rangent dans l’une des trois premières phases, et la séquence de diagnostic permet de cerner efficacement la cause racine.

Avant de parcourir les phases ci-dessous, laissez la plateforme vous indiquer dans laquelle vous vous trouvez. Un seul appareil silencieux signale son propre état dans son Connexion onglet — à savoir si le broker est joignable, si une publication est arrivée sur un topic inattendu et si ses valeurs ont été enregistrées ; voir Diagnostics de l’appareil. Lorsque plusieurs appareils se taisent d’un coup, ouvrez la diagnostics du connecteur zone — État de la source résume l’abonnement au broker, Entrant montre ce qui arrive, et Activité montre l’historique récent des événements du connecteur. Cette lecture indique généralement directement la phase à partir de laquelle commencer.

Phase 1 — Échecs de connexion au broker

Symptôme : l’émetteur (une passerelle de périphérie, une instance Zigbee2MQTT, un firmware personnalisé) indique qu’il ne peut pas se connecter au broker. Dernières données reçues ne se met jamais à jour.

Schéma d’échec	Cause racine	Résolution
connexion refusée / réseau injoignable (MQTT Cloud)	Hôte, port ou schéma incorrects	Vérifiez que l’émetteur utilise mqtts:// sur le port 1884 — et non le 1883 par défaut. Recopiez l’URL du broker depuis la page du connecteur.
connexion refusée / réseau injoignable (MQTT externe)	Joignabilité réseau	La plateforme se connecte à votre broker. Vérifiez que le broker est joignable depuis Internet public (le nom d’hôte DDNS résout, le transfert de port est actif, le pare-feu autorise la plage de sortie de la plateforme).
échec de poignée de main TLS / la vérification du certificat a échoué	Configuration TLS	Pour Cloud MQTT, le certificat est approuvé publiquement — vérifiez que l’émetteur utilise le magasin CA système. Pour External MQTT, vérifiez que les fichiers Certificat CA, Certificat client et Clé privée ont été téléversés en tant que fichiers séparés (et non collés en contenu PEM), et que la Clé privée était non chiffrée lors du téléversement.
échec de l’authentification / non autorisé	Identifiants incorrects	Revérifiez le nom d’utilisateur et le mot de passe. Pour Cloud MQTT, si le mot de passe a été perdu, faites-le tourner depuis les paramètres du connecteur (l’original n’est pas récupérable). Pour l’authentification de base sur External MQTT, vérifiez que le fichier de mots de passe du broker est correct.
échec d’authentification (JWT)	Problèmes de jeton	Vérifiez que le JWT est valide (non expiré), signé avec la bonne clé pour le validateur du broker, et qu’il contient les revendications requises (sujet, autorisations de topic).

Pour les configurations reliées à Z2M en particulier, le journal Z2M affiche explicitement l’état de connexion :

docker compose logs zigbee2mqtt | grep -E "Connecting|Connected|MQTT|Error"

Connecté au serveur MQTT confirme le côté émetteur. L’absence de cette ligne indique un échec de phase 1, quel que soit ce qu’affiche la plateforme.

Phase 2 — La connexion réussit mais Dernières données reçues ne se met pas à jour

Symptôme : l’émetteur signale une connexion réussie au broker. Les journaux montrent des publications réussies. Dernières données reçues dans la page du connecteur Kilo reste vide.

Pour Cloud MQTT, il s’agit d’une discordance du préfixe de topic. Chaque topic publié doit commencer exactement par le préfixe de topic du connecteur. Vérifiez :

• La configuration de topic de l’émetteur utilise le préfixe complet de topic de la page du connecteur (généralement iot/{org}/{connection}).

• Pour Z2M, mqtt.base_topic dans configuration.yaml est {Topic prefix}/zigbee2mqtt.

• Pour un firmware personnalisé, chaque appel de publication ajoute le préfixe.

Pour External MQTT, il s’agit d’un problème de joignabilité ou d’abonnement :

• Exécutez une publication de test unique depuis un hôte qui peut atteindre votre broker :

  mosquitto_pub -h {broker-host} -p {port} \\
    --cafile {ca-bundle} \\
    -u {username} -P {password} \\
    -t "test/connectivity" -m '{"hello":"world"}'

  Si Dernières données reçues ne se met toujours pas à jour, la plateforme ne peut pas atteindre votre broker. Examinez les règles de pare-feu, les listes d’autorisation d’IP, ou les sessions de tunneling expirées lorsque vous utilisez ngrok pour les tests.

• Pour les brokers derrière un NAT avec redirection de port, vérifiez que le port externe est ouvert et redirigé vers le port hôte du broker. Les erreurs de configuration courantes incluent la redirection vers la mauvaise IP d’hôte, le blocage de l’IP source, ou une règle de pare-feu qui prend le pas sur la redirection de port.

Phase 3 — Les Dernières données reçues se mettent à jour mais l’onglet Mapping de l’appareil est vide

Symptôme : le connecteur reçoit des messages (Dernières données reçues est à jour), mais la colonne Valeur de l’onglet Mapping d’un appareil enregistré n’affiche rien.

Deux causes sont fréquentes :

• Le modèle de topic de l’ID d’appareil ne correspond pas au topic de publication. Vérifiez le modèle en le comparant caractère par caractère à un topic issu des journaux de l’émetteur. Erreurs courantes : barre oblique initiale, segments intermédiaires manquants, casse différente, pluralité différente (mètre contre mètres).

• L’ID de l’appareil est différent caractère par caractère du segment extrait. La suppression des espaces dans le champ ID de l’appareil est ici le tueur silencieux. Si le topic de l’émetteur est plant-3/line-a/EM 4492/data (contenant un espace) et que l’ID de l’appareil a été saisi comme EM 4492, la plateforme a enregistré une chaîne normalisée qui ne correspond plus. Supprimez les espaces des identifiants d’appareil — utilisez des tirets ou des underscores. Recréez l’enregistrement de l’appareil avec l’identifiant normalisé.

Pour vérifier ce que l’émetteur envoie réellement :

# Pour Z2M :
docker compose logs zigbee2mqtt | grep "MQTT publish" | grep -v bridge | tail -5

# Pour les autres passerelles : abonnez-vous directement au broker
mosquitto_sub -h {broker} -p {port} -t '#' -v

Le topic affiché dans ces lignes de sortie est le topic auquel votre modèle de topic d’ID d’appareil et le champ ID d’appareil doivent correspondre.

Phase 4 — La colonne Valeur de l’onglet Mapping se met à jour mais l’onglet Logs est vide

Symptôme : Ouvrez un appareil enregistré. L’onglet Mapping affiche des valeurs en direct et des horodatages de Dernière mise à jour. L’onglet Logs est vide.

C’est la confusion opérationnelle la plus courante lors de la mise en service d’un nouvel appareil MQTT. Les deux onglets lisent dans des stockages différents :

• Colonne Valeur de l’onglet Mapping = instantané en direct de la charge utile la plus récente. Se met à jour à chaque publication acceptée, que les clés du connecteur soient renseignées ou non.

• Onglet Logs = historique par capteur, alimenté uniquement par les publications reçues après l’enregistrement des clés du connecteur.

Si la publication la plus récente est arrivée avant l’enregistrement des clés du connecteur, cette publication n’atteint jamais les Logs. Les publications plus anciennes ne sont pas normalisées rétroactivement.

Résolution : générez une nouvelle publication après avoir enregistré les clés du connecteur. Méthodes :

• Attendez la prochaine remontée planifiée de l’appareil — pour les capteurs à cadence de publication périodique.

• Déclenchez un changement d’état sur l’appareil — pour les actionneurs avec sémantique COV au changement d’état.

• Émettez une requête d’interrogation depuis la passerelle — pour les passerelles avec un mécanisme de lecture/polling de type /get-style.

• Envoyez une publication de test depuis le côté broker — pour les scénarios de développement, mosquitto_pub vers le topic de l’appareil avec une charge utile représentative.

Après qu’au moins une publication est arrivée après l’enregistrement, l’onglet Logs se remplit et continue de recevoir le trafic suivant.

Phase 5 — valeurs nulles dans la colonne Valeur de l’onglet Mapping

Symptôme : Les clés du connecteur sont mappées, l’onglet Logs reçoit des données, mais certaines valeurs de métriques apparaissent comme null dans l’onglet Mapping.

La cause la plus courante : le Type du modèle de métrique ne correspond pas au type de la valeur publiée. Par exemple, associer un champ Z2M state ("ON"/"OFF" chaînes) à un modèle de métrique typé Booléen entraîne des valeurs nulles — la plateforme ne peut pas analyser la chaîne comme un booléen.

Vérifiez la translation du type de charge utile vers le type de métrique:

• Les énumérations codées en chaîne (par ex. "OPEN"/"CLOSED", "ON"/"OFF") → Chaîne, pas Booléen.

• Z2M binaires caractéristiques → Chaîne. Z2M numériques caractéristiques → Nombre. Z2M énumérées caractéristiques → Chaîne.

Résolution : modifiez le modèle de métrique (ou remplacez la ligne de Mapping par une ligne utilisant le bon type de modèle) afin que le Type corresponde au type réel de la valeur de la charge utile.

Phase 6 — Valeurs de métriques incohérentes ou dupliquées sur plusieurs appareils

Symptôme : deux enregistrements d’appareil semblent recevoir la télémétrie l’un de l’autre, ou un seul appareil affiche des valeurs alternant entre différentes sources.

Il s’agit d’une collision de modèle de topic de l’ID d’appareil. Si deux appareils publient sur des topics qui correspondent tous deux à un seul modèle de topic d’ID d’appareil à des {{deviceId}} valeurs, mais que le champ ID de l’appareil sur un enregistrement correspond aux deux, les deux publications sont routées vers cet enregistrement.

Vérifiez :

• Chaque enregistrement d’appareil a un ID d’appareil unique.

• Les topics côté publication produisent des valeurs uniques à la position du {{deviceId}} placeholder.

• Aucun émetteur n’est mal configuré pour publier sous l’identifiant d’un autre appareil.

Réinitialisation des identifiants Cloud MQTT

Lorsqu’un identifiant doit être renouvelé :

1. Ouvrez la page de détail du connecteur.

2. En mode édition, régénérez le mot de passe.

3. Capturez immédiatement le nouveau mot de passe ; l’original n’est pas récupérable après régénération.

4. Mettez à jour tous les clients émetteurs (configuration du firmware, Z2M configuration.yaml, configuration de la passerelle de périphérie) avec le nouveau mot de passe.

5. Redémarrez les émetteurs pour prendre en compte la rotation.

Le nom d’utilisateur et le préfixe de topic ne changent pas lors de la rotation.

Réinitialisation des identifiants External MQTT

Pour l’authentification de base, changez le mot de passe côté broker et mettez à jour la configuration d’authentification du connecteur. Pour la certification (certificat client TLS), réémettez le certificat client et téléversez-le à nouveau. Pour JWT, régénérez le jeton et mettez à jour le connecteur. Dans tous les cas, il n’existe pas de flux de rotation des identifiants côté plateforme — l’identifiant se trouve sur le broker ; la plateforme stocke une référence.

Où aller ensuite

• Topics et routage des appareils — pour les détails de configuration du routage.

• External MQTT — pour la configuration côté broker des brokers auto-hébergés.

• Passerelles Edge MQTT — pour les schémas d’intégration des passerelles industrielles de périphérie (dans Passerelles).