---

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.

  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; rebuild