@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