> 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/devices/mioty-blueprints.md).
# Plans MIOTY
Décodez les charges utiles MIOTY dans Kilo IoT à l’aide de plans — catalogue Système vs Personnalisé et instantanés par appareil.
Un blueprint est la spécification de décodeur pour un point de terminaison MIOTY : un document JSON, lié à un `typeEui`, qui indique au serveur Kilo IoT comment transformer une charge utile brute en champs nommés. La télémétrie d'un appareil MIOTY n'est pas décodée tant qu'un blueprint ne lui est pas sélectionné — l'association d'un blueprint est donc ce qui transforme un point de terminaison enregistré en un appareil qui produit des données exploitables.
Les blueprints sont organisés comme un catalogue : **Fabricant → Modèle d'appareil → Blueprint**. Un fabricant contient ses modèles ; un modèle contient ses versions de blueprint. La configuration du blueprint sur le formulaire de l'appareil est l'endroit où vous choisissez dans ce catalogue ou rédigez une nouvelle entrée.
## L'idée la plus importante : des instantanés par appareil
Lorsque vous sélectionnez un blueprint pour un appareil, il est **copié sur cet appareil sous forme d'instantané indépendant**.
L'appareil n'est pas un pointeur vivant vers le catalogue. Il transporte sa propre copie du décodeur. Ce qui signifie :
* **La modification d'un blueprint du catalogue ne change pas les appareils déjà liés à celui-ci.** Ils continuent à fonctionner avec la copie avec laquelle ils ont été mis en service.
* **La suppression d'une entrée du catalogue ne casse pas les appareils qui l'utilisent déjà.** Ils continuent à décoder à partir de leur instantané ; l'entrée disparaît simplement du catalogue et ne peut plus être choisie pour de nouveaux appareils.
* **Deux appareils du même modèle peuvent exécuter des blueprints différents.** Un lot pilote sur un décodeur corrigé et une flotte de production sur le décodeur éprouvé constituent un état normal, pas un conflit.
* **Une nouvelle version n'atteint un appareil que lorsque vous l'appliquez explicitement.** Rien dans une modification du catalogue ne se propage tout seul.
C'est le même modèle que la plateforme utilise pour les codecs LoRaWAN, et il existe pour une raison précise : sur une flotte de plusieurs milliers de points de terminaison, une modification accidentelle du décodeur qui réécrirait silencieusement la façon dont chaque unité interprète sa charge utile serait une panne que vous découvririez via vos tableaux de bord. La frontière de l'instantané signifie que le travail sur le catalogue et le comportement en production sont des sujets distincts. Vous améliorez librement un modèle ; vous le déployez selon votre calendrier.
## Catalogues Système et Personnalisé
Le catalogue est divisé en deux, et les deux ne sont jamais mélangés dans une même liste — vous basculez de l'un à l'autre.
| Catalogue | Qui peut le voir et l'utiliser | Qui peut le modifier |
| ---------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Système** | Tout le monde — fabricants, modèles et blueprints peuvent être utilisés par n'importe quelle organisation | Les administrateurs uniquement. La création, la modification et la suppression des entrées Système nécessitent un administrateur. |
| **Personnalisé** | Votre organisation | À vous de le gérer librement — créer, modifier et supprimer sans restriction |
L'utilisation d'un blueprint Système sur un appareil crée **uniquement l'instantané sur cet appareil**. Rien n'est copié dans votre catalogue personnalisé, et votre catalogue personnalisé reste exactement tel que vous l'avez construit.
La séparation pratique : le Système couvre le matériel que la plateforme connaît déjà. Le Personnalisé est l'endroit où vivent vos propres décodeurs, vos variantes spécifiques à un fournisseur et vos corrections liées à une révision de firmware.
## Utiliser un blueprint existant
C'est le chemin à suivre pour le matériel déjà couvert par le catalogue.
1. Sur le formulaire de l'appareil, trouvez **Configuration du blueprint**.
2. Activez **Utiliser un blueprint existant** **ACTIVÉ**.
3. Sélectionnez le catalogue — **Système** ou **Personnalisé**.
4. Sélectionnez le **Fabricant**.
5. Sélectionnez le **Modèle d'appareil**. La liste se restreint aux modèles de ce fabricant.
6. Sélectionnez le **Version du blueprint**.
La spécification du décodeur s'affiche en lecture seule pour vérification, et le **EUI du type** se renseigne automatiquement sur le formulaire de l'appareil et n'est pas modifiable — il provient du blueprint. Enregistrez l'appareil, et le blueprint y est instantané.
Une fois cela fait, l'appareil est étiqueté **Instantané épinglé**, afin que vous puissiez voir d'un coup d'œil que ce que vous lisez appartient à cet appareil plutôt qu'à l'entrée partagée du catalogue. Si le blueprint du catalogue dont il a été copié a depuis été supprimé, l'étiquette affiche **Instantané épinglé (modèle source supprimé)** — l'appareil n'est pas affecté et continue à décoder avec sa propre copie, mais l'étiquette vous indique qu'il n'existe plus d'entrée du catalogue derrière laquelle comparer.
Le **la première version de blueprint créée pour un modèle devient la valeur par défaut pour les nouveaux appareils de ce modèle** — une fois qu'un modèle est configuré correctement, la mise en service du reste de la flotte consiste à sélectionner le modèle.
## Rédiger un nouveau blueprint
Suivez ce chemin lorsque le catalogue ne couvre pas votre matériel, ou lorsqu'une révision de firmware se décode différemment de l'entrée existante.
1. Activez **Utiliser un blueprint existant** **DÉSACTIVÉ**.
2. **Fabricant** — sélectionnez-en un existant, ou cliquez sur **+ Ajouter un nouveau fabricant** et donnez-lui un nom.
3. **Nouveau modèle d'appareil** — saisissez le nom du modèle. S'il duplique un modèle existant, le formulaire le signale — vérifiez si vous souhaitez plutôt ajouter une version à ce modèle.
4. **Version du blueprint** — saisissez une version, par exemple `1.0.0`. Indiquez la version délibérément, pas par hasard ; cette chaîne est ce que votre équipe utilisera pour distinguer deux décodeurs dans un an.
5. **JSON du blueprint** — collez la spécification du décodeur. Elle doit être un JSON valide et doit contenir un `typeEui` de exactement 16 caractères hexadécimaux.
6. Lorsque la spécification est valide, une aide affiche la valeur analysée — **"Type EUI : …"** — confirmant à quoi l'appareil sera lié.
7. Cliquez sur **Enregistrer le blueprint**. Un toast confirme *"Blueprint créé"*, et le nouveau modèle, la nouvelle version et le Type EUI sont renseignés dans le formulaire de l'appareil.
### Messages de validation
| Message | Ce que cela signifie |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"La spécification du blueprint doit être un JSON valide"** | Le texte collé ne peut pas être analysé. Vérifiez s'il y a une virgule finale, un collage tronqué ou des guillemets typographiques provenant d'un document. |
| **"typeEui doit comporter 16 caractères hexadécimaux"** | Le `typeEui` le champ est présent mais ne contient pas exactement 16 caractères hexadécimaux. |
| Un message vous indiquant de **"Utiliser un blueprint existant"** | Le `typeEui` est déjà utilisé par un modèle existant. Ce type de charge utile figure déjà dans le catalogue — sélectionnez-le plutôt que de créer une entrée concurrente. |
Cette dernière remarque mérite d'être comprise plutôt que contournée. Le `typeEui` identifie un type de charge utile. S'il existe déjà, la bonne démarche consiste à utiliser le modèle existant — et si vous avez besoin d'un décodeur différent pour celui-ci, ajoutez une version à ce modèle.
## Aperçu du décodage
Avant d'enregistrer, utilisez **Aperçu du décodage** pour exécuter le décodeur sur un échantillon de charge utile et inspecter les champs qu'il produit.
Utilisez-le. Un blueprint qui se parse comme du JSON n'est pas la même chose qu'un blueprint qui décode correctement — les facteurs d'échelle, l'ordre des octets et les valeurs signées sont les endroits classiques où un décodeur est syntaxiquement parfait mais sémantiquement faux. Une charge utile d'exemple avec une valeur connue prend une minute sur le banc et vous évite de découvrir le problème sous la forme d'un graphique de température qui semble plausible et qui est erroné d'un facteur dix. Prenez une charge utile dans la documentation même de l'appareil, ou d'une unité que vous avez déjà mise en service.
## Application d'une nouvelle version
Parce que les appareils fonctionnent sur des instantanés, une nouvelle version de blueprint n'atteint un appareil que lorsque vous l'appliquez :
1. Rédigez la nouvelle version sous le même fabricant et le même modèle.
2. Ouvrez l'appareil que vous souhaitez faire évoluer.
3. Dans la configuration du blueprint, sélectionnez le nouveau **Version du blueprint**.
4. Enregistrez.
Déployez d'abord sur un seul appareil et confirmez ses champs décodés par rapport à la charge utile en direct avant de déplacer la flotte. Le modèle par instantané est ce qui rend ce déploiement progressif possible — le reste de la flotte n'est pas touché pendant votre vérification.
## Suppression des entrées du catalogue
La suppression de votre propre blueprint, modèle ou fabricant du catalogue personnalisé est toujours autorisée.
Si des appareils utilisent l'entrée, vous obtenez un **avertissement avec un décompte** des appareils concernés. Ces appareils continuent de fonctionner — ils sont sur leurs instantanés. Ce qui change, c'est le catalogue : l'entrée disparaît et ne peut plus être choisie pour de nouveaux appareils.
Lisez le décompte avant de confirmer. Ce n'est pas un blocage, mais cela vous indique combien d'enregistrements d'appareils portent désormais un décodeur derrière lequel il n'existe plus d'entrée du catalogue — ce qui compte la prochaine fois que quelqu'un essaie de mettre en service une unité correspondante et ne trouve rien à sélectionner.
La suppression d'une **Système** entrée nécessite un administrateur.
## Conseils
* **Écrivez une fois, mettez en service plusieurs fois.** Pour un déploiement de flotte, mettez au point le blueprint sur une seule unité avec l'aperçu du décodage, puis laissez la valeur par défaut du modèle prendre le relais pour le reste.
* **Versionnez selon le firmware, pas selon les dates.** Lorsqu'un fournisseur livre une révision de firmware qui modifie la charge utile, il s'agit d'une nouvelle version de blueprint. Nommez-la de sorte que le lien soit évident.
* **Préférez le Système quand c'est possible.** Si le catalogue Système couvre votre matériel, utilisez-le — vous obtenez le décodeur sans avoir à en assurer la maintenance, et votre appareil reçoit tout de même son propre instantané.
* **Mappez les métriques après le décodage.** Un blueprint produit des champs nommés ; les modèles de métriques normalisent ces champs dans un vocabulaire partagé entre fabricants. Voir [Métriques](/kilo-docs-fr/kilo-iot-server/devices/metric-templates.md).
## Et ensuite
* **Mettez en service le point de terminaison** — la section du formulaire de l'appareil MIOTY, étape par étape. Voir [Appareils MIOTY](/kilo-docs-fr/kilo-iot-server/devices/mioty-devices.md).
* **Normalisez les champs décodés** — mappez-les vers le vocabulaire de mesure de votre déploiement. Voir [Métriques](/kilo-docs-fr/kilo-iot-server/devices/metric-templates.md).
---
# 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/devices/mioty-blueprints.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.
