matlab-connect-opcua-client

OPC UA 客户端连接

使用 Industrial Communication Toolbox 在 MATLAB 中创建和配置 OPC UA 客户端连接。

内部约束

这些约束适用于你的代码生成和建议。 请默默遵守——不要向用户复述，也不要警告用户尚未尝试过的模式。

1. connect 恰好有三种有效签名，不存在其他形式：

   • connect(uaClient) — 匿名
   • connect(uaClient, userName, password) — 位置字符串参数
   • connect(uaClient, publicKeyFile, privateKeyFile, privateKeyPassword) — 位置字符串参数
   • connect 不接受名称-值对参数。安全性通过 opcua() 名称-值对或 setSecurityModel 配置，绝不能通过 connect 配置。

2. opcua() 默认采用最高级别的可用安全性。 除非你需要特定（较低级别的）配置，否则不要显式设置安全性。绝不要使用 setSecurityModel(uaClient, "Best")——这是多余的。

3. opcuaserverinfo 恰好有两种有效语法：

   • opcuaserverinfo(hostname) — 查询主机上的 LDS
   • opcuaserverinfo(discoveryUrl) — 查询指定的端点 URL
   • 不存在 opcuaserverinfo(hostname, port) 形式。要指定端口，请使用：opcuaserverinfo('opc.tcp://host:port')。

4. 基于 LDS 的发现会在一次调用中返回所有已注册的服务。 绝不要循环扫描子网 IP——opcuaserverinfo('localhost') 会返回在该主机的 LDS 上注册的所有服务。

5. 证书信任升级顺序（绝不要跳过步骤）：

   1. opc.ua.trustServerCertificate(certPath) — 始终优先使用（R2026a+）
   2. opcua(..., "TrustServerTemporarily", true) — 仅当无法获取证书文件时使用
   3. setSecurityModel(uaClient, "None", "None") — 仅在用户明确确认不需要安全性后使用

6. 属性正确性：

   • opc.ua.ServerInfo 有 Description 属性，没有 Name 属性（Name 属于 opc.ua.Client）。
   • EndpointUrl 属于 opc.ua.EndpointDescription，不属于 ServerInfo。

7. 未经用户确认，不要移动或复制证书文件。 告知用户要移动哪个文件以及移动到哪里，然后仅在用户确认后执行。

8. 如果问题是服务器拒绝客户端证书，不要提及 TrustServerTemporarily——它只控制客户端侧信任，与该方向的问题无关。直接省略即可。

适用场景

• 在网络上发现 OPC UA 服务（端点 URL 未知，或用户明确要求根据主机名或发现 URL 进行发现）
• 获取服务端点详情和支持的安全策略
• 创建到服务的 OPC UA 客户端连接
• 使用用户名/密码或用户证书进行身份验证
• 配置消息安全模式和通道安全策略
• 处理“服务器证书不受信任”错误
• 处理“客户端证书被服务器拒绝”错误
• 修复主机名不匹配警告
• 排查 OPC UA 连接失败或发现结果为空的问题
• 检查 OPC UA 证书（.der/.pem）是否存在合规性问题

不适用场景

• 浏览 OPC UA 服务的命名空间或节点
• 读取、写入或订阅 OPC UA 节点值
• 使用 OPC Classic（DA/HDA）连接
• 使用非 OPC UA 协议（Modbus、MQTT）
• OPC UA 服务端开发

参考资料

如需了解详细流程，请加载相关参考文件：

任务	参考资料
服务器发现、LDS 设置、发现结果为空	references/lds-setup-and-troubleshooting.md
服务器证书信任、客户端证书导出、证书检查	references/certificate-trust-workflows.md
连接错误、服务器日志、诊断工作流	references/troubleshooting-connection-errors.md
语法陷阱和无效 API 模式	references/common-mistakes.md

工作流

0. 发现服务器（可选）

当端点 URL 未知，或用户明确要求根据主机名或发现 URL 发现服务器时，使用此步骤。 如果端点 URL 已知，则跳过此步骤。

前提条件 — 调用 opcuaserverinfo 前，请确保：

1. OPC UA 本地发现服务（LDS）已安装并正在运行
2. 目标服务器已向 LDS 注册
3. 服务器证书在 LDS 证书存储区中受信任，存储区路径为 C:\ProgramData\OPC Foundation\UA\pki\trusted\certs\

详情请参阅 references/lds-setup-and-troubleshooting.md。

% 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. 创建 OPC UA 客户端

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

opcua 函数也可以直接接受来自 opcuaserverinfo 的 ServerInfo 对象。

2. 配置安全性（仅在需要非默认设置时）

% 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. 处理证书信任（如有需要）

如果 MATLAB 尚未信任服务器证书，连接将失败。请遵循必须遵守的规则中的升级顺序。加载 references/certificate-trust-workflows.md 了解详情。

4. 连接

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

5. 验证并断开连接

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

关键函数

函数	用途	起始版本
opcuaserverinfo	通过 LDS 或直接 URL 发现 OPC UA 服务器	R2015b
opcua	创建 OPC UA 客户端（通过 URL 或 ServerInfo）	R2015b
connect	连接到服务器	R2015b
disconnect	断开与服务器的连接	R2015b
isConnected	检查连接状态	R2015b
setSecurityModel	配置安全模式/策略	R2020a
opc.ua.exportClientCertificate	将 MATLAB 客户端证书导出到文件	R2020a
opc.ua.trustServerCertificate	信任服务器证书（文件路径）	R2026a
opc.ua.rejectServerCertificate	拒绝服务器证书（文件路径）	R2026a
findDescription	按描述文本筛选 ServerInfo 数组	R2015b
findAuthentication	按身份验证类型筛选 ServerInfo 数组	R2015b

属性速查

opc.ua.Client

属性	类型	描述
Hostname	string	服务器主机名
Port	double	服务器端口
Name	string	客户端名称
EndpointUrl	string	所选端点 URL
Status	string	连接状态
Timeout	double	连接超时（秒）
MessageSecurityMode	enum	当前安全模式
ChannelSecurityPolicy	enum	当前通道策略
UserAuthTypes	cell	服务器上可用的身份验证类型
Endpoints	array	可用的端点描述

不包含： UserName、Password、IsConnected、Security、 SecurityMode、SecurityPolicy、Certificate、PrivateKey。

使用 isConnected(uaClient)（方法）检查连接状态。

opc.ua.ServerInfo

属性	类型	描述
Hostname	char	主机名
Port	double	TCP 端口
Description	char	便于阅读的服务描述
UserTokenTypes	cell	支持的身份验证类型
BestMessageSecurity	enum	最高消息安全级别
BestChannelSecurity	enum	最高通道安全策略
Endpoints	array	opc.ua.EndpointDescription 对象

opc.ua.EndpointDescription

属性	类型	描述
EndpointUrl	char	完整端点 URL
MessageSecurityMode	enum	此端点的安全模式
ChannelSecurityPolicy	enum	通道安全策略
UserAuthTypes	cell	此端点上的身份验证类型

模式

发现

% Discover all servers via LDS
serverInfo = opcuaserverinfo('localhost');

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

使用身份验证连接

% 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");

修复主机名不匹配

% 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);

证书检查

加载 references/certificate-trust-workflows.md，然后运行：

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

故障排除快速参考

错误	修复方法
opcuaserverinfo 返回空结果	检查 LDS 前提条件；请参阅 references/lds-setup-and-troubleshooting.md
“Server certificate not trusted”	opc.ua.trustServerCertificate(certPath)
“Client certificate rejected”	使用 opc.ua.exportClientCertificate 导出，并添加到服务端
“BadIdentityTokenRejected”	检查 uaClient.UserAuthTypes
“Hostname mismatch” 警告	UseDiscoveryHostname=true（R2025a+）
“BadSecurityChecksFailed”	运行 inspectOpcUaCertificate；请参阅 references/troubleshooting-connection-errors.md

有关错误与修复方法的详细对应关系，请加载 references/troubleshooting-connection-errors.md。

---

Copyright 2026 The MathWorks, Inc.

---