@mensch-und-maschine/node-red-contrib-modelsphere-sensor 1.0.1
Node-RED node for sending sensor data to the Modelsphere REST API
@mensch-und-maschine/node-red-contrib-modelsphere-sensor
A Node-RED package for sending sensor data to the Modelsphere platform via its REST API.
Developed and maintained by Mensch und Maschine Deutschland GmbH.
Features
- 🔐 Secure authentication via API-Key → Bearer Token exchange (JWT)
- 🔄 Automatic token renewal before expiry (configurable buffer window)
- 📡 Flexible value mapping – read from
msg.*, flow/global context, static values, or JSONata expressions - 🔁 Retry with exponential backoff and jitter on transient errors
- 💾 Offline buffer – persists unsent data locally (JSONL) and replays when the connection is restored
- 🏗️ Hub selection – loads available hubs directly from the API into a dropdown
Installation
Via Node-RED Palette Manager
Search for node-red-contrib-modelsphere-sensor and click Install.
Via npm
cd ~/.node-red
npm install @mensch-und-maschine/node-red-contrib-modelsphere-sensor
Manual (local development)
cd ~/.node-red
npm install /path/to/modelsphere-sensor
Restart Node-RED after installation.
Nodes
modelsphere-config – Server Connection
A shared configuration node that holds all connection and authentication settings. Multiple sensor nodes can share one config.
| Field | Description |
|---|---|
| Server-URL | Base URL of the Modelsphere backend, e.g. https://bimrepo-dev.mumiver.se |
| API-Key | Stored encrypted. Used for POST /api/auth/token-exchange |
| Timeout (ms) | HTTP request timeout in milliseconds (default: 5000) |
| Hub-ID | Target hub – loaded from GET /api/hubs via the dropdown |
| Token renewal (s) | Seconds before expiry at which a new token is fetched proactively (default: 30) |
| Max. retries | Number of retry attempts after a failed request (default: 3) |
| Base delay (ms) | Wait time before the first retry – doubles with each attempt (default: 2000) |
| Max. delay (ms) | Upper limit for retry delay (default: 30000) |
| Buffer enabled | Enable local offline buffer |
| Max. entries | Maximum number of buffered entries – oldest are discarded when full (default: 1000) |
| Flush interval (s) | Seconds between automatic replay attempts (default: 60) |
| Buffer path | Directory for buffer files (default: ~/.node-red/modelsphere-buffer) |
Test button
Click Verbindung testen to verify Server-URL and API-Key without deploying.
Hub selection
Click the ↻ button next to the Hub-ID dropdown to authenticate and load all available hubs from GET /api/hubs.
modelsphere-sensor – Virtual Sensor
Sends a measurement to the Modelsphere API whenever a message arrives.
Endpoint: POST /api/hubs/<hubId>/sensordata
| Field | Description |
|---|---|
| Server | Reference to a modelsphere-config node |
| Sensor Key | Unique identifier for the sensor (key in the payload) |
| Sensor Name | Display name of the sensor (name in the payload) |
| Value | Source of the measurement value (see Value mapping) |
| Data type | auto (detected), numeric, boolean, text, event, or json |
| Unit | Optional unit, e.g. °C, %, hPa, kWh |
Value mapping
The Value field uses Node-RED's typed input and supports:
| Type | Example |
|---|---|
msg |
msg.payload, msg.temperature, msg.data.value |
flow |
Flow context variable |
global |
Global context variable |
str |
Fixed string |
num |
Fixed number |
bool |
true / false |
json |
{"state": "on"} |
jsonata |
$number(msg.temp) * 1.8 + 32 |
env |
Environment variable |
Message overrides
The following msg properties override the node configuration at runtime:
| Property | Type | Description |
|---|---|---|
msg.sensorKey |
string |
Overrides the configured sensor key |
msg.sensorName |
string |
Overrides the configured sensor name |
msg.unit |
string |
Overrides the configured unit |
msg.timestamp |
string |
ISO-8601 timestamp – auto-generated if absent |
msg.meta |
object |
Additional metadata, e.g. { location: "Hall A" } |
Output message
On success, the node forwards the message with:
| Property | Type | Description |
|---|---|---|
msg.payload |
object |
JSON response from the Modelsphere API |
msg.statusCode |
number |
HTTP status code |
msg.modelsphereRequest |
object |
The exact payload that was sent |
API Payload Format
POST /api/hubs/<hubId>/sensordata
{
"key": "sensor-001",
"name": "Temperature Entrance",
"timestamp": "2026-04-14T10:00:00.000Z",
"type": "numeric",
"value": 23.5,
"unit": "°C",
"meta": {
"location": "Hall A",
"description": "Temperature measurement"
}
}
Authentication Flow
API-Key
│
▼
POST /api/auth/token-exchange
│
▼
Bearer JWT (cached, auto-renewed)
│
▼
POST /api/hubs/<hubId>/sensordata
Authorization: Bearer <token>
- On HTTP 401 or 403, the token cache is cleared and a single re-authentication attempt is made automatically.
- On other 4xx errors (except 429), the request fails permanently without retry.
- On 5xx errors or network failures, the retry mechanism with exponential backoff kicks in.
Offline Buffering
When the Modelsphere API is unreachable, measurements are written to a local JSONL file. Once the connection is restored, buffered entries are replayed in order.
~/.node-red/modelsphere-buffer/
└── buffer_<sensorKey>.jsonl
The buffer size is capped at Max. entries – once full, the oldest entry is discarded (FIFO).
Requirements
- Node-RED
>= 2.0.0 - Node.js
>= 14.0.0
License
MIT
