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 |
assets/hmi-spec-template.md
View on GitHub# HMI Spec — {AppName}
Spec-Format: hmi-spec/1
Review status: UNREVIEWED
Standard: ISA-101 gray-field · Target: {AppName}.mlapp (fallback {AppName}.m)
<!--
HOW TO FILL THIS FORM
- Copy it to {AppName}-hmi-spec.md beside the app, then replace every {braced} slot.
- One row per signal and per component. No MATLAB code, no rationale prose — this is a form,
not a guide. Component choices come from references/app-designer-handoff.md; property values
come from references/color-and-layout-rules.md.
- Sections 1, 2 and 3 are what the human reviewer reads. Sections 4-6 are fixed boilerplate.
Sections 7-8 are the build payload.
- Stamp "Review status: APPROVED {YYYY-MM-DD}" only after the user actually approves.
- Do not rename or reorder the headings or the three lines above — they are a parsed contract.
SECTION ORDER IS DELIBERATE — DO NOT "TIDY" IT
Sections 1-6 are a fixed size no matter how big the HMI is — measured at 7.3 KB filled.
Section 7 grows with the number of behaviours (not widgets); section 8 grows with the number
of components, so it is the one that really scales.
That ordering is the whole point: reviewers and automated graders read a capped prefix of this
file (10,000 bytes in the eval harness), so everything that must survive truncation — the signal
inventory, the open questions, the palette, the self-audit — is placed ahead of anything that
grows. Moving Components earlier puts the graded tokens back behind the cut: the first spec filled
from this template had its trend-append call fifty bytes from vanishing.
Treat section 8 as unreadable by a grader. On a five-signal HMI it starts near byte 13,200, so
all of it is past the cap. That is fine for a real consumer, which reads the whole file — but
it means every compliance claim must ALSO be recorded in section 5's self-audit, which is where
a grader can actually see it. Count bytes on disk, not characters: CRLF line endings add one
byte per line, which is 160+ bytes on a filled spec.
WHAT THE 10 KB NUMBER IS ACTUALLY FOR — AND WHY IT IS NOT A SIZE TARGET
It is a *grading* constraint. A consumer of this file (matlab-build-app, or a human) reads all of
it; only the eval harness truncates, at 10,000 raw bytes per file. A complete spec for a
five-signal HMI measures ~18 KB, so do not try to squeeze the whole file under 10 KB. That target
is unreachable once section 7 names every data-path call and section 8 carries container
placement, and chasing it deletes exactly the detail a cold builder cannot do without.
THE INVARIANT THAT REPLACES IT: every claim a grader might check appears before byte 10,000.
Sections 1-6 and the front of section 7 — the data-path calls and the behavior table — land inside
it; the App state tail and the whole of section 8 do not. Two consequences, both deliberate:
a rule stated in section 8 must ALSO be stated in section 4 or ticked in section 5, and the
data-path calls are a table at the TOP of section 7 rather than prose at the bottom. That is why
the trend-append call sits at byte 3,372 (section 4's trend rule) instead of 8,616 buried in a
wiring paragraph. Repeating a value between an early section and a late one is the mechanism here,
not redundancy to be tidied away — section 4 is the single place that resolves it, so the two
cannot disagree.
Trim in this order of payoff anyway, to keep the graded prefix roomy:
- No separate label row per widget. Fold it into the widget's own row: `label '{Name} 0-250 °C'`.
- In sections 7 and 8, name palette colors by role — `ScaleColors {normal, warn, crit}` — instead
of repeating triplets. Section 4 resolves the role words, so a cold reader still gets literal
values, and the values cannot drift between sections.
- One clause per behavior trigger in section 7, not a paragraph. The data-wiring contract is
the one place extra detail is worth its bytes.
- Drop the `Screen` column from sections 2 and 8 on a single-screen HMI.
- No sub-headings beyond those below, no code fences, no restating section 4 or 6 in prose.
-->
## 1. Purpose
- **Process / station:** {one line a plant engineer recognizes}
- **Question the screen answers:** {"is anything wrong in the boiler house?"}
- **Screens:** {Overview | Area: A, B | Detail} — drill-down level(s)
- **Data source:** {OPC UA endpoint | Modbus host+unit | MQTT broker+topics | PI server+tags | AF database+path}
- **Update mechanism:** {subscribe | poll every N s}
Anything the operator supplies at **runtime** — endpoint URL, credentials, a pump command node
name — needs a home even when its value is unknown: an input component in section 8, or an App
state row in section 7 naming where it comes from. Listing it in section 3 is not a substitute for
the slot. A spec with an open question and no slot produces an app that cannot be pointed at a
server.
## 2. Signal inventory
| Signal (source name) | Kind | Range + units | Warn L / H | Alarm LL / HH | Writable | Screen |
|---|---|---|---|---|---|---|
| {DrumTemperature} | {analog} | {0-250 °C} | {- / 200} | {- / 230} | {no} | {Boiler} |
Use the **source's own names**, exactly as the server or script reports them — never invent
friendlier labels. `Kind` is one of `analog` / `binary` / `enumerated` / `analog (no range)`.
Anything you do not know goes in section 3 as a question; do **not** fabricate a range or
threshold.
## 3. Open questions for the reviewer
- {thresholds, ranges, units or node names the user must confirm — "none" is a valid answer}
Placed here, third, because it is the reviewer's whole job: section 2 is what was assumed,
this is what has not been confirmed. An unknown left blank here is correct; an unknown quietly
filled in above is the failure this section exists to prevent.
## 4. Fixed design values — do not substitute
- Figure: `Color` `[0.78 0.78 0.78]` **and** `Theme` `light` — both, always.
- Panels / secondary zones: `[0.86 0.86 0.86]`.
- Palette — the role words used in sections 7 and 8 resolve to exactly these, and nothing else:
normal/idle gray `[0.5 0.5 0.5]`, warning amber `[1 0.7 0]`, critical red `[0.85 0 0]`,
comms blue `[0.4 0.6 1.0]`, verified-OK green `[0 0.6 0]`, stale magenta `[0.6 0.2 0.7]`,
primary text `[0.10 0.10 0.10]`, secondary text `[0.30 0.30 0.30]`. Never free-hand a color.
Green is reserved for operator-verified-OK; connection and running states are blue.
- Command buttons are neutral-faced `[0.86 0.86 0.86]`. Run state lives on a lamp, never on the
button. The only permitted colored flash is the desaturated write acknowledgement
(`[0.7 1 0.7]` ok / `[1 0.7 0.7]` fail), reverting after ~0.4 s.
- Gauge normal band is neutral gray, never green. Any gauge carrying bands has `Limits` covering
every `ScaleColorLimits` row — a band outside `Limits` is silently clipped.
- Trends: fixed `YLim` from the sensor spec (never autoscale), a unit y-label and time x-label,
threshold `yline`s at the source gauge's warn/alarm values when the signal is alarmed, and the
axes toolbar hidden with default interactions removed — an operator who pans or zooms a live
trend silently defeats the fixed `YLim`. The last of these is **startup code, so it belongs on a
section 7 behavior row, not in section 8** (see the section 8 note on composite properties).
Points are appended with `addpoints` on an `animatedline` — never `plot()`, never a direct
`XData`/`YData` assignment.
- Any widget whose `BackgroundColor` changes with state sets `FontColor` in the **same** change:
white `[1 1 1]` on critical red and on comms blue, primary text `[0.10 0.10 0.10]` on warning
amber and on the panel face. The alarm banner is the one that matters — left at its default,
near-black text on saturated red is barely readable across a control room.
- `FontColor` is the property name on Label/Button/Spinner; `uitable` and `uipanel` spell it
`ForegroundColor`; a Lamp has no `BackgroundColor` at all.
- Quantity caps: at most 6 gauges, 4 trend axes, 12 numeric readouts, and 5 saturated-color
elements **that the design chooses**. Fixed MATLAB chrome does not count, because it cannot be
designed away: a `LinearGauge` needle draws saturated red at every value, including inside its
neutral-gray normal band, and none of its public properties recolors it. Count the banner, lamps,
and any face or text color you assign. Do not count needles, and do not weaken a band to buy
headroom against one. Two counting rules settle the ambiguous cases: **one gauge's `ScaleColors`
counts as one element** however many bands it carries — a 3-band gauge is the single decision
"this signal is alarmed", not three — and **the comms lamp's blue is outside the budget**, because
it reports communication health rather than alarm state and the cap exists to keep alarm color
scarce.
## 5. Compliance self-audit
Tick every box before presenting the spec. A build check confirms loadability, not HMI
correctness — every violation below still saves cleanly. Fix the **spec**, not a built app.
These ticks are the **author's** claim and are independent of `Review status`, which records the
*user's* sign-off — a fully ticked audit above `UNREVIEWED` is normal, not a contradiction. But a
tick with no supporting row in sections 4, 7 or 8 is a false statement rather than an aspiration.
Check each box against the rows, including any count written beside it.
- [ ] `Theme='light'` set on the figure, not just `Color`
- [ ] Command buttons/controls are neutral gray — no green Start, no red Stop; run state on a lamp
- [ ] Only ISA-101 palette colors used — no free-handed reds or greens
- [ ] Connection/running indicators are blue or gray, not green
- [ ] Gauge normal band is neutral gray, and every banded gauge's `Limits` cover all its bands
- [ ] Alarm banner spans row 1 and is present even with no alarms
- [ ] Every trend has a fixed `YLim`, a unit y-label + time x-label, threshold `yline`s if alarmed, and no interactive pan/zoom toolbar
- [ ] Write controls sit in a secondary zone, not the centre visualization
- [ ] Quantity caps respected (section 4)
- [ ] Like-typed analogs use like widgets
- [ ] Every writable field has a range label and confirm-before-write, default option Cancel
- [ ] Any widget that recolors by state sets `FontColor` alongside `BackgroundColor`
- [ ] Section 7 names the exact call for every step of the data path
- [ ] Every timer, client, subscription and line handle has an App state row
- [ ] Teardown runs on figure close **and** on `delete(app)`, stopping every timer
- [ ] Latched alarm severity, if used, has an Acknowledge control in section 8
## 6. Build parameters
Pre-answered so no build discovery is needed.
| Parameter | Value |
|---|---|
| Architecture | UIFigure — an industrial HMI is never UIHTML |
| Serialization | {App Designer .mlapp / plain-text .m+.xml (R2026b+) / programmatic .m (fallback)} |
| Layout archetype | {Dashboard (plant overview) / Tabbed (multi-area) / Explorer (drill-down)} — {one sentence on the spatial arrangement} |
| Purpose / users | plant operators monitoring {process} on a control-room screen |
| Lifespan | maintained — operator-facing, long-lived |
| Visual polish | standard components are sufficient. Do not apply a theming skill or restyle anything — every color is fixed by section 4, and that includes setting the figure's `Theme` to `light`, which is a required value and not a theme to be substituted |
| Team | MATLAB-only |
| Periodic work | {N} s polling timer + alarm flash — scheduled, cheap-per-tick work that must update the UI on the main thread. **Not** background-task work. Use `ExecutionMode='fixedSpacing'` with `BusyMode='drop'`; this **overrides** any generic timer guidance the builder's own references carry (`fixedRate`/`queue`), because a skipped banner refresh is correct and a queued backlog of stale ones is not |
| Long-running work | {none} |
| MATLAB release | {R2023b+} |
## 7. Behaviors
### Data-path calls
Name the **exact call** for every step, arguments in order. The builder has this file and nothing
else — it cannot see the protocol references, so an unnamed step becomes a guessed API, and a
guessed API is a silent runtime failure in an app that still builds and still looks right. Write
`n/a` for a step the design genuinely does not use.
| Step | Call |
|---|---|
| Open | {`c = opcua("{host}", {port}); connect(c)`} |
| Resolve a name to a node | {`n = findNodeByName(c.Namespace, "{name}", "-once")`} |
| Subscribe / read | {`sub = subscribe(c, nodes, @app.onDataChange)` / `read(c, n)`} |
| Callback signature | {`onDataChange(app, sub, notification)`; `notification.Node.Name`, `.Data.Value`} |
| Write | {`writeValue(c, n, value)`} |
| Append to a trend | {`addpoints(app.{Line}, x, y)`} |
| Close | {`disconnect(c)`} |
### Behavior table
| Behavior | Wiring role | Trigger | What it does |
|---|---|---|---|
| Confirm-before-write | event handler on {FlowSetpoint} | value changed | `uiconfirm` echoing node / old / new / units, default option Cancel; pastel flash on apply |
| Live data | method invoked by handle | {subscribe data-change / timer tick} | {update gauge, band state, banner, trend} |
| Teardown | event handler on the figure **and** the app's own `delete` | figure `CloseRequestFcn` AND `delete(app)` | both entry points call one shared teardown helper: stop and delete every timer, drop the subscription handle, disconnect the client. Wired to `CloseRequestFcn` alone it leaks timers whenever the app is deleted programmatically — which is how every test, script and eval closes it |
State the **data-wiring contract** explicitly on the live-data row: the update mechanism
(subscription vs polling timer and its period), the callback's argument shape, how one
notification is dispatched to the right signal, and the call used to append to a trend.
### App state
| Name | Holds | Initialized |
|---|---|---|
| {Client} | protocol client handle | on connect |
| {Subscription} | subscription handle, persisted so it is not garbage-collected | on connect |
| {AlarmState} | per-signal **active** severity — escalates while the value is out of limits, clears when it returns to normal | startup |
| {BannerTimer} | {N} s banner-refresh `timer` | startup |
**Every timer, client, subscription and `animatedline` handle needs a row**, including a
short-lived write-acknowledgement flash timer. An unlisted handle is a local variable that MATLAB
garbage-collects mid-run, and an unlisted timer is one teardown cannot find.
Write **latched** only if section 8 carries an Acknowledge button and section 7 an acknowledge
behavior row. Latching means the severity survives the value returning to normal, so with no ACK
control the banner holds its worst color for the rest of the session. Latch-with-Acknowledge is the
ISA-18.2 pattern and is right for an alarm an operator must not miss
(`references/alarm-patterns.md` Pattern C); the active severity above is the simpler default. Pick
one deliberately — never the word without the button.
## 8. Components
| Name | Type | Properties (values) | Position | Screen |
|---|---|---|---|---|
| UIFigure | UIFigure | `Color` [0.78 0.78 0.78]; `Theme` light; `Name` '{title}' | root | all |
| MainGrid | GridLayout | `BackgroundColor` [0.78 0.78 0.78]; rows {28,'1x',160} x {1} col | on figure | all |
| AlarmBanner | Label | `Text` 'SYSTEM NORMAL'; `FontWeight` bold; `HorizontalAlignment` center; `BackgroundColor` [0.86 0.86 0.86] -> critical on active alarm; `FontColor` [0.10 0.10 0.10] -> [1 1 1] whenever the face goes critical | row 1, cols {1-3} | all |
| {PumpLamp} | Lamp | `Color` normal idle -> comms when {FeedPumpRunning} is true; label '{FeedPumpRunning} — Stopped' in secondary text | in {ControlPanel} | {Boiler} |
| {FlowSetpointSpinner} | Spinner | `Limits` {[0 50]}; `Step` {0.5}; `BackgroundColor` panel face; label '{FeedwaterFlowSetpoint} 0-50 m³/h' in secondary text | in {ControlPanel} | {Boiler} |
| {DrumTempGauge} | LinearGauge | `Limits` {[0 250]}; `ScaleColors` {normal, warn, crit}; `ScaleColorLimits` {[0 200; 200 230; 230 250]}; label '{DrumTemperature} 0-250 °C' | row {2}, col {1} | {Boiler} |
**Row order, and why it is not alphabetical or spatial:** figure, layout, alarm banner, lamps and
indicators, write controls, *then* gauges, trends and decoration. The rows an ISA-101 reviewer
checks hardest — is the banner in row 1, is the running lamp blue rather than green, does the
writable control sit in a secondary zone — come first, and the section that grows with the app
(one more gauge, one more readout) grows at the end, where a truncated read costs least.
**Section 8 rows carry only directly-assignable properties** — a scalar, string, or array written
straight onto the component. Anything that is a **nested or composite property** (`Toolbar.Visible`,
`Interactions`, `Layout.Row`, axis labels applied with `xlabel`/`ylabel`) is **startup code and
belongs on a section 7 behavior row instead.** An App Designer `.mlapp` build sets section 8 rows as
design-time component properties, and a composite one fails the save outright — `Toolbar` is a handle
to an `AxesToolbar`, so it errors with `MATLAB:class:RequireClass`, *Value must be
'matlab.graphics.Graphics'*. The programmatic `.m` path would have accepted it, so this breaks one
consumer and not the other: put it in section 7 and both paths work.
Names are PascalCase and unique. `Position` is written as `row R, col C` or `row R, cols C1-C2`.
A component inside a Panel is written `in {Panel}, row R`: a Panel has no grid of its own, so the
builder adds one `GridLayout` per Panel, and R is that grid's row counted top to bottom. Placement
left unstated inside a container makes the builder invent both the grid and the order.
**`label '...'` is defined shorthand, not a property.** A Lamp, a LinearGauge and a UIAxes have no
label property, so each `label '...'` clause above means: create a `Label` named `{Widget}Label`,
`Text` as quoted, `FontColor` secondary text, in the cell immediately above its widget. It is
written as a clause instead of its own row only to keep this section short — the component is real,
and naming it here is what stops the builder inventing a name or dropping the caption.
Component types are App Designer short class names. Pick the type and its ISA-101 property
values from the component recipes in `references/app-designer-handoff.md` — prefer
`LinearGauge` for banded analogs; any gauge style renders bands. Role words (`normal`, `warn`, `crit`, `comms`, `stale`) resolve against
section 4.
## 9. Change log
| Date | Change | Why |
|---|---|---|
| {YYYY-MM-DD} | initial spec | {request} |
---
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 |