> 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/topics-and-device-routing.md).
# Topics et routage des appareils
Structure des topics MQTT et routage par ID d’appareil dans Kilo IoT — espaces réservés de modèle, onglets Mapping/Topic, enregistrement en deux étapes.
Cette page explique comment le serveur Kilo IoT résout un message MQTT entrant vers un Digital Twin spécifique : la structure des topics entrants, le **Topic de l’ID de l’appareil** sémantique du modèle du champ, les sous-onglets internes Mapping/Topic, la correspondance octet par octet entre l’entrée Device ID et le segment de topic au niveau de l’appareil, et le flux de sauvegarde en deux passes exigé par l’onglet Mapping. Lisez ceci avant d’enregistrer des appareils MQTT dans des déploiements de production — la plupart des tickets d’assistance « appareil enregistré mais aucune télémétrie » se résolvent par l’un des schémas documentés ici.
## Forme du topic après le traitement côté broker
Le broker de la plateforme expose les messages MQTT entrants avec un préfixe propre au connecteur. Pour Cloud MQTT, le préfixe est le préfixe de topic du connecteur (`iot/{org}/{connection}`). Pour External MQTT, le bridge sortant de la plateforme republie les messages entrants de votre broker dans un espace de noms interne ; la forme du topic au niveau de l’appareil est conservée.
Après suppression interne du préfixe, le topic vu pour le routage de l’appareil est le segment au niveau de l’appareil :
```
Cloud MQTT: plant-3/line-a/EM-4492/data (après suppression du préfixe)
External MQTT: plant-3/line-a/EM-4492/data (après suppression du préfixe de l’espace de noms du bridge)
```
Le champ Device ID Topic décrit uniquement cette forme au niveau de l’appareil. La gestion du préfixe du connecteur est interne à la plateforme ; l’opérateur ne la configure pas.
## Construction du Device ID Topic
**MQTT Topic pour l’ID de l’appareil** sur l’onglet Connection de l’appareil n’est pas une zone de texte libre — c’est un générateur de segments. Le préfixe de topic du connecteur est déjà en place et verrouillé, et vous ajoutez un segment à la fois avec le **+** bouton. Chaque segment appartient à l’un de deux types :
| Segment | Ce qu’il fait |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Segment texte** | Une partie littérale du topic, saisie telle quelle — `meters`, `line-a`, `SENSOR`. Correspond exactement au topic entrant. |
| **ID de l’appareil** | Marque le segment dont la valeur est *est* l’identifiant de l’appareil. Un seul est requis, et la valeur trouvée à cette position est comparée au **ID de l’appareil** champ ci-dessus. |
Un **Aperçu résolu** sous le générateur affiche le topic complet que le modèle produit pour cet appareil, afin que vous puissiez le comparer à ce que votre éditeur publie réellement avant d’enregistrer. Faites glisser la puce Device ID pour la déplacer vers une autre position.
**Où obtenir l’ID de l’appareil** à côté du générateur décide d’où l’identifiant est lu — **Topic** (la position que vous avez marquée) est le choix habituel.
Exemples de formes de topic et des segments à ajouter après le préfixe :
| Topic de publication | Segments |
| ------------------------------- | ---------------------------------------------------- |
| `plant-3/line-a/EM-4492/data` | `plant-3` · `line-a` · **ID de l’appareil** · `data` |
| `tasmota/PlugKitchen/SENSOR` | `tasmota` · **ID de l’appareil** · `SENSOR` |
| `zigbee2mqtt/LivingRoomSensor` | `zigbee2mqtt` · **ID de l’appareil** |
| `home/sensors/esp-kitchen/data` | `home` · `sensors` · **ID de l’appareil** · `data` |
Pour des formes de topic industrielles imbriquées comme Sparkplug B (`spBv1.0/{group}/DDATA/{node}/{device}`), ajoutez le contexte hiérarchique comme segments texte et placez l’ID de l’appareil sur le segment qui identifie de manière unique l’enregistrement de l’appareil en cours d’enregistrement.
## L’entrée Device ID doit correspondre exactement, octet par octet, au segment extrait
Le champ Device ID de l’enregistrement de l’appareil stocke l’identifiant canonique que la plateforme recherche dans le segment Device ID. La correspondance se fait octet par octet : sensible à la casse, aux espaces et à l’Unicode.
Un schéma qui piège souvent les intégrateurs : **l’entrée Device ID supprime les espaces à l’enregistrement.** Un appareil publiant sur `plant-3/line-a/EM 4492/data` (avec un espace dans l’ID de l’appareil) ne correspondra pas à un Device ID saisi comme `EM 4492` — l’entrée est normalisée en `EM4492` (ou tronquée partiellement ; le comportement exact n’est pas garanti). La discordance est silencieuse — aucune erreur n’apparaît à l’enregistrement et aucune erreur n’apparaît à l’arrivée de la télémétrie. L’onglet Mapping reste simplement vide.
La recommandation pour les déploiements en production : évitez complètement les espaces dans les identifiants d’appareil. Utilisez des tirets (`EM-4492`), des underscores (`EM_4492`), ou aucun séparateur (`EM4492`). Quel que soit votre choix, le côté publication et le champ Device ID doivent produire exactement la même chaîne.
## L’onglet Mapping comporte deux sous-onglets
Lorsque vous ouvrez l’onglet Mapping d’un appareil, l’interface présente un onglet externe intitulé **Mappage** contenant deux sous-onglets : **Topic** et **Mappage**. La sélection de l’onglet externe ouvre par défaut le sous-onglet **Topic** Topic
* **Sous-onglet Topic** — Device ID Topic, Où obtenir l’ID de l’appareil, Device ID Payload Path (lorsque la source est Payload), topics de télémétrie (définitions de métriques par topic pour les schémas de publication d’une métrique par topic).
* **Sous-onglet Mapping** — lignes de clé de connecteur qui relient les clés du payload aux métriques normalisées.
Un appareil enregistré sans avoir visité le sous-onglet interne Mapping a une configuration Topic mais aucune cartographie de métriques — donc même si la correspondance des topics réussit et que le dernier data received se met à jour, l’enregistrement de l’appareil ne contient aucune télémétrie. Cliquez **Suivant** en bas du sous-onglet Topic ou cliquez sur le libellé interne **Mappage** pour accéder aux lignes par clé.
## Topics de télémétrie : quand les configurer
Le **Topics de télémétrie** lignes du sous-onglet Topic concernent les schémas de publication où chaque métrique a son propre topic MQTT — par ex., un pont PLC publiant la puissance vers `meters/{deviceId}/power`, la tension vers `meters/{deviceId}/voltage`, le courant vers `meters/{deviceId}/current`, chacun avec une seule valeur numérique comme payload.
Pour les schémas de publication JSON plat modernes — Zigbee2MQTT, Tasmota avec un objet SENSOR, un firmware personnalisé qui émet un objet d’état JSON — les lignes Topics de télémétrie ne sont pas nécessaires. La plateforme analyse automatiquement chaque clé du payload JSON et les expose comme candidats Connector Key. Les objets imbriqués sont aplatis en chemins en notation pointée (`{"vibration": {"rms": 0.42}}` devient `vibration.rms`).
Configurez les lignes de topic de télémétrie uniquement lorsque vous avez réellement une publication une métrique par topic ou lorsque vous souhaitez remplacer l’analyseur automatique pour une forme de topic spécifique.
## Liste déroulante de clé de connecteur : le flux de sauvegarde en deux passes
La colonne **Clé de connecteur** de l’onglet Mapping est une liste déroulante. Les options de la liste proviennent des clés de payload réellement reçues de l’appareil — pas d’une saisie de texte libre.
Pour un appareil tout juste créé sans trafic historique, la liste déroulante est vide. La plateforme ne sait pas encore ce que l’appareil envoie, donc elle n’a rien pour peupler les options. C’est intentionnel, mais cela signifie que le flux d’enregistrement se fait en deux passes :
**Passage 1 :**
1. Ajoutez une ligne de Mapping par métrique produite par l’appareil.
2. Sélectionnez le **Clé normalisée** dans la liste déroulante des modèles. Utilisez **+ Ajouter une nouvelle métrique** pour créer un nouveau modèle de capteur si nécessaire. (La fenêtre modale gère la création à la fois du nom normalisé et du modèle de capteur — la précréation des noms depuis l’onglet Metrics est facultative.)
3. Définissez **Type de données** (Reported State, Telemetry ou Device Metadata — voir ci-dessous).
4. Laissez **Clé de connecteur** vide.
5. Enregistrez l’enregistrement de l’appareil.
**Passage 2 :**
6. Vérifiez que l’appareil publie — pour un appareil relié via Z2M, que le bridge fonctionne et que l’appareil s’est déclaré au moins une fois. Pour un bridge PLC, que le processus du bridge publie bien des données.
7. Rouvrez l’enregistrement de l’appareil. La **Clé de connecteur** liste déroulante affiche maintenant les clés reçues de l’appareil.
8. Associez une clé de payload à chaque ligne de Mapping.
9. Enregistrez à nouveau.
Les publications suivantes pour les clés mappées sont acheminées vers l’onglet Logs.
## Reported State vs Telemetry vs Device Metadata
Le **Type de données** la liste déroulante classe chaque métrique :
* **État déclaré** — propriétés contrôlables de l’appareil dont la valeur actuelle est publiée par l’appareil. Le point de consigne d’un contrôleur HVAC, l’état ouvert/fermé d’une vanne, l’état marche/arrêt d’un actionneur. Valeurs que l’appareil peut aussi recevoir en commande pour changer.
* **Télémétrie** — mesures en lecture seule. Variables de processus, relevés de compteur d’énergie, valeurs RMS de vibration, qualité de liaison, mesures environnementales. L’appareil observe ; il ne modifie pas celles-ci.
* **Métadonnées de l’appareil** — valeurs qui décrivent l’appareil lui-même plutôt que son état opérationnel. Version du firmware, modèle matériel, numéro de série, date de calibration.
Choisissez le type qui correspond à l’intention opérationnelle. Reported State convient aux champs d’état et aux points de consigne configurables ; Telemetry convient aux relevés de capteurs et aux diagnostics ; Device Metadata convient aux champs statiques d’identité de l’appareil.
## Traduction Type de payload → Type de métrique
Le Type du modèle de métrique (Integer, Float, String, Boolean) est fixé par le modèle choisi pour la Clé normalisée. Faites correspondre le Type du modèle aux données réellement envoyées par l’appareil :
* **Énumérations encodées en chaîne et états binaires** — des valeurs comme `"OPEN"`/`"CLOSED"`, `"ON"`/`"OFF"`, `"running"`/`"stopped"` arrivent sous forme de chaînes JSON. Mappez-les à un Type **String** . Ne sélectionnez pas Boolean — cela entraînera des valeurs null.
* **Scalaires numériques** — Integer ou Float, selon que l’appareil produit des décimales.
* **Texte libre** — String.
Pour les appareils reliés via Zigbee2MQTT, les [zigbee2mqtt.io](https://www.zigbee2mqtt.io/supported-devices/) pages de l’appareil listent chaque fonctionnalité avec un type — traduisez comme suit :
| Type de fonctionnalité Z2M | Type de métrique | Exemple |
| -------------------------- | ---------------- | ---------------------------------- |
| `binaire` | **String** | `état` (`"ON"`/`"OFF"`) |
| `numérique` | **Nombre** | `luminosité`, `qualité de liaison` |
| `énum` | **String** | `power_on_behavior`, `color_mode` |
| `texte` | **String** | Champs de texte libre |
## Colonne Value de l’onglet Mapping vs historique de l’onglet Logs
Après le passage 2 du flux de sauvegarde :
* Le **Valeur** La colonne Value de l’onglet Mapping se met à jour à partir du payload le plus récent — un instantané en direct. Les valeurs apparaissent dès que la correspondance du topic réussit, même avant que toutes les clés Connector ne soient renseignées.
* Le **Journaux** l’onglet est un historique par capteur. Il n’est alimenté que par les publications arrivant *après* Les clés Connector sont enregistrées. Les publications plus anciennes ne sont pas normalisées rétroactivement.
Sur le plan opérationnel : après avoir terminé le passage 2, générez une nouvelle publication (un réveil de l’appareil par événement, un rapport planifié, une requête de sondage depuis le bridge) pour confirmer que l’onglet Logs reçoit des enregistrements. Si l’appareil ne publie que selon un planning ou lors d’un changement d’état, prévoyez la validation autour de cette cadence.
### Affinage itératif du mapping
La cartographie initiale ne couvre presque jamais tous les champs utiles qu’un appareil expose. Les opérateurs découvrent souvent après le déploiement que l’appareil publie des clés supplémentaires — champs de diagnostic du fournisseur, valeurs d’état non documentées, sous-objets imbriqués avec des chemins pertinents sur le plan opérationnel. Le schéma recommandé consiste à revisiter l’onglet Mapping après que les données ont circulé pendant une période représentative :
* Inspectez la **Clé de connecteur** liste déroulante et la **Valeur** colonne pour voir exactement ce que l’appareil publie en production.
* Ajoutez de nouvelles lignes de Mapping pour les champs que le déploiement souhaite désormais voir dans le Digital Twin.
* Définissez la Clé normalisée et le type de données appropriés pour chaque ligne.
* Enregistrez.
* Générez une nouvelle publication pour que l’onglet Logs commence à enregistrer l’historique des champs nouvellement mappés.
Pour des flottes d’appareils nominalement identiques, effectuez ce raffinement sur un échantillon représentatif avant de déployer les changements de cartographie au reste de la flotte — les révisions de firmware peuvent introduire de subtiles différences de clés.
## Où aller ensuite
* [Dépannage](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) — recettes de diagnostic pour les échecs de correspondance de topic et le schéma d’un onglet Logs vide.
* [Passerelles MQTT Edge](/kilo-docs-fr/kilo-iot-server/gateways/mqtt-edge-gateways.md) — schémas pour les passerelles industrielles produisant du MQTT qui alimentent ce pipeline de routage (dans Passerelles).
---
# 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/topics-and-device-routing.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.
