OPC UA read task

Learn how to acquire data from OPC UA servers with Synnax.

This task follows the standard task lifecycle.

Task configuration reference

Table

Parameter	Type	Required	Default	Description
`device`	string	Yes	-	Key of the OPC UA server device
`sample_rate`	number	No	`50`	Samples per second (Hz)
`stream_rate`	number	No	`25`	Rate data is streamed to Synnax (Hz), must be ≤ `sample_rate`. Used when `array_mode=false`
`array_mode`	boolean	No	`false`	Enable array sampling mode for high-rate tasks
`array_size`	number	No	`1`	Number of samples to read in bulk. Required when `array_mode=true`
`channels`	array	Yes	-	List of input channel configurations

Channel configuration reference

OPC UA Read Service Specification

Standard Mode (array_mode=false)

Reads scalar values from an OPC UA node at the specified sample rate. Suitable for most applications with standard data rates.

Table

Parameter	Type	Required	Default	Description
`channel`	number	Yes	-	Synnax channel key
`node_id`	string	Yes	-	OPC UA NodeId (e.g., `ns=2;s=MyVariable`)

NodeId Format Examples:

Numeric: ns=2;i=1000
String: ns=2;s=Temperature
GUID: ns=2;g=12345678-1234-1234-1234-123456789012
Opaque: ns=2;b=aGVsbG8=

Array Mode (array_mode=true)

Reads array data from an OPC UA node in bulk. Designed for high-frequency data (>500 Hz) where the server writes samples into arrays.

When array_mode=true, the task reads multiple samples in bulk from the OPC UA server. This is more efficient for high-rate tasks but requires careful configuration to avoid undersampling or oversampling.

Table

Parameter	Type	Required	Default	Description
`channel`	number	Yes	-	Synnax channel key
`node_id`	string	Yes	-	OPC UA NodeId pointing to an array variable

Array Sampling Guidelines:

Set sample_rate to match the OPC UA server’s sample rate
Set array_size to an integer factor of the sample rate
Oversampling occurs when the server doesn’t fully replace array values between reads
Undersampling occurs when the server writes faster than Synnax reads

Server Timestamp Read

Reads timestamps directly from the OPC UA server for high-precision timing instead of using Synnax-generated timestamps.

Table

Parameter	Type	Required	Default	Description
`channel`	number	Yes	-	Synnax index channel key (must be `TIMESTAMP` data type)
`node_id`	string	Yes	-	OPC UA NodeId containing server timestamps

If timestamp channels are not added to the task, Synnax automatically generates timestamps with ~100 µs precision using software timing.

Important rules

Software timing -> Samples are timestamped in software with ~100 µs precision, which degrades under heavy load.
Array mode -> Use array mode only above 500 Hz. It needs tuning to avoid under- or oversampling.
Stream rate -> For sample rates under 50 Hz, set the stream rate equal to the sample rate. Above that, keep the stream rate under 50 Hz.

How-to

Console

Python

TypeScript

Configure and run task

import synnax as sy
from synnax import opcua

client = sy.Synnax()

# Retrieve OPC UA server device
dev = client.devices.retrieve(name="my_opc_server")

# Create index channel
data_time = client.channels.create(
    name="data_time",
    is_index=True,
    data_type=sy.DataType.TIMESTAMP,
    retrieve_if_name_exists=True,
)

# Create data channels
temp_sensor = client.channels.create(
    name="temperature",
    index=data_time.key,
    data_type=sy.DataType.FLOAT32,
    retrieve_if_name_exists=True,
)

pressure_sensor = client.channels.create(
    name="pressure",
    index=data_time.key,
    data_type=sy.DataType.FLOAT32,
    retrieve_if_name_exists=True,
)

# Create and configure task
task = opcua.ReadTask(
    name="OPC UA Read Task",
    device=dev.key,
    sample_rate=sy.Rate.HZ * 10,
    stream_rate=sy.Rate.HZ * 10,
    channels=[
        opcua.ReadChannel(
            channel=temp_sensor.key,
            node_id="ns=2;s=TemperatureSensor",
        ),
        opcua.ReadChannel(
            channel=pressure_sensor.key,
            node_id="ns=2;s=PressureSensor",
        ),
    ],
)

client.tasks.configure(task)

# Start task and read data
with task.run():
    with client.open_streamer(["temperature", "pressure"]) as streamer:
        for _ in range(10):
            frame = streamer.read()
            print(frame)

Edit task configuration

# Retrieve existing task
task = client.tasks.retrieve(name="OPC UA Read Task")
task = opcua.ReadTask(internal=task)

# Update task-level configuration
task.config.auto_start = True
task.config.stream_rate = int(sy.Rate.HZ * 5)

# Update first channel configuration
task.config.channels[0].node_id = "ns=2;s=TemperatureSensor2"

# Update second channel configuration
task.config.channels[1].node_id = "ns=2;s=PressureSensor2"

# Apply changes
client.tasks.configure(task)

Configure and run task

import { Synnax } from "@synnaxlabs/client";

const client = new Synnax();

// Retrieve OPC UA server device
const [dev] = await client.devices.retrieve({ names: ["my_opc_server"] });

// Create index channel
const dataTime = await client.channels.create(
  {
    name: "data_time",
    isIndex: true,
    dataType: "timestamp",
  },
  { retrieveIfNameExists: true },
);

// Create data channels
const tempSensor = await client.channels.create(
  {
    name: "temperature",
    index: dataTime.key,
    dataType: "float32",
  },
  { retrieveIfNameExists: true },
);

const pressureSensor = await client.channels.create(
  {
    name: "pressure",
    index: dataTime.key,
    dataType: "float32",
  },
  { retrieveIfNameExists: true },
);

// Create and configure task
const task = await client.tasks.create({
  name: "OPC UA Read Task",
  rack: dev.rack,
  type: "opc_read",
  config: {
    device: dev.key,
    sampleRate: 10,
    streamRate: 10,
    arrayMode: false,
    channels: [
      {
        channel: tempSensor.key,
        nodeId: "ns=2;s=TemperatureSensor",
      },
      {
        channel: pressureSensor.key,
        nodeId: "ns=2;s=PressureSensor",
      },
    ],
  },
});

// Start task
await task.start();

// Read data
const streamer = await client.openStreamer(["temperature", "pressure"]);
for (let i = 0; i < 10; i++) {
  const frame = await streamer.read();
  console.log(frame);
}

// Stop task
await task.stop();
await streamer.close();

Edit task configuration

import { opcua } from "@synnaxlabs/client";

// Retrieve existing task
const task = await client.tasks.retrieve({ name: "OPC UA Read Task" });

// Parse and update configuration
const config = opcua.readConfigZ.parse(task.config);

// Update task-level configuration
config.autoStart = true;
config.streamRate = 5;

// Update first channel configuration
config.channels[0].nodeId = "ns=2;s=TemperatureSensor2";

// Update second channel configuration
config.channels[1].nodeId = "ns=2;s=PressureSensor2";

// Apply changes
await client.tasks.create({
  key: task.key,
  rack: task.rack,
  name: task.name,
  type: task.type,
  config,
});

Connect to a server

Write task