node-red-contrib-opcua-suite

An OPC UA suite for Node-RED.

Features

• Shared connections — All nodes referencing the same endpoint share one TCP connection (ref-counted)
• Batch read/write — Single OPC UA service call via msg.items or payload object
• Item collector — Chain opcua-item nodes visually for batch operations
• Drag & drop certificates — Upload certs directly in the editor UI
• Reconnect handling — keepSessionAlive + session recovery + connection fallback
• All-in-one client — Read, write, subscribe, browse, method, history in one node
• ExtensionObject support — Read/write structured types with automatic serialization
• Discovery — getendpoints, registernodes, translatebrowsepath
• Status propagation — Shared endpoint broadcasts connection state to all nodes

Installation

cd ~/.node-red
npm install node-red-contrib-opcua-suite

Quick Start

1. Read a variable

[inject] → [OPC UA Client] → [debug]

Set msg.topic to a NodeId (e.g. ns=2;s=Temperature) in the inject node. Set the client's default operation to Read. Done.

2. Batch read multiple variables

[inject] → [Item: Temp] → [Item: Pressure] → [OPC UA Client] → [debug]

Each OPC UA Item node adds its variables to msg.items. The client reads them all in one OPC UA service call. No function node needed.

3. Write a value

[inject] → [OPC UA Client] → [debug]

Set msg.payload to the value (e.g. 25.5) and msg.topic to the NodeId in the inject node. Set the client's default operation to Write. DataType is auto-detected from the JS type.

4. Subscribe to live changes

[inject] → [OPC UA Client] → [debug]

Set msg.topic to the NodeId and the client's default operation to Subscribe. Click inject once — every value change on the server produces a new message.

Import ready-to-use flows from Menu → Import → Examples → node-red-contrib-opcua-suite.

Nodes

opcua-endpoint (Config Node)

Shared connection configuration. All nodes referencing the same endpoint share one TCP connection.

[Client: Read] ──┐
[Client: Write] ──┤
[Client: Sub]   ──┤── Endpoint (1 shared connection) ──► OPC UA Server
[Browser]       ──┤
[Method]        ──┤
[Event]         ──┘

| Field | Description | |---|---| | Endpoint URL | opc.tcp://localhost:4840 | | Security Mode | None, Sign, SignAndEncrypt | | Security Policy | None, Basic128Rsa15, Basic256, Basic256Sha256, Aes128/Aes256 | | Username / Password | Optional credentials | | Certificates | Drag & drop upload for client cert, private key, CA cert, X509 user token |

Authentication priority: X509 User Token > Username/Password > Anonymous.

opcua-client (All-in-One)

Single node for all OPC UA operations. Set via msg.operation or the default operation in the node config.

| Operation | msg.topic / msg.nodeId | msg.payload | Description | |---|---|---|---| | read | NodeId | — | Read a single variable | | readmultiple | — | — | Read all items in msg.items | | write | NodeId | Value to write | Write a single variable | | writemultiple | — | — | Write all items in msg.items | | subscribe | NodeId | — | Subscribe to value changes | | unsubscribe | NodeId | — | Stop subscription | | browse | NodeId (default: RootFolder) | — | Browse address space | | method | — | Input arguments | Call a method (needs msg.objectNodeId + msg.methodNodeId) | | history | NodeId | — | Read historical values (needs msg.startTime + msg.endTime) | | getendpoints | — | — | Discover server endpoints | | readattribute | NodeId | — | Read BrowseName, DisplayName, etc. | | registernodes | — | — | Register nodes for fast access | | translatebrowsepath | — | Browse path | Translate browse path to NodeId |

When msg.items is present, the client automatically switches to batch mode — even if the operation is set to read or write.

opcua-item (Item Collector)

Defines OPC UA items (variables) for batch operations. Each item needs a NodeId and optionally a Name and DataType.

Chain pattern — multiple Item nodes in series, each adds to msg.items:

[inject] → [Item: Temp] → [Item: Pressure] → [Item: Speed] → [Client]

List pattern — all items in a single node:

[inject] → [Item: Temp, Pressure, Speed] → [Client]

In Collector Mode (default), items are appended to msg.items for batch operations. In Legacy Mode (collector off), only the first item is set on msg.topic / msg.datatype for single operations.

opcua-browser

Browses the OPC UA address space. Send a NodeId via msg.topic to browse from that node, or leave empty to start from RootFolder.

| Input | Description | |---|---| | msg.topic / msg.nodeId | Starting NodeId (default: RootFolder) | | msg.recursive | Set to true for recursive browsing |

Output: msg.payload contains an array of references with browseName, nodeId, nodeClass, and typeDefinition.

opcua-browse-client

Interactive address space browser with an editor tree view. Select variables visually in the editor, then read or subscribe to them at runtime. No NodeIds to type — just click.

Modes:

• Read — trigger via inject to read all selected items
• Subscribe — automatically subscribes on deploy, emits a message per value change

opcua-method

Calls an OPC UA method. Configure the Object NodeId and Method NodeId in the node or pass them via msg.objectNodeId / msg.methodNodeId.

Input arguments via msg.payload as an array:

[{"dataType": "Double", "value": 3.14}, {"dataType": "String", "value": "hello"}]

Or simple values (datatype auto-detected): [3.14, "hello", true]

Output: msg.payload = array of return values, msg.statusCode = method status.

opcua-event

Subscribes to OPC UA events and alarms.

| Config | Description | |---|---| | Source NodeId | Node to monitor (default: i=2253 — Server node) | | Event Type | e.g. BaseEventType, AlarmConditionType |

Send msg.action = "subscribe" to start, msg.action = "unsubscribe" to stop. Each event produces a message with eventType, severity, message, time, and sourceName.

opcua-server

Embedded OPC UA server. Starts automatically on deploy. Build the address space at runtime via msg.command:

| Command | Required fields | Description | |---|---|---| | addFolder | msg.folderName | Create a folder in the address space | | addVariable | msg.variableName, msg.datatype | Add a variable (optional: msg.initialValue) | | addObject | msg.objectName | Add an object node | | addMethod | msg.methodName | Add a callable method | | setValue | msg.nodeId, msg.payload | Update a variable's value | | setWritable | msg.nodeId | Make a variable writable by clients | | deleteNode | msg.nodeId | Remove a node | | raiseEvent | msg.sourceNodeId, msg.message | Raise an event | | getServerInfo | — | Get session count, endpoint URL, server state |

Reference

NodeId Formats

| Format | Example | |---|---| | String | ns=2;s=MyVariable | | Numeric | ns=2;i=1234 | | GUID | ns=2;g=550e8400-e29b-... | | Short | i=84, s=MyVar (ns=0) | | Well-known | RootFolder, ObjectsFolder, TypesFolder, Server |

DataType Auto-Detection

| JS Type | OPC UA DataType | |---|---| | boolean | Boolean | | integer number | Int32 | | float number | Double | | string | String | | Date | DateTime |

Explicit override: msg.datatype = "UInt16" or in item config.

ExtensionObjects (Structured Types)

Reading: ExtensionObjects are automatically serialized to plain JSON in msg.payload. The msg.dataType will be "ExtensionObject" with a _typeName field.

Writing: Set msg.datatype = "ExtensionObject" and msg.dataTypeNodeId to the DataType definition NodeId:

{
    "topic": "ns=2;s=MyStructVar",
    "datatype": "ExtensionObject",
    "dataTypeNodeId": "ns=2;i=3003",
    "payload": { "temperature": 25.5, "unit": "Celsius" }
}

Examples

Import ready-to-use flows in the Node-RED editor: Menu → Import → Examples → node-red-contrib-opcua-suite.

Available examples:

1. Read Single Variable — inject → client → debug
2. Batch Read with Item Collector — inject → item → item → client → debug
3. Write a Value — inject → client → debug
4. Subscribe to Changes — inject → client → debug
5. Browse Address Space — inject → browser → debug
6. Event Subscription — inject → event → debug
7. Call a Method — inject → method → debug
8. Server with Variables — inject → server → debug

All examples work without function nodes.

Docker

docker compose up -d          # Start Node-RED + OPC UA test server
# Node-RED: http://localhost:1881
# Test server: opc.tcp://localhost:4841

docker compose build --no-cache && docker compose up -d --force-recreate  # Rebuild

Testing

npm test                  # 120 unit tests
node test/live-integration.js  # 36 live integration tests (requires Docker)

License

MIT

Author

blanpa