Utility

Device Info

Der Node nimmt eine Uplink-Payload von The Things Network beziehungsweise The Things Industries (TTN/TTI) oder eine beliebige JSON-Payload entgegen und erzeugt daraus eine NGSI-LD-Entität vom Typ Device mit Kennungen, Standort, Signalwerten, Batteriestand und Gateways. Felder werden per Pfad zugeordnet oder statisch gesetzt; eine Namenszuordnung übersetzt technische DeviceIDs in lesbare Namen.

NGSI-LD
LoRaWAN
Device

Node-Typ: device-info
Paket: @htag/node-red-contrib-hypertegrity-utility
Eingänge / Ausgänge: 1 / 1
Abhängigkeit: Keine externe; TTN/TTI-Payload optional

Wofür Sie den Node verwenden

LoRaWAN-Sensoren liefern über TTN/TTI umfangreiche Uplink-Nachrichten mit Gerätekennungen, Gateway-Metadaten und dekodierten Messwerten. Der Device-Info-Node extrahiert daraus die Geräteinformationen und formt sie in eine NGSI-LD-Entität nach dem Smart Data Model Device, die direkt an einen Context Broker übertragen werden kann.

Typische Einsatzfälle sind:

Geräteinventar im Context Broker pflegen: Jeder Uplink aktualisiert die zugehörige Device-Entität mit Standort, Signalstärke und Batteriestand.
Technische IDs in lesbare Namen übersetzen: Die Namenszuordnung ersetzt eui-70b3… durch „Rathaus Büro 1“ und behält die DeviceID als alternateName.
Payloads anderer Anbieter verarbeiten: Mit dem Anbieter „Andere“ ordnen Sie beliebige JSON-Felder zu und ergänzen fehlende Werte statisch.

So funktioniert der Node

Payload prüfen

msg.payload muss ein Objekt sein (kein Array). Ist der Anbieter TTI/TTN oder enthält die Payload end_device_ids und uplink_message, gelten die TTN-Standardpfade als Rückfallebene.

Felder auflösen

Je Attribut gilt die Reihenfolge: statischer Wert, zugeordneter Pfad, TTN-Standardpfad, Vorgabewert. Werte, die wie JSON aussehen, werden geparst.

Entität bauen

ID, Typ Device, Kontext, Kennungen, Name, Standort als GeoProperty, Gateways, RSSI/SNR, Batteriestand, Anbieter, benutzerdefinierte Zuordnungen und dateObserved werden als NGSI-LD-Properties angelegt.

Umformen

Ein Transformations-Skript kann die Entität vor der Ausgabe in einer Sandbox anpassen (Zeitlimit 2 s).

Ergebnis: msg.payload enthält ein Array mit genau einer NGSI-LD-Entität vom Typ Device.

Der Node ist nachrichtengetrieben und verarbeitet jede eingehende Nachricht sofort. Zusätzlich merkt er sich jede DeviceID, die ihn passiert (Anzahl, erstes und letztes Auftreten, maximal 2000 Einträge), und bietet diese Liste im Editor für die Namenszuordnung an. Die Liste wird im Node-Kontext unter dem Schlüssel seenDevices gespiegelt und übersteht Deploys und Neustarts nur, wenn ein persistenter Kontextspeicher konfiguriert ist.

Konfiguration

Der Bearbeitungsdialog hat die Registerkarten Allgemein, Mapping, Sensor Zuordnung und Logik. Auf der Registerkarte Mapping besitzt jedes Attribut zwei Felder: links den Payload-Pfad (Auswahl aus dem Beispiel JSON oder freie Eingabe), rechts Überschreiben (Statisch). Ein statischer Wert hat immer Vorrang.

Registerkarte Allgemein

Feld	Typ	Standard	Bedeutung
Anbieter	Auswahl	TTI / TTN	`TTI/TTN` aktiviert die automatischen TTN-Standardpfade und die Schaltfläche TTI automatisch ausfüllen; `Andere` blendet stattdessen die Felder RSSI und SNR ein.
Normalisieren	Kontrollkästchen	inaktiv	Skaliert einen Batteriewert über 1 durch Division durch 100 (85 → 0,85). Werte über 1 werden anschließend in jedem Fall wiederholt durch 100 geteilt, bis sie im Bereich 0 bis 1 liegen.
Beispiel JSON	Textfeld	leer	Beispiel-Payload des Sensors. Die erkannten Pfade erscheinen als Auswahl in allen Pfadfeldern.
Kontext	Text	leer	Eigene `@context`-URL oder JSON-Array von URLs. Leer bedeutet `https://context.<DOMAIN>/main-context`, wobei `DOMAIN` aus der Umgebungsvariablen gleichen Namens stammt (Rückfall: `domain`).

Registerkarte Mapping

Feld	Typ	Standard	Bedeutung
TTI automatisch ausfüllen	Schaltfläche	–	Belegt die Pfadfelder mit den Standardpfaden einer The-Things-Stack-Payload (Liste unten).
ID Präfix	Text	`urn:ngsi-ld:Device:`	Präfix der Entitäts-ID. Fehlt der abschließende Doppelpunkt, wird er ergänzt. Beginnt die DeviceID bereits mit `urn:ngsi-ld:`, wird sie unverändert übernommen.
Name	Pfad / statisch	leer	Lesbarer Gerätename; wird von der Namenszuordnung und dem statischen Wert überstimmt.
DeviceID	Pfad / statisch	leer	Technische Gerätekennung; bildet die Entitäts-ID. TTN-Rückfall: `end_device_ids.device_id`. Ältere Flows mit den Feldern `mapAlternateName` / `staticAlternateName` werden automatisch übernommen.
DevEUI	Pfad / statisch	leer	Geräte-EUI. TTN-Rückfall: `end_device_ids.dev_eui`. Dient als Entitäts-ID, wenn keine DeviceID vorliegt.
Anbieter Info	Pfad / statisch	leer	Wert für `dataProvider`. Ohne Zuordnung wird der gewählte Anbieter verwendet; `Andere` erzeugt kein Attribut.
Kontaktdaten	statisch	leer	Statischer Wert für das Attribut `contact`.
Breitengrad, Längengrad	Pfad / statisch	leer	Standort. TTN-Rückfall: die Standortpfade aus der Pfadliste unter der Tabelle. Nur gültige Koordinaten erzeugen eine GeoProperty.
RX Metadaten	Pfad / statisch (JSON)	leer	Nur bei TTI/TTN: Gateway-Array. TTN-Rückfall: `uplink_message.rx_metadata`. Daraus werden `gateways` sowie RSSI und SNR des Gateways mit dem besten RSSI abgeleitet.
RSSI, SNR	Pfad / statisch	leer	Nur bei Anbieter „Andere“: direkte Pfade zu den Signalwerten. Fehlen sie, werden sie aus den RX Metadaten übernommen.
Batteriestand	Pfad / statisch	leer	Batteriewert. TTN-Rückfall: der Batteriepfad aus der Pfadliste unter der Tabelle. Ausgabe im Bereich 0 bis 1, auf vier Nachkommastellen gerundet.
Benutzerdefinierte Zuordnungen	Liste	leer	Je Zeile ein Quellpfad in der Payload und ein Zielattribut der Entität. Punkt-Notation im Ziel erzeugt verschachtelte Werte innerhalb einer Property. Die Schlüssel `id`, `type`, `@context` und `scope` sind gesperrt. Gespeichert in `customMappings`.

Pfade, die die Schaltfläche „TTI automatisch ausfüllen“ setzt:

end_device_ids.device_id                 (DeviceID)
end_device_ids.dev_eui                   (DevEUI)
uplink_message.locations.user.latitude
uplink_message.locations.user.longitude
uplink_message.rx_metadata               (RX Metadaten)
uplink_message.decoded_payload.battery   (Batteriestand)

Registerkarte Sensor Zuordnung

Feld	Typ	Standard	Bedeutung
Erkannte DeviceIDs	Liste	leer	DeviceIDs, die der deployte Node bereits gesehen hat, mit Anzahl und Zeitpunkt des letzten Eintreffens. Über Aktualisieren neu laden, über + in die Namenszuordnung übernehmen, über das Papierkorb-Symbol die Liste löschen. Die Liste kommt vom Admin-Endpunkt `/device-info/<Node-ID>/seen-devices`.
Namenszuordnung	Liste	leer	Je Zeile eine DeviceID und ein menschenlesbarer Name. Der Name wird als `name` ausgegeben; weicht er von der DeviceID ab, erscheint die DeviceID zusätzlich als `alternateName`. Gespeichert in `sensorMapping`.

Bei TTI/TTN-Payloads hat die Namenszuordnung eine zweite Funktion: Stimmt eine eingetragene „DeviceID“ mit einem Schlüssel in uplink_message.decoded_payload überein, wird dieser Messwert unter dem zugeordneten Namen als eigene Property in die Entität übernommen.

Registerkarte Logik

Feld	Typ	Standard	Bedeutung
Transformations-Skript aktivieren	Kontrollkästchen	inaktiv	Schaltet das Skript ein.
Transformations-Skript (JS)	Code-Editor	leer	JavaScript, das nach dem Aufbau der Entität läuft. Verfügbar sind `entity`, `payload`, `msg`, `console`, `makeProperty(value, observedAt)` und der ältere Alias `formatProperty`. Ändern Sie `entity` direkt. Das Skript wird einmal beim Deploy kompiliert und je Nachricht mit 2 s Zeitlimit ausgeführt.

Eingang

Eigenschaft	Typ	Bedeutung
`msg.payload`	Objekt	Die Sensor-Payload. Arrays und Nicht-Objekte werden mit dem Fehler `Input payload must be a non-array object` abgewiesen.
`msg.payload.end_device_ids`, `msg.payload.uplink_message`	Objekt	Erkennungsmerkmal einer TTN/TTI-Payload; aktiviert die Standardpfade auch beim Anbieter „Andere“.
`msg.payload.received_at`	Zeitstempel	Wird als `dateObserved` und als `observedAt` der Messwert-Properties verwendet. Fehlt er, gilt die aktuelle Zeit nur für `observedAt`; `dateObserved` wird dann nicht angelegt.
`decoded_payload` (unterhalb von `msg.payload.uplink_message`)	Objekt	Bei TTN/TTI: Quelle für Batteriestand und für Messwerte, die über die Namenszuordnung befördert werden.

Ausgang

msg.payload enthält ein Array mit genau einer Entität. Beispiel für einen TTN-Uplink mit Namenszuordnung:

[
  {
    "id": "urn:ngsi-ld:Device:eui-70b3d57ed0000001",
    "type": "Device",
    "@context": ["https://context.beispielstadt.de/main-context"],
    "deviceEUI": {"type": "Property", "value": "70B3D57ED0000001"},
    "deviceID": {"type": "Property", "value": "eui-70b3d57ed0000001"},
    "name": {"type": "Property", "value": "Rathaus Büro 1"},
    "alternateName": {"type": "Property", "value": "eui-70b3d57ed0000001"},
    "location": {"type": "GeoProperty", "value": {"type": "Point", "coordinates": [8.353, 50.0]}},
    "gateways": {"type": "Property", "value": [{"gatewayId": "gw-rathaus", "eui": "AA555A0000000001", "rssi": -87, "snr": 7.5}], "observedAt": "2026-10-01T08:15:00.000Z"},
    "rssi": {"type": "Property", "value": -87, "observedAt": "2026-10-01T08:15:00.000Z"},
    "snr": {"type": "Property", "value": 7.5, "observedAt": "2026-10-01T08:15:00.000Z"},
    "batteryLevel": {"type": "Property", "value": 0.85, "observedAt": "2026-10-01T08:15:00.000Z"},
    "dataProvider": {"type": "Property", "value": "TTI/TTN"},
    "dateObserved": {"type": "Property", "value": "2026-10-01T08:15:00.000Z"}
  }
]

Feld	Bedeutung
`id`	ID Präfix plus DeviceID, ersatzweise DevEUI, ersatzweise `unknown-<Zufallskennung>`.
`type`	Immer `Device`.
`@context`	Konfigurierter Kontext oder Standardkontext als Array.
`deviceEUI`, `deviceID`	Kennungen als Text, nur wenn vorhanden.
`name`	Reihenfolge: statischer Name, Namenszuordnung, zugeordneter Payload-Name, DeviceID.
`alternateName`	Nur wenn die Namenszuordnung einen Namen liefert, der von der DeviceID abweicht; enthält die DeviceID.
`contact`	Statische Kontaktdaten, nur wenn gesetzt.
`location`	GeoProperty mit GeoJSON-Point `[Längengrad, Breitengrad]`, nur bei gültigen Koordinaten.
`gateways`	Array mit `gatewayId`, `eui`, `rssi`, `snr` je Gateway aus den RX Metadaten.
`rssi`, `snr`	Direkt zugeordnete Werte oder die des Gateways mit dem höchsten RSSI.
`batteryLevel`	Batteriestand 0 bis 1.
`dataProvider`	Anbieter Info oder gewählter Anbieter, nicht bei „Andere“.
Beförderte Messwerte	Properties, deren Name aus der Namenszuordnung stammt (nur TTN/TTI, nur wenn der Name noch nicht belegt ist).
Benutzerdefinierte Attribute	Ziele der benutzerdefinierten Zuordnungen; GeoJSON-Points werden zu GeoProperty, alles andere zu Property.
`dateObserved`	ISO-8601-Zeitstempel aus `received_at`, nur wenn vorhanden.

Alle Messwert-Properties (gateways, rssi, snr, batteryLevel, beförderte und benutzerdefinierte Werte) tragen die Annotation observedAt.

Beispiel-Flow

Das Paket bringt einen Beispiel-Flow mit. Sie importieren ihn in Node-RED über Menü → Importieren → Beispiele → @htag/node-red-contrib-hypertegrity-utility → device-info. Alternativ laden Sie die Datei device-info.json herunter und importieren sie über Menü → Importieren. Der MQTT-In-Node im Beispiel hat keinen Broker und kein Topic; beides tragen Sie nach dem Import ein.

Schritt 1

MQTT In

Ein MQTT-In-Node empfängt die Uplink-Nachrichten, zum Beispiel aus der MQTT-Integration von TTN/TTI.

Schritt 2

Device Info

Der Node erzeugt mit den TTN-Standardpfaden eine Device-Entität ohne weitere Konfiguration.

Schritt 3

Debug

Ein Debug-Node zeigt das Array mit der Entität in der Seitenleiste an.

Beispiel-Flow als JSON anzeigen

[
  {"id": "tab1", "type": "tab", "label": "Device Info", "disabled": false, "info": ""},
  {"id": "mqtt1", "type": "mqtt in", "z": "tab1", "name": "", "topic": "", "qos": "2", "datatype": "auto-detect", "nl": false, "rap": true, "rh": 0, "inputs": 0, "x": 190, "y": 140, "wires": [["di1"]]},
  {"id": "di1", "type": "device-info", "z": "tab1", "name": "", "providerType": "TTI/TTN", "sampleJson": "",
    "mapName": "", "staticName": "", "mapDeviceID": "", "staticDeviceID": "", "mapDevEUI": "", "staticDevEUI": "",
    "mapLat": "", "staticLat": "", "mapLon": "", "staticLon": "", "mapRxMetadata": "", "staticRxMetadata": "",
    "mapRssi": "", "staticRssi": "", "mapSnr": "", "staticSnr": "", "mapBattery": "", "staticBattery": "",
    "mapProvider": "", "staticProvider": "", "idPrefix": "urn:ngsi-ld:Device:", "staticContact": "",
    "normalizeBattery": false, "sensorMapping": "[]", "customMappings": "[]",
    "useTransformation": false, "transformationScript": "", "context": "",
    "x": 390, "y": 140, "wires": [["dbg1"]]},
  {"id": "dbg1", "type": "debug", "z": "tab1", "name": "Device Info Entity", "active": true, "tosidebar": true, "complete": "payload", "targetType": "msg", "x": 610, "y": 140, "wires": []}
]

Status und Fehler

Anzeige	Bedeutung
Grauer Ring „ready“	Node ist deployt, noch keine Nachricht verarbeitet.
Grüner Punkt „…:Device:eui-70b3d57ed0000001 (3 dev)“	Letzte Entität erfolgreich erzeugt; in Klammern die Zahl der bisher gesehenen DeviceIDs. Lange IDs werden vorne gekürzt.
Roter Ring „Input payload must be a non-array object“	`msg.payload` ist kein Objekt. Die Nachricht wird nicht gesendet.
Roter Ring „Transformation script error: …“	Das Transformations-Skript hat einen Fehler geworfen oder das Zeitlimit überschritten.
Fehler „Transformation script compilation failed: …“	Das Skript ließ sich beim Deploy nicht kompilieren; der Node arbeitet ohne Skript weiter.
Warnung „Custom mapping `<Quelle>` -> `<Ziel>`: …“	Eine benutzerdefinierte Zuordnung konnte nicht geschrieben werden; die übrigen werden verarbeitet.

Fehler werden über done(err) gemeldet und lassen sich mit einem Catch-Node abfangen.

Hinweise

Kontextspeicher: Die erkannten DeviceIDs liegen im Node-Kontext (seenDevices) und werden mit 3 s Verzögerung gespeichert. Ohne persistenten Kontextspeicher in settings.js ist die Liste nach einem Neustart leer. Über das Papierkorb-Symbol im Dialog oder POST /device-info/<Node-ID>/seen-devices/clear löschen Sie sie.
Admin-Endpunkte: GET /device-info/<Node-ID>/seen-devices und der Lösch-Endpunkt verlangen die Node-RED-Berechtigungen device-info.read beziehungsweise device-info.write.
Transformations-Skript: Das Skript hat vollen Zugriff auf entity, payload und msg und läuft mit einem Zeitlimit von 2 s. Erlauben Sie die Bearbeitung des Flows nur vertrauenswürdigen Personen.
Batteriestand: Das Smart Data Model erwartet batteryLevel im Bereich 0 bis 1. Prozentwerte werden auch ohne Normalisieren heruntergeteilt; negative Werte werden auf 0 gesetzt.
Zeitstempel: dateObserved und alle observedAt-Annotationen werden als ISO-8601-Text in UTC ausgegeben.
Datenschutz: DeviceIDs, DevEUIs, Standorte und die statischen Kontaktdaten können personenbezogen sein, etwa wenn Geräte einzelnen Personen zugeordnet sind oder Ansprechpersonen genannt werden. Tragen Sie in Kontaktdaten keine privaten Namen oder Adressen ein und prüfen Sie vor der Übertragung in einen Context Broker, welche Attribute veröffentlicht werden dürfen. Die Liste der erkannten DeviceIDs verbleibt im Node-RED-Kontext.
Einheiten: RSSI in dBm, SNR in dB, Koordinaten in Dezimalgrad (WGS 84), Batteriestand als Anteil 0 bis 1.

Device Info

Wofür Sie den Node verwenden

So funktioniert der Node

Payload prüfen

Felder auflösen

Entität bauen

Umformen

Konfiguration

Registerkarte Allgemein

Registerkarte Mapping

Registerkarte Sensor Zuordnung

Registerkarte Logik

Eingang

Ausgang

Beispiel-Flow

MQTT In

Device Info

Debug

Status und Fehler

Hinweise

Weiterführende Themen

Referenzen

Wofür Sie den Node verwenden​

So funktioniert der Node​

Payload prüfen

Felder auflösen

Entität bauen

Umformen

Konfiguration​

Registerkarte Allgemein​

Registerkarte Mapping​

Registerkarte Sensor Zuordnung​

Registerkarte Logik​

Eingang​

Ausgang​

Beispiel-Flow​

MQTT In

Device Info

Debug

Status und Fehler​

Hinweise​

Weiterführende Themen​

Referenzen​

Wofür Sie den Node verwenden

So funktioniert der Node

Konfiguration

Registerkarte Allgemein

Registerkarte Mapping

Registerkarte Sensor Zuordnung

Registerkarte Logik

Eingang

Ausgang

Beispiel-Flow

Status und Fehler

Hinweise

Weiterführende Themen

Referenzen