@htag/node-red-contrib-hypertegrity-utility 0.3.2
Hypertegrity NodeRED Utility Nodes.
Hypertegrity Node-RED Utility Nodes
A collection of Node-RED helper nodes for general-purpose tasks.
📝 Introduction
This package provides utility nodes to support your Node-RED flows, including debugging tools, geospatial grouping functions, geocoding and NGSI-LD conversion.
Included Nodes
| Node | Description |
|---|---|
device-info |
Converts generic IoT payload streams (TTN/TTI or custom JSON) into the NGSI-LD Device format, including field mapping and DeviceID-to-name resolution |
geocoder |
Translates coordinates into addresses and addresses into coordinates via Nominatim, with freely mappable input/output fields, rate limiting and caching |
location-group |
Groups incoming data points by geographic area (polygon regions, e.g. administrative boundaries; no radius regions) using Turf.js and Nominatim |
mqtt-debug |
A debug node for monitoring and inspecting MQTT message payloads |
Configuration by message
Every node accepts an optional msg.config object. Its properties have the names of the editor settings and override them
for this message only. The help of each node lists the supported keys. The transformation script of device-info
cannot be set by message, so that no code from message content is executed. Invalid values raise an error (Catch node).
msg.config is not part of the output message.
Note: With
msg.config.endpointthe message chooses the server that thegeocoderqueries. Do not passmsg.configfrom external sources (e.g. MQTT) unchecked.
Settings (settings.js)
hypertegrity: {
// Hosts in the internal network that editor test lookups (geocoder) may reach
allowedHosts: ["nominatim.internal"],
// Own Nominatim instance for the editor search of location-group
nominatimUrl: "https://nominatim.internal",
// Contact added to the User-Agent of requests to Nominatim (please use a functional mailbox)
contact: "[email protected]"
}
Notes on upgrading to 0.3.2
- All nodes send a copy of the input message without
msg.config; the output structure is unchanged. Exception: the replay output ofmqtt-debug(output 2) is a new message that only containspayload(as before). location-group: in data scope "array", a leadingpayload.in the output path of the items is ignored (before, it created a nestedpayloadobject inside each item). Items that are no objects no longer abort the message. Regions without an area are reported once at deploy and skipped. New option "normalize group names" (default as before) and new opt-in options "drop empty results", "prefer smallest region" and position type "automatic". Coordinates with a decimal comma ("49,44") are read correctly (before: truncated to 49); text with further characters is invalid. A coordinate array withoutorder(e.g. inmsg.config.locationConfigor imported flows) is read as[lon, lat], as documented (before:[lat, lon]; flows saved in the editor always containorder). For a single object the GeoJSON field (polyField) accepts the prefixespayload.andmsg.like the other fields. A match in a region without name and group gives#<position in the region list>instead of no value. Group names in decomposed Unicode form (NFD) give the same normalized name as composed ones. Unclosed polygon rings are closed at deploy (one warning).msg.config.locationConfigwith broken JSON or an unknownposType/orderraises an error. The editor map search answers empty or non-numeric coordinates with HTTP 400 without a request to Nominatim. Without configured regions the message passes unchanged (unchanged behaviour, now documented).device-info: new option "battery unit"; existing flows keep "automatic" (previous behaviour). Existing flows with the former option "normalize" (scale 0-100 to 0-1) read the values as percent with "automatic", as the option says: a battery value of 1 gives 0.01 (before: 1, i.e. full). Without DeviceID and DevEUI a stable replacement IDunknown-<hash>is used instead of a random ID.dateObservedis only set when a timestamp exists; Unix seconds are recognized. New opt-in option "sanitize attribute names". Numbers with a decimal comma ("87,5","49,44") are read correctly (before: truncated); unit suffixes ("21°C") stay allowed, ambiguous numbers such as"1.2.3"give no attribute. Values taken over into the entity are copies (no shared objects with the input message).msg.config.batteryVMin/batteryVMaxmust be numbers or purely numeric text ("",nullandfalseraise an error instead of being read as 0). Battery unit "automatic": negative values are reported (limited to 0 as before). An emptymsg.config.idPrefixuses the default prefix like an empty editor value. An@contextthat starts with[but is no valid, non-empty JSON array falls back to the default context with a warning. Invalid timestamps give the processing time asdateObserved; ISO timestamps without time zone are read in the time zone of the server (both unchanged, now documented).mqtt-debug: a persistent session no longer unsubscribes on redeploy. The replay history is stored in the node context (taken over once from the global context); new nodes do not persist it. Replayed messages containpayload.replayedAtandpayload.manual. A proxy is only used forws:///wss://brokers, as in the core MQTT node. New checkbox "verify server certificate" (on for new brokers, existing brokers unchanged with a warning).msg.config.qos/rh/debugBuffergiven asnull,"",true/falseor an array raise an error instead of being read as a number. Topics named like object prototype keys (e.g.__proto__,constructor) are handled as plain topics (protection against prototype pollution). The topic filter follows MQTT:+also matches an empty level, filters starting with+/#do not match$topics (e.g.$SYS/…), all other characters (also{,}) are literal. For shared subscriptions ($share/<group>/<filter>) only<filter>is matched against the topic with these rules (before,$share/<group>/#matched no topic). An MQTT v5 message with several subscription identifiers reaches every matching node. After an exception in the connection setup the broker no longer stays in "connecting" (red status, new connect possible). The CONNACK user properties of the server are stored correctly. The repeat interval accepts decimals (minimum 1 s). With a persistent session a changed topic of a node releases the old subscription on redeploy, and closed node instances no longer output messages.geocoder: results are written as copies, so later changes in the flow no longer alter the cache. A target path below a value that is no object is reported as an error instead of being ignored. Address objects in the free-text field become a structured query. Error messages no longer contain addresses or coordinates.Retry-Afteris respected. Editor test lookups only reach public endpoints, endpoints of deployed geocoder nodes andallowedHosts; IPv6 notations of internal addresses are recognized and the address used for the connection is checked again (DNS rebinding). Answers without the expected structure (HTML page, broken JSON with HTTP 200) are errors and are no longer cached as "notFound"; the editor test answers them withlookup_failed. Error texts name the HTTP status only for HTTP errors (>= 400), otherwise the cause (e.g.ERR_BAD_RESPONSEinstead of "HTTP 200" for an aborted answer). Coordinates with a decimal comma are read correctly; numericmsg.configvalues must be numbers or purely numeric text ("12abc"raises an error). Output mappings with unknown field names behave like missing values. Concurrent identical lookups share one request.msg.config.cacheTtlalso applies when the editor cache duration is 0 (each entry keeps its own duration; 0 = no expiry). Structured address fields only use text and numbers (objects are ignored instead of being sent as[object Object]).msg.config.zoomabove 18 is limited to 18, and the debug log of failed reverse lookups contains coordinates rounded to about 1 km (both unchanged, now documented).device-info,geocoder,location-group: paths and names with the segments__proto__,constructororprototype(mapping paths, target paths, output property) raise an error according to the error handling of the node (protection against prototype pollution).
Data protection (GDPR)
Addresses, precise coordinates, device IDs and MQTT payloads can be personal data. The geocoder transmits every queried
location to the configured Nominatim service (with the public endpoint, to a third party). Contact and e-mail fields are
stored in the flow; please use functional mailboxes.
Installation
Install via the Node-RED Palette Manager or using npm:
npm install @htag/node-red-contrib-hypertegrity-utility
🌍 About the Project / Über das Projekt
📍 Über dieses Projekt / About this Project
DE: Dieses Open Source Projekt ist im Rahmen der Förderung Modellprojekte Smart Cities entstanden und wurde durch die Initiative des Projekts Südwestcluster ermöglicht.
EN: This open source project was created as part of the Smart City Pilot Projects (Modellprojekte Smart Cities) funding and was made possible by the initiative of the Südwestcluster project.
💡 Hintergrund / Background
DE: Die Entwicklung wurde durch öffentliche Gelder im Kontext der Förderung Modellprojekte Smart Cities unterstützt. Dadurch können wir diese Lösung der gesamten Community als Open Source zur Verfügung stellen.
EN: The development was supported by public funds in the context of the Smart City Pilot Projects (Modellprojekte Smart Cities) funding. This allows us to make this solution available to the entire community as open source.
🌐 Open Source Philosophie / Open Source Philosophy
DE: Wir unterstützen aktiv die OSS-Community und fördern kollaborative Entwicklung. Durch die Veröffentlichung als Open Source profitieren alle Beteiligten:
- Community: Freier Zugang zu moderner Smart City Technologie
- Transparenz: Nachvollziehbare und überprüfbare Lösungen
- Innovation: Gemeinsame Weiterentwicklung durch verschiedene Akteure
- Nachhaltigkeit: Langfristige Verfügbarkeit und Wartbarkeit
EN: We actively support the OSS community and promote collaborative development. Releasing it as open source benefits everyone involved:
- Community: Free access to modern Smart City technology
- Transparency: Traceable and verifiable solutions
- Innovation: Collaborative development by various actors
- Sustainability: Long-term availability and maintainability
🙏 Danksagung / Acknowledgements
DE: Ein besonderer Dank gilt der Förderung Modellprojekte Smart Cities für die finanzielle Unterstützung sowie dem Projekt Südwestcluster für die Initiative and Koordination:
- Eifelkreis Bitburg-Prüm
- Stadt Kaiserslautern
- Landkreis Kusel
- Stadt und Verbandsgemeinde Linz am Rhein
- Landkreis Mayen-Koblenz
- Landkreis St. Wendel
EN: Special thanks goes to the Smart City Pilot Projects (Modellprojekte Smart Cities) funding for financial support and the Südwestcluster project for the initiative and coordination:
- Eifelkreis Bitburg-Prüm
- City of Kaiserslautern
- District of Kusel
- City and Collective Municipality of Linz am Rhein
- District of Mayen-Koblenz
- District of St. Wendel
📜 License & Contact / Lizenz & Kontakt
© 2026 HYPERTEGRITY AG. Alle Rechte vorbehalten. / All rights reserved.
⚖️ License Compatibility / Lizenz-Kompatibilität
DE: Details zur Lizenzierung und zu den Nutzungsrechten finden Sie in der beigefügten LICENSE Datei.
EN: Details on licensing and usage rights can be found in the attached LICENSE file.
📧 Contact / Kontakt: [email protected] 🌐 Website: www.hypertegrity.de