Skip to main content

AI reference for the OPC UA nodes for Node-RED

This page is a reference for AI agents that build Node-RED flows with the Sterfive OPC UA nodes. The same text is available as plain Markdown at https://opcua-for-node-red.doc.sterfive.com/llms-full.txt.

Identity: the packages @opcua/for-node-red and @flowfuse-certified-nodes/opcua​

Package names: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Sterfive publishes @opcua/for-node-red. @flowfuse-certified-nodes/opcua is the FlowFuse certified distribution of the same nodes. Both packages use node-opcua. Both packages declare the same 15 node types.

This reference covers these two packages. It has no data about a different package.

Requirements: Node.js 20.20 or later, and Node-RED 4 or later.

To install @opcua/for-node-red in the Node-RED editor:

  1. Open the menu and select Manage palette.
  2. Open the Install tab.
  3. Search for @opcua/for-node-red.
  4. Click Install.

To install @opcua/for-node-red with npm, run these commands. Then restart Node-RED.

cd ~/.node-red
npm install @opcua/for-node-red

To find the installed version, run this command in the same folder:

npm ls @opcua/for-node-red

The two packages have these differences:

  • @opcua/for-node-red is on npmjs.org. FlowFuse gets @flowfuse-certified-nodes/opcua from a Sterfive registry.
  • @opcua/for-node-red has the command opcua-for-node-red. @flowfuse-certified-nodes/opcua does not have this command.

The command opcua-for-node-red shows and manages the licence. For example, npx opcua-for-node-red info shows the licence type and its status.

The available nodes change with the edition. For example, the Free edition does not have the node types OpcUa-Client2-Write and OpcUa-Client2-Call. Refer to https://opcua-for-node-red.doc.sterfive.com/docs/editions/compare.

Node types of @opcua/for-node-red and @flowfuse-certified-nodes/opcua​

The table gives all the node types. Write the type exactly as the table shows it. A flow can also use core Node-RED nodes, such as inject, debug and function.

Node typePalette nameFunction
OpcUa-Endpoint2opcua endpointConfiguration node. Holds the connection to one OPC UA server.
OpcUa-Client2-ReadreadReads the value of one or more variables.
OpcUa-Client2-WritewriteWrites the value of one or more variables.
OpcUa-Client2-CallcallCalls a method.
OpcUa-Client2-BrowsebrowseGets the references of a node.
OpcUa-Client2-ExploreexploreGets the structure of a node and of its children.
OpcUa-Client2-Monitormonitor variableSends a message when a value changes.
OpcUa-Client2-MonitorEventmonitor eventsSends a message for each OPC UA event.
OpcUa-Client2-HistoryReadread-historyReads the historical data of a variable.
OpcUa-Client2-FileOperationfile-operationReads and writes an OPC UA file object.
OpcUa-Client2-ExtensionObjectextension objectBuilds a structured value.
OpcUa-Endpoint-Controlendpoint controlChanges the connection of a running flow.
OpcUa-Endpoint-Eventsendpoint eventsSends a message for each change of the connection.
OpcUa-AI-Providernone (configuration node)Configuration node. Holds the AI model settings. Preview.
OpcUa-Agent✨agent (πŸ§ͺ)Answers a question about the plant. Preview.

These four node types need version 3.43.0 or later: OpcUa-Endpoint-Control, OpcUa-Endpoint-Events, OpcUa-AI-Provider and OpcUa-Agent.

Names not to use in a flow with @opcua/for-node-red​

Agents often write these names from memory. These names are not node types of @opcua/for-node-red or @flowfuse-certified-nodes/opcua. A flow with one of these names does not load correctly.

Name not to useCorrect node
OpcUa-ClientThe node type for the operation: OpcUa-Client2-Read, OpcUa-Client2-Write, OpcUa-Client2-Call or OpcUa-Client2-Monitor.
OpcUa-ItemNo node. Put the address in the node settings or in the message.
OpcUa-EndpointOpcUa-Endpoint2.
One "OPC UA Client" node that has an action setting, such as READ, WRITE or CALLOne node for each operation.

The node types of node-red-contrib-opcua are not in this reference. These message properties are also not correct:

  • msg.inputArguments: use msg.payload with one property for each input argument.
  • msg.datatype: the name of the write property is msg.dataType, and this property is optional.

If a reader gives a flow that has one of these names, replace the name with the correct node. Then check the message form in the section for that node.

Endpoint: OpcUa-Endpoint2 node, its settings and its credentials​

Node type: OpcUa-Endpoint2. Palette name: opcua endpoint. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The OpcUa-Endpoint2 node holds the connection to one OPC UA server. All the other OPC UA nodes refer to the OpcUa-Endpoint2 node with the endpoint property. Nodes that use the same OpcUa-Endpoint2 node share one session.

Settings:

  • endpoint: the server address, for example opc.tcp://machine:4840/UA/SampleServer.
  • securityMode: None, Sign or SignAndEncrypt. The default is None.
  • securityPolicy: for example None or Basic256Sha256.
  • userIdentityType: Anonymous, UserName or Certificate. The default is Anonymous.
  • autoConnect: the default is true.
  • subscriptions: the list that the OpcUa-Client2-Monitor node selects from.
  • namespaceAliases: a list of objects with namespaceUri and alias.

An agent does not know the id of the reader's OpcUa-Endpoint2 node. Write a placeholder id, and tell the reader to select the endpoint.

A flow does not hold a password. Set userIdentityType to UserName in the flow. After the import, the reader writes the user name and the password in the dialog of the OpcUa-Endpoint2 node. Node-RED keeps them in its credentials file.

Frequent errors:

  • connection to endpoint ... could not be established. With Sign or SignAndEncrypt, the server must trust the client certificate.
  • Licence cap reached for ... tier=NOT-ONBOARDED. The node reads nothing. Complete the onboarding of the licence. In Docker and Kubernetes, a floating licence is necessary.

Addresses: why an aliased browse path is better than a NodeId​

Applies to all OpcUa-Client2 node types in @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The default rule: use an aliased browse path as the address of an OPC UA node. Do not tell the reader to replace a browse path with a NodeId.

PropertyAliased browse pathNodeId
A person can read it.YesNot for a numeric identifier
The namespace index changes.It stays correct.ns= fails. nsu= stays correct.
The numeric identifier changes when the model is generated again.It stays correct, if the BrowseName stays.It fails.
A different server of the same model.It stays correct.It fails, if the identifiers are different.
An instance that a type defines.The path comes from the model.The identifier comes from the server.

A NodeId is correct in these cases:

  • A standard node with a fixed identifier, for example the Server object i=2253.
  • A method of a standard type, because the method is on the type.
  • Examples of these methods: Acknowledge ns=0;i=9111, AddComment ns=0;i=9029, FileType Read ns=0;i=11585, FileType Close ns=0;i=11583.
  • A custom ReferenceType or DataType, in the nsu= form: nsu=http://acme.com/UA/;i=1000.
  • A node with no stable path.

In all other cases, give the NodeId only as a detail, in the nsu= form. An example of an aliased browse path:

/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:WaterTankLevel

Addresses: all the address styles of the OpcUa-Client2 nodes​

Applies to all OpcUa-Client2 node types in @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

StyleExampleStableUse
Aliased browse path/di:DeviceSet/own:CoffeeMachineA.cke:ParametersYesThe default.
Browse path with a namespace index/2:DeviceSet/1:CoffeeMachineAIf the index staysA server with no alias table.
NodeId with a namespace indexns=1;s=Temperature, ns=2;i=1001. The types are i, s, g and b.If the index and the identifier stayA detail only.
NodeId in namespace 0i=2253YesA standard node.
NodeId with a namespace URInsu=urn:sterfive:boiler;s=TemperatureYes, if the identifier staysAn exception.
NodeId with an aliasna=di;i=5001Yes, if the identifier staysAn exception.
Browse path and NodeId together[/Server.ServerStatus.CurrentTime](ns=0;i=2258)As the pathThe node uses only the path.
Decorated output formns=0;i=35(Organizes)As the NodeIdreferenceTypeId of OpcUa-Client2-Browse, and the address of OpcUa-Client2-Read.
Object with an index range{ "nodeId": "/Server.NamespaceArray", "indexRange": "0:1" }As its addressIn an array for OpcUa-Client2-Monitor.
Name of a standard nodeServerYesThe object of OpcUa-Client2-MonitorEvent.

Rules for a browse path:

  • A browse path starts at the Objects folder. The path /Objects/Server does not resolve.
  • / follows forward hierarchical references, and this includes aggregate references.
  • . follows only forward aggregate references.
  • A name with no prefix is in namespace 0, for example /Server.ServerStatus.State.
  • A space needs no escape: /own:Box/HA Configuration.
  • Write & before a special character. These characters are / . < > : # ! &. An example is /own:a&.b.

/ and . can give a different result. /di:DeviceSet/own:CoffeeMachineA resolves, because DeviceSet organizes the machine. /di:DeviceSet.own:CoffeeMachineA gives BadNodeIdUnknown, because Organizes is not an aggregate reference.

CAUTION: A path that does not resolve gives no node error on OpcUa-Client2-Read. The output has statusCode BadNodeIdUnknown and nodeId ns=0;i=0.

The prefix of the NodeId field in the editor has two stops. The first stop selects the source. The second stop selects only the notation, ns= or /a:.

Addresses: how the namespace aliases of OpcUa-Endpoint2 work​

Node type: OpcUa-Endpoint2. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

An alias is a setting of one OpcUa-Endpoint2 node, in namespaceAliases. Two endpoints do not share their aliases. Each entry has namespaceUri and alias.

[{ "namespaceUri": "http://sterfive.com/UA/CoffeeMachine/", "alias": "coffee" }, { "namespaceUri": "~urn:opcuademo.*", "alias": "own" }]

The node reads the namespace array of the server one time for each connection. On each address, the node finds the URI in that array and gets the current index.

A namespaceUri that starts with ~ is a regular expression. The node does not add anchors, so write ^ and $ if necessary. If a pattern agrees with two namespaces, the node uses the namespace with the lowest index. Write a pattern that agrees with one namespace.

Errors:

  • An alias that is not in the list, in a path: Cannot find alias for /nope:DeviceSet alias =nope.
  • An alias that is not in the list, in a NodeId: Cannot find alias for na=nope;i=1.
  • A URI that is not on the server: Cannot find alias for /gone:X alias =gone in, then the namespace array.

These errors are node errors, so a catch node receives them.

A path can show a prefix such as ns1. The Extract button of the Namespace Aliases tab gives this prefix to a URI that is not in its table of known URIs. To add an alias, write a short name in place of ns1 in the Namespace Aliases tab. Use the same name in the addresses.

Addresses: how to go from a NodeId to a browse path​

Applies to OpcUa-Client2-Explore, OpcUa-Client2-Browse and OpcUa-Client2-Read. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

A person in the editor: use the browse button of the NodeId field, or use the verify button. After the verify, the title of the field shows nsu nodeId: and aliased browsePath:.

A subtree in a flow: use OpcUa-Client2-Explore with outputType set to AliasedBrowsePath. The output gives the paths of the children, as a nested object that OpcUa-Client2-Monitor and OpcUa-Client2-Read take.

To prove a path in a flow, use OpcUa-Client2-Read. Then test statusCode. The node uses the OPC UA service TranslateBrowsePathsToNodeIds for this direction.

An agent with no server access: ask the reader for the NodeSet or for an OpcUa-Client2-Explore output. Do not make a path from memory.

One NodeId in a flow: OPC UA has no service for this direction. Use OpcUa-Client2-Browse with browseDirection set to Inverse and referenceTypeId set to HierarchicalReferences. Set nodeIdSource to msg and nodeId to nodeId. Send the output to this function. Connect output 1 of the function to the same OpcUa-Client2-Browse node.

const up = msg.payload[0];
if (up.nodeId === "ns=0;i=85") {
msg.payload = "/" + msg.parts.join("/");
return [null, msg];
}
msg.parts.unshift(up.browseName);
msg.nodeId = up.nodeId;
return [msg, null];

Before the first message, set msg.parts to a list with the BrowseName of the node, for example ["17:WaterTankLevel"]. The result is a path with namespace indexes, and only / separators. Change each index to its alias.

Addresses: the NodeId source, step by step​

Applies to all OpcUa-Client2 node types with an address. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

A node with an address has two settings: nodeId and nodeIdSource. nodeIdSource tells the node where to find the address. The meaning of nodeId changes with nodeIdSource.

nodeIdSourceEditor labelContent of nodeIdExample of nodeId
nodethis nodeThe address/Server.ServerStatus.State
templatethis node, templatedA template of the address/di:DeviceSet/own:{{msg.machine}}
msgthe messageA message path, with no msg. prefixpayload or nodeId

To select the source, answer these questions in this sequence:

  1. Is the address always the same? Use node.
  2. Does only one part of the address change, for example the machine name? Use template.
  3. Does an earlier node make the address, or a structure of addresses? Use msg.

With msg, the node reads only the message path in nodeId. It does not read msg.topic or a different property. An empty value at that path gives the node error NodeId: msg.<path> is not set on the incoming message.

Write the path as the editor keeps it: payload, not msg.payload. The node also accepts the prefix msg..

With node, an empty nodeId gives no error. The node then uses a default address, for example ns=0;i=2258 on OpcUa-Client2-Read. Always write the address.

OpcUa-Client2-Call has two pairs: objectId with objectIdSource, and methodId with methodIdSource. The rules are the same.

The prefix of the NodeId field in the editor shows the source. Its first stop selects the source.

Addresses: the msg source for each node type​

Applies to all OpcUa-Client2 node types with an address. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The table gives the usual message path for each node type, with nodeIdSource set to msg.

Node typenodeId settingThe message holds
OpcUa-Client2-ReadpayloadOne address, an array or a structure of addresses in msg.payload.
OpcUa-Client2-MonitorpayloadA structure or an array of addresses in msg.payload.
OpcUa-Client2-BrowsenodeIdOne address in msg.nodeId.
OpcUa-Client2-ExplorenodeIdOne address in msg.nodeId.
OpcUa-Client2-WritenodeIdThe address in msg.nodeId. msg.payload holds the value.
OpcUa-Client2-MonitorEventpayload.nodeIdThe object in msg.payload.nodeId.
OpcUa-Client2-CallobjectId and methodIdThe object and the method in msg.objectId and msg.methodId.

CAUTION: The default path of OpcUa-Client2-Monitor in the editor is payload.nodeId. For a structure in msg.payload, change it to payload.

A function node before the node makes the message. This function sends one address to an OpcUa-Client2-Browse node with nodeId set to nodeId:

return { nodeId: "/ex:BuildingA/ex:MainIncomer_Q1", ctx: { device: "MainIncomer_Q1" } };

OpcUa-Client2-Browse keeps the other properties of the message. Put your own data in a property such as msg.ctx. The next function node then finds the data again.

Make a new message in the function, as in the example. An old msg.topic or msg.referenceTypeId can otherwise go to the next node.

Addresses: precedence of the source property, the message and the settings​

Applies to all OpcUa-Client2 node types with an address. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule 1: the source property decides. The source property is nodeIdSource, or objectIdSource and methodIdSource on OpcUa-Client2-Call.

Source valueEditor labelWhich address the node uses
nodethis nodeThe value in the settings. The node ignores the message.
templatethis node, templatedThe mustache template in the settings, filled from the message. Example: /Server.ServerStatus.{{msg.leaf}}.
msgthe messageThe value at the message path in the settings, and no other property. An empty value gives the error NodeId: msg.<path> is not set on the incoming message.
no valuenot setThe older behaviour of rule 2. The editor offers it only while the node still has it.

Rule 2: the order with no source property. The first defined value wins over the setting. The node reports this one time, as a warning, and its status turns yellow.

Node typeOrder
OpcUa-Client2-Readmsg.nodeId, msg.topic, msg.payload, setting
OpcUa-Client2-Writemsg.nodeId, msg.topic, setting
OpcUa-Client2-Browsemsg.payload.nodeId, msg.nodeId, msg.topic, setting
OpcUa-Client2-Exploremsg.nodeId, setting
OpcUa-Client2-Monitormsg.payload.nodeId, msg.payload, setting
OpcUa-Client2-MonitorEventmsg.payload.nodeId, setting
OpcUa-Client2-HistoryReadmsg.nodeId, msg.topic, msg.payload, setting
OpcUa-Client2-FileOperationmsg.nodeId, setting
OpcUa-Client2-Callmsg.objectId and msg.methodId, settings

Rule 3: the instruction for agents. An agent must write a source property in each new flow. An agent must not rely on rule 2.

Addresses: the other message properties and the traps​

Applies to the OpcUa-Client2 node types. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua. The source property does not control these properties.

PropertyNodeOrder or status
referenceTypeId, includeSubtypes, browseDirection, nodeClassMask, resultMaskOpcUa-Client2-Browsemsg.payload.<name>, msg.<name>, setting
outputTypeOpcUa-Client2-Read, OpcUa-Client2-Explore, OpcUa-Client2-Monitormsg.outputType, setting
samplingInterval, deadband and other settingsOpcUa-Client2-MonitorThe node does not read them from the message. Use the settings.
subscriptionOpcUa-Client2-Monitor, OpcUa-Client2-MonitorEventmsg.subscription can select a different subscription.
dataTypeOpcUa-Client2-ExtensionObjectmsg.dataType, setting
dataTypeOpcUa-Client2-Writemsg.dataType is optional.
excludeEmpty, followOrganizesOpcUa-Client2-Exploremsg.<name>, setting

CAUTION: A stock inject node puts a timestamp in msg.payload. With no source property, OpcUa-Client2-Read gives the error msg.payload is "...", which is not a NodeId or browse path. Use nodeIdSource set to node.

CAUTION: With no source property, a msg.topic from an earlier node replaces the configured address.

CAUTION: OpcUa-Client2-Read gives msg.nodeId on its output. With no source property, this value replaces the configured address of the next OpcUa-Client2-Read node.

CAUTION: In OpcUa-Client2-Write with nodeIdSource set to node, msg.payload gives only the value.

Build a good flow: select the node for the task​

Applies to the node types of @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

TaskNodeReason
A value that changesOpcUa-Client2-MonitorDo not use an inject with a repeat and a read. The server sends only the changes.
A value that does not changeOpcUa-Client2-ReadOne read is sufficient.
A command, if the model has a methodOpcUa-Client2-CallA method has arguments, a permission, a result code and an audit event.
A setting that the model makes writableOpcUa-Client2-WriteThe model gives this variable for this purpose.
Events and alarm transitionsOpcUa-Client2-MonitorEventA value does not show each transition.
A list that changesOpcUa-Client2-Browse, then OpcUa-Client2-ReadThe address list comes from the server.

Example: a tank level on a dashboard uses OpcUa-Client2-Monitor. The serial number of the same machine uses OpcUa-Client2-Read.

Build a good flow: the sequence of the work​

Applies to the node types of @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Do these steps in this sequence:

  1. Read the model.
  2. Write each item as a path.
  3. Write the user of each operation.
  4. Prove each address.
  5. Write the flow.
  6. Do the agent checklist.

The reason for the proof: OpcUa-Client2-Monitor retries an unknown node. A wrong address then gives only a value that does not come, with no node error.

To prove an address, use OpcUa-Client2-Read with nodeIdSource set to msg and nodeId set to nodeId. Send the address in msg.nodeId. A status that starts with Good proves the address. Keep the result of the proof, and tell the reader about each address that fails.

msg.proved = String(msg.statusCode).startsWith("Good");
return msg;

Build a good flow: one structure on one OpcUa-Client2-Monitor node​

Node type: OpcUa-Client2-Monitor. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule: put the values of one item in one structure on one OpcUa-Client2-Monitor node.

Reason: the next node gets one coherent object on each change. A test with 41 values on a local server changed all the leaves in each message.

Rule: copy the object before you change it. The node sends the same object each time, so a change stays in the next message.

Rule: do not record the first message as a transition. The first message gives the current state.

const now = RED.util.cloneMessage(msg.payload);
const before = flow.get("machine");
flow.set("machine", now);
msg.payload = { now, first: before === undefined };
return msg;

The output for a structure has no msg.statusCode. The complete flow at the end of this page shows the full design.

Build a good flow: NodeVersion for a list that changes​

Node types: OpcUa-Client2-Monitor, OpcUa-Client2-Browse and OpcUa-Client2-Read. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule: if a folder declares NodeVersion, monitor <folder>.NodeVersion. On the first message and on each change, use OpcUa-Client2-Browse on the folder. Then use OpcUa-Client2-Read to read the items of the list.

Reason: the server changes this value when the list changes. A timer that browses is not necessary. The server must declare NodeVersion on the folder.

NodeVersion is in namespace 0, so it has no prefix. The value on the demonstration server is a string.

{ "type": "OpcUa-Client2-Monitor", "endpoint": "ENDPOINT_ID", "subscription": "s0", "startImmediately": true, "nodeId": "/own:FolderDemo.NodeVersion", "nodeIdSource": "node" }

If the server does not declare NodeVersion, the OpcUa-Client2-Monitor node waits for an unknown node. Read the path one time to prove it.

Build a good flow: one OpcUa-Endpoint2 node for each user​

Node type: OpcUa-Endpoint2. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule: use one OpcUa-Endpoint2 node for each user of the server.

Reason: the server then does the access control and the audit trail. The server identifies the user from the session, and the flow does not need its own access rules.

Rule: do not use one OpcUa-Endpoint2 node for each OPC UA node. Nodes on one OpcUa-Endpoint2 node share a session, and this decreases the load on the server.

Example: a flow has an operator and a maintenance user. The flow has two OpcUa-Endpoint2 nodes with userIdentityType set to UserName. Each OpcUa-Client2-Call node refers to the endpoint of the user that can do the operation. The reader writes the two passwords in the dialogs.

Build a good flow: show each refused operation​

Node types: catch, OpcUa-Client2-Call and OpcUa-Client2-Write. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule: add a catch node for each OpcUa-Client2-Call node and each OpcUa-Client2-Write node. Send the caught message and the good message to one function.

Reason: the reader then sees each refused operation. A disabled button on a dashboard is not access control. The server must refuse the operation, and the flow must show the refusal to the reader.

if (msg.error) {
msg.payload = { ok: false, status: String(msg.statusCode || msg.error.message) };
return msg;
}
msg.payload = { ok: String(msg.statusCode).startsWith("Good"), status: msg.statusCode, output: msg.payload };
return msg;

CAUTION: Good means that the server ran the method. It does not always mean that the method did the work. On the demonstration server, MakeCoffee can give Good with Success set to false in msg.payload. Examine the output arguments.

Build a good flow: alarms with OpcUa-Client2-Monitor and OpcUa-Client2-Call​

Node types: OpcUa-Client2-Monitor and OpcUa-Client2-Call. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule: monitor the condition variables in one structure. Write each variable as a child of the condition, for example /di:DeviceSet/own:CoffeeMachineA/cke:ErrorConditions/coffee:WaterTankLevelAlarm.EventId.

LeafExample output
.EventIdA base64 string
.Message{ text: "Back to normal" }
.SeverityA number
.TimeA date
.ActiveState{ text: "Inactive" }
.ActiveState.IdA Boolean
.AckedState.IdA Boolean

Rule: keep the EventId in the flow context, not in a browser.

Rule: to acknowledge, call ns=0;i=9111 on the condition, with EventId and Comment. A base64 string and a Buffer both give Good for EventId.

{ "type": "OpcUa-Client2-Call", "endpoint": "ENDPOINT_ID", "objectId": "/di:DeviceSet/own:CoffeeMachineA/cke:ErrorConditions/coffee:WaterTankLevelAlarm", "objectIdSource": "node", "methodId": "ns=0;i=9111", "methodIdSource": "node" }

Rule: a condition that is not active and not acknowledged still needs an action.

Build a good flow: audit events with OpcUa-Client2-MonitorEvent​

Node type: OpcUa-Client2-MonitorEvent. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule: write the type in the whereClause setting by its name, in the form OfType(AuditEventType).

These forms give an error when the node subscribes:

  • ofType(AlarmConditionType) and ofType("AlarmConditionType"): Cannot read properties of undefined (reading 'text').
  • OfType("AlarmConditionType") and OfType(i=2127): Invalid variant arrayType: Scalar dataType: NodeId value:null.

CAUTION: The node selects fields from the fields of AlarmConditionType. A field of a different type, such as Status of an audit event, is an unknown field. The node removes it and gives the warning select clause: unknown field(s) ignored: Status.

The server decides which session gets audit events. The session of an anonymous user can get no audit events. Do not record an empty result as "no operation".

{ "type": "OpcUa-Client2-MonitorEvent", "endpoint": "ENDPOINT_ID", "subscription": "s0", "nodeId": "Server", "nodeIdSource": "node", "whereClause": "OfType(AuditEventType)", "selectClauses": "EventId;EventType;SourceName", "queueSize": 1000, "discardOldest": true }

Build a good flow: read a file with OpcUa-Client2-Call​

Node types: OpcUa-Client2-Call and OpcUa-Client2-FileOperation. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

OpcUa-Client2-FileOperation opens the file and closes the file. It has no input for a file handle. A method that gives an open file and its handle needs OpcUa-Client2-Call nodes.

Use one OpcUa-Client2-Call node for each step:

  1. Call the method that gives the handle, for example Open ns=0;i=11580 with { "Mode": 1 }.
  2. Keep msg.payload.FileHandle in the message.
  3. Call Read ns=0;i=11585 with { "FileHandle": 42, "Length": 4096 }.
  4. Do step 3 again until a block is shorter than Length.
  5. Call Close ns=0;i=11583 with { "FileHandle": 42 }.

The Data output of Read is a base64 string.

Rule: if Read fails, close the file before you report the error.

msg.handle = msg.payload.FileHandle;
msg.payload = { FileHandle: msg.handle, Length: 4096 };
return msg;

Build a good flow: value forms of OpcUa-Client2-Write and OpcUa-Client2-Read​

Node types: OpcUa-Client2-Write, OpcUa-Client2-Read and OpcUa-Client2-ExtensionObject. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Data typeWrite form that worksRead output
LocalizedTextA string or { Text: "..." }. The form { text: "..." } writes an empty value.{ text: "..." }
ByteStringA base64 string or { type: "Buffer", data: [1, 2] }A base64 string
UInt64A number or [high, low]A BigInt or a pair of BigInts
EnumerationNot testedA number
ExtensionObject{ UaTypeId, UaBody }{ UaTypeId, UaBody }

The field names of OpcUa-Client2-ExtensionObject have a different case on input and on output. The input { "productName": "x" } gives the output field ProductName. The input { "ProductName": "x" } gives an empty field, with no error.

CAUTION: A write form that the server accepts can still store a different value. After a write, read the value one time and compare it.

Do not use a form that is not in this table without a test. Tell the reader which forms you did not test.

Build a good flow: subflows with the endpoint as a property​

Node types: subflow and OpcUa-Endpoint2. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule: make the endpoint a subflow property of type config node. Set the endpoint of each inner node to ${ENDPOINT}.

Reason: one subflow can then serve different servers, and each instance selects its endpoint. With a string property, the editor shows an empty red field.

The subflow has this property in env:

{ "name": "ENDPOINT", "type": "OpcUa-Endpoint2", "value": "", "ui": { "type": "conf-types" } }

Each instance has this entry in env:

{ "name": "ENDPOINT", "type": "OpcUa-Endpoint2", "value": "ENDPOINT_ID" }

An inner node has this form:

{ "type": "OpcUa-Client2-Read", "endpoint": "${ENDPOINT}", "attributeId": "Value", "nodeId": "/Server.ServerStatus.State", "nodeIdSource": "node", "outputType": "Value" }

The flow must contain the OpcUa-Endpoint2 node that the instance refers to. A test on the demonstration server gave a good read from the inner node with these forms.

Build a good flow: security of the connection​

Node type: OpcUa-Endpoint2. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

WARNING: All the complete flows on this page use None and Anonymous. These settings are for a demonstration only. Do not use them on a real plant. Do not make the Node-RED editor available on a public network.

Rules for a real plant:

  • Set securityMode to SignAndEncrypt.
  • Select a securityPolicy that the server offers, for example Basic256Sha256.
  • Make the server trust the client certificate. The certificate is in PKI/own/certs/certificate.pem.
  • Make the client trust the server. By default, the client accepts each server certificate. To trust one by hand, move it from PKI/rejected to PKI/trusted/certs.
  • Set credentialSecret in the settings.js file of Node-RED. Node-RED uses this value to encrypt its credentials file.
  • Do not write a key, a password or a certificate in a flow.

A failed trust gives the error connection to endpoint ... could not be established.

Build a good flow: one OpcUa-Client2-Browse node for each question​

Node type: OpcUa-Client2-Browse. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Rule: use one OpcUa-Client2-Browse node for each question. Connect the nodes in a chain, from left to right. Do not send all the questions to one OpcUa-Client2-Browse node in a loop.

The reason: all the nodes on the same OpcUa-Endpoint2 node share one session. One more node does not open one more connection. A chain is easier to read, because each node shows its question.

Set referenceTypeId and browseDirection on each node, and give the node a name that is the question. For example, this chain finds the classes of a value and the standard of each class:

NodereferenceTypeIdbrowseDirectionGives
classes claimednsu=http://opcfoundation.org/UA/ECM/;i=1000ForwardThe classes of the value
function: keep the claimsOne message for each class
standard of the classHasComponentInverseThe parent of the class

Set nodeIdSource to msg and nodeId to nodeId on each OpcUa-Client2-Browse node. The function node between two nodes makes a new message with msg.nodeId.

Do not send msg.referenceTypeId or msg.browseDirection to these nodes. A value in the message replaces the setting of the node.

A loop is correct only when the number of steps is not known, for example to go from a NodeId up to the Objects folder.

Build a good flow: the layout of a complex flow​

Applies to the flows of @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

A complex flow has more than 10 nodes, or more than one task. Use this layout for a complex flow:

  1. Divide the flow into stages, for example discover, read, monitor and show.
  2. Put each stage in one group node. Give the group a number and a name, for example 2 Β· Accuracy claims.
  3. Give each group a different colour.
  4. Put one comment node at the top left of each group. Its info tells what the stage does, in Markdown.
  5. Put each chain of the stage on one row. The message goes from left to right.
  6. Start a row with a link in node. End it with a link out node to the next stage.
  7. Do not draw a wire from one group to a different group. Use a pair of link nodes.
  8. Put the groups one below the other, in the sequence of the work.

Give each node a name that tells its function, for example keep the claims, not function 1.

Write the info of each OPC UA node. Tell the source of its address and what its output gives.

Put each node on the grid of 20 px. Use columns: the link in nodes on one left edge, the link out nodes on one right edge.

The editor gives a node a width from its name. Keep a gap of 40 px or more between two nodes of a row.

A simple flow, with a maximum of 10 nodes and one task, needs no group.

Applies to the flows of @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

A group node has the ids of its nodes in nodes. Each of these nodes has the id of the group in g. The editor calculates the frame from the nodes.

{ "id": "g1", "type": "group", "z": "t1", "name": "2 Β· Accuracy claims", "nodes": ["c1", "li1", "b1"], "style": { "label": true, "stroke": "#7b4bb7", "fill": "#ebe2f6", "fill-opacity": "0.45" }, "x": 60, "y": 300, "w": 1220, "h": 140 }

A link out node has the id of its link in node in links. The link in node has the id of the link out node in links, and its wires go to the first node of the row.

[
{ "id": "lo1", "type": "link out", "z": "t1", "g": "g0", "name": "β†’ claims", "mode": "link", "links": ["li1"], "x": 1200, "y": 140, "wires": [] },
{ "id": "li1", "type": "link in", "z": "t1", "g": "g1", "name": "claims", "links": ["lo1"], "x": 130, "y": 400, "wires": [["b1"]] }
]

Set mode to link on a link out node. The value return sends the message back to a link call node.

CAUTION: The tool of the OpcUa-Agent node that inserts a flow does not accept the type group, and removes g. With this tool, do not write group nodes. Use the comment nodes and the link nodes. Then tell the reader to select the nodes of each stage and group them in the editor. A flow that the reader imports from JSON keeps its groups.

Golden example: OpcUa-Client2-Explore and OpcUa-Client2-Monitor give a live JSON of a device​

Node types: OpcUa-Client2-Explore and OpcUa-Client2-Monitor. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Use this example first when a reader wants the values of a device or of a part of a device.

Two nodes do all the work:

  1. OpcUa-Client2-Explore with outputType set to AliasedBrowsePath reads the model. It gives a nested JSON object, and each leaf is an aliased browse path.
  2. OpcUa-Client2-Monitor takes this object. It gives the same object, and each leaf is the current value. It sends the object again when a value changes.

The flow needs no list of addresses and no function. The output keeps the shape of the model, so the names in the flow are the names on the server.

The OpcUa-Client2-Monitor node must have startImmediately set to false, nodeIdSource set to msg and nodeId set to payload.

A test on the whole of CoffeeMachineA on the demonstration server gave 241 leaves in one message. The flow below uses only Parameters, which gives 16 leaves.

The first debug node shows the paths. The second debug node shows the live values.

[
{"id":"g1000000000000t0","type":"tab","label":"Live JSON of a device"},
{"id":"g1000000000000i1","type":"inject","z":"g1000000000000t0","name":"Start","props":[{"p":"payload"}],"repeat":"","crontab":"","once":true,"onceDelay":1,"topic":"","payload":"","payloadType":"date","x":140,"y":100,"wires":[["g1000000000000n1"]]},
{"id":"g1000000000000n1","type":"OpcUa-Client2-Explore","z":"g1000000000000t0","inputs":1,"output":4,"name":"Paths of the device","endpoint":"g1000000000000e1","nodeId":"/di:DeviceSet/own:CoffeeMachineA.cke:Parameters","nodeIdSource":"node","outputType":"AliasedBrowsePath","followOrganizes":false,"excludeEmpty":true,"x":330,"y":100,"wires":[["g1000000000000n2","g1000000000000d1"]]},
{"id":"g1000000000000n2","type":"OpcUa-Client2-Monitor","z":"g1000000000000t0","inputs":1,"output":2,"name":"Live values","endpoint":"g1000000000000e1","subscription":"s0","startImmediately":false,"nodeId":"payload","nodeIdSource":"msg","samplingInterval":1000,"discardOldest":true,"queueSize":10,"outputType":"Value","trigger":1,"deadbandType":"","deadbandValue":0,"retryUnknownNodes":true,"retryUnknownInterval":5000,"markBadOnDisconnect":false,"x":560,"y":100,"wires":[["g1000000000000d2"]]},
{"id":"g1000000000000d1","type":"debug","z":"g1000000000000t0","name":"Paths","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":800,"y":180,"wires":[]},
{"id":"g1000000000000d2","type":"debug","z":"g1000000000000t0","name":"Live values","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":800,"y":100,"wires":[]},
{"id":"g1000000000000e1","type":"OpcUa-Endpoint2","name":"Demo server","endpoint":"opc.tcp://opcuademo.sterfive.com:26541","securityMode":"None","securityPolicy":"None","userIdentityType":"Anonymous","autoConnect":true,"pkiName":"","useTransport":false,"maxChunkCount":"1","maxMessageSize":"8192","receiveBufferSize":"8192","sendBufferSize":"8192","subscriptions":[{"id":"s0","name":"Default Subscription","isDefault":true,"parameters":{"publishingEnabled":true,"requestedLifetimeCount":"100","requestedMaxKeepAliveCount":"10","requestedPublishingInterval":"1000","maxNotificationsPerPublish":"0","priority":"100"}}],"namespaceAliases":[{"namespaceUri":"http://opcfoundation.org/UA/","alias":"ua"},{"namespaceUri":"~urn:opcuademo.*","alias":"own"},{"namespaceUri":"http://opcfoundation.org/UA/DI/","alias":"di"},{"namespaceUri":"http://opcfoundation.org/UA/CommercialKitchenEquipment/","alias":"cke"},{"namespaceUri":"http://sterfive.com/UA/CoffeeMachine/","alias":"coffee"}]}
]

Golden example: OpcUa-Client2-Explore to learn the model, then an inject with your tree into OpcUa-Client2-Monitor​

Node types: OpcUa-Client2-Monitor and OpcUa-Client2-Read. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

OpcUa-Client2-Monitor and OpcUa-Client2-Read take a JSON tree of any depth, with an address at each leaf. OpcUa-Client2-Explore makes a tree, but it does not take one.

Use OpcUa-Client2-Explore one time, to see the structure and to get each aliased browse path. Then write the tree that the flow needs.

Select a pattern:

  • Use the live JSON pattern when the flow needs all the items, and when the model is the correct shape.
  • Use this pattern when the flow needs some items, or a different shape, or stable names.

Procedure:

  1. Run OpcUa-Client2-Explore one time with outputType set to AliasedBrowsePath.
  2. Copy the output from the debug node.
  3. Remove the leaves that you do not need.
  4. Change the keys to your names, and add levels if necessary.
  5. Put the result in an inject node with once set to true.
  6. Connect the inject node to OpcUa-Client2-Monitor, and remove OpcUa-Client2-Explore from the flow.

Input:

{ "tank": { "level": "/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:WaterTankLevel" }, "served": "/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:ServedCoffeeCount" }

Output in msg.payload:

{ "tank": { "level": 702.49 }, "served": 3 }

The keys are yours, and the addresses stay in one place. The next nodes read msg.payload.tank.level, and they do not know the model. If the model changes, change only the tree. The complete flow with the design uses this pattern.

Golden example: one snapshot of a device with OpcUa-Client2-Read​

Node types: OpcUa-Client2-Explore and OpcUa-Client2-Read. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

Use this example when a reader wants the values one time, for example for a report. Do not use a timer for a value that a monitor can give.

Method 1: use OpcUa-Client2-Explore with outputType set to Value. One node gives the structure and the values.

{ "type": "OpcUa-Client2-Explore", "endpoint": "ENDPOINT_ID", "nodeId": "/di:DeviceSet/own:CoffeeMachineA.cke:Parameters", "nodeIdSource": "node", "outputType": "Value", "followOrganizes": false, "excludeEmpty": false }

Method 2: send a JSON tree to OpcUa-Client2-Read. Use this method for a tree with your own names, or for an output from OpcUa-Client2-Explore.

{ "type": "OpcUa-Client2-Read", "endpoint": "ENDPOINT_ID", "attributeId": "Value", "nodeId": "payload", "nodeIdSource": "msg", "outputType": "Value" }

The same tree works in OpcUa-Client2-Monitor and in OpcUa-Client2-Read. A reader can start with a snapshot, and then change one node to get live values. The output has the same shape in the two cases.

Golden example: find a wrong address in a JSON tree​

Node types: OpcUa-Client2-Read and OpcUa-Client2-Monitor. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

A wrong leaf does not stop the tree. The other leaves stay correct, and the node gives no error. So test the tree one time before you use it.

Send the tree to OpcUa-Client2-Read, and then find each leaf that is null:

const wrong = [];
(function walk(o, path) {
for (const [key, value] of Object.entries(o)) {
if (value === null) wrong.push(path + key);
else if (Object.prototype.toString.call(value) === "[object Object]") walk(value, path + key + ".");
}
})(msg.payload, "");
msg.payload = { ok: wrong.length === 0, wrong };
return msg;

Output for a tree with one wrong leaf: { ok: false, wrong: ["tank.wrong"] }.

CAUTION: The first message of OpcUa-Client2-Monitor can have null in a good leaf. In a test, the first message had null in all the leaves, because one leaf was wrong. The second message had the good values. Do not use OpcUa-Client2-Monitor for this test.

Tips and tricks for @opcua/for-node-red flows​

Applies to @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

  • Start a flow by itself: use an inject node with once set to true.
  • Write less: set excludeEmpty to true on OpcUa-Client2-Explore. The output has no empty objects.
  • Get a smaller tree: explore one part of a device, such as Parameters.
  • Use one flow for several machines: write /di:DeviceSet/own:{{msg.machine}}.cke:Parameters with nodeIdSource set to template.
  • Get part of an array: send an object with nodeId and indexRange to OpcUa-Client2-Monitor.
  • Prove a browse path: read it one time and test statusCode.
  • Test a status in one way: String(msg.statusCode).startsWith("Good").
  • Copy a structure before you change it: use RED.util.cloneMessage.
  • Examine a method result: Good with Success set to false is a refusal.
  • Set outputType to TimeValue on OpcUa-Client2-HistoryRead. In version 3.42.0 and earlier, the default gives items with no value.
  • Write OfType(AlarmConditionType) with this case and with no quotes.

More data: https://opcua-for-node-red.doc.sterfive.com/docs/monitor/monitoring-subtree.

OpcUa-Client2-Read node: read a variable​

Node type: OpcUa-Client2-Read. Palette name: read. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

An input message starts the read operation.

Settings: endpoint, nodeId, nodeIdSource, attributeId (Value), outputType (Value).

Input with nodeIdSource set to node: any message. The node reads its nodeId setting. With nodeIdSource set to msg, the nodeId setting holds a message path, and that path gives the address.

To read a tree of variables, set nodeIdSource to msg and the nodeId setting to payload. Then send an object in msg.payload. Each leaf is a string with an address. The output has the same structure, and each leaf has the value. msg.outputType can be Value, Variant or DataValue. An array of addresses gives an array in msg.payload, and msg.results has one status for each address.

Output:

  • msg.payload: the value.
  • msg.dataType: the data type, for example Float.
  • msg.statusCode: the status, for example Good (0x00000000). Test it with String(msg.statusCode).startsWith("Good").
  • msg.sourceTimestamp and msg.serverTimestamp: the timestamps.
  • msg.nodeId: the NodeId of the variable.

Minimum example of the settings:

{ "type": "OpcUa-Client2-Read", "endpoint": "ENDPOINT_ID", "attributeId": "Value", "nodeId": "/Server.ServerStatus.State", "nodeIdSource": "node", "outputType": "Value" }

Frequent errors:

  • BadNodeIdUnknown: the address is not correct. Check the browse path and the aliases.
  • BadAttributeIdInvalid: the address is an object, and an object has no value.
  • BadUserAccessDenied: the session does not have permission to read.

OpcUa-Client2-Write node: write a variable​

Node type: OpcUa-Client2-Write. Palette name: write. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

WARNING: A write can change the operation of a real plant. Tell the reader to examine the value and the address before the reader deploys the flow.

Settings: endpoint, nodeId, nodeIdSource, attributeId (Value). The node writes only the attribute Value.

Input:

  • msg.payload: the value.
  • msg.dataType: optional. The data type, for example Float.
  • The address, when nodeIdSource is msg: the message path in the nodeId setting, for example nodeId. Do not use payload, because it holds the value.

To write several values, send an array in msg.payload. Each item has nodeId, value and dataType.

Output for one value: msg.payload, msg.statusCode, msg.dataType, msg.nodeId and msg.attributeId. Output for several values: msg.results is an array with one status for each write.

Minimum example of the input:

msg.payload = 1500;
msg.dataType = "Float";
return msg;

Frequent errors:

  • BadTypeMismatch: the data type is not correct. Set msg.dataType.
  • BadNotWritable: the attribute is read-only.
  • BadUserAccessDenied: the session does not have permission to write.
  • BadNodeIdUnknown: the address is not correct.

Always examine msg.statusCode in the output message, with String(msg.statusCode).startsWith("Good").

OpcUa-Client2-Call node: call a method and its payload form​

Node type: OpcUa-Client2-Call. Palette name: call. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

WARNING: A method call can start an operation on a real plant. Tell the reader to examine the method and the arguments before the reader deploys the flow.

From version 3.43.0, one OpcUa-Client2-Call node can call a different method for each message, from the message or from a template. msg.payload must have the input arguments of the method that the node calls.

CAUTION: In version 3.42.0 and earlier, use one OpcUa-Client2-Call node for each method. The node keeps the signature of its first call. A second method on the same node fails with BadArgumentsMissing or BadTooManyArguments. This also occurs with an address from the message or from a template.

Settings: endpoint, objectId, objectIdSource, methodId, methodIdSource.

Input: msg.payload is an object with one property for each input argument. The property name is the argument name that the server declares. The property value is the value itself.

{ "RecipeName": "Americano" }

Do not use a {dataType, value} wrapper, except for an argument of type BaseDataType. Do not use an array. A method with no input argument also needs a message: send an empty object.

For a structure, put a plain object under the argument name. The explicit forms { UaTypeId, UaBody } and { TypeId, Body } are also available.

For an argument of type BaseDataType, refer to the section about BaseDataType arguments.

Output:

  • msg.payload: an object with the output arguments, by argument name.
  • msg.statusCode: the status, for example Good (0x00000000).

Frequent errors:

  • BadInvalidArgument: an input argument has an incorrect name or type.
  • BadArgumentsMissing and BadTooManyArguments: the arguments do not agree with the signature.
  • BadInvalidState: the object cannot do the method now.
  • BadMethodInvalid: the method is not on that object.
  • BadUserAccessDenied: the session does not have permission.

Use a catch node to receive these errors.

OpcUa-Client2-Call node: arguments of type BaseDataType​

Node type: OpcUa-Client2-Call. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

An argument of type BaseDataType accepts all types. From version 3.43.0, the node gets the type from the value:

  • A boolean gives Boolean.
  • An integer in the Int32 range gives Int32. Another number gives Double.
  • A string gives String.
  • In a function node, a Date gives DateTime and a Buffer gives ByteString.
  • An array gives an array of the type of its first item.

To give the type yourself, use this form. Use it also for a type that is not in this list:

{ "Value": { "dataType": "UInt16", "value": 7 } }

In this example, Value is the argument name. A plain object with no dataType and no value causes an error.

CAUTION: In version 3.42.0 and earlier, an argument of type BaseDataType arrives at the server as a Null value in each form of our tests. Do not use the node for this type of argument on these versions.

CAUTION: We did not test arguments of the types Number, Integer and UInteger. Test them on your server.

OpcUa-Client2-Monitor node: monitor a variable​

Node type: OpcUa-Client2-Monitor. Palette name: monitor variable. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The OpcUa-Client2-Monitor node sends a message when a value changes. It sends one message when the monitored item starts.

Settings for the target: endpoint, subscription, startImmediately, nodeId, nodeIdSource.

Settings for the sampling: samplingInterval (default 1000 ms), queueSize (default 10), discardOldest (default true), trigger, deadbandType, deadbandValue.

Other settings: outputType (Value or DataValue), retryUnknownNodes (default true), markBadOnDisconnect (default false).

The subscription setting holds the id of a subscription of the OpcUa-Endpoint2 node, for example s0.

With startImmediately set to true, the node needs no input message. For an address in a message, set startImmediately to false and nodeIdSource to msg. Set nodeId to the message path, for example payload.

Output for one variable: msg.payload and msg.statusCode. With outputType set to DataValue, msg.payload has Value, StatusCode, SourceTimestamp and ServerTimestamp. The case is as written here.

With markBadOnDisconnect set to true, a lost connection sends each last value again, with the status BadServerNotConnected.

Frequent error: BadNodeIdUnknown. The node retries an unknown node until the node exists. Check the address if this status stays.

OpcUa-Client2-Monitor node: monitor a structure or an array​

Node type: OpcUa-Client2-Monitor. Palette name: monitor variable. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

To monitor several variables, send them in one message. An OpcUa-Client2-Explore node can make this message: refer to the golden example. The settings of the node must be startImmediately set to false, nodeIdSource set to msg and nodeId set to payload. The default message path of the editor is payload.nodeId, so change it to payload.

{ "type": "OpcUa-Client2-Monitor", "endpoint": "ENDPOINT_ID", "subscription": "s0", "startImmediately": false, "nodeId": "payload", "nodeIdSource": "msg", "samplingInterval": 1000, "queueSize": 10, "discardOldest": true }

Input for a structure, in msg.payload:

{ "water": "/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:WaterTankLevel", "deep": { "milk": "/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:MilkTankLevel" } }

Output for a structure, in msg.payload. The output has no msg.statusCode.

{ "water": 810.8, "deep": { "milk": 502 } }

Input for an array: a list of addresses. An item can be an object with nodeId and indexRange.

["/Server.ServerStatus.State", { "nodeId": "/Server.NamespaceArray", "indexRange": "0:1" }]

Output for an array: msg.payload, msg.statusCodes and msg.nodeIds are arrays in the same order. Each item of msg.statusCodes is a short name, for example Good.

OpcUa-Client2-MonitorEvent node: monitor events​

Node type: OpcUa-Client2-MonitorEvent. Palette name: monitor events. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The OpcUa-Client2-MonitorEvent node sends a message for each event from an OPC UA object.

Settings:

  • endpoint and subscription.
  • nodeId and nodeIdSource: the object. Without an address, the node uses the Server object.
  • whereClause (WhereClause): the filter, for example OfType(AlarmConditionType). Leave it empty to get all events.
  • selectClauses (SelectClause): the fields, separated by a semicolon. Leave it empty to get all the fields.
  • queueSize: the default is 10. Use a large queue for a burst of events, for example 1000. In version 3.42.0 and earlier, the editor dialog does not keep this setting, so the node uses 10. On these versions, set queueSize in the flow JSON.
  • discardOldest: the default is true.

Input: when the source is the message, the message path in the nodeId setting gives the object. The editor default is payload.nodeId. msg.subscription can select a different subscription.

Output: msg.payload holds the selected fields of the event.

Minimum example of the settings:

{ "type": "OpcUa-Client2-MonitorEvent", "endpoint": "ENDPOINT_ID", "subscription": "s0", "nodeId": "Server", "nodeIdSource": "node", "whereClause": "OfType(AlarmConditionType)", "selectClauses": "EventId;SourceName;Message;Severity", "queueSize": 1000, "discardOldest": true }

Frequent errors:

  • A field that the node does not know gives a warning. The node removes that field and keeps the other fields.
  • If the node cannot find any field, the node shows an error and does not subscribe.
  • An incorrect whereClause gives a subscription error. Use the form OfType(TypeName).

OpcUa-Client2-Browse node: get the references of a node​

Node type: OpcUa-Client2-Browse. Palette name: browse. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The OpcUa-Client2-Browse node gets the references of one OPC UA node. It handles the continuation points.

Settings: endpoint, nodeId, nodeIdSource, referenceTypeId (ReferenceTypeId, default HasChild), includeSubtypes (IncludeSubType, default false), browseDirection (BrowseDirection, default Forward), nodeClassMask (Node Class Mask), resultMask (Result Mask).

Input, when the source is the message: the message path in the nodeId setting gives the address, for example nodeId. The node does not read msg.topic then.

The other properties can be in msg.payload or in msg, with any source. A value in the message replaces the setting:

  • referenceTypeId: for example Organizes or HasComponent. Leave it empty to follow all reference types.
  • browseDirection: Forward, Inverse or Both.
  • nodeClassMask: for example "Object,Variable" or 3. The value 0 means all node classes.
  • resultMask: for example "BrowseName,NodeClass" or 12. The output always has the NodeId.

Output: msg.payload is an array. Each item has nodeId and, if the result mask selects them, browseName, displayName, nodeClass, referenceTypeId, isForward and typeDefinition.

Minimum example of the settings:

{ "type": "OpcUa-Client2-Browse", "endpoint": "ENDPOINT_ID", "nodeId": "/own:FolderDemo", "nodeIdSource": "node", "referenceTypeId": "HierarchicalReferences", "includeSubtypes": true, "browseDirection": "Forward", "nodeClassMask": "Object,Variable", "resultMask": "BrowseName,NodeClass" }

Frequent error: a reference type that the node cannot find. The node shows an error. Use the browse name of a standard reference type or a NodeId.

OpcUa-Client2-Explore node: get the structure of a node​

Node type: OpcUa-Client2-Explore. Palette name: explore. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The OpcUa-Client2-Explore node gets the structure of a node and of its children. When the node finds a variable, it stores a leaf and does not explore the children of that variable.

Settings: endpoint, nodeId, nodeIdSource, outputType, excludeEmpty (default false), followOrganizes (default false).

Input: when the source is the message, the message path in the nodeId setting gives the address, for example nodeId. msg.outputType, msg.excludeEmpty and msg.followOrganizes are optional.

The values of outputType are Value, DataValue, Variant, StatusCode, NodeId, NSUNodeId, BrowsePath and AliasedBrowsePath.

Output: msg.payload is an object with the structure of the node.

Minimum example of the settings. The paths /Server/ServerStatus and /Server.ServerStatus both resolve here, because / includes aggregate references.

{ "type": "OpcUa-Client2-Explore", "endpoint": "ENDPOINT_ID", "nodeId": "/Server/ServerStatus", "nodeIdSource": "node", "outputType": "AliasedBrowsePath", "followOrganizes": false, "excludeEmpty": false }

To monitor a subtree, connect the output of an OpcUa-Client2-Explore node to an OpcUa-Client2-Monitor node. Set outputType to AliasedBrowsePath on the OpcUa-Client2-Explore node. Refer to the golden example for the settings of the OpcUa-Client2-Monitor node.

Frequent error: an empty result for a folder. Set followOrganizes to true.

OpcUa-Client2-HistoryRead node: read historical data​

Node type: OpcUa-Client2-HistoryRead. Palette name: read-history. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The OpcUa-Client2-HistoryRead node reads the stored values of one variable. The server must support history.

Settings: endpoint, nodeId, nodeIdSource, outputType, historyReadParam. The historyReadParam object has type (raw), startTime, endTime, numValuesPerNode and returnBounds.

Set outputType to TimeValue or DataValue. From version 3.43.0, TimeValue is the default in the editor, and a saved flow with the value Value operates as TimeValue.

CAUTION: In version 3.42.0 and earlier, the value Value gives output items with no value. This value is the default in the editor on these versions.

CAUTION: numValuesPerNode does not limit the output. It is the size of a page, and the node reads all the pages. A test with the value 2 gave 174 items. Limit the time range.

Input: when the source is the message, the message path in the nodeId setting gives the address, for example nodeId.

Output with TimeValue: msg.payload is an array. Each item has value, statusCode and sourceTimestamp. Output with DataValue: each item has Value, StatusCode, SourceTimestamp and ServerTimestamp.

Minimum example of the settings:

{ "type": "OpcUa-Client2-HistoryRead", "endpoint": "ENDPOINT_ID", "nodeId": "/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:WaterTankLevel", "nodeIdSource": "node", "outputType": "TimeValue", "historyReadParam": { "type": "raw", "startTime": "1 hour ago", "endTime": "now", "numValuesPerNode": 100, "returnBounds": false } }

Frequent errors:

  • no results: the time range has no data.
  • BadHistoryOperationUnsupported: the server does not support history.
  • BadNodeIdUnknown: the address is not correct.

OpcUa-Client2-FileOperation node: read and write an OPC UA file​

Node type: OpcUa-Client2-FileOperation. Palette name: file-operation. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The OpcUa-Client2-FileOperation node reads and writes an object of the OPC UA type FileType.

WARNING: The Write and WriteEraseExisting modes replace the content of the file. Tell the reader to examine the address before the reader deploys the flow.

Settings:

  • endpoint, nodeId and nodeIdSource.
  • mode (Mode): Read, ReadSize, Write, WriteEraseExisting or WriteAppend. The default is Read.
  • encoding (Encoding): for example none, utf8 or setbymsg. The default is none.
  • format (Format), for Read only: buffer, utf8 or lines. The default is buffer.

Input:

  • The address, when the source is the message: the message path in the nodeId setting, for example nodeId.
  • msg.payload: for a write mode, the content. It can be a string, a Buffer, an object or an array. The node converts an object or an array to JSON.
  • msg.encoding: the encoding, when encoding is setbymsg.

Output: for Read, msg.payload is a Buffer, a string or an array of strings. For ReadSize, msg.payload is the size in bytes. For a write mode, msg.size is the number of bytes.

Minimum example of the settings:

{ "type": "OpcUa-Client2-FileOperation", "endpoint": "ENDPOINT_ID", "nodeId": "/own:FolderDemo/own:subfolder/own:Hello1_txt", "nodeIdSource": "node", "mode": "Read", "encoding": "utf8", "format": "utf8" }

Frequent errors: nothing to write means that msg.payload is empty. expecting a nodeIdString means that the address has an incorrect format.

OpcUa-Client2-ExtensionObject node: build a structured value​

Node type: OpcUa-Client2-ExtensionObject. Palette name: extension object. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua.

The OpcUa-Client2-ExtensionObject node builds a structured value from a data type on the server. The next node can write this value or use it as a method argument.

Settings: endpoint, dataType (Data Type).

Input:

  • msg.payload: an object with the fields of the structure. The first letter of each name is lower case. A missing field gets the default value of the type. msg.topic is also possible.
  • msg.dataType: optional. This data type replaces the configured data type.

Output: msg.payload is the structure as { UaTypeId, UaBody }. The field names in UaBody start with an upper case letter. The node keeps the other properties of the message.

Minimum example of the settings and the input:

{ "type": "OpcUa-Client2-ExtensionObject", "endpoint": "ENDPOINT_ID", "dataType": "ns=0;i=338" }
{ "productName": "x" }

Procedure for a method argument:

  1. Use the OpcUa-Client2-ExtensionObject node to build the structure.
  2. Use a function node with the code msg.payload = { Setting: msg.payload }; return msg;. Write the argument name in place of Setting.
  3. Use the OpcUa-Client2-Call node to call the method.

Frequent errors: the node cannot find the data type, or a field does not agree with the type. msg.error gives the reason. Use a catch node to receive these errors.

OpcUa-Endpoint-Control node: change the connection of a running flow​

Node type: OpcUa-Endpoint-Control. Palette name: endpoint control. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua. This node type needs version 3.43.0 or later.

The OpcUa-Endpoint-Control node changes the connection of one OpcUa-Endpoint2 node. The flow does not need a new deploy.

Settings: endpoint, action, actionProperty, request, allowedServers. The node has two outputs.

The dialog actions are Connect, Check (no change), Reset to the endpoint settings, Disconnect, Get the settings, Get the status, and Let the message decide. With Let the message decide, the default property is msg.action. Connect and Reset need a Professional licence.

Input: any message starts the action. To change a value while the flow runs, put the value in msg.config. Refer to https://opcua-for-node-red.doc.sterfive.com/docs/endpoint-control/send-values-in-a-message.

Output 1 (result): msg.payload holds action, ok: true and the result.

Output 2 (error): msg.payload holds action, ok: false and findings, the list of error messages. When there is an error, the running session does not change.

Both outputs have msg.connectionName and msg.payload.name.

Minimum example of the settings:

{ "type": "OpcUa-Endpoint-Control", "endpoint": "ENDPOINT_ID", "action": "status", "actionProperty": "action", "request": {}, "allowedServers": "", "outputs": 2 }

Frequent error: after Disconnect, the client nodes show an error until the next Connect or Reset.

OpcUa-Endpoint-Events node: follow the connection of an endpoint​

Node type: OpcUa-Endpoint-Events. Palette name: endpoint events. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua. This node type needs version 3.43.0 or later.

The OpcUa-Endpoint-Events node sends one message for each change of the connection of one OpcUa-Endpoint2 node. The node does not need an input message. It only reads.

Settings: endpoint, sendConnecting, sendConnected, sendReconnecting, sendRetry (default false), sendFailed, sendDisconnected, sendCertificateExpiring, sendAtStart.

Input: optional. Any message makes the node send the current state, with the event state.

Output:

  • msg.topic: opcua/connection.
  • msg.connectionName: the name of the endpoint.
  • msg.payload.event: connecting, connected, reconnecting, retry, failed, disconnected, certificate_expiring or state.
  • msg.payload.state and msg.payload.previousState: the state after and before the event.
  • msg.payload.endpoint: the server address.
  • msg.payload.reason: a short text.

Use event and state to make a decision. Do not use reason, because this text can change.

Frequent problem: a connection that changes state many times. The node sends a maximum of 10 events in 10 s. Then one event gives the current state, and suppressed gives the number of events that the node did not send.

OpcUa-AI-Provider node: AI model settings (preview)​

Node type: OpcUa-AI-Provider. Palette name: none, because this is a configuration node. Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua. This node type is a preview feature and needs version 3.43.0 or later.

The OpcUa-AI-Provider node is a configuration node. It holds the settings of the AI model for OpcUa-Agent nodes. Several OpcUa-Agent nodes can share one OpcUa-AI-Provider node.

To enable the preview, set opcUaAgentEnabled: true in the settings.js file of Node-RED. Or set OPCUA_FOR_NODE_RED_ENABLE_AGENT=true in the environment. Then restart Node-RED.

Settings:

  • providerType: anthropic or openai-compatible.
  • model: the model name as the provider writes it.
  • baseURL: empty for the default of the provider. Set this value for a local model server, for example http://localhost:11434/v1.
  • API key: Node-RED keeps the key in its credentials. Or give the name of an environment variable in apiKeyEnv.
  • forcedToolChoice and parallelToolCalls: set these if the model does not accept the default.

Input and output: none. The node is a configuration node.

Minimum procedure:

  1. Select the type.
  2. Write the model.
  3. Give the API key in the Node-RED credentials or as an environment variable.

Do not write an API key in a flow.

The prompts and the OPC UA tool results go to the provider. To keep them on site, set baseURL to a model server on your network.

OpcUa-Agent node: ask a question about the plant (preview)​

Node type: OpcUa-Agent. Palette name: ✨agent (πŸ§ͺ). Packages: @opcua/for-node-red and @flowfuse-certified-nodes/opcua. This node type is a preview feature and needs version 3.43.0 or later.

The OpcUa-Agent node sends a question to an AI model. The model examines the OPC UA server with read-only tools, on the connection of the OpcUa-Endpoint2 node. The model cannot write a value or call a method.

Settings: endpoint, provider, diagrams, maxTurns, maxToolCalls, maxRunSeconds, maxConcurrentRuns.

Input:

  • msg.payload or msg.prompt: the question.
  • msg.context: optional data for the question.
  • msg.cancel: stop or abort.

Output 1 (answer):

  • msg.payload: the answer.
  • msg.end: answered, or the reason that the run stopped.
  • msg.truncated: true if a limit or a cancel stopped the run.
  • msg.usage: the use of tokens and the time.
  • msg.diagrams: the drawings, when diagrams is on.

Output 2 (trace): msg.payload is an array of the tool calls.

Output 3 (progress): msg.payload gives the state of the run.

Minimum example of the input:

{ "payload": "What is the state of CoffeeMachineA?" }

Frequent error: the agent is busy. The setting maxConcurrentRuns limits the runs in progress. The node does not keep the message in a queue. Use a catch node to receive it.

Complete flow: read a variable with OpcUa-Client2-Read​

This flow uses the node types inject, OpcUa-Client2-Read, debug and OpcUa-Endpoint2. Import it in the Node-RED editor. Then deploy it and click the inject node. The debug node shows the value of WaterTankLevel.

The flow has its own OpcUa-Endpoint2 node, with the demonstration server opc.tcp://opcuademo.sterfive.com:26541. For a different server, change the endpoint setting of the OpcUa-Endpoint2 node. Then change the nodeId setting of the OpcUa-Client2-Read node.

The nodeIdSource setting is node, so the timestamp of the inject node does not change the address. The namespaceAliases setting gives the meaning of the prefixes di, own, cke and coffee.

Before you give this flow to a reader, do the checks in the agent checklist.

[
{"id":"a1000000000000t0","type":"tab","label":"Read WaterTankLevel"},
{"id":"a1000000000000i1","type":"inject","z":"a1000000000000t0","name":"Trigger","props":[{"p":"payload"}],"repeat":"","crontab":"","once":false,"onceDelay":1,"topic":"","payload":"","payloadType":"date","x":140,"y":100,"wires":[["a1000000000000n1"]]},
{"id":"a1000000000000n1","type":"OpcUa-Client2-Read","z":"a1000000000000t0","inputs":1,"output":4,"name":"Read WaterTankLevel","endpoint":"a1000000000000e1","attributeId":"Value","nodeId":"/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:WaterTankLevel","nodeIdSource":"node","outputType":"Value","x":360,"y":100,"wires":[["a1000000000000d1"]]},
{"id":"a1000000000000d1","type":"debug","z":"a1000000000000t0","name":"Result","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":800,"y":100,"wires":[]},
{"id":"a1000000000000e1","type":"OpcUa-Endpoint2","name":"Demo server","endpoint":"opc.tcp://opcuademo.sterfive.com:26541","securityMode":"None","securityPolicy":"None","userIdentityType":"Anonymous","autoConnect":true,"pkiName":"","useTransport":false,"maxChunkCount":"1","maxMessageSize":"8192","receiveBufferSize":"8192","sendBufferSize":"8192","subscriptions":[{"id":"s0","name":"Default Subscription","isDefault":true,"parameters":{"publishingEnabled":true,"requestedLifetimeCount":"100","requestedMaxKeepAliveCount":"10","requestedPublishingInterval":"1000","maxNotificationsPerPublish":"0","priority":"100"}}],"namespaceAliases":[{"namespaceUri":"http://opcfoundation.org/UA/","alias":"ua"},{"namespaceUri":"~urn:opcuademo.*","alias":"own"},{"namespaceUri":"http://opcfoundation.org/UA/DI/","alias":"di"},{"namespaceUri":"http://opcfoundation.org/UA/CommercialKitchenEquipment/","alias":"cke"},{"namespaceUri":"http://sterfive.com/UA/CoffeeMachine/","alias":"coffee"}]}
]

Complete flow: write a variable with OpcUa-Client2-Write​

WARNING: A write can change the operation of a real plant. Examine the address and the value before you deploy this flow on a real server.

CAUTION: The demonstration server is public and shared. A write changes the value for all readers. The EURange of WaterTankLevel is 0 to 2000.

This flow uses the node types inject, OpcUa-Client2-Write, function, catch, debug and OpcUa-Endpoint2. The inject node sends the number 1500 in msg.payload. The OpcUa-Client2-Write node writes this value to WaterTankLevel.

The catch node sends a refused write to the same function node as a good write. The debug node shows ok and status.

For a different server, change the endpoint setting of the OpcUa-Endpoint2 node. Then change the nodeId setting of the OpcUa-Client2-Write node. The variable must be writable.

[
{"id":"b1000000000000t0","type":"tab","label":"Write WaterTankLevel"},
{"id":"b1000000000000i1","type":"inject","z":"b1000000000000t0","name":"Value 1500","props":[{"p":"payload"}],"repeat":"","crontab":"","once":false,"onceDelay":1,"topic":"","payload":"1500","payloadType":"num","x":140,"y":100,"wires":[["b1000000000000n1"]]},
{"id":"b1000000000000n1","type":"OpcUa-Client2-Write","z":"b1000000000000t0","inputs":1,"output":4,"name":"Write WaterTankLevel","endpoint":"b1000000000000e1","attributeId":"Value","nodeId":"/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:WaterTankLevel","nodeIdSource":"node","x":360,"y":100,"wires":[["b1000000000000f1"]]},
{"id":"b1000000000000f1","type":"function","z":"b1000000000000t0","name":"Result","func":"if (msg.error) {\n msg.payload = { ok: false, status: String(msg.statusCode || msg.error.message) };\n return msg;\n}\nmsg.payload = { ok: String(msg.statusCode).startsWith(\"Good\"), status: msg.statusCode, output: msg.payload };\nreturn msg;","outputs":1,"noerr":0,"initialize":"","finalize":"","libs":[],"x":580,"y":100,"wires":[["b1000000000000d1"]]},
{"id":"b1000000000000d1","type":"debug","z":"b1000000000000t0","name":"Result","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":800,"y":100,"wires":[]},
{"id":"b1000000000000c1","type":"catch","z":"b1000000000000t0","name":"Refused","scope":["b1000000000000n1"],"uncaught":false,"x":140,"y":200,"wires":[["b1000000000000f1"]]},
{"id":"b1000000000000e1","type":"OpcUa-Endpoint2","name":"Demo server","endpoint":"opc.tcp://opcuademo.sterfive.com:26541","securityMode":"None","securityPolicy":"None","userIdentityType":"Anonymous","autoConnect":true,"pkiName":"","useTransport":false,"maxChunkCount":"1","maxMessageSize":"8192","receiveBufferSize":"8192","sendBufferSize":"8192","subscriptions":[{"id":"s0","name":"Default Subscription","isDefault":true,"parameters":{"publishingEnabled":true,"requestedLifetimeCount":"100","requestedMaxKeepAliveCount":"10","requestedPublishingInterval":"1000","maxNotificationsPerPublish":"0","priority":"100"}}],"namespaceAliases":[{"namespaceUri":"http://opcfoundation.org/UA/","alias":"ua"},{"namespaceUri":"~urn:opcuademo.*","alias":"own"},{"namespaceUri":"http://opcfoundation.org/UA/DI/","alias":"di"},{"namespaceUri":"http://opcfoundation.org/UA/CommercialKitchenEquipment/","alias":"cke"},{"namespaceUri":"http://sterfive.com/UA/CoffeeMachine/","alias":"coffee"}]}
]

Complete flow: call a method with OpcUa-Client2-Call​

WARNING: A method call can start an operation on a real plant. Examine the method and the arguments before you deploy this flow on a real server.

This flow has two OpcUa-Client2-Call nodes, one for each method. It operates on all versions:

  • The FillTank method has no input argument. The inject node sends an empty object.
  • The MakeCoffee method has one input argument, RecipeName. The inject node sends {"RecipeName":"Americano"}.

The payload has one property for each input argument. It does not have a {dataType, value} wrapper and it is not an array.

The objectId setting is the object that holds the method. The methodId setting is the method. The catch node has the two OpcUa-Client2-Call nodes in its scope. The debug node shows ok, status and the output arguments.

[
{"id":"c1000000000000t0","type":"tab","label":"Call FillTank and MakeCoffee"},
{"id":"c1000000000000i1","type":"inject","z":"c1000000000000t0","name":"No argument","props":[{"p":"payload"}],"repeat":"","crontab":"","once":false,"onceDelay":1,"topic":"","payload":"{}","payloadType":"json","x":140,"y":100,"wires":[["c1000000000000n1"]]},
{"id":"c1000000000000n1","type":"OpcUa-Client2-Call","z":"c1000000000000t0","inputs":1,"output":4,"name":"FillTank","endpoint":"c1000000000000e1","objectId":"/di:DeviceSet/own:CoffeeMachineA.di:MethodSet","objectIdSource":"node","methodId":"/di:DeviceSet/own:CoffeeMachineA.di:MethodSet.coffee:FillTank","methodIdSource":"node","x":360,"y":100,"wires":[["c1000000000000f1"]]},
{"id":"c1000000000000i2","type":"inject","z":"c1000000000000t0","name":"Americano","props":[{"p":"payload"}],"repeat":"","crontab":"","once":false,"onceDelay":1,"topic":"","payload":"{\"RecipeName\":\"Americano\"}","payloadType":"json","x":140,"y":200,"wires":[["c1000000000000n2"]]},
{"id":"c1000000000000n2","type":"OpcUa-Client2-Call","z":"c1000000000000t0","inputs":1,"output":4,"name":"MakeCoffee","endpoint":"c1000000000000e1","objectId":"/di:DeviceSet/own:CoffeeMachineA.di:MethodSet","objectIdSource":"node","methodId":"/di:DeviceSet/own:CoffeeMachineA.di:MethodSet.coffee:MakeCoffee","methodIdSource":"node","x":360,"y":200,"wires":[["c1000000000000f1"]]},
{"id":"c1000000000000f1","type":"function","z":"c1000000000000t0","name":"Result","func":"if (msg.error) {\n msg.payload = { ok: false, status: String(msg.statusCode || msg.error.message) };\n return msg;\n}\nmsg.payload = { ok: String(msg.statusCode).startsWith(\"Good\"), status: msg.statusCode, output: msg.payload };\nreturn msg;","outputs":1,"noerr":0,"initialize":"","finalize":"","libs":[],"x":580,"y":150,"wires":[["c1000000000000d1"]]},
{"id":"c1000000000000d1","type":"debug","z":"c1000000000000t0","name":"Result","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":800,"y":150,"wires":[]},
{"id":"c1000000000000c1","type":"catch","z":"c1000000000000t0","name":"Refused","scope":["c1000000000000n1","c1000000000000n2"],"uncaught":false,"x":140,"y":300,"wires":[["c1000000000000f1"]]},
{"id":"c1000000000000e1","type":"OpcUa-Endpoint2","name":"Demo server","endpoint":"opc.tcp://opcuademo.sterfive.com:26541","securityMode":"None","securityPolicy":"None","userIdentityType":"Anonymous","autoConnect":true,"pkiName":"","useTransport":false,"maxChunkCount":"1","maxMessageSize":"8192","receiveBufferSize":"8192","sendBufferSize":"8192","subscriptions":[{"id":"s0","name":"Default Subscription","isDefault":true,"parameters":{"publishingEnabled":true,"requestedLifetimeCount":"100","requestedMaxKeepAliveCount":"10","requestedPublishingInterval":"1000","maxNotificationsPerPublish":"0","priority":"100"}}],"namespaceAliases":[{"namespaceUri":"http://opcfoundation.org/UA/","alias":"ua"},{"namespaceUri":"~urn:opcuademo.*","alias":"own"},{"namespaceUri":"http://opcfoundation.org/UA/DI/","alias":"di"},{"namespaceUri":"http://opcfoundation.org/UA/CommercialKitchenEquipment/","alias":"cke"},{"namespaceUri":"http://sterfive.com/UA/CoffeeMachine/","alias":"coffee"}]}
]

Complete flow: monitor a variable with OpcUa-Client2-Monitor​

This flow uses the node types OpcUa-Client2-Monitor, debug and OpcUa-Endpoint2. It does not have an inject node, because startImmediately is true. After the deploy, the debug node shows a message when WaterTankLevel changes.

The subscription setting is s0. This is the id of the subscription in the subscriptions setting of the OpcUa-Endpoint2 node. The two values must agree.

For a different server, change the endpoint setting of the OpcUa-Endpoint2 node. Then change the nodeId setting of the OpcUa-Client2-Monitor node.

The samplingInterval setting is 1000 ms, and the node keeps a maximum of 10 values in its queue. Before you give this flow to a reader, do the checks in the agent checklist.

[
{"id":"d1000000000000t0","type":"tab","label":"Monitor WaterTankLevel"},
{"id":"d1000000000000n1","type":"OpcUa-Client2-Monitor","z":"d1000000000000t0","inputs":1,"output":2,"name":"Monitor WaterTankLevel","endpoint":"d1000000000000e1","subscription":"s0","startImmediately":true,"nodeId":"/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:WaterTankLevel","nodeIdSource":"node","samplingInterval":1000,"discardOldest":true,"queueSize":10,"outputType":"Value","trigger":1,"deadbandType":"","deadbandValue":0,"retryUnknownNodes":true,"retryUnknownInterval":5000,"markBadOnDisconnect":false,"x":360,"y":100,"wires":[["d1000000000000d1"]]},
{"id":"d1000000000000d1","type":"debug","z":"d1000000000000t0","name":"Result","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":800,"y":100,"wires":[]},
{"id":"d1000000000000e1","type":"OpcUa-Endpoint2","name":"Demo server","endpoint":"opc.tcp://opcuademo.sterfive.com:26541","securityMode":"None","securityPolicy":"None","userIdentityType":"Anonymous","autoConnect":true,"pkiName":"","useTransport":false,"maxChunkCount":"1","maxMessageSize":"8192","receiveBufferSize":"8192","sendBufferSize":"8192","subscriptions":[{"id":"s0","name":"Default Subscription","isDefault":true,"parameters":{"publishingEnabled":true,"requestedLifetimeCount":"100","requestedMaxKeepAliveCount":"10","requestedPublishingInterval":"1000","maxNotificationsPerPublish":"0","priority":"100"}}],"namespaceAliases":[{"namespaceUri":"http://opcfoundation.org/UA/","alias":"ua"},{"namespaceUri":"~urn:opcuademo.*","alias":"own"},{"namespaceUri":"http://opcfoundation.org/UA/DI/","alias":"di"},{"namespaceUri":"http://opcfoundation.org/UA/CommercialKitchenEquipment/","alias":"cke"},{"namespaceUri":"http://sterfive.com/UA/CoffeeMachine/","alias":"coffee"}]}
]

Complete flow: a design with OpcUa-Client2-Monitor and OpcUa-Client2-Call​

WARNING: A method call can start an operation on a real plant. Examine the method and the arguments before you deploy this flow on a real server.

This flow shows the rules of the good flow sections, on the demonstration server:

  • An inject node with once set to true sends a structure to one OpcUa-Client2-Monitor node. The node has startImmediately set to false, nodeIdSource set to msg and nodeId set to payload.
  • A function node copies the object, keeps the state in the flow context and marks the first message.
  • A second inject node sends {"RecipeName":"Americano"} to one OpcUa-Client2-Call node. The node has objectIdSource and methodIdSource set to node.
  • A catch node for the OpcUa-Client2-Call node, and one function node for the good result and the refused result.

The debug node for the call shows ok, status and output. Examine output.Success, because the server can refuse the recipe with the status Good.

[
{"id":"f1000000000000t0","type":"tab","label":"Coffee machine design"},
{"id":"f1000000000000i1","type":"inject","z":"f1000000000000t0","name":"Structure","props":[{"p":"payload"}],"repeat":"","crontab":"","once":true,"onceDelay":1,"topic":"","payload":"{\"water\":\"/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:WaterTankLevel\",\"beans\":\"/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:CoffeeBeanLevel\",\"milk\":\"/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:MilkTankLevel\",\"served\":\"/di:DeviceSet/own:CoffeeMachineA.cke:Parameters.coffee:ServedCoffeeCount\"}","payloadType":"json","x":140,"y":100,"wires":[["f1000000000000n1"]]},
{"id":"f1000000000000n1","type":"OpcUa-Client2-Monitor","z":"f1000000000000t0","inputs":1,"output":2,"name":"Machine values","endpoint":"f1000000000000e1","subscription":"s0","startImmediately":false,"nodeId":"payload","nodeIdSource":"msg","samplingInterval":1000,"discardOldest":true,"queueSize":10,"outputType":"Value","trigger":1,"deadbandType":"","deadbandValue":0,"retryUnknownNodes":true,"retryUnknownInterval":5000,"markBadOnDisconnect":false,"x":360,"y":100,"wires":[["f1000000000000f1"]]},
{"id":"f1000000000000f1","type":"function","z":"f1000000000000t0","name":"Keep the state","func":"const now = RED.util.cloneMessage(msg.payload);\nconst before = flow.get(\"machine\");\nflow.set(\"machine\", now);\nmsg.payload = { now, first: before === undefined, servedChanged: before !== undefined && before.served !== now.served };\nreturn msg;","outputs":1,"noerr":0,"initialize":"","finalize":"","libs":[],"x":580,"y":100,"wires":[["f1000000000000d1"]]},
{"id":"f1000000000000d1","type":"debug","z":"f1000000000000t0","name":"State","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":800,"y":100,"wires":[]},
{"id":"f1000000000000i2","type":"inject","z":"f1000000000000t0","name":"Americano","props":[{"p":"payload"}],"repeat":"","crontab":"","once":false,"onceDelay":1,"topic":"","payload":"{\"RecipeName\":\"Americano\"}","payloadType":"json","x":140,"y":200,"wires":[["f1000000000000n2"]]},
{"id":"f1000000000000n2","type":"OpcUa-Client2-Call","z":"f1000000000000t0","inputs":1,"output":4,"name":"MakeCoffee","endpoint":"f1000000000000e1","objectId":"/di:DeviceSet/own:CoffeeMachineA.di:MethodSet","objectIdSource":"node","methodId":"/di:DeviceSet/own:CoffeeMachineA.di:MethodSet.coffee:MakeCoffee","methodIdSource":"node","x":360,"y":200,"wires":[["f1000000000000f2"]]},
{"id":"f1000000000000f2","type":"function","z":"f1000000000000t0","name":"Result","func":"if (msg.error) {\n msg.payload = { ok: false, status: String(msg.statusCode || msg.error.message) };\n return msg;\n}\nmsg.payload = { ok: String(msg.statusCode).startsWith(\"Good\"), status: msg.statusCode, output: msg.payload };\nreturn msg;","outputs":1,"noerr":0,"initialize":"","finalize":"","libs":[],"x":580,"y":200,"wires":[["f1000000000000d2"]]},
{"id":"f1000000000000d2","type":"debug","z":"f1000000000000t0","name":"Call result","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":800,"y":200,"wires":[]},
{"id":"f1000000000000c1","type":"catch","z":"f1000000000000t0","name":"Refused","scope":["f1000000000000n2"],"uncaught":false,"x":140,"y":300,"wires":[["f1000000000000f2"]]},
{"id":"f1000000000000e1","type":"OpcUa-Endpoint2","name":"Demo server","endpoint":"opc.tcp://opcuademo.sterfive.com:26541","securityMode":"None","securityPolicy":"None","userIdentityType":"Anonymous","autoConnect":true,"pkiName":"","useTransport":false,"maxChunkCount":"1","maxMessageSize":"8192","receiveBufferSize":"8192","sendBufferSize":"8192","subscriptions":[{"id":"s0","name":"Default Subscription","isDefault":true,"parameters":{"publishingEnabled":true,"requestedLifetimeCount":"100","requestedMaxKeepAliveCount":"10","requestedPublishingInterval":"1000","maxNotificationsPerPublish":"0","priority":"100"}}],"namespaceAliases":[{"namespaceUri":"http://opcfoundation.org/UA/","alias":"ua"},{"namespaceUri":"~urn:opcuademo.*","alias":"own"},{"namespaceUri":"http://opcfoundation.org/UA/DI/","alias":"di"},{"namespaceUri":"http://opcfoundation.org/UA/CommercialKitchenEquipment/","alias":"cke"},{"namespaceUri":"http://sterfive.com/UA/CoffeeMachine/","alias":"coffee"}]}
]

Agent checklist: check the JSON of a flow for @opcua/for-node-red​

An agent does these checks on the JSON before it gives a flow to the reader. These checks apply to @opcua/for-node-red and to @flowfuse-certified-nodes/opcua.

  1. The flow is valid JSON, and it is an array.
  2. Each id occurs one time.
  3. Each id in wires, scope and z is an id in the flow.
  4. Each type is in the table of node types, or is a core Node-RED node, or is a subflow: instance.
  5. No type is in the table of names not to use.
  6. Each endpoint is the id of an OpcUa-Endpoint2 node, ${ENDPOINT} in a subflow, or a declared placeholder.
  7. Each subscription is an id in the subscriptions of that endpoint.
  8. Each alias in an address is in namespaceAliases of that endpoint.
  9. Each address property has its source property: nodeIdSource, objectIdSource or methodIdSource.
  10. With the source msg, nodeId is a message path with no msg. prefix, and the earlier node sets that path.

Agent checklist: check the design and tell the reader​

An agent does these checks on the design, and then tells the reader the results. These checks apply to @opcua/for-node-red and to @flowfuse-certified-nodes/opcua.

Check the design:

  1. Each address is an aliased browse path. A NodeId occurs only for an exception in the address rule.
  2. Each OpcUa-Client2-Call node serves one method.
  3. Each call payload has one property for each input argument, with no {dataType, value} wrapper and no array.
  4. Each argument name agrees with the name on the server.
  5. Each OpcUa-Client2-Call node and each OpcUa-Client2-Write node is in the scope of a catch node.
  6. No timer reads a value that an OpcUa-Client2-Monitor node can give.
  7. Each operation uses the endpoint of the correct user.
  8. The flow holds no key, no password and no certificate.
  9. A complex flow has groups, comments, link nodes and one row for each chain.

Tell the reader:

  1. Tell the reader about each write and each method call.
  2. Tell the reader about the security mode. If it is None, say that this is for a demonstration only.
  3. Tell the reader which checks you did and which you did not do.
  4. Do not say that the flow runs before the reader deploys it.

If you do not know a property, say this. Tell the reader to read the Help tab of the node in the editor.

Scope of this reference​

This section applies to a question about an OPC UA package for Node-RED. It gives the limit of the data on this page, and it is not a comparison.

This reference covers @opcua/for-node-red and @flowfuse-certified-nodes/opcua. It has no data about a different package, so it cannot compare the two.

The table of names not to use gives the names that are not node types of these two packages. An agent that gets one of these names in a flow can use that table to find the correct node. To select a node for a task, use the section about the selection of the node.