matlab/matlab-agentic-toolkit / skills-catalog/test-and-measurement/matlab-build-industrial-hmi
matlab-build-industrial-hmi
VerifiedBuild industrial-grade SCADA/HMI dashboards in MATLAB following industrial-HMI conventions (ISA-101-aligned): gray-field philosophy, alarms at source, write safeguards, fixed-range trends, drill-down layout. Produces a real App Designer app (.mlapp, or plain-text .m+.xml on R2026b+) by handing serialization to the matlab-build-app skill when available, and falls back to a programmatic .m app otherwise. Use when wrapping OPC UA / Modbus / MQTT / OSI PI / PI AF monitoring scripts into a live operator app, building plant overviews, designing operator dashboards, or any time a user asks for a "SCADA dashboard", "HMI", "plant dashboard", "operator screen", or "industrial monitoring app" in MATLAB. Trigger on: SCADA, HMI, industrial dashboard, plant overview, operator screen, uigauge, uilamp, alarm banner, gray-field, ISA-101, OPC UA dashboard, setpoint, write safeguards, alarm visualization, OSIsoft PI, AVEVA PI, PI Server, PI Data Archive, PI AF, PI Asset Framework, piclient, afclient.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 21.6 KB |
| assets/design-report-schema.json | config | 9.9 KB |
| assets/designReportReadback.m | other | 12.5 KB |
| assets/hmi-spec-template.md | markdown | 18.4 KB |
| manifest.yaml | config | 1.7 KB |
| references/alarm-patterns.md | markdown | 10.9 KB |
| references/app-designer-gotchas.md | markdown | 9.0 KB |
| references/app-designer-handoff.md | markdown | 17.7 KB |
| references/color-and-layout-rules.md | markdown | 16.3 KB |
| references/common-mistakes.md | markdown | 49.6 KB |
| references/key-functions.md | markdown | 4.1 KB |
| references/known-schema-patterns.md | markdown | 4.1 KB |
| references/pi-af-cheatsheet.md | markdown | 16.7 KB |
| references/protocol-cheatsheet.md | markdown | 19.1 KB |
| references/server-agnostic-discovery.md | markdown | 8.4 KB |
| references/trend-config-reference.md | markdown | 10.9 KB |
| references/widget-selection-flowchart.md | markdown | 6.6 KB |
| references/write-safeguards-reference.md | markdown | 9.2 KB |
SKILL.md
View on GitHub---
name: matlab-build-industrial-hmi
description: >
Build industrial-grade SCADA/HMI dashboards in MATLAB following industrial-HMI
conventions (ISA-101-aligned): gray-field philosophy, alarms at source, write
safeguards, fixed-range trends, drill-down layout. Produces a real App Designer
app (.mlapp, or plain-text .m+.xml on R2026b+) by handing serialization to the
matlab-build-app skill when available, and falls back to a programmatic .m app
otherwise. Use when wrapping OPC UA / Modbus / MQTT / OSI PI / PI AF monitoring
scripts into a live operator app, building plant overviews, designing operator
dashboards, or any time a user asks for a "SCADA dashboard", "HMI", "plant
dashboard", "operator screen", or "industrial monitoring app" in MATLAB.
Trigger on: SCADA, HMI, industrial dashboard, plant overview, operator screen,
uigauge, uilamp, alarm banner, gray-field, ISA-101, OPC UA dashboard,
setpoint, write safeguards, alarm visualization, OSIsoft PI, AVEVA PI,
PI Server, PI Data Archive, PI AF, PI Asset Framework, piclient, afclient.
license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata:
author: MathWorks
version: "1.2"
---
# Industrial HMI Builder
Build operator-facing SCADA/HMI dashboards in MATLAB App Designer that follow industrial-HMI conventions: gray-field color philosophy, alarms shown at the data source, write safeguards on every setpoint, fixed-range trends with threshold lines, and a drill-down layout (plant overview → area → detail).
## When to Use
- A user asks to "wrap this OPC UA / Modbus / MQTT / OSI PI / PI AF script into a SCADA dashboard / HMI / operator screen" — including scripts generated by the **OPC UA Explorer** or **Modbus Explorer** apps (`opcuageneratedScript.mlx`, `modbusgeneratedScript.mlx`)
- Building a plant overview, area screen, or detail screen for industrial monitoring
- Adding alarm visualization, setpoint writes, or live trends to an existing App Designer app
- Reviewing or refactoring an HMI that uses gauges, lamps, or trend axes for process data
- Any prompt mentioning ISA-101, gray-field, alarm banner, write confirm, setpoint, or "operator dashboard"
## When NOT to Use
- General App Designer mechanics (`uigridlayout`, callback wiring, lifecycle, `matlab.apps.AppBase` scaffolding) and serialization to a real App Designer file — this skill **delegates** those to `matlab-build-app`. See `references/app-designer-handoff.md`. Two things stay here and must **not** be routed away: gray-field theming (never hand color/dark-mode to `matlab-apply-theme`) and HMI trends (never hand them to `matlab-build-chart`).
- Discovering OPC UA servers on a network, finding endpoint URLs, connecting or configuring security and certificate trust, or browsing the address space to find nodes for the first time — use `matlab-use-opcua-client`.
- Non-process domains (consumer apps, lab utilities, scientific GUIs) — the conventions here are tailored to plant operators monitoring physical processes.
## Must-Follow Rules
### Widget & Layout
- **Gray-field background** `[0.78 0.78 0.78]`; panels `[0.86 0.86 0.86]`; 80%+ of the screen neutral. Color is reserved for *exception*. See `references/color-and-layout-rules.md`.
- **Construct EVERY HMI `uifigure` with both `'Color', [0.78 0.78 0.78]` and `'Theme', 'light'`.** Neither alone is enough: on a dark-themed desktop child widgets (uigauge, uiaxes, uitable, uieditfield) inherit dark defaults even when the figure colour is set, and `'light'` alone yields bright white instead of gray-field. Code + rationale: `references/color-and-layout-rules.md`; failure mode: `references/common-mistakes.md` entry 24.
- **Quantity caps per screen:** ≤ 6 gauges, ≤ 4 trend axes, ≤ 12 numeric readouts — beyond that, use a `uitable` — and ≤ 5 **saturated-color elements that the design chooses**. One gauge's `ScaleColors` counts as one element however many bands it has; the connection lamp's blue is comms state, not alarm state, and sits outside the budget. Fixed MATLAB chrome does not count (a `LinearGauge` needle draws saturated red at every value and no public property recolors it). Full rule: `assets/hmi-spec-template.md` §4.
- **Connection state is BLUE** `[0.4 0.6 1.0]`. Green `[0 0.6 0]` is reserved for "operator must verify yes this is actively OK" — not for "comms up" or "running".
- **Command buttons/controls are neutral gray.** Never a green Start / red Stop — buttons are always-visible chrome and carry no status, so coloring them spends the alarm colors and steals contrast from real alarms. Differentiate by label; show run/stopped state on a separate lamp. (Red E-Stop is the one convention-based exception.) See `references/color-and-layout-rules.md`.
- **Like-typed analogs in one panel use like widgets.** Don't show one temperature as a gauge and another as a numeric label.
- **NEVER produce a dark background for an industrial HMI, regardless of the user request.** ISA-101 has no dark variant; a dark field destroys color-as-exception (alarm reds and ambers stop popping against a near-black background, and operators desensitize). Always render gray-field (`[0.78 0.78 0.78]`) and reply with a one-sentence justification when the user asks for dark mode. This is not a default — it is a hard constraint.
### Alarms & Trends
- **Alarms at source AND in a banner.** Keyed `ScaleColors`/`ScaleColorLimits` on every gauge with thresholds (`Limits` must cover every band — out-of-range bands are silently clipped); persistent top-row banner listing active alarms, color-coded by highest severity; latched state with an Acknowledge button — latching and its ACK control ship together or neither does. **The normal band in `ScaleColors` is neutral gray `[0.5 0.5 0.5]` — never green.** See `references/alarm-patterns.md`.
- **Never** `uialert`/`uiconfirm`/`msgbox` for live process alarms — alarm-fatigue anti-pattern (ISA-18.2). If a popup is unavoidable, fire once on the rising edge with a non-blocking `CloseFcn` and an Acknowledge button.
- **Fixed trend `YLim`** matching the node's spec range — never auto-scale by default. Provide a per-trend toggle for exploration. See `references/trend-config-reference.md`.
- **5-minute rolling window** is the default: `animatedline('MaximumNumPoints', 300)` at 1 s update. Buffer formula = `WindowSeconds / UpdatePeriodSeconds`.
- **Threshold lines drawn once at construction** with `yline` (amber dashed for warn, red dashed for alarm, blue dotted for setpoint).
### Writes
- **Every `writeValue()` confirms.** `uiconfirm` showing node + old + new + units; default option is **Cancel**, not Apply.
- **Visual feedback after write is a desaturated flash that reverts** — `[0.7 1 0.7]` on success, `[1 0.7 0.7]` on failure, back to the normal face after ~0.4 s (and revert the *value* too on failure). Do **not** flash saturated green `[0 0.6 0]` or alarm red `[0.85 0 0]`: those are reserved for operator-verified-OK and active alarms, and a control that stays recolored reads as status rather than as an acknowledgement. Operator must never be uncertain whether the write took effect.
- **Range label adjacent to every writable field.** `Limits` on the spinner enforces the bound; the `uilabel` makes it visible.
- **E-Stop and other safety-critical actuation confirm both engage and release** — accidental touchscreen clicks are the threat. See `references/write-safeguards-reference.md`.
- **Disable write controls** when the system can't accept them (disconnected, E-Stop active) rather than letting writes fail mid-call.
### Protocol Selection
- **OPC UA: `subscribe()` is the default** at any node count and update rate, including 1 Hz with a small node set. Reserve `timer` for non-node UI work (clock displays, alarm flashing, idle dimming).
- **R2026a OPC UA contract:** `subscribe(client, nodes, cb, PublishInterval=<s>)` — always set `PublishInterval` to the required rate (seconds; default 1) — invokes `cb(sub, notification)`; data lives at `notification.Data.Value` / `notification.Data.Timestamp`; the originating node is `notification.Node` (struct with `Name`, `Identifier`, `NamespaceIndex`). Don't reference `src.Name` — that worked in older releases when `src` was the node, but errors in R2026a.
- **Two callback shapes — match the source.** When *you* write the `subscribe` call, use the **2-arg** `cb(sub, notification)` above. When you paste an **OPC UA Explorer**–generated `dataChangeCallback`, it is **3-arg vectorized** — `cb(subObj, notification, ~)` — and `notification` is a **struct array** (one entry per node changed this cycle): iterate `notification(i).Node.Name` / `notification(i).Data.Value`; never treat it as scalar. Writing a 2-arg `@(src, evt)` for an Explorer script throws *"Too many input arguments"*; treating `notification` as scalar reads only the first node. See `references/protocol-cheatsheet.md` §OPC UA and `references/common-mistakes.md` #17.
- **Modbus has no `subscribe()`** — use a polling `timer` with `BusyMode='drop'`, `ExecutionMode='fixedSpacing'`. The 6-arg `write()` order is `write(m, target, addr, val, serverId, 'precision')` — `serverId` BEFORE `'precision'`. Putting `'precision'` in slot 5 (or dropping `serverId` on a non-default unit) throws *"Expected input number 5, serverId, to be one of these types: double, single, …"* — the single most common Modbus HMI bug.
- **MQTT `subscribe(c, topic, Callback=@cb)`** — the callback is a **name-value pair**, not positional. Decode `message` (a string) per the broker's payload schema (`str2double`, `jsondecode`).
- **OSI / AVEVA PI Data Archive: use `piclient`** (Industrial Communication Toolbox, R2022a+). **Never** call `NET.addAssembly('OSIsoft.AFSDK')` or write `OSIsoft.AF.PI.PIServers` / `OSIsoft.AF.PISystems` code in MATLAB — the toolbox client wraps the AFSDK and returns native MATLAB types (`timetable`, `table`, `datetime`); rolling your own .NET interop loses type coercion, throws on permission errors that the toolbox handles, runs slowly because batched reads are bypassed, and breaks the integrated browser app. PI has **no `subscribe()`** — drive trends with a polling timer (same shape as Modbus). Writes via `write(piClient, tag, value, TimeInstance=datetime("now"))` are R2024a+.
- **PI Asset Framework: use `afclient`** (Industrial Communication Toolbox, R2026a+). Browse with `getRootElements` / `getChildren` / `findElementByName` / `findElementByPath` / `findElementByTemplate`; read with `Attribute.read` (current → table) and `Attribute.readHistory` (archive → timetable). The AF hierarchy maps directly onto Level 1 → Level 2 → Level 3 drill-down screens. **AF current-value writes are not exposed by the toolbox** — there is no `Attribute.write`; route writes through the underlying `Attribute.PITag` and the PI client.
- **Identify writable attributes from `Attribute.WriteAccess` and `HasTimeSeriesData`**, the same way OPC UA uses `AccessLevelCurrent`. Don't infer writability from the name.
- **Use the server's actual tag / attribute names** from `tags(c).Name` or `attribute.Name` / `attribute.Path`. Never invent labels — the HMI must mirror the source script's identifiers so operators can cross-reference with the OPC UA Explorer / OSI PI viewer / AF browser.
See `references/protocol-cheatsheet.md` for OPC UA / Modbus / MQTT API shapes and `references/pi-af-cheatsheet.md` for PI Data Archive and PI AF; see `references/common-mistakes.md` for the silent-failure modes.
### App Designer Language
- **Initialize typed `struct` properties:** `Foo struct = struct()`. A bare `Foo struct` declaration becomes `0×0 struct` and `app.Foo.Bar = 1` errors with *"A dot name structure assignment is illegal when the structure is empty."*
- **`classdef` first.** A `function` block before `classdef` in the same file is a parse error. Drop the wrapper; the file's first non-comment statement must be `classdef`, name matching filename.
- **No `function … end` in inline evaluation.** Function definitions are legal only inside code files, never in a command-window / inline context. When you sanity-check helper logic (severity bands, alarm math) through `evaluate_matlab_code`, the transcript *is* a command-window context — a pasted `function … end` block errors with `"Function definitions are not supported in this context."` Verify by exercising the helper from its file, or inline the arithmetic directly.
- **Subscription cleanup:** `opc.ua.Subscription` has no public `delete`. Drop the handle (`app.Subscription = opc.ua.Subscription.empty;`) and `disconnect(client)` — that releases all subscriptions on that client.
- **Subscribe per widget**, never rebuild a single global subscription on each add — each `subscribe()` accumulates a channel listener; rebuilds leak.
- **Teardown body lives in `delete(app)`; `CloseRequestFcn` only routes to it.** Stop and delete timers, drop subscription handles and disconnect clients inside `delete(app)`, then wire `app.UIFigure.CloseRequestFcn = @(~,~) delete(app);`. Putting the body on `CloseRequestFcn` instead leaks everything whenever the app is closed programmatically — which is how every test, script and eval closes it. A leaked timer keeps firing after the figure closes with stale handles. See `references/common-mistakes.md` #32.
See `references/app-designer-gotchas.md` for full reproductions, the release-aware `AccessLevelCurrent` check, and per-widget subscription patterns.
### Spec, Review, and Output
- **Write the spec, get it approved, then build.** Fill `assets/hmi-spec-template.md` into `<AppName>-hmi-spec.md` beside the app, present a ≤10-line summary, and **STOP for review**. Build only after the user approves. Corrections go into the spec, never into a built app. That file *is* the hand-off contract.
- **Build by invoking the `matlab-build-app` skill under the exact name it appears as in your available-skills list** — plugin-scoped (`<plugin>:matlab-build-app`) or bare; only the listed form resolves, so never type a guessed slash command. Hand it the approved spec, which pre-answers its discovery (UIFigure — an HMI is never UIHTML — plus `.mlapp`, archetype, users, timers). How it builds and what format it emits is its concern.
- **Availability is that same list lookup, never a filesystem search.** Not listed → emit the programmatic `.m` app yourself from the same approved spec; say it runs identically but won't open in App Designer, and that enabling the `matlab-app-building` plugin and rebuilding from the same spec produces a `.mlapp`. **Never scan the disk for its skill folder** — it ships in a different plugin (`matlab-app-building`), so a recursive search above this skill runs for tens of minutes and still misses.
- **Editing an existing HMI is a delta, not a rebuild** — patch the spec, confirm only changed rows, hand off the change.
- `references/app-designer-handoff.md` has the division of labor, the hand-off protocol, and the component/behavior recipes the spec is filled from.
## Workflow
When wrapping a monitoring script into an HMI, work through these steps in order. Widget choice depends on data type, layout depends on widget choice, alarms/trends/writes layer on top — and the finished design is written to a spec the user reviews before anything is built.
1. **Classify each node / tag / attribute** — binary, enumerated, analog with range, analog without range, writable, alarm thresholds (LL/L/H/HH). This list drives every later step. → `references/widget-selection-flowchart.md`. If the schema isn't given upfront → `references/server-agnostic-discovery.md`. If wrapping a generated script (OPC UA/Modbus Explorer or MQTT demo) → `references/protocol-cheatsheet.md` first; if wrapping a PI / PI AF script → `references/pi-af-cheatsheet.md`, for the exact API shapes.
2. **Pick widgets** via the decision flowchart, cross-checking quantity caps. → `references/widget-selection-flowchart.md`.
3. **Lay out by hierarchy** — Level 1 plant overview, Level 2 area, Level 3 detail; row 1 reserved for the persistent alarm banner. → `references/color-and-layout-rules.md`.
4. **Wire live data per protocol** — OPC UA `subscribe()` (self-written callback = 2-arg `cb(sub, notification)`; an Explorer-generated `dataChangeCallback` = **3-arg vectorized** over a struct array), Modbus polling `timer`, MQTT `subscribe(... Callback=...)`, PI / PI AF polling `timer` against `read()` / `Attribute.read`. → `references/protocol-cheatsheet.md` and `references/pi-af-cheatsheet.md`.
- **Paint the screen before you connect.** A client constructed against an unreachable host blocks **~21 s** then throws, and no `Timeout` shortens it. Build the gray-field layout, `drawnow`, show "Connecting to `<host>`…" in the banner, and only **then** construct the client inside a `try`. Measurements: `references/protocol-cheatsheet.md` §Polling pattern.
5. **Configure alarms at source AND in a banner**, latched only alongside an Acknowledge control. → `references/alarm-patterns.md`.
6. **Configure trends** — 5-minute window, fixed YLim, threshold lines. → `references/trend-config-reference.md`.
7. **Add write safeguards** on every setpoint — confirm, range label, flash feedback. → `references/write-safeguards-reference.md`.
8. **Write the HMI spec** — fill `assets/hmi-spec-template.md` into `<AppName>-hmi-spec.md` beside the app: signals, components with ISA-101 values, behaviors and wiring roles, build parameters. Self-audit section 5 first. → `assets/hmi-spec-template.md`.
9. **STOP — spec review gate.** Present a ≤10-line summary plus the file path, then **wait**; revise the spec and re-present until the user approves, then stamp `Review status: APPROVED <date>`. Proceed unprompted **only** on pre-approval, or when the session cannot take a reply (batch/eval run) — then leave it `UNREVIEWED` and say so **before building** — summary first, then build. "Seems busy" is not a bypass.
10. **Build from the approved spec** per "Spec, Review, and Output" above. → `references/app-designer-handoff.md`.
11. **Verify by reading the built app back, then close it cleanly.** Copy `assets/designReportReadback.m` beside the app **verbatim, keeping its filename** — it is a function; **do not edit it, do not rename it, and do not re-author your own readback**. Call it via `mcp__matlab__evaluate_matlab_code`: `designReportReadback("<AppClass>", "<AppClass>-hmi-spec.md")`. It reads the live figure and source, writes `design-report.json`, deletes the app and reports leaks. Confirm the file's first key is `"reportFormat":"hmi-report/1"` (self-check: `references/common-mistakes.md` #33), then compare it with the spec row by row and fix the **app** where they disagree. Never hand-write or reshape the numbers. If construction fails on a struct or classdef error → `references/app-designer-gotchas.md`.
## Key Functions and Release Gates
`references/key-functions.md` lists every widget, client, and read/write call with its toolbox and
release, plus the four gates that change the *design* rather than the call — the floor is **R2023b**
(`manifest.yaml`), set by OPC UA `subscribe()`. Check it before writing a call on an unknown
install; `mcp__matlab__detect_matlab_toolboxes` confirms what's present.
## Common Mistakes
`references/common-mistakes.md` is a **grep-first lookup table** of 33 documented anti-patterns — App Designer gotchas, ISA-101 violations, and protocol-specific silent failures — each a **Symptom → Wrong → Right → Why** block. Don't load it whole: `Grep` it for the user's error string, or find the anti-pattern in its index table, and read only the matching `### N.` entry.
## References
Each file carries executable patterns for its topic — calling conventions, constructor arguments, property names, full callback handlers. Load the relevant one **before** writing code.
| Load when... | Reference |
|---|---|
| Writing the HMI spec for review and hand-off | `assets/hmi-spec-template.md` — fill it; it's a form, not a source of domain rules |
| Verifying a built HMI against its spec (workflow step 11) | `assets/designReportReadback.m` (copy verbatim; see step 11); key contract in `assets/design-report-schema.json` |
| Picking widgets for a list of nodes | `references/widget-selection-flowchart.md` |
| Designing screen structure or choosing colors | `references/color-and-layout-rules.md` |
| Wiring alarm bands at source or the persistent banner | `references/alarm-patterns.md` |
| Configuring a trend (window, YLim, threshold lines) | `references/trend-config-reference.md` |
| Adding a writable setpoint with confirm + flash feedback | `references/write-safeguards-reference.md` |
| Wrapping an OPC UA Explorer / Modbus Explorer / MQTT script — invoking OPC UA method nodes — or hitting protocol-specific bugs | `references/protocol-cheatsheet.md` |
| Wrapping an OSI / AVEVA PI Data Archive script (`piclient`, `tags`, `read`) or a PI AF script (`afclient`, `getRootElements`, `getAttributes`, `Attribute.read`/`readHistory`) | `references/pi-af-cheatsheet.md` |
| Browsing an unknown server and inferring widgets at runtime | `references/server-agnostic-discovery.md` |
| Hard-wiring a known node-to-widget schema | `references/known-schema-patterns.md` |
| Construction errors (`struct` props, `classdef` ordering, listener leaks, `AccessLevelCurrent`) | `references/app-designer-gotchas.md` |
| Handing the approved spec to `matlab-build-app`, picking components/behaviors to fill it, or editing an existing app | `references/app-designer-handoff.md` |
| Debugging a specific error, silent failure, or anti-pattern | **Grep** `references/common-mistakes.md` for the error text or anti-pattern (it has an index table) — read only the matching entry, not the whole file |
| Checking whether a function exists in the user's release, or which toolbox ships it | `references/key-functions.md` — `manifest.yaml` carries the product requirement |
---
Copyright 2026 The MathWorks, Inc.
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |