Skip to main content

OPC UA Client

Purpose​

The OPC UA Client connects to an OPC UA server, browses nodes, reads values, and optionally creates subscriptions for data changes.

Open the plugin​

Open Development Configuration → Collection Configuration, create a device, and select OPC UA Client.

This plugin manages its connection in the device properties and does not use an ordinary TCP, UDP, or serial channel. Configure common variables through Collection Configuration.

Plugin properties​

Connection and authentication​

SettingDescription
Connection URLDefault opc.tcp://127.0.0.1:49320. Enter the OPC UA server endpoint.
UsernameUsername required by the OPC UA server. Leave empty when the endpoint allows anonymous access.
PasswordPassword for the OPC UA user. Do not expose it in screenshots or logs.
Security policyEnables a secure OPC UA endpoint according to the server policy.
Accept untrusted certificateTemporary commissioning option. In production, configure the trust chain instead.
Client certificateClient certificate selected from Certificate Management. Required by the endpoint's security policy.

Subscription​

SettingDescription
Data-change triggerSelects which OPC UA data changes trigger a notification. Keep the server's required mode.
Activate subscriptionEnables subscription updates. Disable only when the project uses polling.

Protocol and data format​

SettingDescription
Application nameDefault ThingsGateway_OPC_UA_Master. The OPC UA application identity shown to the server.
Load server data typesLoads the server's node data types so variables can use the correct runtime type.
Use SourceTimeUses the source timestamp supplied by the OPC UA server when enabled.

Runtime and grouping​

SettingDescription
Update rateDefault 1000 ms. Polling or subscription update rate used by the plugin.
Keep-alive rateDefault 3000 ms. Interval used to check the OPC UA session.
DeadbandDefault 0. Variable-level deadband for subscription changes.
Maximum group sizeDefault 500. Maximum nodes grouped in one read or subscription operation.

Data-change trigger options are Status, StatusValue, and StatusValueTimestamp: trigger on status changes, status-or-value changes, or status/value/timestamp changes. Choose the last option when a timestamp-only change must be reported.

Address rule​

Regular variables​

Use the OPC UA NodeId as the address of a regular collection variable, for example ns=2;s=Channel1.Temperature. Browse and read the node in device debug first, then copy the complete namespace and identifier.

OPC UA method variables​

To let an external system call a method on the OPC UA server, create a dedicated variable under the OPC UA device and configure it as follows.

SettingRequired value
Variable nameUse a name that identifies the action, such as Start method or Recipe switch method. External RPC requests use this name to locate the method variable.
Other MethodSelect CallMethodByNodeIdAsync, currently displayed as 调用 OPC UA 方法 in the plugin method list.
Variable addressEnter a standard JSON array containing the object and method NodeIds, for example ["ns=2;s=Machine1","ns=2;s=Machine1.Start"]. The first element must be the object that provides the method; the second must be the method node.
Read/Write PermissionSelect Write Only. A control method must not enter periodic collection, which could trigger it repeatedly.
RPC Write EnableEnable it. Web API, MQTT, and other external entries reject the call when this permission is disabled.
Write CheckDisable it. A method call is not a readable point; verify it from the RPC result and device state.

After saving the variable, provide the external RPC value in the same order as the OPC UA method's InputArguments. The outer JSON array is the argument list.

Method inputsRPC variable value
No input arguments[]
One scalar argument[123]
Two arguments[123, "start"]
One array argument[[1, 2, 3]]

The client reads the standard InputArguments metadata from the server and converts each JSON value to the declared OPC UA data type. All output arguments are returned in order as a JSON array; a method without outputs returns an empty array.

Remote-control safety

Bind method variables only to control methods approved for the site. Grant the integration account only the required variable-write permission, and commission the call with an object and parameters that cannot affect production.

External RPC call​

Web API​

Call /api/gatewaywritevariablecontroller/setvariablevalue. Organize the request as device name → method variable name → input argument array:

{
  "OPC device": {
    "Start method": [123, "start"]
  }
}

The gateway checks that the variable exists, is writable, allows RPC writing, and does not belong to a paused device before calling the OPC UA method. The variable result's Content contains the server output-argument array. For a failed call, inspect ErrorMessage, the RPC log, and the device log.

MQTT and other entries​

MQTT RPC and every other entry connected to the variable RPC service use the same method variable. After the target RPC topic or script resolves the device name, variable name, and JSON argument array, it invokes the same OPC UA method. See Reverse RPC for topic, authentication, and response rules.

Functions​

FunctionPurpose
Browse nodesBrowse the OPC UA namespace and inspect NodeId, data type, value, status, and timestamp.
Read and write nodesRead one selected node; write only to a server-approved test node.
Export and importExport selected nodes to a variable file or import them into the current device.
Subscription managementCreate, inspect, or cancel subscriptions for selected NodeIds.

Device debug​

Open Development Configuration → Collection Configuration, select the OPC UA device, and click More Functions, then open Debug.

OPC UA client protocol panel​

OPC UA Client protocol debug panel

Browse the server namespace, select a node, and read it before importing variables. Use write operations only for approved writable nodes.

Debug checklist​

  1. Confirm the endpoint URL and security mode.
  2. Browse the namespace and copy the exact NodeId.
  3. Read one node and compare its value and data type with the server tool.
  4. Create a subscription only after single-node reading works.

Verify the configuration​

  1. Browse to a known NodeId and read it. Confirm that the status code is good.
  2. Change the approved test node on the server and confirm that the read result or subscription value updates.
  3. Import a small set of test nodes and check NodeId, data type, value, and timestamp.
  4. When subscriptions are enabled, confirm the update rate, data-change trigger, deadband, and group size.
  5. Write only to a server-approved test node, then read it again.
  6. Call a non-production test method first and verify the object NodeId, method NodeId, and input-argument count.
  7. Invoke the method once from the variable write dialog and once from the intended external RPC entry. Compare the output arguments, RPC log, and server-side result.

Troubleshooting​

SymptomCheck
Cannot connectEndpoint URL, server availability, firewall, security policy, certificate trust, and username/password.
Certificate rejectedClient certificate, server certificate trust, application name, and whether untrusted certificates are allowed for commissioning.
Browse returns no nodesSession security, user permissions, namespace selection, and the starting NodeId.
Read returns an errorExact NodeId spelling, namespace index, node access permission, and server data type.
Subscription does not updateActivate subscription, data-change trigger, deadband, update rate, and server subscription limits.
Value type is wrongEnable Load server data types and compare the variable data type with the OPC UA node type.
CallMethodByNodeIdAsync is missingConfirm that the device uses the current OPC UA Client plugin and restart GatewayRuntime after updating the application.
Input-argument count is invalidThe outer RPC array is the argument list. For one array argument, use a nested array such as [[1, 2, 3]].
Input type does not matchCompare the payload with the method's InputArguments data types and value ranks, and confirm that the server publishes the standard metadata.
Method is invalid or not executableCheck that the object owns the method, the OPC UA user can execute it, and the method is executable.
Method runs repeatedlySet the method variable to Write only so periodic collection cannot invoke it.
External RPC is rejectedEnable RPC writing on the method variable, confirm that the device is not paused, and grant the integration account variable-write permission.