@scorp-io/node-red-contrib-scorp-io 0.2.0
Node-RED nodes for SCorp-io MQTTS integration with DBIRTH and DDATA messages.
@scorp-io/node-red-contrib-scorp-io
Node-RED nodes for SCorp-io MQTTS integration.
The package exposes a shared SCorp-io configuration node and a multi-device publishing node for:
DBIRTHmessages: device metric declarations;DDATAmessages: device metric values with timestamps.
Requirements
- Node.js
>=18.0.0 - Node-RED
>=3.0.0 - SCorp-io MQTT credentials for production mode
Installation
From the Node-RED editor
Open Menu → Manage palette → Install, then search for:
@scorp-io/node-red-contrib-scorp-io
From npm
Run from the Node-RED user directory, usually ~/.node-red:
cd ~/.node-red
npm install @scorp-io/node-red-contrib-scorp-io
Restart Node-RED after installation.
Nodes
scorp-io-config
Shared configuration node for the SCorp-io MQTT connection.
| Field | Description |
|---|---|
| Mode | test disables MQTT publishing; production publishes to the broker |
| Client ID | MQTT client identifier |
| Login | MQTT username |
| Password | MQTT password, stored as a Node-RED credential |
| Project ID | SCorp-io project identifier used in MQTT topics |
| Node ID | Edge node identifier used in MQTT topics |
Production broker endpoint:
mqtts://broker-public-prod.scorp-io.com:8883
scorp-io-device
Multi-device node that builds and publishes SCorp-io DBIRTH and DDATA payloads.
Input
The node has one input.
| Message | Behavior |
|---|---|
msg.topic === "birth" |
Emits a DBIRTH for all configured devices |
msg.deviceId set |
Emits DDATA for the matching configured device |
| regular payload | Emits DDATA for every device where at least one metric path resolves |
Output
The node has one debug output containing the generated message:
| Property | Description |
|---|---|
msg.topic |
MQTT topic that was/would be published |
msg.payload |
Generated SCorp-io payload |
msg._scorp.type |
DBIRTH or DDATA |
msg._scorp.device |
Target device id |
msg._scorp.simulated |
true in test mode |
Metric configuration
Each device has a list of metrics.
| Metric field | Description | Example |
|---|---|---|
name |
Metric name sent to SCorp-io | pompe-1/etats |
dataType |
Metric type: Integer, Short, Long, Double, Float, Boolean, String |
Integer |
valuePath |
Path resolved from incoming msg for DDATA |
msg.payload.pompe1.etats |
Supported value paths:
msg.payload.pompe1.etats
msg.pompe.etat
pompe1.etats
Paths without the msg. prefix are resolved from msg.payload.
DDATA publish modes
scorp-io-device supports two DDATA publish modes. The node-level setting defaults to full; each device can override it or inherit the node setting.
| Mode | Behavior | Use case |
|---|---|---|
full |
Publishes all configured metrics. If a valuePath cannot be resolved, the metric is still emitted with value: undefined and a warning is logged. |
Legacy flows and sources that send a full device snapshot. |
partial |
Publishes only metrics whose valuePath resolves to a value different from undefined. Missing paths are ignored without warning. If no metric resolves, no DDATA is published. |
Event sources such as KNX, LoRaWAN or Modbus events that send one metric at a time. |
null, 0, false and an empty string are legitimate values and are published in partial mode. NaN is treated as absent in partial mode and logs a distinct warning because it usually indicates a flow bug.
DBIRTH is unchanged: it always declares the complete metric list for the device, regardless of the DDATA publish mode. For heartbeat-only messages, model the heartbeat as a dedicated metric or emit a DBIRTH; partial mode does not publish empty DDATA payloads.
Topic format
mqtts/{PROJECT_ID}/{MESSAGE_TYPE}/{EDGE_NODE_ID}/{DEVICE_ID}
Examples:
mqtts/my-project/DBIRTH/edge-01/pompe-1
mqtts/my-project/DDATA/edge-01/pompe-1
Payload examples
DBIRTH
{
"metrics": [
{ "name": "pompe-1/etats", "dataType": "Integer" },
{ "name": "pompe-1/defaut", "dataType": "Boolean" }
]
}
DDATA
{
"metrics": [
{
"name": "pompe-1/etats",
"timestamp": 1710000000000,
"dataType": "Integer",
"value": 1
},
{
"name": "pompe-1/defaut",
"timestamp": 1710000000000,
"dataType": "Boolean",
"value": false
}
]
}
Example flow
An importable example is provided in:
examples/scorp-io-basic-flow.json
It runs in test mode by default, so it does not publish to the production MQTT broker.
Development
npm install
npm test
npm run pack:dry-run
License
MIT
