Eigenen Codec schreiben

Wenn die Bibliothek keinen Codec für Ihren Sensor hat oder Sie eine andere Ausgabe als ein Bibliothekscodec möchten, schreiben Sie Ihren eigenen. Ihre Codecs sind Tabellen in JSON, keine Skripte: Hermetry führt niemals Code aus einem Codec aus. Sie veröffentlichen sie in Ihrer Organisation, und Ihre Geräte und Profile können sie wie Bibliothekscodecs verwenden.

Zum Schreiben von Codecs benötigen Sie die Berechtigung, Ihre eigenen LoRaWAN-Codecs hinzuzufügen, zu ändern und zu löschen (standardmäßig Administratoren). Jede Veröffentlichung und jede Löschung wird protokolliert.

Zwei Wege zum Start

Eine Kopie eines Bibliothekscodecs speichern

Am besten, wenn ein Bibliothekscodec Ihren Anforderungen nahekommt.

Öffnen Sie Geräte > ⋯ > LoRaWAN-Codecs und öffnen Sie den Bibliothekscodec.
Wählen Sie Kopie speichern.
Der Editor öffnet sich mit der Bibliothekstabelle, der ID t.<Bibliotheks-ID> (ändern Sie sie bei Bedarf), dem Ursprung tenant und einer Quellenzeile mit dem kopierten Codec und der Revision.
Ändern Sie die Tabelle, wählen Sie Prüfen und danach Veröffentlichen.

Einen neuen Codec anlegen

Wählen Sie im Codec-Bereich Neuer Codec.
Geben Sie die ID ein und fügen Sie die Tabelle unter Codec-Tabelle (JSON) ein oder schreiben Sie sie. Der Editor bietet eine Gliederung als Ausgangspunkt an.
Wählen Sie Prüfen und danach Veröffentlichen.

IDs

Ihre Codec-IDs beginnen mit t., gefolgt von 2 bis 62 Kleinbuchstaben, Ziffern oder Bindestrichen, zum Beispiel t.cold-room-probe. Die ID ändert sich später nie. Eine in Ihrer Organisation bereits verwendete ID wird abgelehnt: Ein Codec mit dieser ID existiert. Wählen Sie eine andere ID.

Die Codec-Tabelle

Ein Codec ist ein JSON-Dokument. Seine wichtigsten Felder:

Feld	Pflicht	Bedeutung
`id`	Ja	Die Codec-ID (`t.…`)
`title`	Ja	Ein lesbarer Name, bis zu 160 Zeichen
`vendor`	Ja	Der Gerätehersteller, bis zu 64 Zeichen
`models`	Nein	Modellnamen, die dieser Codec abdeckt (bis zu 64)
`fports`	Nein	FPorts, die er dekodiert (1–255, bis zu 64). Weglassen für alle Ports.
`oui`	Nein	Herstellercodes: die ersten 6 hexadezimalen Ziffern der DevEUI, Großbuchstaben (bis zu 32). Wird bei der automatischen Auswahl verwendet.
`kind`	Nein	`layout` (Felder an festen Byte-Positionen) oder `tlv` (Kanal-, Typ-, Datensätze)
`frames`	Für `layout`	Wie Frames unterschieden werden (nach `fport`, `length`, `min_length`, einem Markierungs-`byte` oder maskierten `bits`) und die `fields` jedes Frames
`channels`, `types`, `attributes`, `default`	Für `tlv`	Die Datensatzdefinitionen
`tests`	Ja, mindestens einer	Testvektoren: `fport`, `hex` und die erwarteten Werte `expect` (bis zu 200)

Ein Feld in einem layout-Frame hat at (Byte-Offset), field (Ausgabeschlüssel), fmt (das Byte-Format) und optional scale, digits, offset, unit und enum. Formate sind u8, i8, u16be, u16le, i16be, i16le, u24be, u24le, u32be, u32le, i32be, i32le, f32be, f32le, hex, ascii sowie Bit-splits eines Bytes.

Unbekannte Felder auf oberster Ebene werden abgelehnt. JavaScript-Decoder werden nicht akzeptiert: Dies ist ein JavaScript-Decoder. Nur das Tabellenformat wird akzeptiert.

Beispiel

Ein Sensor sendet auf FPort 2 Batterie in mV (2 Byte), Temperatur in Zehntel °C (2 Byte, vorzeichenbehaftet) und Feuchte in % (1 Byte):

{
  "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 } }
  ]
}

Skalierte Werte werden auf 2 Dezimalstellen gerundet, sofern das Feld nicht digits setzt.

Prüfen und veröffentlichen

Prüfen führt jeden Testvektor aus und zeigt jeden als Bestanden oder Fehlgeschlagen mit Abweichung. Wenn alle bestehen: Jeder Testvektor besteht. Die Veröffentlichung macht ihn für Ihre Geräte und Router verfügbar.

Veröffentlichen führt dieselben Prüfungen erneut aus und lehnt den Codec mit Nicht veröffentlicht: und dem Grund ab:

Angezeigter Grund	Bedeutung
der Text ist kein gültiges JSON.	Korrigieren Sie die JSON-Syntax.
ein Feld fehlt oder ist nicht erlaubt (…).	Ein Pflichtfeld fehlt oder ein unbekanntes Feld ist vorhanden.
die ID muss mit t. beginnen, gefolgt von Kleinbuchstaben, Ziffern und Bindestrichen.	Korrigieren Sie die ID.
der Codec ist größer als 40960 Byte.	Ihre Codecs sind auf 40 KB begrenzt.
die Tabellen haben nicht das erwartete Format (…).	Eine Frame- oder Felddefinition ist fehlerhaft.
ein Codec benötigt mindestens einen Testvektor.	Fügen Sie einen Testvektor hinzu.
einige Testvektoren schlagen fehl (siehe unten).	Korrigieren Sie die Tabelle oder die erwarteten Werte.
eine veröffentlichte Version dekodierte Schlüssel, die diese nicht mehr dekodiert (…). Veröffentlichen Sie sie stattdessen unter einer neuen ID.	Siehe unten die Revisionen.
ein anderer Ihrer Codecs deckt bereits models ab.	Zwei Ihrer Codecs können nicht dasselbe Modell beanspruchen.

Tabellen dürfen höchstens 32 Ebenen tief verschachtelt sein.

Revisionen

Jede Veröffentlichung eines bestehenden Codecs erzeugt eine neue Revision. Zum Schutz Ihrer Flows und Dashboards darf eine neue Revision Schlüssel hinzufügen, aber nie einen entfernen oder umbenennen und nie die Einheit eines Schlüssels ändern. Wenn Sie Schlüssel entfernen oder umbenennen müssen, veröffentlichen Sie unter einer neuen ID und verschieben Sie Ihre Geräte dorthin.

Revisionen auf der Seite des Codecs listet jede Revision mit ihrer Größe und Anzahl der Schlüssel auf.

Ihr Codec und die Bibliothek

Ihre Codecs werden bei der automatischen Auswahl vor denen der Bibliothek geprüft. Eine Kopie behält die Herstellercodes und FPorts des Bibliothekscodecs, daher wechseln Geräte dieses Herstellers auf Automatisch zu Ihrer Kopie, sobald Sie sie veröffentlichen. Einer Ihrer Codecs darf dasselbe Modell wie ein Bibliothekscodec beanspruchen; so überschreiben Sie die Bibliothek für Ihre Geräte.

Einen Codec löschen

Öffnen Sie Ihren Codec und wählen Sie Löschen. Der Codec verschwindet aus Ihrer Liste; Geräte und Profile, die ihn gewählt haben, dekodieren ab dann mit der automatischen Auswahl. Seine Revisionen bleiben erhalten, und die ID behält ihre Bedeutung: Wenn Sie dieselbe ID erneut anlegen, muss sie der Revisionsregel gegenüber der letzten Revision des gelöschten Codecs folgen.