Data Connectors · Environment

Pegelonline

On deployment the node connects to the EDIS MQTT broker of the German Federal Waterways and Shipping Administration and subscribes to the gauging stations you select by water body or individually. Every incoming reading, for example a new water level, leaves the node as a flat WaterObserved entity.

Data source
Event-based (MQTT)
WaterObserved

Node type: pegelonline
Package: @htag/node-red-contrib-hypertegrity-environment
Inputs / outputs: 0 / 1
Data source: Pegelonline (WSV) via EDIS MQTT broker and Dict API

When to use this node

Pegelonline provides the readings of more than 600 gauging stations on German federal waterways: water level, discharge, water temperature and further parameters. Instead of polling the REST interface regularly, the Pegelonline node receives the readings as events via MQTT as soon as the station delivers them.

Typical use cases are:

Water levels of the Rhine, Moselle or Elbe transferred into an NGSI-LD context broker in near real time.
Flood early warning for municipalities along federal waterways through threshold checks in the flow.
Shipping and tourism applications that display current levels and water temperatures.

How the node works

Resolve topics

On deployment the node queries the Pegelonline Dict API and determines the MQTT topics and master data of the requested stations.

Connect and subscribe

The node connects to the EDIS broker via TLS and subscribes to the station topic of each station in chunks of 50.

Filter and enrich

Incoming messages are filtered to the selected parameters and enriched with station name, water body, agency and coordinates.

Emit

Every reading leaves the node as its own message with a WaterObserved entity in msg.payload.

Result: A continuous stream of individual readings that can be passed directly to the NGSI-LD Builder.

The node is event-based and has no input. It starts automatically after deployment or when Node-RED starts. If the Dict API request fails, the node retries up to ten times at 10-second intervals. If the MQTT connection drops, the client reconnects every 5 seconds.

Configuration

The edit dialog is divided into the tabs Stations, Parameters and Settings.

Stations tab

Field	Type	Default	Meaning
Name	Text	empty	Display name of the node in the flow. Without a name the node shows "Pegelonline: water body" or "Pegelonline: Global".
Filter Mode	Select (`water`, `all`)	`water`	Filter by water shows the water body selection; Global (All Waters) clears the water body and lists all stations. Stored as `selectionMode`.
Water Body	Select	empty (all waters)	Short name of the water body from the Waters API, for example `RHEIN`. Stored as `water`.
Available Stations / Subscribed Stations	Dual list with search field	no selection	Use the arrow buttons to move stations to the right-hand list. The station UUIDs are stored in the array `stations`. If the right-hand list is empty, the node subscribes to all stations matching the water filter.

Parameters tab

Field	Type	Default	Meaning
Select Parameters	Checkboxes	`W`	Measured quantities that are passed on. Stored as the array `parameters`. Without a selection the node uses `W`.

Available parameters by group:

Group	Parameters
Primary	Water Level (W)
Hydrology	Discharge (Q), Flow Velocity (VA), Flow Direction (RV), Wave Height (SIGH), Wave Period (TP)
Water Quality	Water Temperature (WT), Salinity (S), pH Value (PH), Oxygen Content (O2), Conductivity (LF), Turbidity (TR)
Meteorology	Air Temperature (LT), Precipitation (P), Wind Velocity (WG), Wind Direction (WR)

Not every station provides all parameters. The node always subscribes to the complete station topic and discards messages with parameters that are not selected.

Settings tab

Field	Type	Default	Meaning
Broker URL	Text	see below	Address of the EDIS MQTT broker. The connection uses TLS with certificate verification.
Username	Text (credential)	empty	Username for the broker. Stored encrypted in the Node-RED credentials.
Password	Password (credential)	empty	Password for the broker. Stored encrypted.
Dict-API	Text	see below	Endpoint that delivers station master data and MQTT topics.
Waters-API	Text	see below	REST endpoint for the list of water bodies in the dialog.
Stations-API	Text	see below	REST endpoint for the station list in the dialog.
Debug Mode	Checkbox	off	Writes detailed logs as warnings to the debug sidebar.

Default values of the URL fields:

Broker URL:   ssl://edis.pegelonline.wsv.de:8883
Dict-API:     https://dict-api.pegelonline.wsv.de/search
Waters-API:   https://pegelonline.wsv.de/webservices/rest-api/v2/waters.json
Stations-API: https://pegelonline.wsv.de/webservices/rest-api/v2/stations.json

Credentials for the EDIS broker

The EDIS broker requires a login. For public read-only access the user edis-mqtt-ro is available; take the matching password from the Pegelonline documentation on MQTT access. Enter username and password on the Settings tab before deploying.

Input

The node has no input. It is triggered by:

the deployment of the flow or the start of Node-RED, which loads the master data and establishes the MQTT connection;
every MQTT message from the EDIS broker on a subscribed station topic.

To change the selection, edit the node and deploy again. On deployment or removal of the node the MQTT connection is closed cleanly.

Output

For every received reading the node sends a separate message. msg.payload is a flat object modelled on the Smart Data Model WaterObserved. The measured value is stored in an attribute whose name depends on the parameter.

{
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "type": "WaterObserved",
    "name": "EXAMPLETOWN - Wasserstand",
    "description": "Exampletown at EXAMPLE RIVER (km 123.4)",
    "dataProvider": "WSA Example River",
    "areaServed": "Example District, Example State",
    "location": {"type": "Point", "coordinates": [7.4001, 50.4302]},
    "dateObserved": "2026-10-01T08:15:00+02:00",
    "unit": "cm",
    "stationId": "00000000-0000-4000-8000-000000000001",
    "parameter": "W",
    "parameterName": "Wasserstand",
    "riverKilometer": 123.4,
    "waterLevel": 212
  },
  "topic": "edis/pegelonline/EXAMPLE RIVER/…/00000000-0000-4000-8000-000000000001/W",
  "_station": {"…": "station master data from the Dict API"},
  "_originalPayload": {"…": "unmodified MQTT message"}
}

Field	Meaning
`payload.id`, `payload.stationId`	UUID of the gauging station.
`payload.type`	Always `WaterObserved`.
`payload.name`	Short name of the station and long name of the parameter, separated by a hyphen.
`payload.description`	Long name of the station, water body and river kilometre.
`payload.dataProvider`	Responsible agency according to the master data, for example the Waterways and Shipping Office.
`payload.areaServed`	District and federal state of the station. Missing values appear as `Unknown`.
`payload.location`	GeoJSON point in the order longitude, latitude.
`payload.dateObserved`	Timestamp of the reading from the MQTT message; if missing, the time of receipt.
`payload.unit`	Unit according to the station's time series, for example `cm`, `m³/s` or `°C`.
`payload.parameter`, `payload.parameterName`	Short code and long name of the parameter (long names are delivered in German by the API).
`payload.riverKilometer`	River kilometre of the station.
Measurement attribute	The measured value under the attribute name from the table below.
`topic`	MQTT topic on which the message was received.
`_station`	Complete master data record of the station from the Dict API.
`_originalPayload`	Unmodified MQTT message.

Mapping of parameters to attribute names:

Parameter	Attribute	Parameter	Attribute
W	`waterLevel`	S	`salinity`
Q	`discharge`	PH	`ph`
WT	`waterTemperature`	O2	`oxygenContent`
LT	`airTemperature`	VA	`flowVelocity`
P	`precipitation`	RV	`flowDirection`
LF	`conductivity`	TR	`turbidity`
WG	`windSpeed`	SIGH	`significantWaveHeight`
WR	`windDirection`	TP	`wavePeriod`

Unknown parameters end up in the attribute measuredValue.

Example flow

The package ships with an example flow. Import it in Node-RED via Menu → Import → Examples → @htag/node-red-contrib-hypertegrity-environment → pegelonline. Alternatively download pegelonline.json and import it via Menu → Import.

Step 1

Pegelonline

The node 'Pegel Andernach' is preconfigured in global mode with exactly one subscribed station and the parameter W.

Step 2

Add credentials

Enter username and password for the EDIS broker on the Settings tab and deploy.

Step 3

Debug

A Debug node shows every incoming reading as a complete message in the sidebar.

Show example flow as JSON

[
  {"id": "pegel1", "type": "pegelonline", "z": "tab1", "name": "Pegel Andernach", "water": "", "stations": "[\"5735892a-ec65-4b29-97c5-50939aa9584e\"]", "selectionMode": "all", "brokerUrl": "ssl://edis.pegelonline.wsv.de:8883", "dictApiUrl": "https://dict-api.pegelonline.wsv.de/search", "restApiWatersUrl": "https://pegelonline.wsv.de/webservices/rest-api/v2/waters.json", "restApiStationsUrl": "https://pegelonline.wsv.de/webservices/rest-api/v2/stations.json", "parameters": "[\"W\"]", "debug": false, "x": 140, "y": 100, "wires": [["debug1"]]},
  {"id": "debug1", "type": "debug", "z": "tab1", "name": "Gauge output", "active": true, "tosidebar": true, "console": false, "tostatus": false, "complete": "false", "x": 400, "y": 100, "wires": []}
]

Status and errors

Indicator	Meaning
Blue dot "resolving topics..."	The Dict API is being queried.
Yellow ring "retry setup (n / 10)..."	The Dict API request failed; the node waits 10 seconds and tries again.
Yellow ring "no stations found"	The Dict API returned no stations.
Yellow ring "no stations match"	None of the selected station UUIDs is contained in the Dict API result.
Yellow ring "no topics match parameters"	No MQTT topic was found for the target stations.
Blue dot "connecting mqtt..."	The connection to the broker is being established.
Green dot "connected"	The connection is up; subscriptions are being set up.
Green dot "(n Stations)"	Subscriptions have been requested; n stations are monitored.
Yellow dot "reconnecting..."	The MQTT client is trying to re-establish the connection.
Red dot "offline"	The client lost the connection to the broker.
Red ring "subscribe error"	A subscription chunk was rejected by the broker. The message "Subscription chunk error: …" is reported via `node.error`.
Red dot "mqtt error"	The MQTT client reported an error, for example rejected credentials. The message "MQTT Error: …" is reported via `node.error`.
Red ring "disconnected"	The connection was closed.
Red dot "setup failed"	Initialisation failed after all attempts. The message "Nodes initialization failed: …" is reported via `node.error`.

Errors are reported via node.error and can be handled with a Catch node. Messages that do not contain valid JSON are silently discarded.

Notes

Credentials and terms of use: The EDIS broker and the Pegelonline interfaces are subject to the terms of use of the German Federal Waterways and Shipping Administration. The data is usually provided under the Data licence Germany; check the current terms on the Pegelonline website.
Persistent connection: The node keeps a permanent TLS connection (keepalive 60 seconds, connect timeout 30 seconds). Several node instances each open their own connection. Group stations in one node where possible.
Proxy and firewall: Operation requires outgoing connections to port 8883 (MQTT over TLS) as well as HTTPS to the Pegelonline endpoints.
Admin endpoints: The dialog loads water bodies and stations via the endpoints /pegelonline/waters and /pegelonline/stations of the Node-RED server, which forward the request to the REST API.
Units: Units come from the station's time series and are passed on unchanged (for example cm for water level, m³/s for discharge, °C for temperatures).
Personal data: The data describes official gauging stations and contains no personal information. dataProvider names the responsible agency.
Output format: The node delivers a flat object without NGSI-LD context. Use the NGSI-LD Builder to shape the data for a context broker.

When to use this node​

How the node works​

Resolve topics

Connect and subscribe

Filter and enrich

Emit

Configuration​

Stations tab​

Parameters tab​

Settings tab​

Input​

Output​

Example flow​

Pegelonline

Add credentials

Debug

Status and errors​

Notes​

Related topics​

References​

When to use this node

How the node works

Configuration

Stations tab

Parameters tab

Settings tab

Input

Output

Example flow

Status and errors

Notes

Related topics

References