Matlab Build Industrial Hmi

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.

Copyright 2026 The MathWorks, Inc.