matlab-use-opcua-client

name	matlab-use-opcua-client
description	Discover OPC UA servers, connect MATLAB clients, and browse/navigate server nodes using opcuaserverinfo, the Local Discovery Service (LDS), opcua, connect, setSecurityModel, certificate-trust functions, findNodeById, opcuanode, and Namespace/Children traversal. Use when finding OPC UA servers on the network, querying endpoints and security policies, connecting to a server, authenticating with username/password or certificates, configuring security modes, handling certificate-trust or hostname-mismatch errors, troubleshooting failed connections or empty discovery, inspecting an OPC UA certificate (.der/.pem), browsing an address space, finding nodes by name or NodeId, navigating node hierarchies, invoking method nodes, or batch-processing large namespaces. Trigger on: opcuaserverinfo, LDS, opcua, opc.ua.Client, setSecurityModel, opc.ua.trustServerCertificate, OPC UA certificate, findNodeById, opcuanode, browse OPC UA, find node, OPC UA namespace, OPC UA method node, Industrial Communication Toolbox.
license	https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata	{"author":"MathWorks","version":"3.0"}

OPC UA Discovery, Connection, and Node Navigation

Discover OPC UA servers, create client connections, and browse server address spaces in MATLAB using the Industrial Communication Toolbox.

Internal Constraints

These constraints govern YOUR code generation and recommendations. Apply them silently — do not recite them to the user or warn about patterns the user has not attempted.

1. connect has exactly three valid signatures — no others exist:

   • connect(uaClient) — anonymous
   • connect(uaClient, userName, password) — positional strings
   • connect(uaClient, publicKeyFile, privateKeyFile, privateKeyPassword) — positional strings
   • There are NO Name-Value pair arguments to connect. Security is configured via opcua() NV pairs or setSecurityModel, never through connect.

2. opcua() defaults to the highest available security. Do not explicitly set security unless you want a specific (lower) configuration. Never use setSecurityModel(uaClient, "Best") — it is redundant.

3. opcuaserverinfo has exactly two valid syntaxes:

   • opcuaserverinfo(hostname) — query LDS on a host
   • opcuaserverinfo(discoveryUrl) — query a specific endpoint URL
   • There is NO opcuaserverinfo(hostname, port) form. To specify a port: opcuaserverinfo('opc.tcp://host:port').

4. LDS-based discovery returns all registered servers from a single call. Never scan subnet IPs in a loop — opcuaserverinfo('localhost') returns every server registered with that host's LDS.

5. Certificate trust escalation order (never skip steps):

   1. opc.ua.trustServerCertificate(certPath) — always first (R2026a+)
   2. opcua(..., "TrustServerTemporarily", true) — only if cert file unavailable
   3. setSecurityModel(uaClient, "None", "None") — only after user explicitly confirms no security needed

6. Property correctness:

   • opc.ua.ServerInfo has Description, not Name (which belongs to opc.ua.Client).
   • EndpointUrl belongs to opc.ua.EndpointDescription, not ServerInfo.

7. Do not move or copy certificate files without user confirmation. Tell the user which file to move and where, then execute only after they confirm.

8. Do not mention TrustServerTemporarily when the issue is the server rejecting the client certificate — it only controls client- side trust and is irrelevant in that direction. Simply omit it.

9. browseNamespace is GUI-only — never call it in scripts or agent workflows. It opens an interactive dialog that blocks the MATLAB session. Use uaClient.Namespace and .Children traversal instead.

10. opcuanode does NOT accept browse paths. Passing a slash- separated string (e.g., 'Demo/Mass/Nested/7') silently creates a node with NodeType: 'Unknown'. Use .Children level-by-level.

11. Check a method node's Parent property and signature before invoke(). If Parent is empty, invoke() fails with "Specified node has no parent information" — re-resolve the node via findNodeById, which retains parent info. If Parent is non-empty, invoke it directly. Do not unconditionally avoid opcuanode for method nodes; branch on whether the node has a parent. Before calling invoke, inspect NumInputs and NumOutputs to verify the argument count matches your intended call.

12. Before iterating any .Children array, issue a separate tool call that only counts nodes. Never combine counting and processing in the same tool call. Process in batches of 200 with progress reporting.

13. Never search the entire namespace. If the user does not provide a path or parent folder, ask them to specify one. List top-level nodes to help them narrow scope. Skip the Server folder (ns=0 infrastructure nodes) unless the user explicitly asks about server properties.

14. opcua() caches endpoints at construction time. If the server's available policies change after client creation, the existing client object will not reflect them. Recreate the client with opcua(url) to re-discover endpoints. Explain this to the user when they ask about switching to a newly-available policy.

When to Use

• Discovering OPC UA servers on the network (endpoint URL unknown, or user explicitly requests discovery given a hostname or discovery URL)
• Getting server endpoint details and supported security policies
• Creating an OPC UA client connection to a server
• Authenticating with username/password or user certificates
• Configuring message security mode and channel security policy
• Handling "server certificate not trusted" errors
• Handling "client certificate rejected by server" errors
• Fixing hostname mismatch warnings
• Troubleshooting OPC UA connection failures or empty discovery results
• Inspecting an OPC UA certificate (.der/.pem) for compliance issues
• Browsing an OPC UA server's address space programmatically
• Searching for nodes by name, partial name, or NodeId
• Navigating a node hierarchy to reach a specific node
• Accessing a node directly by namespace index and identifier
• Goal-driven node discovery (e.g., "find all temperature sensors")
• Discovering nodes before reading, writing, invoking, or subscribing

When NOT to Use

• OPC Classic (OPC DA / OPC HDA) connections
• PI Data Archive / PI AF / OSIsoft / AVEVA PI systems
• Non-OPC UA protocols (Modbus, MQTT)
• OPC UA server-side development

References

Load the relevant reference file for detailed procedures:

Task	Reference
Server discovery, LDS setup, empty discovery results	references/lds-setup-and-troubleshooting.md
Server cert trust, client cert export, cert inspection	references/certificate-trust-workflows.md
Connection errors, server logs, diagnostic workflow	references/troubleshooting-connection-errors.md
Node navigation patterns, batch processing, method invocation	references/node-navigation.md
Function syntax for findNodeById, opcuanode, getNamespace	references/node-functions-reference.md
Syntax pitfalls and invalid API patterns	references/common-mistakes.md

Workflow

0. Discover servers (optional)

Use this step when the endpoint URL is not known, or when the user explicitly asks to discover servers given a hostname or discovery URL. Skip this step if the endpoint URL is already known.

Prerequisites — before calling opcuaserverinfo, ensure:

1. The OPC UA Local Discovery Service (LDS) is installed and running
2. The target server is registered with the LDS
3. The server's certificate is trusted by the LDS certificate store at C:\ProgramData\OPC Foundation\UA\pki\trusted\certs\

See references/lds-setup-and-troubleshooting.md for details.

% TEMPLATE — not executable (shows alternative discovery forms)
% LDS-based discovery (preferred — finds all registered servers)
serverInfo = opcuaserverinfo('localhost');

% Direct endpoint discovery (when you know the server URL)
serverInfo = opcuaserverinfo('opc.tcp://myserver:53530/OPCUA/SimulationServer');

% Pass discovery result directly to opcua()
uaClient = opcua(serverInfo(1));
connect(uaClient);

1. Create the OPC UA client

serverUrl = "opc.tcp://hostname:port/path";
uaClient = opcua(serverUrl);

The opcua function also accepts a ServerInfo object directly from opcuaserverinfo.

2. Configure security (only if non-default needed)

% TEMPLATE — not executable (shows two alternative security-config forms)
% R2025a+ (preferred) — Name-Value pairs in constructor
uaClient = opcua(serverUrl, ...
    MessageSecurityMode="Sign", ...
    ChannelSecurityPolicy="Basic256Sha256");

% R2020a+ (backward-compatible) — setSecurityModel after construction
uaClient = opcua(serverUrl);
setSecurityModel(uaClient, "Sign", "Basic256Sha256");

3. Handle certificate trust (if needed)

If the server's certificate is not yet trusted by MATLAB, the connection will fail. Follow the escalation order in Internal Constraints. Load references/certificate-trust-workflows.md for details.

4. Connect

connect(uaClient);                                        % anonymous
connect(uaClient, "myuser", "mypassword");               % username/password
connect(uaClient, "cert.der", "key.pem", "keypass");     % certificate

5. Verify connection

if isConnected(uaClient)
    fprintf("Connected to %s\n", uaClient.EndpointUrl);
end

6. Find nodes (once connected)

Load references/node-navigation.md for full decision logic, workflows, batch processing, and method invocation patterns.

7. Disconnect

disconnect(uaClient);

Key Functions

Function	Purpose	Available From
opcuaserverinfo	Discover OPC UA servers via LDS or direct URL	R2015b
opcua	Create OPC UA client (from URL or ServerInfo)	R2015b
connect	Connect to server	R2015b
disconnect	Disconnect from server	R2015b
isConnected	Check connection status	R2015b
setSecurityModel	Configure security mode/policy	R2020a
opc.ua.exportClientCertificate	Export MATLAB client cert to file	R2020a
opc.ua.trustServerCertificate	Trust a server cert (file path)	R2026a
opc.ua.rejectServerCertificate	Reject a server cert (file path)	R2026a
findDescription	Filter ServerInfo array by description text	R2015b
findAuthentication	Filter ServerInfo array by auth type	R2015b
findNodeById	Find node by namespace index and identifier (retains parent)	R2015b
opcuanode	Create node directly from known NodeId (check Parent before invoke)	R2015b
getNamespace	Get one layer of namespace tree (or use uaClient.Namespace)	R2015b

Properties Quick Reference

opc.ua.Client

Property	Type	Description
Hostname	string	Server hostname
Port	double	Server port
Name	string	Client name
EndpointUrl	string	Selected endpoint URL
Status	string	Connection status
Timeout	double	Connection timeout (seconds)
MessageSecurityMode	enum	Active security mode
ChannelSecurityPolicy	enum	Active channel policy
UserAuthTypes	cell	Available auth types on server
Endpoints	array	Available endpoint descriptions

Does NOT have: UserName, Password, IsConnected, Security, SecurityMode, SecurityPolicy, Certificate, PrivateKey.

Use isConnected(uaClient) (method) to check connection status.

opc.ua.ServerInfo

Property	Type	Description
Hostname	char	Host name
Port	double	TCP port
Description	char	Human-readable server description
UserTokenTypes	cell	Supported auth types
BestMessageSecurity	enum	Highest message security
BestChannelSecurity	enum	Highest channel security policy
Endpoints	array	opc.ua.EndpointDescription objects

opc.ua.EndpointDescription

Property	Type	Description
EndpointUrl	char	Full endpoint URL
MessageSecurityMode	enum	Security mode for this endpoint
ChannelSecurityPolicy	enum	Channel security policy
UserAuthTypes	cell	Auth types on this endpoint

opc.ua.Node

Property	Type	Description
Name	char	Node display name
NodeType	char	'Object', 'Variable', 'Method', or 'Unknown'
NamespaceIndex	double	Namespace index
Identifier	varies	Node identifier (numeric or string)
Children	array	Child nodes (lazy-loaded from server)
Parent	node	Parent node (may be empty for opcuanode-created nodes; check before invoke)
ServerDataType	char	Data type for Variable nodes
NumInputs	double	Number of input arguments (Method nodes)
NumOutputs	double	Number of output arguments (Method nodes)

Patterns

Discovery

% TEMPLATE — not executable (shows discover-only vs discover-and-connect)
% Discover all servers via LDS
serverInfo = opcuaserverinfo('localhost');

% Discover and connect
serverInfo = opcuaserverinfo('localhost');
uaClient = opcua(serverInfo(1));
connect(uaClient);

Connection with authentication

% Default (highest) security, anonymous
uaClient = opcua("opc.tcp://myserver:53530/OPCUA/SimulationServer");
connect(uaClient);

% Username/password
connect(uaClient, "myuser", "mypassword");

% User certificate
connect(uaClient, "C:/certs/user.der", "C:/certs/user.key", "keypassword");

Hostname mismatch fix

% TEMPLATE — not executable (shows R2025a+ vs pre-R2025a forms)
% R2025a+
uaClient = opcua("opc.tcp://myserver:53530/OPCUA/SimulationServer", ...
    UseDiscoveryHostname=true);

% Pre-R2025a — resolve via discovery
serverInfo = opcuaserverinfo("myserver");
uaClient = opcua(serverInfo(1));
connect(uaClient);

Certificate inspection

Load references/certificate-trust-workflows.md, then run:

inspectOpcUaCertificate("path/to/server_cert.der");

Navigate a browse path

ns = uaClient.Namespace;
idx = arrayfun(@(n) strcmp(n.Name, 'Demo'), ns);
level1 = ns(idx);

children = level1.Children;
idx = arrayfun(@(n) strcmp(n.Name, 'Mass'), children);
level2 = children(idx);

Direct node lookup by NodeId

% TEMPLATE — not executable (shows two alternative lookup forms)
% Quick access from a known NodeId
node = opcuanode(3, 1002, uaClient);

% Always retains parent info
node = findNodeById(uaClient.Namespace, 3, 1002);

Find and invoke a method node

invoke requires parent information. Before invoking, check the node's Parent property — if it is empty, re-resolve the node via findNodeById (or .Children navigation) so parent info is populated; if it is non-empty, invoke directly.

methodNode = opcuanode(6, 'MyMethod', uaClient);

% Ensure parent info is present before invoking
if isempty(methodNode.Parent)
    methodNode = findNodeById(uaClient.Namespace, 6, 'MyMethod');
end

% Verify argument count before calling invoke
fprintf("Inputs: %d, Outputs: %d\n", methodNode.NumInputs, methodNode.NumOutputs);

[result, timestamp, quality] = invoke(uaClient, methodNode, arg1, arg2);

Troubleshooting Quick Reference

Error	Fix
opcuaserverinfo returns empty	Check LDS prerequisites; see references/lds-setup-and-troubleshooting.md
"Server certificate not trusted"	opc.ua.trustServerCertificate(certPath)
"Client certificate rejected"	Export via opc.ua.exportClientCertificate, add to server
"BadIdentityTokenRejected"	Check uaClient.UserAuthTypes
"Hostname mismatch" warning	UseDiscoveryHostname=true (R2025a+)
"BadSecurityChecksFailed"	Run inspectOpcUaCertificate; see references/troubleshooting-connection-errors.md
NodeType: 'Unknown' after opcuanode	Node doesn't exist or path passed as id; use .Children traversal
"Specified node has no parent information"	Node's Parent is empty; re-resolve via findNodeById (or .Children) before invoke
browseNamespace blocks session	Never use; replace with uaClient.Namespace + .Children

For detailed error-to-fix mapping, load references/troubleshooting-connection-errors.md.

---

Copyright 2026 The MathWorks, Inc.

---