Lorsque la bibliothèque n’a pas de codec pour votre capteur, ou que vous voulez une sortie différente d’un codec de la bibliothèque, vous écrivez le vôtre. Vos codecs sont des tables au format JSON, pas des scripts : Hermetry n’exécute jamais de code issu d’un codec. Vous les publiez dans votre organisation, et vos appareils et profils peuvent les utiliser comme les codecs de la bibliothèque.
Écrire des codecs nécessite l’autorisation d’ajouter, modifier et supprimer vos propres codecs LoRaWAN (administrateurs par défaut). Chaque publication et chaque suppression est journalisée.
Deux façons de commencer
Enregistrer une copie d’un codec de la bibliothèque
Idéal lorsqu’un codec de la bibliothèque est proche de vos besoins.
- Ouvrez Appareils > ⋯ > Codecs LoRaWAN et ouvrez le codec de la bibliothèque.
- Sélectionnez Enregistrer une copie.
- L’éditeur s’ouvre avec la table de la bibliothèque, l’identifiant
t.<identifiant bibliothèque>(modifiez-le si vous le souhaitez), l’originetenantet une ligne de source indiquant le codec copié et sa révision. - Modifiez la table, sélectionnez Vérifier, puis Publier.
Créer un nouveau codec
- Dans le tiroir des codecs, sélectionnez Nouveau codec.
- Saisissez l’Identifiant et collez ou écrivez la table sous Table du codec (JSON). L’éditeur propose un plan de départ.
- Sélectionnez Vérifier, puis Publier.
Identifiants
Les identifiants de vos codecs commencent par t., suivi de 2 à 62 lettres minuscules, chiffres ou tirets, par exemple t.cold-room-probe. L’identifiant ne change jamais. Un identifiant déjà utilisé dans votre organisation est refusé : un codec avec cet identifiant existe. Choisissez un autre identifiant.
La table du codec
Un codec est un document JSON. Ses principaux champs :
| Champ | Obligatoire | Signification |
|---|---|---|
id | Oui | L’identifiant du codec (t.…) |
title | Oui | Un nom lisible, jusqu’à 160 caractères |
vendor | Oui | Le fabricant de l’appareil, jusqu’à 64 caractères |
models | Non | Noms de modèles couverts par ce codec (jusqu’à 64) |
fports | Non | FPorts décodés (1–255, jusqu’à 64). Omettre pour tous les ports. |
oui | Non | Codes fabricant : les 6 premiers chiffres hexadécimaux du DevEUI, en majuscules (jusqu’à 32). Utilisé par le choix automatique. |
kind | Non | layout (champs à positions d’octets fixes) ou tlv (enregistrements canal, type, données) |
frames | Pour layout | Comment distinguer les trames (par fport, length, min_length, un octet marqueur byte ou des bits masqués) et les fields de chacune |
channels, types, attributes, default | Pour tlv | Les définitions des enregistrements |
tests | Oui, au moins un | Vecteurs de test : fport, hex et les valeurs attendues (expect) (jusqu’à 200) |
Un champ d’une trame layout possède at (décalage d’octet), field (clé de sortie), fmt (le format de l’octet) et, optionnellement, scale, digits, offset, unit et enum. Les formats comprennent u8, i8, u16be, u16le, i16be, i16le, u24be, u24le, u32be, u32le, i32be, i32le, f32be, f32le, hex, ascii ainsi que les découpages en bits (split) d’un octet.
Les champs de premier niveau inconnus sont refusés. Les décodeurs JavaScript ne sont pas acceptés : ceci est un décodeur JavaScript. Seul le format de table est accepté.
Exemple
Un capteur qui envoie, sur FPort 2, la batterie en mV (2 octets), la température en dixièmes de °C (2 octets, signés) et l’humidité en % (1 octet) :
{
"id": "t.room-sensor",
"title": "Room sensor, temperature and humidity",
"vendor": "Example maker",
"models": ["RS-1"],
"fports": [2],
"kind": "layout",
"frames": [
{
"fport": 2,
"min_length": 5,
"fields": [
{ "at": 0, "field": "battery", "fmt": "u16be", "unit": "mV" },
{ "at": 2, "field": "temperature", "fmt": "i16be", "scale": 0.1, "unit": "°C" },
{ "at": 4, "field": "humidity", "fmt": "u8", "unit": "%" }
]
}
],
"tests": [
{ "name": "normal reading", "fport": 2, "hex": "0BC4010A32",
"expect": { "battery": 3012, "temperature": 26.6, "humidity": 50 } }
]
}Les valeurs mises à l’échelle sont arrondies à 2 décimales, sauf si le champ définit digits.
Vérifier et publier
Vérifier exécute chaque vecteur de test et affiche chacun comme Réussi ou Échoué, avec Différences. Lorsque tous réussissent : Tous les vecteurs de test réussissent. La publication le rend disponible pour vos appareils et routeurs.
Publier relance les mêmes contrôles et refuse le codec avec Non publié : et la raison :
| Raison affichée | Signification |
|---|---|
| le texte n’est pas du JSON valide. | Corrigez la syntaxe JSON. |
| un champ est manquant ou non autorisé (…). | Un champ obligatoire est manquant ou un champ inconnu est présent. |
| l’identifiant doit commencer par t. suivi de lettres minuscules, de chiffres et de tirets. | Corrigez l’identifiant. |
| le codec dépasse 40960 octets. | Vos codecs sont limités à 40 Ko. |
| les tables ne sont pas au format attendu (…). | Une définition de trame ou de champ est incorrecte. |
| un codec nécessite au moins un vecteur de test. | Ajoutez un vecteur de test. |
| certains vecteurs de test échouent (voir ci-dessous). | Corrigez la table ou les valeurs attendues. |
| une version publiée a décodé des clés que celle-ci ne décode plus (…). Publiez-la sous un nouvel identifiant à la place. | Voir les révisions ci-dessous. |
| un autre de vos codecs revendique déjà models. | Deux de vos codecs ne peuvent pas revendiquer le même modèle. |
Les tables imbriquent au maximum 32 niveaux.
Révisions
Chaque publication d’un codec existant crée une nouvelle révision. Pour protéger vos flux et tableaux de bord, une nouvelle révision peut ajouter des clés, mais ne supprime ni ne renomme jamais une clé, et ne modifie jamais l’unité d’une clé. Si vous devez supprimer ou renommer des clés, publiez sous un nouvel identifiant et déplacez vos appareils vers celui-ci.
Révisions sur la page du codec liste chaque révision avec sa taille et son nombre de clés.
Votre codec et la bibliothèque
Vos codecs sont essayés avant ceux de la bibliothèque dans le choix automatique. Une copie conserve les codes fabricant et les FPorts du codec de la bibliothèque, donc les appareils de ce fabricant en Automatique passent à votre copie dès que vous la publiez. L’un de vos codecs peut revendiquer le même modèle qu’un codec de la bibliothèque ; c’est ainsi que vous remplacez la bibliothèque pour vos appareils.
Supprimer un codec
Ouvrez votre codec et sélectionnez Supprimer. Le codec quitte votre liste ; les appareils et profils qui l’avaient choisi décodent désormais avec le choix automatique. Ses révisions sont conservées, et l’identifiant ne change jamais de sens : si vous recréez le même identifiant, il doit respecter la règle de révision par rapport à la dernière révision du codec supprimé.