> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector.md). # Connecteur MQTT Faites entrer des appareils compatibles MQTT dans Kilo IoT — Cloud MQTT (broker provisionné par la plateforme) ou MQTT externe (le vôtre via un pont). Le connecteur MQTT vous permet d’intégrer n’importe quel appareil compatible MQTT dans le Kilo IoT Server sans passer par LoRaWAN. Les automates programmables d’usine, les contrôleurs CVC, les compteurs d’énergie des bâtiments, les passerelles de périphérie produisant du MQTT (ponts Modbus-to-MQTT, BACnet-to-MQTT, OPC-UA-to-MQTT), ainsi que les capteurs à firmware personnalisé qui publient déjà des données via MQTT peuvent tous être connectés directement. Une fois connectées, leurs données transitent par le même pipeline de normalisation, déclenchent le même moteur de règles et apparaissent dans les mêmes tableaux de bord que tous les autres appareils du serveur. Deux variantes sont disponibles : | Variante | Comment le broker est fourni | Limite | Idéal pour | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **External MQTT** | Votre propre broker — hébergé dans le cloud, sur site, ou dans un réseau d’installation, tant qu’il est accessible par la plateforme | Jusqu’à 10 par organisation | Connexion d’une infrastructure existante qui publie déjà vers MQTT | | **Cloud MQTT** | Fournie par la plateforme — le serveur fournit un point de terminaison de broker dédié et des identifiants pour chaque connecteur | Illimité | Nouveaux déploiements, pilotes et sites distants où vous souhaitez ingérer du MQTT sans gérer vous-même l’infrastructure du broker | Utilisez MQTT externe lorsque vous avez déjà un broker en fonctionnement. Utilisez Cloud MQTT lorsque vous souhaitez que la plateforme en fournisse un — vous donnez un nom au connecteur, la plateforme provisionne le reste.
The Add connector dialog with External MQTT and Cloud MQTT in the connector type list
> **Portée.** Cette documentation couvre l’ingestion de télémétrie MQTT et le mappage des appareils. L’envoi de commandes dans l’autre sens — le contrôle d’un appareil connecté via des downlinks — se configure pour chaque appareil sous [Commandes de l’appareil](/kilo-docs-fr/kilo-iot-server/devices/commands.md). ## Dans cette section * [Qu’est-ce que MQTT](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/what-is-mqtt.md) — Introduction au protocole pour les ingénieurs qui découvrent MQTT ou qui rafraîchissent le modèle. * [Cloud MQTT](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/cloud-mqtt.md) — Provisionnement d’un broker géré par la plateforme pour un connecteur. * [External MQTT](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md) — Connexion d’un broker existant, y compris l’accessibilité réseau, l’authentification et la vérification. * [Topics et routage des appareils](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — Comment les modèles de topics, l’extraction de l’ID d’appareil et l’onglet Mapping fonctionnent ensemble. À lire avant d’enregistrer des appareils. * [Dépannage](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) — Diagnostic des problèmes de connexion, de correspondance des topics et de l’onglet Logs. Pour la partie matérielle / passerelle de périphérie de l’intégration — ponts Modbus, BACnet, OPC-UA, Sparkplug B et Zigbee2MQTT qui publient du MQTT vers le connecteur — voir [Passerelles Edge MQTT](/kilo-docs-fr/kilo-iot-server/gateways/mqtt-edge-gateways.md) dans la section Passerelles. *** ## Ajout d’un connecteur MQTT externe 1. Accédez à **Connecteurs** dans la barre latérale. 2. Cliquez sur **Ajouter un connecteur**. 3. Sélectionner **External MQTT** depuis le **type de connecteur** menu déroulant. 4. Remplissez le formulaire de configuration : | Champ | Obligatoire | Détails | | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Nom** | Oui | Nom d’affichage de ce connecteur | | **URL du broker** | Oui | URL complète avec schéma et port. Le broker doit être joignable sur le réseau depuis la plateforme — un broker accessible uniquement sur un réseau local isolé ne se connectera pas. Schémas acceptés : `mqtt://`, `mqtts://`, `tcp://`, `ssl://`. Exemple : `mqtts://broker.facility.example.com:8883` | 5. Choisissez une **méthode d’authentification** dans les onglets : | Méthode | À renseigner | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Anonyme** | Aucun identifiant requis | | **Basique** | Nom d’utilisateur et mot de passe (le mot de passe peut être affiché/masqué) | | **Certificat** | Trois boutons de téléversement de fichiers : **Certificat CA**, **Certificat client**, **Clé privée**. Téléversez chaque fichier — ne collez pas le contenu PEM | | **Jeton JWT** | Champ Jeton (afficher/masquer + copier). Le jeton est l’identifiant JWT requis. Un champ de téléversement de certificat apparaît dans le formulaire — il est facultatif ; la plateforme n’envoie que le jeton pour l’authentification JWT | 6. Cliquez sur **Ajouter**. Le connecteur apparaît dans le tableau des connecteurs. Cliquez sur sa ligne pour ouvrir la page de détails du connecteur. *** ## Ajout d’un connecteur Cloud MQTT 1. Accédez à **Connecteurs** dans la barre latérale. 2. Cliquez sur **Ajouter un connecteur**. 3. Sélectionner **Cloud MQTT** depuis le **type de connecteur** menu déroulant. 4. Saisissez un **Nom** pour le connecteur. 5. Cliquez sur **Ajouter**. La plateforme provisionne un point de terminaison de broker dédié et affiche les identifiants générés : | Identifiant | Détails | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **URL du broker** | Le point de terminaison MQTT géré. Copiez-le à l’aide du bouton de copie. | | **Préfixe de topic** | Tous les messages publiés vers ce connecteur doivent utiliser ce préfixe. Il permet de garder vos données organisées sous l’espace de noms attribué au connecteur. Copiez-le à l’aide du bouton de copie. | | **Nom d’utilisateur** | Attribué automatiquement. Copiez-le à l’aide du bouton de copie. | | **Mot de passe** | Affiché une seule fois. **Copiez-le immédiatement.** En cas de perte, faites pivoter les identifiants depuis les paramètres du connecteur — les appareils devront être reconfigurés avec le nouveau mot de passe. En mode édition, un bouton de régénération est disponible. | #### Connexion des appareils à Cloud MQTT Configurez vos appareils ou le logiciel de passerelle pour publier vers le point de terminaison fourni. Points clés avant la connexion : * **L’URL du broker est le point de terminaison complet** — copiez-la exactement telle qu’elle est affichée. Elle utilise MQTTS (TLS) sur le port 1884. Configurez vos appareils en conséquence ; ce n’est pas le port standard 1883. * **Tous les topics publiés doivent commencer par le préfixe de topic.** Le topic complet sur lequel votre appareil publie est `{Topic prefix}/{device topic}` — par exemple, si le préfixe est `iot/abc123/xyz789` et que votre appareil publie des relevés de puissance, vous pourriez publier sur `iot/abc123/xyz789/EM-4492/power`. * **Les modèles de routage sur l’appareil n’incluent pas le préfixe.** Lors de la configuration du Device ID Topic dans l’onglet Topic, saisissez uniquement la partie au niveau de l’appareil — par exemple `{{deviceId}}/power`. La plateforme supprime le préfixe avant le routage. Aucune infrastructure de broker n’est requise de votre côté — la plateforme gère le broker. *** ## Enregistrement d’un appareil sur MQTT Chaque appareil qui publie via un connecteur MQTT doit être enregistré individuellement. L’enregistrement mappe la structure des topics MQTT et le format du payload au modèle d’appareil du serveur. 1. Depuis la page de détails du connecteur, cliquez sur **Ajouter un appareil** — ou accédez à **Appareils → Enregistrement des appareils** et sélectionnez ce connecteur. 2. Renseignez les champs standard de l’appareil (nom, connecteur, modèle). > **ID de l’appareil = segment du topic, à l’octet près.** Tout ce que vous saisissez comme identifiant de l’appareil doit correspondre exactement au segment du topic au niveau de l’appareil que votre matériel publie. Le champ Device ID supprime les espaces, donc des identifiants comme `EM 4492` ne correspondront silencieusement pas à un appareil publiant sur `EM-4492`. Utilisez exactement la même chaîne dans l’enregistrement de l’appareil et du côté publication ; la casse est conservée et significative. 3. L’appareil s’ouvre avec un **Mappage** onglet. Dans Mapping, il y a deux sous-onglets : **Sujet** (où la plateforme apprend à trouver l’appareil dans le flux de topics) et **Mappage** (où vous mappez les clés du payload vers des métriques normalisées). La sélection de **Mappage** ouvre le **Sujet** sous-onglet d’abord ; cliquez sur **Suivant** ou sur l’onglet interne **Mappage** pour accéder aux lignes par clé. ### Topic L’onglet Topic indique au connecteur où trouver l’identifiant de l’appareil dans chaque message MQTT, et quels topics transportent les données de télémétrie. #### Sujet de l'ID de l'appareil *(obligatoire)* Le modèle de topic MQTT sur lequel cet appareil publie. Utilisez `{{deviceId}}` pour marquer le segment du topic qui contient l’identifiant de l’appareil. **Exemple :** Si votre compteur d’énergie publie sur `facility/meters/EM-4492/power`, saisissez : ``` facility/meters/{{deviceId}}/power ``` Le serveur extrait `EM-4492` de ce segment et achemine tous les messages correspondants vers le jumeau numérique de cet appareil. #### Où obtenir l'ID de l'appareil * **Sujet** *(par défaut)* — L’ID est extrait du `{{deviceId}}` segment du topic. * **Charge utile** — L’ID est pris à partir d’un champ à l’intérieur du payload JSON. Lorsqu’il est sélectionné, le **Chemin du payload de l’ID de l’appareil** champ devient obligatoire. #### Chemin du payload de l’ID de l’appareil *(affiché lorsque source = Payload)* Un chemin en notation par points vers le champ d’ID de l’appareil dans le payload JSON. **Exemple :** Pour un payload `{"device": {"id": "EM-4492"}, "power": 4.2}`, saisissez : ``` device.id ``` #### Sujets de télémétrie *(facultatif)* Les lignes de topics de télémétrie définissent comment les mesures individuelles sont extraites des messages MQTT. Elles sont facultatives. Pour les appareils qui publient un payload JSON plat sur un seul topic — comme les systèmes de gestion technique du bâtiment ou les PLC publiant un objet d’état — vous pouvez ignorer entièrement cette section. Le serveur analyse automatiquement toutes les clés du payload JSON, y compris les objets imbriqués, qui sont aplatis en chemins en notation par points (par exemple, `{"device": {"temperature": 22.5}}` devient accessible sous `device.temperature`). L’onglet Mapping reste néanmoins requis — chaque clé de payload a besoin d’une ligne correspondante avec une Clé du connecteur correspondante pour devenir une métrique normalisée de la plateforme. N’ajoutez des lignes de topics de télémétrie que lorsque vous avez besoin d’un contrôle explicite par topic : par exemple, lorsque les valeurs de métrique sont intégrées dans le chemin du topic plutôt que dans le payload, ou lorsque vous souhaitez renommer certaines métriques. | Champ | Détails | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Topic MQTT pour la télémétrie** | Modèle de topic pour cette ligne de métrique, en utilisant `{{deviceId}}` l’espace réservé | | **Clé du connecteur** | Désigne la clé source arrivant depuis MQTT. Cette clé doit correspondre à ce que l’appareil publie. La Clé du connecteur ne crée pas à elle seule une métrique de la plateforme — c’est dans l’onglet Mapping qu’elle est reliée à une métrique normalisée. | **Ajouter un nouveau topic** — ajoute une ligne de topic de télémétrie. **Appliquer tout** — utilise le modèle de topic de l’ID de l’appareil comme préfixe pour générer des modèles de topics de télémétrie pour les lignes qui ont déjà une Clé du connecteur renseignée. Il génère des modèles par topic à partir du topic de l’ID de l’appareil — il ne copie pas la valeur du topic de l’ID de l’appareil mot pour mot. #### Référence des espaces réservés | Espace réservé | Où il est utilisé | Ce qu'il fait | | -------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{{deviceId}}` | Topic d’ID de l’appareil, modèles de topics de télémétrie | Marque le segment du topic contenant l’identifiant de l’appareil | | `{{value}}` | Modèles de topics de télémétrie | Marque un segment de topic dont le contenu est la valeur de mesure elle-même — par exemple, `meters/EM-4492/230.5` où `230.5` est la mesure. N’utilisez pas `{{value}}` pour les segments de topic qui nomment la métrique (comme `power` ou `voltage`) — si le segment est une étiquette plutôt qu’une valeur, utilisez plutôt l’approche de type payload | *** ### Onglet Mapping L’onglet Mapping relie les données MQTT entrantes aux métriques normalisées de la plateforme. C’est ici que les valeurs brutes de l’appareil deviennent des données de capteur interrogeables dans le Jumeau numérique. La Clé du connecteur dans l’onglet Mapping doit correspondre à la clé publiée dans le message MQTT (ou à la Clé du connecteur définie dans l’onglet Topic). Sans correspondance, les données sont ignorées silencieusement — le texte d’aide au-dessus du tableau le confirme : **« Si la clé du connecteur n’est pas renseignée, les données seront ignorées. »** Le tableau comporte 8 colonnes : | Colonne | Type | Détails | | ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------- | | **Clé normalisée** | Liste déroulante | Sélectionnez parmi les modèles de capteurs ; comprend une option « + Ajouter une nouvelle métrique » | | **Unité** | Lecture seule | Dérivé du modèle sélectionné | | **Type** | Lecture seule | Entier, flottant, chaîne ou booléen — dérivé du modèle | | **Type de données** | Liste déroulante | État déclaré, télémétrie ou métadonnées de l’appareil | | **Clé du connecteur** | Liste déroulante | Répertorie les clés reçues du payload de cet appareil. Vide jusqu’à ce qu’au moins une publication soit arrivée | | **Valeur** | Lecture seule | Valeur active actuelle reçue du broker | | **Dernière mise à jour** | Lecture seule | Horodatage de la valeur la plus récemment reçue | | **Actions** | Icône | L’icône de corbeille supprime la ligne | **Ajouter une clé** — ajoute une nouvelle ligne de mappage vide. #### État déclaré vs télémétrie Les **Type de données** la liste déroulante distingue deux catégories opérationnelles : * **État signalé** — propriétés d’appareil contrôlables dont l’appareil publie la valeur actuelle. Le point de consigne d’un contrôleur CVC, l’état marche/arrêt d’un actionneur intelligent, l’état ouvert/fermé d’une vanne. Ce sont des valeurs que l’appareil peut aussi être commandé à modifier. * **Télémétrie** — mesures en lecture seule. Sondes de température, relevés de compteurs d’énergie, valeurs RMS de vibration, qualité de liaison. Ce sont des observations que l’appareil fait sur lui-même ou sur son environnement. Choisissez le type qui correspond à l’intention opérationnelle de la valeur. L’État déclaré convient aux champs d’automate et aux points de consigne configurables ; la Télémétrie convient aux relevés de capteurs et au diagnostic. #### La liste déroulante Clé du connecteur est vide jusqu’à ce que l’appareil publie une première fois Les **Clé du connecteur** La colonne est une liste déroulante alimentée par les clés du payload réellement reçues depuis l’appareil — pas une saisie en texte libre. Avant l’arrivée de la première publication, la liste déroulante est vide et les lignes ne peuvent pas être complétées. L’enregistrement d’un appareil MQTT est donc un workflow en deux passes : 1. Ajoutez une ligne par métrique, sélectionnez le **Clé normalisée** dans la liste déroulante des modèles (ou utilisez **+ Ajouter une nouvelle métrique** pour en créer un), définissez le **Type de données**, et laissez le **Clé du connecteur** vide. 2. Cliquez sur **Enregistrer**L’enregistrement de l’appareil est sauvegardé. 3. Confirmez que l’appareil publie — pour une passerelle de périphérie produisant du MQTT, que le processus de la passerelle est en cours d’exécution et que l’appareil a émis au moins un message. 4. Rouvrez l’appareil. La **Clé du connecteur** liste déroulante liste maintenant les clés reçues lors des publications les plus récentes. 5. Associez une clé à chaque ligne de mappage. 6. Cliquez sur **Enregistrer** à nouveau. #### Colonne Value de l'onglet Mapping vs historique de l'onglet Logs La colonne de l’onglet Mapping **Valeur** reflète le payload le plus récent — un instantané en direct. Les valeurs apparaissent ici dès que la correspondance des topics réussit, avant même que les clés du connecteur ne soient renseignées. Les **Journaux** l'onglet est l'historique par capteur. Il n'est alimenté que par les publications qui arrivent *après* Les clés du connecteur sont enregistrées. Après la deuxième passe du workflow ci-dessus, effectuez une nouvelle publication (un réveil à l’événement depuis l’appareil, un rapport planifié ou, pour les passerelles de développement, une requête de sondage) pour confirmer que l’onglet Logs reçoit des enregistrements. #### Le mappage est itératif — revisitez-le une fois les données arrivées Le mappage MQTT n’est pas une opération en une seule fois. L’enregistrement initial repose souvent sur l’anticipation par l’opérateur de ce que l’appareil ou la passerelle de périphérie publiera ; le premier payload réel révèle fréquemment des clés supplémentaires — champs de diagnostic définis par le fournisseur, champs d’état non documentés, objets imbriqués avec des sous-chemins utiles. Considérez l’onglet Mapping comme un endroit à revisiter : 1. Après que des données en direct ont circulé pendant une période représentative, rouvrez l’enregistrement de l’appareil. 2. Inspectez la **Clé du connecteur** liste déroulante et la **Valeur** colonne pour voir ce que l’appareil publie réellement. 3. Ajoutez des lignes de Mapping pour les champs que le déploiement souhaite désormais suivre (un champ de diagnostic pour la maintenance prédictive, un champ d’état devenu opérationnellement pertinent, une sous-métrique de vibration imbriquée, etc.). 4. Choisissez la bonne clé normalisée et le bon type de données pour chaque nouvelle ligne. 5. Enregistrez. 6. Déclenchez une nouvelle publication afin que l’onglet Logs commence à collecter l’historique des nouveaux mappages. Ce raffinement itératif est le workflow attendu, en particulier pour les parcs mixtes de plusieurs fournisseurs où les schémas de payload varient subtilement selon les révisions de firmware de dispositifs nominalement identiques. #### Traduction du type de payload vers le type de métrique Lorsqu’un appareil publie un état énuméré sous forme de chaîne (par exemple, un actionneur publiant `"OPEN"`/`"CLOSED"`, ou un champ Zigbee `state` avec `"ON"`/`"OFF"`), la valeur arrive sous forme de chaîne — même si le type conceptuel est binaire. Mappez-les vers le **Chaîne** Type du modèle de métrique, et non vers Booléen. Sélectionner Booléen pour une énumération encodée en chaîne entraînera des valeurs nulles. Pour les appareils bridgés par Zigbee2MQTT en particulier, le [zigbee2mqtt.io](https://www.zigbee2mqtt.io/supported-devices/) listent chaque fonctionnalité avec un type — traduisez comme suit : | Type de fonctionnalité Z2M | Type de métrique | Notes | | -------------------------- | ---------------- | ------------------------------------------------------------- | | `binaires` | **Chaîne** | Les valeurs sont `"ON"`/`"OFF"` des chaînes, pas des booléens | | `numériques` | **Number** | Plages numériques mappées directement | | `énumérées` | **Chaîne** | Les valeurs énumérées arrivent sous forme de chaînes | | `text` | **Chaîne** | Texte libre | #### Comment découvrir quelles clés un appareil publie L’onglet Mapping ne détecte pas automatiquement les clés. Trois méthodes de découverte, par ordre de praticité : 1. **La documentation de l’appareil ou la fiche technique du fournisseur.** Les appareils industriels sont généralement fournis avec un schéma de payload ou un catalogue de topics. 2. **Pour les appareils bridgés par Zigbee2MQTT**, la page de l’appareil à `https://www.zigbee2mqtt.io/devices/{modelId}.html` liste l’ensemble Exposes. Notez que les payloads réels peuvent inclure des clés absentes de la page de l’appareil — fiez-vous au payload en direct plutôt qu’à la documentation lorsqu’ils diffèrent. 3. **Abonnez-vous au broker et inspectez le payload en direct** — `mosquitto_sub` sur le broker (ou l’onglet Logs une fois qu’au moins une ligne de mappage est résolue) affiche directement le payload JSON. Toute clé de premier niveau est une clé de connecteur valide. *** ## Résultats attendus Après que le connecteur est configuré et que les appareils sont enregistrés : * La ligne du connecteur sur la **Connecteurs** page affiche **Dernières données reçues** une mise à jour à mesure que les messages arrivent. * Les **Appareils connectés** le compteur reflète les appareils enregistrés. * Le jumeau numérique de chaque appareil se met à jour avec la télémétrie entrante — visible sur la page de détails de l’appareil et dans les tableaux de bord. * Les conditions du moteur de règles faisant référence à ces métriques d’appareil s’évaluent en temps réel. *** ## Dépannage Une courte liste — voir [Dépannage](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) pour des recettes de diagnostic couvrant les échecs d’authentification, les incohérences de certificats, le modèle d’onglet Logs vide et les outils de vérification. **Aucune donnée n’arrive après la connexion :** * Pour MQTT externe : vérifiez le schéma de l’URL du broker (`mqtt://`, `mqtts://`, `tcp://`, ou `ssl://`), confirmez que le broker est joignable depuis Internet (Kilo IoT Server se connecte à votre broker), et revérifiez les identifiants. * Pour TLS (authentification par certificat) : vérifiez que le certificat CA correspond à la chaîne de certificats du broker, et que le certificat client et la clé privée constituent une paire correspondante. * Pour Cloud MQTT : confirmez que vos appareils publient vers la bonne URL du broker et le bon préfixe de topic, et que le nom d’utilisateur et le mot de passe sont corrects. Si le mot de passe a été perdu, faites-le pivoter depuis les paramètres du connecteur. **L’appareil est enregistré mais aucune donnée n’apparaît :** * Comparez le Device ID Topic enregistré avec le topic exact sur lequel l’appareil publie. Les topics sont sensibles à la casse et doivent correspondre exactement. * Confirmez la `{{deviceId}}` position de l’espace réservé correspond bien au segment réel de l’ID de l’appareil dans le topic. * Confirmez que le champ Device ID est identique à l’octet près au segment au niveau de l’appareil — les espaces sont supprimés à la saisie et cassent la correspondance. * Si vous utilisez la source Payload : vérifiez que le Device ID Payload Path se résout correctement par rapport à la structure réelle du payload. **La colonne Value de l’onglet Mapping se met à jour mais l’onglet Logs est vide :** C’est le schéma le plus courant lorsque les clés du connecteur sont enregistrées après l’arrivée de la publication la plus récente. L’onglet Logs n’est alimenté que par les publications reçues *après* Les clés du connecteur sont enregistrées. Déclenchez une nouvelle publication — un réveil de l’appareil, un rapport planifié ou une `/get` requête de sondage pour les passerelles de développement — et l’onglet Logs se remplira. **Valeurs de métriques manquantes ou mauvaises clés affichées :** * Vérifiez que la Clé du connecteur dans l’onglet Mapping correspond exactement à la clé du payload MQTT (sensible à la casse). * Si vous vous appuyez sur l’analyse JSON automatique (aucun topic de télémétrie défini) : la plateforme aplatit l’ensemble du payload JSON, y compris les objets imbriqués, en clés en notation par points — par exemple, `{"device": {"temperature": 22.5}}` devient accessible sous `device.temperature`. Utilisez ces chemins en notation par points dans la colonne Clé du connecteur de l’onglet Mapping. **Mot de passe Cloud MQTT perdu :** Le mot de passe ne peut pas être récupéré après création. Faites pivoter les identifiants depuis les paramètres du connecteur et reconfigurez les appareils avec le nouveau mot de passe. **Échec de l’enregistrement de l’appareil sur un connecteur Cloud MQTT :** Si l’enregistrement d’un appareil sur un connecteur Cloud MQTT échoue, contactez le support. Le support peut aider à finaliser l’enregistrement via le parcours assisté par API pris en charge. *** ## Exemples opérationnels **PLC d’usine — télémétrie par topic :** Un PLC publie des mesures discrètes sur des topics MQTT séparés sur un broker de l’atelier (`mqtts://plc-broker.plant.example.com:8883`). Connecteur MQTT externe, authentification par nom d’utilisateur / mot de passe. Device ID Topic : `plant/line-a/{{deviceId}}/data`. Une ligne de topic de télémétrie par mesure (cycle\_time, reject\_count, temperature). Chaque ligne est mappée vers une métrique normalisée de la plateforme dans l’onglet Mapping. **Système CVC de bâtiment — payload JSON plat :** Un système de gestion technique du bâtiment publie un objet d’état JSON par appareil sur un seul topic. Le payload est un JSON plat, donc aucune ligne de topic de télémétrie n’est nécessaire — toutes les clés sont analysées automatiquement. L’ID de l’appareil se trouve dans le segment du topic. L’onglet Mapping mappe chaque clé JSON vers la métrique normalisée appropriée. **Nouveau déploiement sur site — Cloud MQTT :** Un site de facility distant a besoin d’ingestion MQTT, mais l’équipe ne souhaite pas exploiter de broker. Un connecteur Cloud MQTT est créé ; la plateforme provisionne un point de terminaison de broker. Les compteurs d’énergie et les capteurs environnementaux sont configurés pour publier vers le point de terminaison fourni et le préfixe de topic. Aucune infrastructure de broker à gérer — la plateforme s’en charge. **Système de sous-comptage énergétique :** Les compteurs d’énergie publient des relevés individuels (kWh, kW, tension, courant) vers des topics séparés. Les lignes de topic de télémétrie mappent chaque topic à une Clé du connecteur nommée. L’onglet Mapping relie chaque Clé du connecteur à des métriques normalisées de la plateforme. Tous les relevés s’agrègent dans un seul jumeau numérique d’appareil. *** ## Et ensuite * [Enregistrement des appareils](/kilo-docs-fr/kilo-iot-server/devices/registering-devices.md) — Finaliser l’enregistrement de l’appareil et la configuration du jumeau numérique. * [Connecteurs](/kilo-docs-fr/kilo-iot-server/connectors.md) — Aperçu de tous les types de connecteurs. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kiloiot.io/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.