Connect a Siemens S7-1500 over OPC UA

This guide takes a Siemens S7-1500 from an enabled OPC UA server to live tags in the dashboard. It is for the engineer who sets up the first PLC. The OPC UA driver has read one real S7-1500 (S7_VN_NIRO, 830 tags) in this way; decoding of structured values (whole UDTs read as one node) is not proven yet, so this guide creates one tag per variable.

Prerequisites

• A gateway with the OPC UA driver module (io.scadex.driver.opcua) running. Gateway, then Modules shows its state; see Modules.
• An account with the engineer role (connections and tags need it), or an API key with that role. See Users and roles and API keys.
• On the PLC, in general terms: the OPC UA server is enabled in the CPU properties and licensed, the data blocks you want to read are accessible to OPC UA (not optimized-only, with the "accessible from OPC UA" attribute set on the block or its fields), and either anonymous access is allowed or a server user exists. Write access to a variable is set on the PLC side too.
• Network reach from the gateway to the CPU's OPC UA port (4840 by default).

On an S7-1500 the data blocks appear in namespace 3. A node id looks like ns=3;s="DB_Name"."Field", with the quotes as part of the string.

Steps

1. Add the connection

1. Open Connections, then OPC UA servers.
2. Press Add a server. A panel opens beside the list.
3. Fill in Name (for example Line1_PLC; tags and status tags refer to the connection by this name, so use letters, digits, dots, hyphens or underscores and no spaces) and Address (opc.tcp://192.168.0.10:4840). Leave Enabled on.
4. Press Add server.

The connection's security mode, certificate trust and sign-in live in the driver's advanced settings; the Security section of the panel links there (Open advanced settings). The driver's own fields are:

Field	Key	Values
Endpoint URL	url	opc.tcp://host:4840
Security	securityMode	None (none) or Most secure the server offers (secure)
Trust the server's certificate	trustServerCertificate	Accept an untrusted certificate. Otherwise move it from the module's pki/rejected folder to pki/trusted.
Username, Password	username, password	Empty for anonymous access

The same connection over the API, with a browser session cookie:

curl -b cookies.txt -H "Origin: https://app.scadex.io" -H "Content-Type: application/json" \
  https://app.scadex.io/api/v1/modules/io.scadex.driver.opcua/connections \
  -d '{"name":"Line1_PLC","enabled":true,"configuration":{"url":"opc.tcp://192.168.0.10:4840","securityMode":"none","trustServerCertificate":true,"username":"scadex","password":"secret"}}'

Or with an API key: replace -b cookies.txt -H "Origin: ..." by -H "Authorization: Bearer scx_...". The reply is the connection with its id; the password is never sent back.

2. Test it

1. Select the connection in the list. Its detail page opens.
2. Press Test connection.

A good result shows the round trip time. A failure shows the driver's message under the status. Over the API: POST /api/v1/modules/io.scadex.driver.opcua/connections/<id>/test.

Once saved and enabled, the gateway connects on its own and keeps trying until the server answers. The Driver section of the detail page shows Tags subscribed and the last error the driver reported, and Tags with a problem now lists the tags whose quality is not good.

3. Browse to a data block

1. On the connection's detail page open the Browse tab (or press Browse the address space on the empty tags tab).
2. Expand the tree: Objects, the PLC's node, then DataBlocksGlobal, then the data block. The driver starts the browse at ns=0;i=85 (the Objects folder). Type in Filter open nodes to narrow what is already open.
3. Hover a variable to see its node id, data type and quality; the row shows its current value.

4. Create tags from variables

1. On a variable's row press the Create a tag from ... action. A New tag panel opens beside the tree with the node id as its subtitle and the tag bound to that node.
2. Set the tag's path (the folder and name it gets in the tag tree) and press the panel's save action. The toast says Created <path>.
3. Repeat for the variables you need. Each one is an external tag owned by this connection.

Over the API a tag bound to a node is an ordinary POST /api/v1/tags with the driver and connection as producer and the node id in the binding:

curl -b cookies.txt -H "Origin: https://app.scadex.io" -H "Content-Type: application/json" \
  https://app.scadex.io/api/v1/tags \
  -d '{"path":"Line1.Motor1.Run","kind":"external","producerModuleId":"io.scadex.driver.opcua","producerInstanceId":"<connection id>","binding":{"nodeId":"ns=3;s=\"DB_Motor1\".\"Run\""}}'

The Tags tab of the connection lists every tag it owns with its node id; GET /api/v1/modules/io.scadex.driver.opcua/connections/<id>/tags returns the same list.

5. Check value, quality and timestamp

Open Tags and types and find the new tags in the tree. Each row shows the current value and its quality; a bad quality carries the driver's reason as its detail. The timestamp is the moment the gateway accepted the value. See Tags for how values, qualities and timestamps are kept.

The driver subscribes to the nodes, so a value changes in the browser when it changes in the PLC.

6. Write a value

Select a writable tag in the tag browser and use its write action, or write from a screen widget (see Widgets). Writes need the operator role. The dashboard and the SDK's client.write(path, value) write over the /sync WebSocket as tag.write {path, value}, and the gateway answers tag.write when accepted or tag.write.error {path, error}; see Live data over /sync. A program without a socket can use the REST route POST /api/v1/runtime/tags/{id}/write with {"value": ...} (operator role); see Tags.

The driver casts the value to the variable's declared OPC UA type. A write is refused with a message when the server is not connected ("The OPC UA server for this tag is not connected."), when the variable has more than one dimension, or when an array is written to a scalar.

7. Read the connection's status tags

The gateway keeps a tag folder for every connection under @gateway.connection.opcua.<name> (dots and spaces in the name become _), refreshed every two seconds:

Tag	Value
state	connected, connecting, faulted (has an error) or disabled
connected, enabled	booleans
address	the endpoint, without any credentials typed into it
tags	how many tags the connection serves
error	the last error text, or empty
since	when state last changed (ISO 8601, UTC)

@gateway.connection.opcua.count and .connected count the connections of this kind. The numeric and boolean leaves (connected, tags, rates) are stored with history, so they can be trended and alarmed on; text leaves are live only. See Alarms for alarming on connected.

Troubleshooting

What you see	Meaning
Tags are bad with "The connection is disabled."	The connection's Enabled switch is off. Its tags keep their last value with bad quality.
Tags are bad with "Disconnected from the server." or a socket error	The session dropped. The driver reconnects on its own; @gateway.connection.opcua.<name>.error holds the message.
Tags are bad with "The connection was deleted."	The connection was removed while tags still point at it.
The connection page answers 503 "Module unavailable", or the API does	The OPC UA module is stopped, starting or failed. Start it under Gateway, Modules.
Test connection fails at once	Endpoint, security or certificate mismatch. Check the address, that the PLC offers an endpoint for the chosen Security mode, and that the server's certificate is trusted (or Trust the server's certificate is on). With secure, the PLC must also trust the gateway's own certificate, which it writes under the module's pki folder.
A variable reads Uncertain or Bad from the PLC	The OPC UA status code the PLC returned was not good; the browser row shows the quality name. Check the variable's OPC UA accessibility on the PLC.

Where to go next

• The OPC UA driver, for everything the module offers.
• Tags and Tag types: turn repeated DB structures into a type with the Create a UDT type from this action on a structure node, see Model a motor as a tag type.
• Alarms on the new tags, then Alarm to webhook.
• Connections API for scripting the setup.