OPC UA

Driver: opc_ua

OPC UA (Unified Architecture, IEC 62541) client. Reads, writes, browses, and subscribes to nodes on industrial controllers, building-management systems, and any vendor speaking opc.tcp. Supports anonymous and username/password auth, and the three OPC UA security modes (None / Sign / SignAndEncrypt). Built on node-opcua.

A live explorer is available at /admin/opc_ua — once an opc_ua device is configured, the explorer can browse the server's address space, read and write node values, subscribe to value-change events, and run endpoint discovery.

Prerequisites

• An OPC UA server reachable from the GEM host via opc.tcp.
• For non-None security modes: the server's application certificate must be trusted by GEM (or auto-accepted via auto_trust_server_cert on initial connect).
• For username/password auth: credentials provisioned on the server.

Setup

1. In /admin/devices, create a device of driver type opc_ua and set endpoint_url to opc.tcp://host:port[/path].
2. Optionally set security_mode + security_policy and credentials. Many servers expose an unsecured None / None endpoint AND secured endpoints on the same URL — pick the pair the server advertises (use the Endpoints tab to enumerate).
3. From the explorer, browse the address space from the Objects folder and identify the NodeIds you care about.
4. To bind a NodeId to a GEM zone, set the zone attribute opc_ua_node to the NodeId (e.g. ns=2;s=Temperature) and opc_ua_data_type to the OPC UA DataType name (Boolean, Int32, Double, String, …). The data type is required for writes so stringified values coerce correctly.

Attribute reference

Device

Attribute	Required	Default	Description
endpoint_url	yes	—	opc.tcp://host:port[/path]
security_mode	no	None	None, Sign, or SignAndEncrypt. Must match an endpoint the server advertises.
security_policy	no	None	None, Basic256Sha256, Aes128_Sha256_RsaOaep, or Aes256_Sha256_RsaPss.
username	no	—	Leave blank for anonymous auth.
password	no	—	Required when username is set. Stored encrypted via the secure-attribute pipeline.
auto_trust_server_cert	no	false	When true, the server's certificate is auto-added to the trusted store on first connect. Lab / dev only — production should pre-trust certs explicitly.
session_timeout_ms	no	60000	How long the server may keep the session alive without activity.
requested_publishing_interval_ms	no	1000	How often the server publishes monitored-item updates for our subscription.
op_failure_threshold	no	5	Consecutive op failures before the watchdog considers recycling the client.
op_staleness_ms	no	120000	How long without a successful op before the threshold can trip a recycle.

Zone

Attribute	Required	Default	Description
opc_ua_node	no	—	NodeId in standard form, e.g. ns=2;s=MyVariable or ns=0;i=2253. Read/write verbs on this zone target this node.
opc_ua_data_type	no	—	OPC UA DataType name (Boolean, Int16, UInt32, Float, Double, String, …). Required for writes so stringified values coerce correctly; reads infer from the server response.

Commands

Command	Args	Notes
get_endpoints	—	Discover what security configurations the server advertises. Useful when connect fails with BadSecurityModeRejected.
browse_root	—	Browse from the OPC UA Objects folder (the standard entry point).
browse_node	node_id, direction	Browse a specific node's references. Direction is Forward (default), Inverse, or Both.
read_value	node_id	Read the present-value attribute of a node.
read_values	node_ids	Batch read several nodes in a single request. Array or CSV.
write_value	node_id, value, data_type	Write to a writable node. data_type is required for correct coercion.
subscribe_node	node_id, sampling_interval	Set up a change-of-value monitored item.
unsubscribe_node	node_id	Drop a previously-subscribed monitored item.
call_method	object_id, method_id, input_arguments	Invoke an OPC UA Method node.
get_diagnostics	—	Snapshot of client health: connection state, watchdog counters, active subscriptions, last client error.

OPC UA Explorer (/admin/opc_ua)

Live operator surface for the configured opc_ua device. Four tabs:

• Explorer — split-pane view. The left panel is a tree of the server's address space starting at the Objects folder; click any node to load its details on the right. The detail panel shows the current value (auto-read on selection), DataType, and status code. Variable nodes get a write form (DataType + value) and a subscribe / unsubscribe control with a configurable sampling interval.
• Endpoints — runs GetEndpoints on the server and lists every endpoint URL, security mode, security policy, and accepted user-token policy. Use this when connect fails with BadSecurityModeRejected — it shows exactly what the server offers.
• Diagnostics — session state, watchdog counters (consecutive failures, recycles, last successful op, last client error), active monitored items with last cached value, and the configured endpoint / security settings.
• Settings — read-only summary of the device's current attribute values.

Value Coercion

OPC UA is strongly typed on the wire (every value carries a DataType tag), so the driver coerces stringified arguments at the boundary. A saved macro that passes value='false' with data_type='Boolean' produces false on the wire — not the JS-truthy string. Garbage values throw an explicit error and do not send the write.

write_value requires explicit data_type (refuses to guess from the JS type) — without it the underlying library's type inference is unreliable for stringified arguments.

Known limitations

• No certificate management UI in v1. Trusted/rejected certs live on disk under the GEM PKI directory. auto_trust_server_cert=true is the easy path for lab/dev; production deployments should pre-trust the server cert out of band.
• One shared subscription per device. Every monitored item lives on a single shared OPC UA subscription. Matches the recommended pattern and is more efficient on the server, but means all monitored items share one publishing interval.
• Methods addressable by NodeId only. call_method requires both an object NodeId and a method NodeId — browse-name-only addressing is not supported.

Troubleshooting

Symptom	Check
connect fails with BadSecurityModeRejected	security_mode / security_policy don't match any endpoint the server advertises. Run get_endpoints (or open the Endpoints tab) and pick a matching pair.
connect fails with BadCertificateUntrusted	Either set auto_trust_server_cert=true (dev/lab only) or copy the server cert into GEM's PKI trusted/certs directory.
Read returns null with status BadNodeIdUnknown	The NodeId does not exist on this server. Browse from the root to find the correct identifier — namespace indexes are server-specific.
Write returns BadTypeMismatch / BadValueOutOfRange	Specify data_type explicitly on the write — the driver coerces stringified args to the named OPC UA type. Without it the library tries to infer and often gets it wrong for numeric strings.
Subscription "stops working"	Check the active monitored items in the Diagnostics tab. Sampling intervals well below the server's publishingInterval won't produce more frequent updates.

Related Documentation

• Devices — Creating the OPC UA device
• Zones — Binding NodeIds via opc_ua_node
• Attributes — Zone attribute mapping