OPC UA Server

Applies to ThinkLink 2.00.099 (introduced in 2.00.096). OPC UA exposes device telemetry and selected attributes to supervisory clients. Telemetry nodes are read-only; attribute writes require explicit opt-in. Configuration persistence, a running service, client read/write, and physical feedback require separate acceptance.

Enable and connect

1. Check mode and permissions: the tenant service card follows the gw / tke mode restriction; only explicit false in service_enable.OpcUaServer disables it. The role needs node-menu permission (510). Disabling stops the instance while preserving configuration and nodes; re-enabling does not start it automatically.
2. Enable device opc_ua (string "TRUE" / "FALSE") in basic information. Device templates also support it. Editing a template does not apply it to existing devices automatically; check device values after template creation/reset. If offline tracking is enabled, verify the device is online under the current rules.
3. Open Tenant Service Configuration → OPC UA Server (/tenant/am/server-config), save and click Restart to apply configuration. Check RUNNING and the actual listener; a successful save is not evidence that it is running.
4. Open Maintenance → OPC UA Node List (/tenant/om/opc-ua-node-list) to add, edit or generate nodes from a thing model. Batch deletion and Excel import/export are supported. Configuration writes affect the running instance.
5. Connect the supervisory client to opc.tcp://server-address:4840/thinklink. Defaults are port 4840 and resource path /thinklink. Check container mappings, host firewall and network reachability separately.

Only one tenant OPC UA instance runs in each backend process. Starting another tenant stops and replaces the current instance; this is not concurrent multi-tenant service hosting. One tenant's stop request cannot stop another tenant's instance. Startup waits for Worker ready and a full node sync. An unexpected exit schedules recovery after 60 seconds using saved configuration; manual stop or administrator disable cancels recovery.

Service configuration and certificates

Field	Meaning
port	Listening port, default 4840
resource_path	Resource path, default /thinklink
security_mode	None or SignAndEncrypt; encryption uses Basic256Sha256
allow_anonymous	Anonymous access; None is for isolated anonymous debugging only
username / password	Credentials dedicated to this OPC UA service; disabling anonymous access requires both credentials and encryption, not a platform token

Certificates and private keys persist under opc-ua-pki/<tenant_code>/ relative to the backend process working directory. Preserve this directory during upgrades, packaging and restarts. Encryption does not automatically trust unknown client certificates: verify each certificate, then place it in that tenant's trusted/certs through a controlled deployment. Untrusted requests appear in rejected. Clients must also trust the server certificate. Restart after certificate changes; do not put private keys in examples, repositories or public logs. Successful tenant deletion stops its Worker and removes its PKI directory.

Nodes and thing-model fields

Key node fields are below; database IDs use strings:

Field	Meaning
node_id / name	Node identifier and display name
eui	Existing device in the current tenant
data_from	telemetry_data, shared_attrs, app_attrs, server_attrs
thing_model_id	Bound thing model for telemetry; not needed for attributes
name_path	Dot-separated path, for example status.value
value_type	Boolean, Int16, UInt16, Int32, UInt32, Float, Double, String
writable	Boolean; telemetry must be false, attributes may explicitly use true
rpc_id	Optional RPC for writable attributes, authorized and bound to the device

NodeId is ns=1;s=<node_id> and the namespace URI is urn:thinklink:opc-ua:<tenant_code>. Clients should resolve the index by URI instead of relying on a hardcoded index across server configurations.

Example body to save a read-only attribute node (POST /thinklink/opc-ua-node-list/batch-save-update, JSON and token header; submission saves and syncs nodes):

{
  "dataList": [
    {
      "node_id": "test/temperature",
      "name": "Test temperature",
      "eui": "00112233",
      "data_from": "shared_attrs",
      "name_path": "opc_test",
      "value_type": "Double",
      "writable": false
    }
  ]
}

First save numeric opc_test: 25.6 in the test device's shared attributes and enable OPC UA on that device. Then save the node. For write acceptance, edit this node and explicitly enable writable. Do not use a telemetry node to control a device.

Thing-model fields are stored in opc_ua_config.field_list; a read-only temperature field is:

{
  "opc_ua_config": {
    "field_list": [
      {
        "name": "Temperature",
        "data_from": "telemetry_data",
        "name_path": "temperature",
        "value_type": "Double",
        "writable": false
      }
    ]
  }
}

Select the model in the node page and explicitly generate nodes. Only devices in the current tenant that bind the model and enable OPC UA are included; existing mappings are preserved. Without configured field_list, generation uses number/string/boolean display fields from telemetry_config.fields as read-only nodes. Editing a model never automatically overwrites the node table; review and edit existing nodes as needed. Worker sync occurs after the database transaction commits. If sync fails, configuration remains saved, the request returns an error and the service enters ERROR. Repair, restart and read back; do not assume rollback.

API entry points

All paths below have the /thinklink prefix and use the token's current tenant; a body cannot override it. Configuration reuses system-service/find-by-name and batch-save-update with service name OpcUaServer. Service-management operations are outside public user-edition API search.

Operation	POST path	Request/result notes
Start or restart	/system-service/start-opc-ua-server	Side effect; starts with saved configuration
Stop	/system-service/stop-opc-ua-server	Side effect; stops the current tenant instance
Query	/opc-ua-node-list/find-page	Filters and pagination
Save	/opc-ua-node-list/batch-save-update	dataList; an id merges an existing current-tenant record
Delete	/opc-ua-node-list/batch-delete-by-ids	ids; side effect
Generate from model	/opc-ua-node-list/add-node-by-thing-model	thingModelId; side effect
Import Excel	/opc-ua-node-list/import-excel	multipart/form-data file; writes configuration, not a JSON upload
Export Excel	/opc-ua-node-list/export-excel	Filters; XLSX binary response, not JSON

Quality codes and limits

Status	What to check
Good	Platform processing completed; not confirmation of physical device execution
BadNoData	Missing field value
BadTypeMismatch	Value does not match its declared type; no implicit string/boolean/number coercion
BadOutOfService	OPC UA disabled on the device, device missing, or offline while offline tracking is enabled
BadNotWritable	Writing to a read-only node
BadNodeIdUnknown	Deleted node or unknown NodeId

Only the eight scalar types above are supported. Arrays, structures, historical reads, events, and method calls are unsupported. Telemetry timestamps use model update_time; attributes use config_update_time, with Worker processing time as fallback.

Attribute writes validate the current mapping revision, type, device switch and RPC permission/binding. They preserve other attribute-tree fields, update configuration time and enter the persistence buffer before forwarding and optional RPC execution. A later forwarding or RPC error does not roll back the attribute. The Worker waits up to 15 seconds; timeout after execution starts does not mean rollback. Check attributes, RPC logs and device feedback before retrying.

Deployment and acceptance

The target runtime requires Node.js ≥22.13.0. Deploy the complete backend package containing work-thread/opc-ua-server.js, node-opcua runtime dependencies and nodeset/certificate resources; the Worker file alone is insufficient. 2.00.099 retains the complete packaging workflow introduced in 2.00.098. Preserve PKI, configuration, original packages and database backups, and run the full official migration sequence from the actual database version. Migration 2.00.096 adds nodes, device/template switches and model configuration, but is not the only required migration.

In a test environment verify start/stop and port-change restart, read-only rejection, attribute writing with sibling preservation, wrong types, missing values, offline/disabled devices, node deletion, model generation, Excel round trip, mutual certificate trust, correct/incorrect passwords, tenant switching and instance replacement. Record attribute readback, RPC logs, physical feedback, client brand/version and security mode.

This documentation's local build and static example checks do not establish real database migration, deployed services, browser interaction, or client/physical-device acceptance. See the 2.00.099 upgrade guide.