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).

One GEM device is one OPC UA server. Individual NodeIds are bound to GEM zones so their values reflect into GEM and can be written back.

The OPC UA Explorer is where you do the work

Browsing the address space, reading and writing nodes, discovering endpoints, mapping nodes to zones, and reading client diagnostics all happen on the OPC UA Explorer page. This page covers the device itself — attributes, commands, and what to check when it won't connect.

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 first connect.
• For username/password auth: credentials provisioned on the server.

Unlike BACnet, KNX, and Modbus, OPC UA is a core integration — no separate license product is needed to add a device.

Setup

1. Open Devices (System → Devices), choose Add Device, and pick the driver opc_ua.
2. Set Endpoint URL to opc.tcp://host:port[/path]. The conventional discovery port is 4840, but use the host and port the server documents — some servers return session endpoints on a different port.
3. Leave Security Mode and Security Policy at None for a first connection, or set them to a pair the server advertises. Run get_endpoints (or the Explorer's Endpoints tab) to see exactly what is on offer.
4. Fill in Username / Password only if the server requires them. Blank means anonymous.
5. Save and reload the device. Reload after any connection, security, or credential change.
6. Bind the NodeIds you care about to zones — the Explorer's Map to Zone tab is the fastest path, and the AI Assistant's map_opc_ua_points skill handles a whole tag export at once. Both are described on the OPC UA integration page.

Attributes

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.
auto_trust_server_cert	no	false	Auto-adds the server's certificate to the trusted store on first connect. Lab/dev only — production should pre-trust certs out of band.
session_timeout_ms	no	60000	How long the server may keep the session alive without activity. Keep-alives are automatic.
requested_publishing_interval_ms	no	1000	How often the server publishes monitored-item updates. Shared by every monitored item on the device.
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	Default	Description
opc_ua_node	—	NodeId in standard form, e.g. ns=2;s=MyVariable or ns=0;i=2253. Read/write/subscribe verbs aimed at this zone with no explicit node_id target this node.
opc_ua_data_type	—	OPC UA DataType name (Boolean, Int16, UInt32, Float, Double, String, …). Required for writes; reads infer from the server response. Used as the fallback data_type when a zone-scoped write_value omits it.

A zone with opc_ua_node set is auto-subscribed on every connect, and change notifications land on the zone's value attribute — that is what triggers, history, and widgets should read.

Commands

Command	Args	Description
get_endpoints	—	Discover what security configurations the server advertises.
browse_root	—	Browse from the OPC UA Objects folder.
browse_node	node_id, direction	Browse a node's references. Direction is Forward (default), Inverse, or Both.
read_value	node_id	Read a node's present value.
read_values	node_ids	Batch read in a single request. Array or CSV.
write_value	node_id, value, data_type	Write to a writable node. data_type is required.
subscribe_node	node_id, sampling_interval	Create a change-of-value monitored item.
unsubscribe_node	node_id	Drop a monitored item.
call_method	object_id, method_id, input_arguments	Invoke an OPC UA Method node.
get_diagnostics	—	Connection state, watchdog counters, active subscriptions, last client error.

The driver implements no standard zone verb — there is no on, off, or set_level. To actuate an output point from a panel button, set the zone's on_action / off_action overrides to a write_value against the node with typed on/off 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, the same way the Modbus and BACnet drivers do. A saved macro passing value='false' with data_type='Boolean' produces false on the wire, not the JS-truthy string. A value that cannot be coerced throws an explicit error and the write is not sent.

write_value refuses to guess the type from the JS value, so data_type is mandatory — the underlying library's inference is unreliable for stringified arguments.

Known limitations

• No certificate management UI. Trusted and rejected certs live on disk under the GEM PKI directory.
• One shared subscription per device. Every monitored item shares a single subscription and therefore one publishing interval.
• Manual subscriptions are not restored on reload. Items created with subscribe_node live only for the current session; zone-mapped nodes (opc_ua_node) are re-subscribed automatically on every connect.
• Methods are addressable by NodeId only. call_method needs both an object and a method NodeId, and its input arguments are passed through already-typed rather than coerced.
• No polling. Value reflection is change-of-value only. For servers without subscription support, schedule a macro that runs read_value.

Troubleshooting

Symptom	Check
connect fails with BadSecurityModeRejected	security_mode / security_policy don't match any advertised endpoint. Run get_endpoints and pick a matching pair.
connect fails with BadCertificateUntrusted	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 BadNodeIdUnknown	The NodeId does not exist on this server. Browse from the root — namespace indexes are server-specific.
Write returns BadTypeMismatch / BadValueOutOfRange	Specify data_type explicitly on the write.
A zone bound with opc_ua_node never shows a value	The zone updates on change only. Run read_value once, check the monitored item in the Explorer's Diagnostics tab, and reload the zone if the mapping was added by hand-editing attributes.
A subscription stopped producing updates	Sampling intervals below the server's publishing interval won't produce more frequent updates. Monitored items reset on device reload.

See also

• OPC UA — the OPC UA Explorer, zone mapping, and bulk point mapping with the AI Assistant.
• Devices — adding the device and reading its log.
• Zones — binding NodeIds to zones.
• Attributes — zone attribute mapping.