OPC UA Server

OPC UA (Open Platform Communications Unified Architecture) is an industrial communication protocol for exchanging data between devices, PLCs, and SCADA systems. The OPC UA Server is an edge container service that publishes tags on the device so industrial clients can read inference results and write values back.

You define the tags, folders, and server settings from the Deployment Manager Configuration tab, then point your OPC UA client at the device.

Connection Details

Replace <device-ip> with the IP address shown on the device page in Deployment Manager.

Configuration Source

The "Configuration Source" toggle at the top of the Configure modal controls where the tag and folder configuration comes from. Only one source is ever active on the device at a time.

In "File" mode the server validates at startup that the file exists, is readable, and is not empty, and fails to start with an explicit log entry if any of that is untrue. OPCUA_CONFIG_FILE takes precedence over OPCUA_CONFIG.

Switching sources keeps both the inline values and the file path while the modal is open. On save, the source you did not pick is cleared, so exactly one of the two variables is set. In "File" mode the service card shows the configured file path in place of the inline tag list.

Server Settings

Every client holds one session, including each inference pod writing tags and each SCADA connection. A session belonging to a client that crashed is only released when the server times it out, so a busy site can hold more sessions than it has live clients. Once the cap is reached, further clients are refused with BadTooManySessions and their tags stop updating. Raise the value if a site runs more concurrent clients than the default. Setting it in the modal writes it into the server config, and OPCUA_MAX_SESSIONS can override it per device for hand-managed deployments.

Folders and Tags

Folders organize tags into a hierarchy. Each folder has a name and an optional description, and appears as a node in the OPC UA address space so clients can browse and discover tags. A tag can belong to a folder or sit at the root level.

Tags define the data points the server exposes. Each tag has these fields:

Data Types

These are the types the Configure modal offers. A hand-written configuration file may also use Int16, UInt16, and UInt32, which the server accepts.

Access Levels

ReadWrite tags can be read and written by OPC UA clients as well as the REST API, CLI, and web UI. Use them for control outputs, setpoints, and user-adjustable values.

ReadOnly tags reject OPC UA client writes with BadNotWritable. The REST API, CLI, and web UI can still update the value regardless of access level, so use ReadOnly for sensor values, calculated outputs, and system status that only the device should produce.

Optional Constraints

Numeric types support "Min Value" and "Max Value" to restrict the allowed range, plus "Engineering Units" for a descriptive unit label (ex: °C, PSI, RPM). String types support "Max Length" to cap the character count.

Authentication

The server allows anonymous connections by default, using SecurityPolicy None. Turn on "Require authentication" in the Configure modal to require a username and password from every client.

When the toggle is on you must supply both a username and a password. The password is hashed with bcrypt before it is stored, so the original is never saved and cannot be retrieved later. To change the password on an existing server, enter a new one in the Configure modal, or leave the field blank to keep the current password. Turning the toggle off restores anonymous access.

The credentials are stored as two environment variables, which must be set together or both left unset:

Tag Reporting

The server can report its tags to Roboflow on a schedule, so you can see what it serves without a site visit. Set this in the "Tag Reporting" section of the Configure modal.

The settings are stored as environment variables, which the server reads at startup:

A value the server does not accept turns reporting off rather than falling back to the default, so a typo stops reports. The device page shows such a device as not reporting.

If any of these variables is set by reference ({$ref}), the modal cannot edit reporting and leaves it as it is on save. Replace the reference with a literal value to manage reporting from the form.

Monitoring

The device page shows a live OPC UA status card with the connected client count, sessions in use against "Max Sessions", and the latest tag report. A device on an image older than tag reporting says so in place of the report.

When the server hits the session cap and refuses new clients, the card shows a banner with the session count, the cap, and how many clients were refused. To get an email about it, add an "OPC UA Refusing Clients" alert from the device's "Device Alerts" tab and set how many minutes of refusals to allow first. See Set up Device Alerts.

Web Interface

The server hosts a web interface at http://<device-ip>:8092.

HTTP API

The REST API gives programmatic access to tag values and server information. All endpoints return JSON. The base URL is http://<device-ip>:8092/api. See Services for the rules shared by all on-device service APIs.

Tag structure is immutable at runtime. Tags and folders come from the OPCUA_CONFIG environment variable, or the file named by OPCUA_CONFIG_FILE for large configurations, and cannot be created, changed, or deleted through this API. Only values can be written.

Read and Write Tag Values

accessLevel governs the OPC UA protocol, not this API. A tag marked ReadOnly rejects writes from OPC UA clients with BadNotWritable but remains writable here, which is how a pipeline publishes a sensor value that industrial clients should only consume.

curl http://<device-ip>:8092/api/tags

curl -X PUT http://<device-ip>:8092/api/tags/tag_temperature/value \
  -H "Content-Type: application/json" \
  -d '{"value": 25.5}'

GET /tags HTTP/1.1
Host: device-ip:8092
Accept: application/json

curl -L \
  --request GET \
  --url 'http://device-ip:8092/api/tags' \
  --header 'Accept: application/json'

const response = await fetch("http://device-ip:8092/api/tags", {
  method: "GET",
  headers: {
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "http://device-ip:8092/api/tags"
headers = {
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

{
  "tags": [
    {
      "id": "text",
      "nodeId": "text",
      "displayName": "text",
      "dataType": "Boolean",
      "accessLevel": "ReadOnly",
      "currentValue": true,
      "lastUpdated": "text",
      "folder": "text"
    }
  ]
}

GET /tags/{id} HTTP/1.1
Host: device-ip:8092
Accept: application/json

curl -L \
  --request GET \
  --url 'http://device-ip:8092/api/tags/{id}' \
  --header 'Accept: application/json'

const response = await fetch("http://device-ip:8092/api/tags/{id}", {
  method: "GET",
  headers: {
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "http://device-ip:8092/api/tags/{id}"
headers = {
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

{
  "tag": {
    "id": "text",
    "nodeId": "text",
    "displayName": "text",
    "dataType": "Boolean",
    "accessLevel": "ReadOnly",
    "currentValue": true,
    "lastUpdated": "text",
    "folder": "text"
  }
}

{
  "error": "text"
}

PUT /tags/{id}/value HTTP/1.1
Host: device-ip:8092
Content-Type: application/json
Accept: application/json

{
  "value": true
}

curl -L \
  --request PUT \
  --url 'http://device-ip:8092/api/tags/{id}/value' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "value": true
}'

const response = await fetch("http://device-ip:8092/api/tags/{id}/value", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    "value": true
  })
});

const data = await response.json();
console.log(data);

import requests

url = "http://device-ip:8092/api/tags/{id}/value"
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
  "value": True
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

{
  "tag": {
    "id": "text",
    "nodeId": "text",
    "displayName": "text",
    "dataType": "Boolean",
    "accessLevel": "ReadOnly",
    "currentValue": true,
    "lastUpdated": "text",
    "folder": "text"
  }
}

{
  "error": "Missing \"value\" in request body"
}

A write is rejected with 400 when the value is missing, the type does not match the tag's dataType, or it falls outside a configured minValue, maxValue, or maxLength. Writing to a tag that does not exist also returns 400, not 404. GET /tags/{id} does return 404, so use it if you need to distinguish an unknown tag from a bad value.

Configuration Endpoints

Read-only views of the running configuration, useful for discovering tag IDs and their constraints before writing.

GET /config HTTP/1.1
Host: device-ip:8092
Accept: application/json

curl -L \
  --request GET \
  --url 'http://device-ip:8092/api/config' \
  --header 'Accept: application/json'

const response = await fetch("http://device-ip:8092/api/config", {
  method: "GET",
  headers: {
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "http://device-ip:8092/api/config"
headers = {
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

{
  "version": 1,
  "server": {
    "port": 1,
    "namespace": "text",
    "serverName": "text",
    "maxSessions": 1
  },
  "folders": [
    {
      "id": "text",
      "name": "text",
      "description": "text"
    }
  ],
  "tags": [
    {
      "id": "text",
      "nodeId": "text",
      "browseName": "text",
      "displayName": "text",
      "description": "text",
      "dataType": "Boolean",
      "folderId": "text",
      "accessLevel": "ReadOnly",
      "initialValue": true,
      "engineeringUnits": "text",
      "minValue": 1,
      "maxValue": 1,
      "maxLength": 1
    }
  ]
}

GET /config/folders HTTP/1.1
Host: device-ip:8092
Accept: application/json

curl -L \
  --request GET \
  --url 'http://device-ip:8092/api/config/folders' \
  --header 'Accept: application/json'

const response = await fetch("http://device-ip:8092/api/config/folders", {
  method: "GET",
  headers: {
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "http://device-ip:8092/api/config/folders"
headers = {
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

{
  "folders": [
    {
      "id": "text",
      "name": "text",
      "description": "text"
    }
  ]
}

Sessions and Health

Once maxSessions is reached, further clients are refused with BadTooManySessions, so compare sessionCount against maxSessions for headroom.

A 200 from /subscriptions with a zeroed session list and maxSessions omitted means the OPC UA server is not running. Treat it as an outage rather than a warm-up: if the endpoint answers at all, startup has already finished or failed. Confirm with /health, which reports status: "unhealthy" and opcuaServer: "stopped".

maxSessions is omitted rather than zeroed in that case so a consumer computing maxSessions - sessionCount does not read an unknown cap as a full one.

GET /subscriptions HTTP/1.1
Host: device-ip:8092
Accept: application/json

curl -L \
  --request GET \
  --url 'http://device-ip:8092/api/subscriptions' \
  --header 'Accept: application/json'

const response = await fetch("http://device-ip:8092/api/subscriptions", {
  method: "GET",
  headers: {
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "http://device-ip:8092/api/subscriptions"
headers = {
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

{
  "sessionCount": 1,
  "maxSessions": 1,
  "subscriptionCount": 1,
  "sessions": [
    {
      "sessionId": "text",
      "sessionName": "text",
      "clientDescription": "text",
      "connectedAt": "text",
      "lastContactTime": "text",
      "subscriptionCount": 1,
      "subscriptions": [
        {
          "subscriptionId": 1,
          "publishingInterval": 1,
          "monitoredItemCount": 1,
          "monitoredItems": [
            {
              "nodeId": "text",
              "displayName": "text",
              "samplingInterval": 1
            }
          ]
        }
      ]
    }
  ]
}

/health returns 200 whether or not the OPC UA server is running. Check status and opcuaServer rather than the status code.

GET /health HTTP/1.1
Host: device-ip:8092
Accept: application/json

curl -L \
  --request GET \
  --url 'http://device-ip:8092/api/health' \
  --header 'Accept: application/json'

const response = await fetch("http://device-ip:8092/api/health", {
  method: "GET",
  headers: {
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "http://device-ip:8092/api/health"
headers = {
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

{
  "status": "healthy",
  "opcuaServer": "running",
  "uptime": 3600,
  "tagCount": 5
}

CLI

The opcua-cli tool gives terminal access to the server for debugging, scripting, and quick tag operations when the web UI is not reachable.

docker exec -it opcua-server opcua-cli

docker exec opcua-server opcua-cli <command>

docker exec opcua-server opcua-cli read Temperature
docker exec opcua-server opcua-cli write Temperature 25.5
docker exec opcua-server opcua-cli clients --detailed

Logging

Set LOG_LEVEL on the service to control verbosity. See Update Device Configuration for where to edit service environment variables, and View Device Logs for reading the output.

Values are case-insensitive, and an unrecognized value falls back to INFO.