matlab-build-industrial-hmi

工业 HMI 构建器

在 MATLAB App Designer 中构建面向操作员的 SCADA/HMI 仪表板，遵循工业 HMI 惯例：灰底配色理念、在数据源处显示报警、为每个设定值提供写入保护、带阈值线的固定范围趋势图，以及逐级下钻布局（工厂总览 → 区域 → 详情）。

适用场景

• 用户要求“将此 OPC UA / Modbus / MQTT / OSI PI / PI AF 脚本封装成 SCADA 仪表板 / HMI / 操作员画面”——包括由 OPC UA Explorer 或 Modbus Explorer 应用生成的脚本（opcuageneratedScript.mlx、modbusgeneratedScript.mlx）
• 构建工业监控的工厂总览、区域画面或详情画面
• 为现有 App Designer 应用添加报警可视化、设定值写入或实时趋势图
• 审查或重构使用仪表、指示灯或趋势坐标区显示过程数据的 HMI
• 提示中提及 ISA-101、灰底、报警横幅、写入确认、设定值或“操作员仪表板”

不适用场景

• 通用 App Designer 机制（uigridlayout、回调连接、生命周期、matlab.apps.AppBase 脚手架）以及序列化为真正的 App Designer 文件——此技能会将这些工作委派给 matlab-build-app。请参阅 references/app-designer-handoff.md。有两件事仍由此技能负责，不得转交：灰底主题（绝不将颜色/深色模式交给 matlab-apply-theme）和 HMI 趋势图（绝不将其交给 matlab-build-chart）。
• 在网络上发现 OPC UA 服务、查找端点 URL，或首次浏览命名空间——请使用 matlab-use-opcua-client。
• 非过程控制领域（消费类应用、实验室工具、科学 GUI）——此处的惯例专为监控物理过程的工厂操作员设计。

必须遵循的规则

控件与布局

• 灰底背景 [0.78 0.78 0.78]；面板 [0.86 0.86 0.86]；屏幕中 80% 以上保持中性色。颜色仅用于异常情况。请参阅 references/color-and-layout-rules.md。

• 构建每个 HMI uifigure 时，都必须同时设置 'Color' 和 'Theme', 'light'。 在深色主题的 MATLAB 桌面环境中，即使明确设置了图窗颜色，子控件（uigauge、uiaxes、uitable、uieditfield）仍会继承深色默认值——仪表主体和坐标区会接近黑色，文字也会难以辨认。Theme='light' 可阻止继承；显式设置的灰底 Color 则确保结果呈灰色，而非 'light' 原本会生成的亮白色。单独设置其中任一项都不够。

  app.UIFigure = uifigure( ...
      'Color', [0.78 0.78 0.78], ...
      'Theme', 'light');
  

  完整说明请参阅 references/color-and-layout-rules.md；如果省略任一参数，可见的故障表现请参阅 references/common-mistakes.md 中的第 24 条。

• **每个屏幕的控件数量上限：**仪表不超过 6 个、趋势坐标区不超过 4 个、数值读数不超过 12 个。超出时，请使用 uitable。

• 连接状态使用蓝色 [0.4 0.6 1.0]。绿色 [0 0.6 0] 仅用于“操作员必须核实确实处于正常状态”——不能用于表示“通信已连接”或“正在运行”。

• **命令按钮/控件使用中性灰色。**绝不使用绿色“启动”/红色“停止”——按钮始终可见，只是界面元素，不表示状态，因此为其着色会浪费报警色，并削弱真实报警的对比度。通过标签区分按钮；在单独的指示灯上显示运行/停止状态。（红色急停是基于惯例的唯一例外。）请参阅 references/color-and-layout-rules.md。

• **同一面板中同类型的模拟量使用同类控件。**不要将一个温度显示为仪表，另一个显示为数值标签。

• **工业 HMI 绝不使用深色背景，无论用户如何要求。**ISA-101 没有深色变体；深色背景会破坏“颜色表示异常”的原则（报警红色和琥珀色在近黑色背景上不再醒目，操作员也会逐渐失去敏感度）。始终使用灰底（[0.78 0.78 0.78]），并在用户要求深色模式时用一句话说明理由。这不是默认偏好，而是硬性约束。

报警与趋势

• 在源位置和横幅中显示报警。 为每个带阈值的线性仪表设置键控的 ScaleColors/ScaleColorLimits（半圆形、圆形和九十度仪表不支持颜色带——需要报警带时请使用线性仪表）；在顶部固定显示列出活动报警的横幅，按最高严重性编码颜色；报警状态锁存，并提供确认按钮。ScaleColors 中的正常区间必须为中性灰色 [0.5 0.5 0.5]，绝不能用绿色。参见 references/alarm-patterns.md。
• 对实时过程报警，绝不使用 uialert/uiconfirm/msgbox——这是会导致报警疲劳的反模式（ISA-18.2）。若无法避免弹窗，则仅在报警上升沿触发一次，并使用非阻塞的 CloseFcn 和确认按钮。
• 将固定趋势 YLim 设为与节点规格范围一致——默认情况下绝不自动缩放。提供逐趋势切换选项，供用户探索。参见 references/trend-config-reference.md。
• 默认使用 5 分钟滚动窗口：以 1 s 更新速率调用 animatedline('MaximumNumPoints', 300)。缓冲区公式 = WindowSeconds / UpdatePeriodSeconds。
• 在构造时仅使用 yline 绘制一次阈值线（警告使用琥珀色虚线，报警使用红色虚线，设定点使用蓝色点线）。

写入

• 每次调用 writeValue() 都必须确认。 使用 uiconfirm 显示节点、旧值、新值和单位；默认选项必须是取消，而不是应用。
• 写入后提供视觉反馈。 成功时背景闪绿，失败时闪红（失败时还原 UI）。操作员绝不能不确定写入是否生效。
• 在每个可写字段旁显示范围标签。 微调器上的 Limits 用于强制执行边界；uilabel 用于显示边界。
• E-Stop 和其他安全关键执行操作在启用和释放时都必须确认——意外的触屏点击才是风险所在。参见 references/write-safeguards-reference.md。
• 系统无法接受写入时（断开连接、E-Stop 已启用），应禁用写入控件，而不是让写入在调用过程中失败。

协议选择

• OPC UA：无论节点数量和更新速率如何，默认使用 subscribe()，包括小型节点集的 1 Hz 更新。timer 仅用于非节点类 UI 工作（时钟显示、警报闪烁、空闲变暗）。
• R2026a OPC UA 契约：subscribe(client, nodes, cb) 会调用 cb(sub, notification)；数据位于 notification.Data.Value / notification.Data.Timestamp；来源节点是 notification.Node（包含 Name、Identifier、NamespaceIndex 的结构体）。不要引用 src.Name——在较早版本中，src 是节点时这样写有效，但在 R2026a 中会报错。
• 两种回调形式——须与来源匹配。 当你自己编写 subscribe 调用时，使用上文的 2 参数 cb(sub, notification)。当你粘贴由 OPC UA Explorer 生成的 dataChangeCallback 时，它采用 3 参数向量化形式——cb(subObj, notification, ~)——且 notification 是结构体数组（每个在此周期发生变化的节点对应一个条目）：遍历 notification(i).Node.Name / notification(i).Data.Value；切勿将其视为标量。为 Explorer 脚本编写 2 参数的 @(src, evt) 会报错 "Too many input arguments"；将 notification 视为标量则只会读取第一个节点。参见 references/protocol-cheatsheet.md §OPC UA 和 references/common-mistakes.md #17。
• Modbus 没有 subscribe()——使用轮询 timer，并设置 BusyMode='drop'、ExecutionMode='fixedSpacing'。6 参数 write() 的顺序是 write(m, target, addr, val, serverId, 'precision')——serverId 在 'precision' 之前。
• MQTT subscribe(c, topic, Callback=@cb)——回调是名称-值对，不是位置参数。根据代理的负载架构解码 message（字符串）（str2double、jsondecode）。
• OSI / AVEVA PI Data Archive：使用 piclient（Industrial Communication Toolbox，R2022a+）。在 MATLAB 中切勿调用 NET.addAssembly('OSIsoft.AFSDK') 或编写 OSIsoft.AF.PI.PIServers / OSIsoft.AF.PISystems 代码——工具箱客户端封装了 AFSDK，并返回原生 MATLAB 类型（timetable、table、datetime）；自行编写 .NET 互操作代码会丢失类型强制转换，在工具箱能够处理的权限错误上抛出异常，因绕过批量读取而运行缓慢，并破坏集成浏览器应用。PI 没有 subscribe()——使用轮询计时器驱动趋势（与 Modbus 的模式相同）。通过 write(piClient, tag, value, TimeInstance=datetime("now")) 写入需要 R2024a+。
• PI Asset Framework：使用 afclient（Industrial Communication Toolbox，R2026a+）。使用 getRootElements / getChildren / findElementByName / findElementByPath / findElementByTemplate 浏览；使用 Attribute.read（当前值 → 表格）和 Attribute.readHistory（归档 → 时间表）读取。AF 层次结构可直接映射到 Level 1 → Level 2 → Level 3 下钻屏幕。工具箱不提供 AF 当前值写入功能——没有 Attribute.write；请通过底层的 Attribute.PITag 和 PI 客户端路由写入操作。
• **与 OPC UA 使用 AccessLevelCurrent 的方式相同，使用 Attribute.WriteAccess 和 HasTimeSeriesData 确认属性是否可写。**不要根据名称推断可写性。
• 使用服务器实际的标签 / 属性名称，从 tags(c).Name 或 attribute.Name / attribute.Path 获取。切勿自行编造标签——HMI 必须与源脚本中的标识符保持一致，以便操作员对照 OPC UA Explorer / OSI PI viewer / AF browser。

有关 OPC UA / Modbus / MQTT API 形式，参见 references/protocol-cheatsheet.md；有关 PI Data Archive 和 PI AF，参见 references/pi-af-cheatsheet.md；有关会导致静默失败的情形，参见 references/common-mistakes.md。

App Designer 语言

• 初始化类型化 struct 属性： Foo struct = struct()。仅声明 Foo struct 会得到 0×0 struct，而执行 app.Foo.Bar = 1 会报错："当结构体为空时，不能对结构体进行点名称赋值。"
• classdef 必须放在首位。 同一文件中，classdef 前的 function 块会导致解析错误。删除包装代码；文件中第一个非注释语句必须是 classdef，且类名必须与文件名一致。
• 内联求值中不能使用 function … end。 函数定义只能放在代码文件中，不能放在命令窗口或内联上下文中。通过 evaluate_matlab_code 检查辅助逻辑（严重性区间、报警计算）时，执行记录所在的环境就是命令窗口上下文——粘贴 function … end 块会报错："Function definitions are not supported in this context."。请从函数所在文件调用它，或直接内联运算。
• 清理订阅： opc.ua.Subscription 没有公共的 delete 方法。释放句柄（app.Subscription = opc.ua.Subscription.empty;），并调用 disconnect(client)——这会释放该客户端上的所有订阅。
• 每个组件分别订阅，不要在每次添加组件时重建单个全局订阅——每次 subscribe() 都会累积一个通道监听器；重建会造成泄漏。
• 在 delete(app) 或 CloseRequestFcn 中停止并删除计时器。计时器泄漏会在窗口关闭后继续触发，并持有已失效的句柄。

完整复现示例、考虑版本的 AccessLevelCurrent 检查以及每个组件的订阅模式，请参阅 references/app-designer-gotchas.md。

App Designer 输出

• 将序列化工作交给 matlab-build-app，生成真正的 App Designer 应用。 当该技能的 AppDesignerAgentInterface 工具可用时（exist('AppDesignerAgentInterface','class')==8，即该工具位于路径上），请在此处设计 HMI，然后调用其操作生成真正的 .mlapp（R2025a+）——这是默认输出，可在 App Designer 中打开。纯文本 .m+.xml 仅在 R2026b+ 可用，供源代码管理使用。架构问题已有答案：工业 HMI 始终使用 UIFigure（绝不使用 UIHTML），因此无需进行父级架构和序列化方式的调研。
• 父级不可用时的备用方案： 按照这些参考文档的说明生成程序化 .m 应用。它的运行效果相同，只是无法在 App Designer 中打开。请向用户说明这一点。
• 有关与 matlab-build-app 的分工、交接协议、HMI→操作映射（灰显字段、报警仪表、调色板、清理）以及序列化前的领域合规检查清单，请参阅 references/app-designer-handoff.md。该文件将所有序列化机制——操作 API、文件格式选择和生命周期——交由父级的 references/app-designer/agent-guide-shared.md 处理。

工作流

将监控脚本封装为 HMI 时，请按顺序完成以下步骤。小组件的选择取决于数据类型，布局取决于小组件的选择，随后叠加警报、趋势图和写入功能；最后再序列化为实际的 App Designer 应用。

1. 对每个节点 / 标签 / 属性进行分类——二进制、枚举、有范围的模拟量、无范围的模拟量、可写、警报阈值（LL/L/H/HH）。此清单决定后续所有步骤。→ references/widget-selection-flowchart.md。如果未预先提供架构 → references/server-agnostic-discovery.md。如果封装的是生成的脚本（OPC UA/Modbus Explorer 或 MQTT 演示）→ 先查看 references/protocol-cheatsheet.md；如果封装的是 PI / PI AF 脚本 → 查看 references/pi-af-cheatsheet.md，了解确切的 API 形式。
2. 通过决策流程图选择小组件，并对照数量上限进行检查。→ references/widget-selection-flowchart.md。
3. 按层级布局——第 1 级为工厂总览，第 2 级为区域，第 3 级为详细信息；第 1 行保留给常驻警报横幅。→ references/color-and-layout-rules.md。
4. 按协议连接实时数据——OPC UA 使用 subscribe()（自行编写的回调 = 2 个参数的 cb(sub, notification)；Explorer 生成的 dataChangeCallback = 对结构体数组进行向量化操作的 3 个参数），Modbus 轮询使用 timer，MQTT 使用 subscribe(... Callback=...)，PI / PI AF 轮询使用 timer 调用 read() / Attribute.read。→ references/protocol-cheatsheet.md 和 references/pi-af-cheatsheet.md。
5. 在数据源和横幅中配置警报，并通过确认操作锁存。→ references/alarm-patterns.md。
6. 配置趋势图——5 分钟窗口、固定 YLim、阈值线。→ references/trend-config-reference.md。
7. 为每个设定点添加写入保护措施——确认操作、范围标签、闪烁反馈。→ references/write-safeguards-reference.md。
8. **序列化为实际的 App Designer 应用。**如果提供了 matlab-build-app，请将设计交给其 AppDesignerAgentInterface 并生成 .mlapp（默认）；否则生成程序化的 .m 应用。编辑现有 App Designer HMI 时，也应通过父级的 open()/inspect() 循环进行。→ references/app-designer-handoff.md。
9. **验证：启动、操作并正常关闭。**使用 mcp__matlab__evaluate_matlab_code 实例化应用并执行 delete(app)；确认没有遗留的计时器、订阅或图窗。对于 .mlapp，确认 save() 成功且 validate() 为空。如果构造因结构体或 classdef 错误而失败 → references/app-designer-gotchas.md。

核心功能

功能	用途	工具箱	起始版本
uigauge('linear'|'circular'|'semicircular'|'ninetydegree')	单个值，范围已知	core MATLAB	R2016a
uigauge.ScaleColors / .ScaleColorLimits	在源端设置报警区间	core MATLAB	R2018a
uilamp	二进制状态指示器	core MATLAB	R2016a
使用 MaximumNumPoints 的 animatedline	滚动趋势缓冲区	core MATLAB	R2014b
addpoints / clearpoints	趋势更新 / 重置	core MATLAB	R2014b
yline	趋势图上的阈值线或设定值线	core MATLAB	R2018b
uiconfirm	模态写入确认	core MATLAB	R2017b
使用 Limits 的 uispinner	有界数值输入	core MATLAB	R2016a
uieditfield('numeric','Editable',false)	精确的只读数值显示	core MATLAB	R2016a
uitable	用于显示超过 8 个节点的表格	core MATLAB	R2017b
uitree + uitreenode	OPC UA 命名空间导航	core MATLAB	R2017b
opcua / connect	打开 OPC UA 客户端	Industrial Communication	R2022a
findNodeByName / readValue / writeValue	浏览节点并进行读写	Industrial Communication	R2022a
subscribe(uaClient, nodeList, dataChangeFcn, PublishInterval=...)	实时节点更新（优先于 timer）	Industrial Communication	R2023b
modbus('tcpip', host, port) / read / write	Modbus 客户端及寄存器读写	Industrial Communication	R2022a
mqttclient(brokerAddr) / subscribe(c, topic, Callback=...) / write	MQTT 发布 / 订阅	Industrial Communication	R2022a
piclient(server, ...)	OSI / AVEVA PI Data Archive 客户端	Industrial Communication	R2022a
tags(piClient, Name=q) / read(piClient, tag, DateRange=, Interval=, AggregateFcn=)	PI 标签搜索、当前值及历史 / 聚合读取（返回 table / timetable）	Industrial Communication	R2022a
write(piClient, tag, value, TimeInstance=...)	PI 设定值写入	Industrial Communication	R2024a
afclient(server, Database=...)	PI Asset Framework 客户端	Industrial Communication	R2026a
getRootElements / getChildren / getAttributes / findElementByName / findElementByPath / findElementByTemplate	AF 树浏览 → 下钻布局	Industrial Communication	R2026a
read(attr, Unit=...) / readHistory(attr, t0, t1, ...) / listSupportedUnits	AF 属性当前值、历史记录及单位	Industrial Communication	R2026a
timer（BusyMode='drop'、ExecutionMode='fixedSpacing'）	Modbus / PI / PI AF 轮询循环 / 非 OPC 定期 UI 工作	core MATLAB	base

模式

每个参考文件都包含该主题的可执行代码模式。编写代码前请先加载相关参考文件——其中包含正确的调用约定、构造函数参数、属性名称和完整的回调处理程序。请参阅下方的参考文件路由表。

常见错误

references/common-mistakes.md 是一份优先使用 grep 的查找表，记录了 26 个反模式，每项都采用症状 → 错误做法 → 正确做法 → 原因的结构。不要一次性加载整个文件——使用 Grep 搜索用户的错误字符串，或通过索引表查找反模式，然后只阅读匹配的 ### N. 条目。内容涵盖 App Designer struct / classdef 陷阱、ISA-101 违规（绿色表示“正常”、绿色 Start / 红色 Stop 命令按钮、弹出式报警、趋势自动缩放、用 uilabel 显示数值、暗色字段），以及特定协议的静默故障（Modbus serverId / 'precision' 顺序、MQTT 位置参数回调、JSON 负载中的 MQTT NaN、虚构的 OPC UA 节点名称、OPC UA evt.Value 与 evt.Data.Value 的区别、Explorer 三参数向量化回调、服务器端 1601 时间戳）。

参考

在以下情况下加载……	参考资料
为节点列表选择控件	references/widget-selection-flowchart.md
设计屏幕结构或选择颜色	references/color-and-layout-rules.md
在源端或持久横幅中接入报警区间	references/alarm-patterns.md
配置趋势图（窗口、YLim、阈值线）	references/trend-config-reference.md
添加带确认和闪烁反馈的可写设定点	references/write-safeguards-reference.md
封装 OPC UA Explorer / Modbus Explorer / MQTT 脚本、调用 OPC UA 方法节点，或处理特定协议的 Bug	references/protocol-cheatsheet.md
封装 OSI / AVEVA PI Data Archive 脚本（piclient、tags、read）或 PI AF 脚本（afclient、getRootElements、getAttributes、Attribute.read/readHistory）	references/pi-af-cheatsheet.md
浏览未知服务并在运行时推断控件	references/server-agnostic-discovery.md
为已知节点到控件的架构进行硬编码	references/known-schema-patterns.md
构造错误（struct 属性、classdef 顺序、监听器泄漏、AccessLevelCurrent）	references/app-designer-gotchas.md
通过 matlab-build-app 序列化为实际的 App Designer .mlapp 文件，或编辑现有的 App Designer 应用	references/app-designer-handoff.md
调试特定错误、静默故障或反模式	在 references/common-mistakes.md 中对错误文本或反模式进行 Grep 搜索（该文件包含索引表）——只阅读匹配的条目，不要阅读整个文件

工具箱依赖项

• Core MATLAB：uifigure、uigridlayout、uigauge、uilamp、uispinner、uieditfield、uitable、uitree、uiconfirm、uialert、uiaxes、animatedline、addpoints、yline、timer。
• Industrial Communication Toolbox：opcua、connect、disconnect、findNodeByName、findNodeById、readValue、writeValue、subscribe（OPC UA）；modbus、read、write（Modbus）；mqttclient、subscribe、unsubscribe、write、read（MQTT）；piclient、tags、read、write、viewer（PI Data Archive，R2022a+；write 需 R2024a+）；afclient、listDatabases、selectDatabase、getRootElements、getChildren、getAttributes、findElementByName、findElementByPath、findElementByTemplate、findAttributeByPath、Attribute.read、Attribute.readHistory、Attribute.listSupportedUnits（PI AF，R2026a+）。

如果用户的 MATLAB 版本未知，请在开始前使用 mcp__matlab__detect_matlab_toolboxes 验证。

---

版权所有 2026 The MathWorks, Inc.

---