OPC UA Connector

On ctrlX OS this connector is not used: a ctrlX PLC on the same device uses the nodes directly, see Connecting a PLC.

The LumiScan OPC UA Connector (lumiscan_opcua_connector) shows the tree of LumiScan Keryx as an OPC UA address space. A PLC, a SCADA system or any OPC UA client reads, writes, calls and subscribes to the nodes of the apps without a Data Layer client of its own. The connector forwards every request to the Data Layer when it arrives; it stores no values of its own.

The address space is the Data Layer’s own tree, not an OPC UA companion specification such as OPC 40100 (Machine Vision).

Endpoint and address space

Endpoint

opc.tcp://<pc>:4840, on every network interface of the PC

Security

security policy None, anonymous login, see Security

Namespace URI

urn:hdvisionsystems:keryx

NodeId

the Data Layer address as a string identifier in that namespace: ns=<n>;s=hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code

BrowseName

the last segment of the address, for example code

Root

one object under Objects, called Keryx, that holds hdvisionsystems and the other top-level folders. Started with --root hdvisionsystems it is hdvisionsystems; the NodeIds stay the same

Find the namespace index n from the URI in the server’s NamespaceArray. Do not write a fixed index into your program: another start can number it differently.

Data Layer OPC UA node

folder

Object (FolderType)

value

Variable (BaseDataVariableType), with the access the node allows

method

Method with no input arguments and one output argument Result, belonging to the object of its parent address

The connector walks the tree at start and again every 2 seconds. An app that starts later, a module that is added and a node that disappears show up within about 2 seconds. There are no model change events: a client that cached its browse result must browse again. An app that stops keeps its nodes in the tree; reading them answers BadTimeout, then BadNoCommunication, until the app registers again.

Starting the connector

The installer adds a Start menu shortcut that starts the connector without options: port 4840, the whole Data Layer, anonymous, read and write.

Start it after the apps. The connector never starts a broker: without one it logs the reason and ends with exit code 1, and its window closes. Stop it with Ctrl+C. Like the apps it is protected with CodeMeter, see LumiScan Licensing.

Option Meaning

-p, --port <n>

OPC UA port, default 4840

-r, --root <address>

show only this subtree, for example hdvisionsystems

--read-only

refuse writes (BadNotWritable) and method calls (BadNotExecutable)

--keryx-url <url>

the broker, default tcp://127.0.0.1:5555

--request-timeout-ms <ms>

how long a read or write may take, default 2000

--method-timeout-ms <ms>

how long a method call may take, default 60000

--method-workers <n>

method calls that run at the same time, default 4

--min-publishing-ms <ms>

the fastest a subscription sends notifications, default 10

--resync-ms <ms>

how often the tree is walked again, default 2000

--sampling-ms <ms>

sampled mode instead of event mode; not recommended

lumiscan_opcua_connector --help lists all options.

Security

There is none. The connector accepts any client, anonymous and unencrypted, and the client can write every writable node and call every method - including starting and stopping the camera and changing settings through system/settings. Treat it like an unprotected field-bus port:

  • run it on a network you trust, such as the machine network between the PC and the PLC;

  • open TCP 4840 in the PC’s firewall for the PLC’s address only;

  • for a client that only observes, run a second instance read-only on its own port: lumiscan_opcua_connector --root hdvisionsystems --port 4841 --read-only.

Certificates, user names and encryption are not supported; a client that insists on a secure channel cannot connect.

Reading, writing and types

The type must be exactly the node’s. The connector does not convert: a Boolean node takes a Boolean, not 0 or 1; a UInt32 node takes UInt32, not Int32. Most trouble with a first connection is a type that is one size off.

Node type OPC UA type IEC 61131-3

bool

Boolean

BOOL

int32

Int32

DINT

uint32

UInt32

UDINT

uint64

UInt64

ULINT

float32

Float

REAL

float64

Double

LREAL

string

String

STRING

arrays of these

the same type, one dimension

ARRAY [..] OF …​

FlatBuffers result, image

ByteString

not usable without a decoder

  • A read waits up to 2 seconds. A node that did not answer is BadNoCommunication for the next 5 seconds.

  • A write replaces the whole value and is never repeated. A write with a NumericRange is refused (BadWriteNotSupported).

  • The timestamps of a value are the connector’s: the Data Layer carries no time of its own.

  • Do not build PLC logic on FlatBuffers values. Use the plain nodes beside them.

Calling the three patterns

Handshake: only reads and writes, as in Handshake. Poll at 50 to 100 ms.

Execute: write the method’s inputs - a method has no arguments, its inputs are separate nodes - then use the Call service with objectId = the parent address (for example …​/camera1/control/trigger) and methodId = the method (…​/camera1/control/trigger/execute). The call answers when the method has finished, after up to 60 seconds; set your client’s call timeout higher than your slowest method. The status of the call says whether the operation could run, see Results of a method call. Then read control/status/code and the outputs.

Stream: subscribe to the result node, see Subscriptions.

Subscriptions

Create a subscription and add a monitored item for the node:

Setting Value Why

Publishing interval

10 ms or more

the server’s fastest

Sampling interval

0

reports every push as it arrives (event mode)

Queue size

10 to 100

with 1 only the newest push arrives

DataChange trigger

StatusValueTimestamp

otherwise two identical results count as one

DiscardOldest

true

  • A node reports a change when the app pushes it; streams do. A value too large to be pushed never reports in event mode: use a positive sampling interval for it.

  • Large values cost: a 1.5 MB camera frame sampled every 10 ms is 150 MB/s for one item. Do not monitor output/image, …​/stream/frame or …​/stream/result unless you decode them. For coordinates, monitor Calibration’s plain-points.

  • At start the connector checks that event mode works. If it does not, it logs that and samples every item on a timer (sampled mode). If your client gets fewer notifications than pushes, read the connector’s log first.

OPC UA status codes

Beyond the results of a method call:

Status Meaning

BadNodeIdUnknown

wrong address, case or namespace index; the app is not running; the module is missing

BadNoCommunication

the app has stopped or hangs

BadTimeout

the app did not answer in 2 s (read, write) or 60 s (call)

BadTypeMismatch

the value is not of the node’s type

BadWriteNotSupported

a write with a NumericRange

BadNotWritable

an output, or the connector is read-only

BadNotExecutable

the connector is read-only

BadMethodInvalid

the node is no longer a method of the tree: browse again

After an app has restarted, run your start-up sequence again: the camera is not connected and the Cam Driver’s stream is off. If a monitored item does not report again, delete and create it.