Wireless M-Bus Decoder

Das Modul Wireless M-Bus Decoder ermöglicht eine einfache Dekodierung und Entschlüsselung von Wireless M-Bus Nachrichten (wM-Bus), welche von einem wM-Bus-Konzentrator über einen Konnektor an niotix gesendet werden.

Als wM-Bus-Konzentratoren werden im Folgenden die Geräte bezeichnet, welche die wM-Bus Nachrichten von Zählern oder anderen Geräten empfangen und diese über LoRaWAN oder ein anderes LPWAN-Protokoll wie NB-IoT übertragen. Der Wireless M-Bus Decoder wird über einen Konnektor eingebunden, welcher mit den Virtuellen Geräten verwendet wird. Hierdurch werden die Pakete von den wM-Bus-Konzentratoren auf die einzelnen wM-Bus-Geräte verteilt und zusätzlich entschlüsselt sowie dekodiert.

Funktionsübersicht

Der Wireless M-Bus Decoder bietet eine umfassende Lösung zur Dekodierung und Entschlüsselung von wM-Bus-Nachrichten, die von Zählern oder anderen Geräten über einen Konzentrator an niotix gesendet werden. Hier sind die zentralen Funktionen des Features:

1. Dekodierung und Entschlüsselung von wM-Bus-Nachrichten

• Das Modul empfängt verschlüsselte AES-verschlüsselte OMS-Nachrichten von wM-Bus-Geräten.
• Nachrichten werden entschlüsselt und dekodiert, um Werte wie Zählerstände, Temperaturen oder andere Messdaten anzuzeigen.

2. Unterstützung für Hersteller-spezifische Felder

• Neben standardisierten OMS-Nachrichten unterstützt der Decoder auch herstellerspezifische Felder für eine verbesserte Integration mit Geräten von Herstellern wie Kamstrup, Landis+Gyr und Sontex.
  Liste der Hersteller

  • BMeters
  • Carlo Gavazzi
  • Danfoss
  • Diehl Metering
  • EBZ
  • Engelmann
  • Flonida
  • Integra Metering
  • Kamstrup
  • Landis+Gyr
  • Lansen
  • Minol-ZENNER
  • Müller-Electronic
  • Sagemcom
  • Sontex

3. Virtuelle Geräte-Zuordnung

• Dekodierte Nachrichten werden den entsprechenden Virtuellen Geräten zugeordnet, die als Zähler oder andere wM-Bus-Geräte angelegt sind. Die Daten werden im Virtuellen Gerät gespeichert und für die Weiterverarbeitung zur Verfügung gestellt.

4. Transformation von Daten

• Mithilfe von Transformations- und Berechnungsregeln können die dekodierten Nachrichten weiter verarbeitet und angepasst werden, z. B. für Einheitenkonvertierungen oder Namensänderungen der Variablen.

5. Fehlerbehandlung und Weiterleitung von Decoder-Fehlern

• Decoder-Fehler werden an das Virtuelle Gerät weitergeleitet und im JSON-Objekt unter dem Schlüssel decoderErrors ausgegeben.

Datenfluss

Nachrichten eines wM-Bus-Gerätes werden im sogenannten Fixed-Network-Betrieb zunächst von einem wM-Bus-Konzentrator erfasst und weitergeleitet. Die AES-verschlüsselten wM-Bus-Nachrichten werden beispielsweise über LoRaWAN oder NB-IoT an niotix weitergeleitet und über einen Konnektor an ein Virtuelles Gerät des Konzentrators weitergegeben.

Wenn ein Virtuelles Gerät, beispielsweise ein wM-Bus-Zähler, mit dem Wireless M-Bus Konnektor angelegt wird, so werden Informationen wie die Herstellerseriennummer und der wM-Bus Key (AES-Key) als konnektorspezifischer Parameter in dem Gerät hinterlegt.

Über einen Integrationsflow werden die Nachrichten dann an den Wireless M-Bus Decoder gesendet, welcher die Pakete entschlüsselt und dekodiert, sowie diese den einzelnen Geräten zuordnet. Das dekodierte wM-Bus Paket wird im Virtuellen Gerät über einen Gerätetreiber wie gewohnt transformiert und über Datenpunkte im persistiert und steht für die Weiterverarbeitung zur Verfügung.

Der Datenfluss sieht sieht in der Übersicht wie folgt aus:

Konfiguration im Detail

Die Schritte für die Integration von wM-Bus Geräten und Konzentratoren werden im Folgenden detailliert beschrieben. Wenn die erstmalige Integration erfolgt ist, sind zum Anlegen weiterer Geräte und Konzentratoren nur die Schritte 3 und 8 erforrderlich.

1. Konnektor für den wM-Bus-Konzentrator anlegen

Im ersten Schritt wird ein Konnektor für die wM-Bus-Konzentratoren angelegt. Es können dabei alle verfügbaren eingangsseitigen Konnektoren für Virtuelle Geräte verwendet werden.

Konzentratoren mit NB-IoT oder LTE

Konzentratoren, welche die Daten über NB-IoT oder LTE versenden, können mit den Konnektoren Webhook (incoming)" und “MQTT (incoming)” eingebunden werden.

Im Tab “Verbindungsdaten” kann basierend auf dem Standard-Template “Virtual Device Inbound” eine Transformation der Daten vorgenommen werden. Im Standard wird der Parameter “id” als externe ID des Virtuellen Geräts verwendet. Die Standard-Struktur für eingehende Datenpakete ist:

{                                                                 
    "id": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890", 
    "timestamp": "2022-09-08T12:51:51.897Z",      
    "payload": {
        "omsPayload": "44c14b2053fc2c486d67288a16b5b6ae6f03fe7830711d6fba9d2",
        "receptionTimestamp": "2024-01-08T06:00:00.000Z"
    }                         
 }       

• omsPayload: Die verschlüsselte OMS-Nachricht des wMBus Gerätes als Hex-String
• receptionTimestamp: Der Zeitstempel des Paketempfangs durch das Wireless M-Bus Gateway im ISO-Format (ISO 8601). Sofern dieser Zeitstempel nicht vorhanden ist, wird der Eingangszeitstempel in niotix verwendet

In den Eigenschaften des Payload-Objekts muss die OMS-Nachricht enthalten sein. Die Payload kann, falls erforderlich, noch im Gerätetreiber des Konzentzrators transformiert werden (siehe Schritt 2).

Erfolgt der Versand der Nachrichten über LTE oder NB-IoT, so wird die komplette OMS-Nachricht zusammen mit ggf. weiteren Werten von dem Konzentrator als Objekt versendet.

Datenfluss im Detail

Konzentratoren mit LoRaWAN

wM-Bus-Konzentratoren mit LoRaWAN senden in der Regel zwei unterschiedliche Nachrichtentypen:

• OMS-Payload: Die kodierte wM-Bus Nachricht wird vom Konzentrator zerteilt und in einzelnen LoRaWAN-Payloads versendet
• Statuspayloads: Statuspayloads enthalten Informationen über den Status des Konzentrators und werden beispielsweise über einen abweichenden Port versendet

Da die wM-Bus-Payloads herstellerabhängig in einzelne LoRaWAN-Payloads zerteilt werden, müssen diese über einen zusätzlichen Service (Reassembler) wieder zusammengefügt werden. Dies kann beispielsweise über NodeRed in niotix, oder über einen vom Hersteller bereitgestellten Service erfolgen.

Die vollständigen OMS-Nachrichten werden dann vom Reassembler über die Konnektoren Webhook (incoming)" oder “MQTT (incoming)” in niotix an das Virtuelle Gerät des wM-Bus-Konzentrators weitergegeben.

Datenfluss im Detail

2. Gerätetreiber für wM-Bus-Konzentrator anlegen

Der Gerätetreiber des wM-Bus-Konzentrators hat zum einen die Funktion, Statusnachrichten des Konzentrators zu transformieren und zu persistieren, beispielsweise einen Batteriestand. Außerdem kann die Nachricht des Konzentrators gerätespezifisch transformiert werden, sofern diese noch nicht dem erforderlichen Format entspricht.

Der Wireless m-Bus-Konnektor erwartet die OMS Payload als Ausgabeobjekt des Javascript-Funktionsparsers mit folgenden Eigenschaften:

• omsPayload: Die verschlüsselte OMS-Nachricht des wMBus Gerätes als Hex-String
• receptionTimestamp: Der Zeitstempel des Paketempfangs durch das Wireless M-Bus Gateway im ISO-Format (ISO 8601). Sofern dieser Zeitstempel nicht vorhanden ist, wird der Eingangszeitstempel in niotix verwendet

Beispielobjekt als Ausgabe des Funktions Parsers:

{
        "omsPayload": "44c14b2053fc2c486d67288a16b5b6ae6f03fe7830711d6fba9d2",
        "receptionTimestamp": "2024-01-08T06:00:00.000Z"
}

Zusätzlich können im Gerätetreiber des wM-Bus-Konzentrators mit Hilfe der Berechnungsvariablen und Typdefinitionen weitere Datenpunkte für die Überwachung des Gerätes, wie beispielsweise ein Batteriestand angelegt werden. Ist im Gerätetreiber keine weitere Transformation erforderlich, dann wird im Javascript Parser folgende minimale Funktion verwendet:

module.exports = function (payload, meta) {
  return payload;
}

Sofern die eingehende Payload transformiert werden muss, beispielsweise weil etwa weil die OMS-Payload in einem String mit weiteren Informationen enthalten ist, oder nicht als Hex-String gesendet wird, dann erfolgt diese Transformation mit Hilfe des Javascript Parsers. Zusätzlich können die Berechnungsvariablen genutzt werden, um einfache Transformationen und Berechnungen (beispielsweise eine Umbenennung oder Division) vorzunehmen. Es muss immer mindestens der minimale Javaskript Parser definiert werden.

3. wM-Bus Konzentrator als Virtuelles Gerät anlegen

Für jeden Konzentrator wird ein Virtuelles Gerät mit dem definierten Gerätetreiber und Konnektor angelegt. Hierfür stehen alle bekannten Optionen zur Verfügung: einzeln über das User-Interface, als CSV-Import oder über die XAPI

4. Anlegen einer Transformation

In den folgenden Schritten werden im Menü “Integrationen” die Komponenten eines Integrationsflows definiert und anschließend der Integrationsflow selbst angelegt. Es wird in der Regel nur eine einfache Transformation benötigt:

• Ausgabeformat: application/json
• Typ: jsonata
• Transformation: $

Sofern der _parsed-Datenpunkt noch nicht die geforderten Parameter aufweist, kann dieser mit Hilfe der Transformation in das erforderliche Format gebracht werden. Es wird jedoch empfohlen, diese Transformation im jeweiligen Gerätetreiber durchzuführen (siehe 2. Gerätetreiber für wM-Bus-Konzentrator anlegen). Der Parameter receptionTimestamp ist optional.

Erforderliches Ausgabeformat der Transformation (nur erforderliche Felder):

{
  "meta": {
    "state_identifier": "_parsed"
  },
  "value": {
    "omsPayload": "44c14b2053fc2c486d67288a16b5b6ae6f03fe7830711d6fba9d2",
    "receptionTimestamp": "2024-01-08T06:00:00.000Z"
  }
}

5. Anlegen eines Filters

Der Filter wird so gewählt, dass nur die zu dekodierenden OMS-Nachrichten weitergeleitet werden. Beispielsweise kann folgender Filter verwendet werden:

• Modus: erweitert
• Typ: JSONATA
• Eingabetyp: application/json
• Code:

$.meta.state_identifier = '_parsed' and $exists($.value.omsPayload)

Wenn der Parameter omsPayload innerhalb des Accounts auch ohne den Wireless-M-Bus Konnektor verwendet werden soll, wird empfohlen, den Filter abweichend zu definieren, beispielsweise auf Basis der Gerätegruppe oder einer anderen Eigenschaft.

6. Anlegen eines Konnektors vom Typ “Wireless MBus Decoder”

Sofern das Modul aktiviert ist, kann im Menüpunkt Integrationen / Konnektoren ein Konnektor vom Typ “Wireless M-Bus Decoder” angelegt werden. Wenn das Modul deaktiviert wird, dann werden auch die Konnektoren vom Typ “Wireless M-Bus Decoder” deaktiviert.

Standardmäßig ist das Template “Simple Default Format” aktiviert. Dieses erzeugt aus den dekodierten Werten und den OMS-Deskriptoren automatisch Eigenschaften, welche direkt im Virtuellen Gerät verarbeitet werden können. Der Schlüssel wird nach folgendem Schema generiert:

Schlüssel = [Beschreibung] + _ + [Tarif] + _ + [SpeicherNr] + _ + [Untereinheit]

Beispiel

Die folgende Eigenschaft:

"Volume_0_1_0": 236.666

setzt sich zusammen aus den Parametern

• Beschreibung: Volume
• Tarif: 0
• Speichernummer: 1
• Untereinheit: 0
• Wert: 236.666

Folgende Einstellung im Konnektor aktiviert das vereinfachte Format:

• Template: Simple Default Format

Das Objekt decoderRaw enthält das komplette Output-Objekt des Decoders, welches alternativ verwendet werden kann und zusätzliche Informationen enthält.

Die Zeitstempel werden nach folgender Logik generiert:

1. Sofern ein Zeitstempel in der OMS-Nachricht kodiert ist, wird dieser verwendet. Die Zeitzone des Geräts kann im Template im Tab “Verbindungsdaten” über den Parameter utcMinuteOffset in Minuten eingestellt werden.

Beispiel für Zeitzone UTC+1 (Standard)

const utcMinuteOffset = 60;

2. Sofern kein Zeitstempel in der OMS-Nachricht kodiert ist, dann wird Zeitstempel receptionTimestamp verwendet, welcher vom Konzentrator gesendet oder andernfalls durch niotix generiert wird.

Beispieloutput:

[
    {
        "meta": {
            "time": "2024-01-30T11:59:45Z"
        },
        "decoderRaw": {"..."},
        "Volume_0_0_0": 240.216,
        "On_time_0_0_0": 2449383,
        "Manufacturer_specific_VIF__0x20_0_0_0": 0
    },
    {
        "meta": {
            "time": "2023-12-30T23:00:00.000Z"
        },
        "Volume_0_1_0": 236.666,
        "Flow_temperature_0_1_0": 16,
        "External_temperature_0_1_0": 22
    }
]

Fehler beim dekodieren der Nachricht werden zusätzlich ausgegeben, beispielsweise bei fehlerhaftem AES-Key:

[
  {
  "meta": {
    "time": "2023-12-30T23:00:00.000Z"
  },
  "On_time_0_0_0": 141834,
  "decoderErrors": "No working key found"
  }
]

7. Anlegen eines Integrationsflows

Anschließend kann ein Integrationsflow angelegt werden, welcher erstens aus dem angelegten Filter, zweitens dem Transformator und drittens dem Konnektor vom Typ Wireless MBus Decoder besteht. Dieser Integrationsflow sendet die wM-Bus Nachrichten an den Wireless M-Bus Decoder. Von dort aus werden die Nachrichten auf die jeweiligen Virtuellen Geräte dieses Konnektors verteilt.

9. Anlegen eines Gerätetreibers je Zählertyp

Der Wireless MBus Decoder erzeugt ein dekodiertes und entschlüsseltes Nachrichtenobjekt. Mit Hilfe eines Gerätetreibers mit einem Funktions Parser oder mit den Berechnungsvariablen kann eine Transformation der Variablennamen oder eine Anpassung der Einheiten erfolgen. Über die Definition der Zielvariablen im Gerätetreiber wird festgelegt, welche Datenpunkte des Virtuellen Gerätes angelegt werden. Wenn in Schritt 6 das Template Simple Default Format ausgewählt wurde, so kann der einfache Parser erwendet werden:

module.exports = function (payload, meta) {
  return payload;
}

Über die Berechnungsvariablen können dann einfache Kalkulationen oder Umbenennungen vorgenommen werden.

8. Anlegen des Zählers als Virtuelles Gerät

Das Anlegen des Virtuellen Geräts erfolgt wie gewohnt einzeln über das User-Interface, als CSV-Import oder über die XAPI. Wenn das Gerätelimit des für den Wireless M-Bus Decoder in dem aktuellen Konto erreicht ist, können keine weiteren Geräte angelegt werden. Das Feld “Externe ID” wird im Unterschied zu anderen Konnektoren zu externen Systemen nicht ausgefüllt, sondern vom System generiert. Folgende konnektorspezifischen Felder sind verfügbar:

• Externe ID: Die externe ID wird automatisch generiert zur internen Verwendung nach dem Schema: Herstellercode_Seriennummer
• Herstellercode: Der Herstellercode besteht aus drei Großbuchstaben und eröglicht eine Identifizierung des Herstellers
• Gerätekey: AES Key bei wM-Bus (HEX, 32-stellig), nicht erforderlich bei unverschlüsselten Nachrichten
• Geräteseriennummer: Seriennummer des Herstellers (HEX, 8-stellig)