Matlab Build Industrial Hmi

---
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.1"
---

# 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, or browsing namespaces 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'` and `'Theme', 'light'`.** On a dark-themed MATLAB desktop, child widgets (uigauge, uiaxes, uitable, uieditfield) inherit dark defaults even when the figure colour is set explicitly — gauge bodies and axes go near-black, text becomes unreadable. `Theme='light'` blocks the inheritance; the explicit gray-field `Color` keeps the result gray rather than the bright white that `'light'` would otherwise produce. Neither alone is enough.

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

  See `references/color-and-layout-rules.md` for the full rationale and `references/common-mistakes.md` entry 24 for the visible failure mode if either argument is omitted.
- **Quantity caps per screen:** ≤ 6 gauges, ≤ 4 trend axes, ≤ 12 numeric readouts. Beyond that, use a `uitable`.
- **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 **linear** gauge with thresholds (semicircular/circular/ninetydegree gauges don't support color bands — use linear when alarm bands are needed); persistent top-row banner listing active alarms, color-coded by highest severity; latched state with Acknowledge button. **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.** Background flash green on success, red on failure (revert UI on failure). 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)` 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'`.
- **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.
- **Stop and delete timers** in `delete(app)` or `CloseRequestFcn`. A leaked timer keeps firing after the figure closes with stale handles.

See `references/app-designer-gotchas.md` for full reproductions, the release-aware `AccessLevelCurrent` check, and per-widget subscription patterns.

### App Designer Output

- **Produce a real App Designer app by handing serialization to `matlab-build-app`.** When that skill's `AppDesignerAgentInterface` tool is available (`exist('AppDesignerAgentInterface','class')==8`, i.e. on the path), design the HMI here, then drive its verbs to emit a genuine `.mlapp` (R2025a+) — the default output, which opens in App Designer. Plain-text `.m`+`.xml` is available only on R2026b+ for source control. The architecture question is pre-answered: an industrial HMI is **always UIFigure** (never UIHTML), so skip the parent's architecture and serialization discovery.
- **Fallback when the parent is unavailable:** generate a programmatic `.m` app exactly as these references describe. It runs identically; it just won't open in App Designer. State this to the user.
- See `references/app-designer-handoff.md` for the division of labor with `matlab-build-app`, the hand-off protocol, the HMI→verb mapping (gray-field, alarm gauges, palette, cleanup), and the pre-serialize domain-compliance checklist. That file defers all serialization mechanics — verb API, file-format choice, and lifecycle — to the parent's `references/app-designer/agent-guide-shared.md`.

## 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, and alarms/trends/writes layer on top; serialization to a real App Designer app comes last.

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`.
5. **Configure alarms at source AND in a banner**, latched with Acknowledge. → `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. **Serialize to a real App Designer app.** If `matlab-build-app` is available, hand the design to its `AppDesignerAgentInterface` and emit a `.mlapp` (the default); otherwise emit a programmatic `.m` app. Editing an *existing* App Designer HMI also routes through the parent's `open()`/`inspect()` loop. → `references/app-designer-handoff.md`.
9. **Verify: launch, exercise, close cleanly.** Use `mcp__matlab__evaluate_matlab_code` to instantiate the app and exercise `delete(app)`; confirm no leaked timers, subscriptions, or figures. For a `.mlapp`, confirm `save()` succeeds and `validate()` is empty. If construction fails on a struct or classdef error → `references/app-designer-gotchas.md`.

## Key Functions

| Function | Purpose | Toolbox | Available From |
|---|---|---|---|
| `uigauge('linear'\|'circular'\|'semicircular'\|'ninetydegree')` | Single value, known range | core MATLAB | R2016a |
| `uigauge.ScaleColors` / `.ScaleColorLimits` | Alarm bands at source | core MATLAB | R2018a |
| `uilamp` | Binary state indicator | core MATLAB | R2016a |
| `animatedline` with `MaximumNumPoints` | Rolling trend buffer | core MATLAB | R2014b |
| `addpoints` / `clearpoints` | Trend update / reset | core MATLAB | R2014b |
| `yline` | Threshold or setpoint line on trend | core MATLAB | R2018b |
| `uiconfirm` | Modal write confirmation | core MATLAB | R2017b |
| `uispinner` with `Limits` | Bounded numeric input | core MATLAB | R2016a |
| `uieditfield('numeric','Editable',false)` | Precise read-only numeric display | core MATLAB | R2016a |
| `uitable` | Tabular display for >8 nodes | core MATLAB | R2017b |
| `uitree` + `uitreenode` | OPC UA namespace navigation | core MATLAB | R2017b |
| `opcua` / `connect` | Open OPC UA client | Industrial Communication | R2022a |
| `findNodeByName` / `readValue` / `writeValue` | Browse and read/write nodes | Industrial Communication | R2022a |
| `subscribe(uaClient, nodeList, dataChangeFcn, PublishInterval=...)` | Live node updates (preferred over `timer`) | Industrial Communication | **R2023b** |
| `modbus('tcpip', host, port)` / `read` / `write` | Modbus client and register R/W | Industrial Communication | R2022a |
| `mqttclient(brokerAddr)` / `subscribe(c, topic, Callback=...)` / `write` | MQTT publish/subscribe | Industrial Communication | R2022a |
| `piclient(server, ...)` | OSI / AVEVA PI Data Archive client | Industrial Communication | **R2022a** |
| `tags(piClient, Name=q)` / `read(piClient, tag, DateRange=, Interval=, AggregateFcn=)` | PI tag search, current and archive/aggregated reads (returns table/timetable) | Industrial Communication | R2022a |
| `write(piClient, tag, value, TimeInstance=...)` | PI setpoint write | Industrial Communication | **R2024a** |
| `afclient(server, Database=...)` | PI Asset Framework client | Industrial Communication | **R2026a** |
| `getRootElements` / `getChildren` / `getAttributes` / `findElementByName` / `findElementByPath` / `findElementByTemplate` | AF tree browse → drill-down layout | Industrial Communication | R2026a |
| `read(attr, Unit=...)` / `readHistory(attr, t0, t1, ...)` / `listSupportedUnits` | AF attribute current value, history, units | Industrial Communication | R2026a |
| `timer` (`BusyMode='drop'`, `ExecutionMode='fixedSpacing'`) | Modbus / PI / PI AF poll loop / non-OPC periodic UI work | core MATLAB | base |

## Patterns

Each reference file includes executable code patterns for its topic. Load the relevant reference before writing code — it contains correct calling conventions, constructor arguments, property names, and full callback handlers. See the **References** routing table below.

## Common Mistakes

`references/common-mistakes.md` is a **grep-first lookup table** of 26 documented anti-patterns, each a **Symptom → Wrong → Right → Why** block. Don't load it whole — `Grep` it for the user's error string, or for the anti-pattern via its index table, and read only the matching `### N.` entry. It covers App Designer struct/classdef gotchas, ISA-101 violations (green for "normal", green Start / red Stop command buttons, popup alarms, auto-scaling trends, `uilabel` for numerics, dark-field), and protocol-specific silent failures (Modbus `serverId`/`'precision'` order, MQTT positional callback, MQTT `NaN` from JSON payloads, OPC UA invented node names, OPC UA `evt.Value` vs `evt.Data.Value`, Explorer 3-arg vectorized callback, server-side 1601 timestamps).

## References

| Load when... | Reference |
|---|---|
| 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` |
| Serializing to a real App Designer `.mlapp` via `matlab-build-app`, or editing an existing App Designer 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 |

## Toolbox Dependencies

- **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+).

Verify with `mcp__matlab__detect_matlab_toolboxes` before starting if the user's MATLAB release is unknown.

---

Copyright 2026 The MathWorks, Inc.

---