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.

Et ensuite

• Mettez en service le point de terminaison — la section du formulaire de l'appareil MIOTY, étape par étape. Voir Appareils MIOTY.

• Normalisez les champs décodés — mappez-les vers le vocabulaire de mesure de votre déploiement. Voir Métriques.