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 |
references/write-safeguards-reference.md
View on GitHub# Write Safeguards Reference
Industrial HMIs control physical equipment. Every write path must have safeguards — bounded input, visible range, explicit confirm, visible feedback. Treat every `writeValue()` as if a typo could damage equipment.
## The five required safeguards
1. **No direct inline editing of live values.** A live readout and a setpoint are different widgets. The setpoint shows the *target*, not the current value.
2. **Confirm before write.** `uiconfirm` dialog showing node, old, new, units. The default option is **Cancel**, not Apply.
3. **Display min/max bounds.** A `uilabel` adjacent to the field showing the valid range, in addition to `Limits` enforcement.
4. **Visual feedback on success/failure.** Brief background flash — **desaturated** green `[0.7 1 0.7]` on success, **desaturated** red `[1 0.7 0.7]` on failure — reverting to the component's original face after ~0.4 s. Operator must never be uncertain whether the write took effect. Use the pastels, **not** the saturated `[0 0.6 0]` / `[0.85 0 0]` pair: those two are the ISA-101 *exception* colors, reserved for real alarm state, and a control that borrows them competes with the alarm it should be making stand out. This is precisely why flashing a **button** face stays compatible with the neutral-command-button rule — the flash is transient and desaturated, so the button is still chrome. See `color-and-layout-rules.md`, "Command buttons and controls are neutral".
5. **Separate read and write areas.** Setpoint controls live in their own panel (right side or bottom row), distinguishable by background color or border. Never inline a setpoint inside a live-readout grid.
## Pattern A — Bounded numeric setpoint with confirm and feedback
```matlab
% --- Construction (in createComponents) ---
spnr = uispinner(panel, ...
'Limits', [0 250], ...
'Step', 1, ...
'Value', app.CurrentSetpoint, ...
'ValueDisplayFormat', '%d °C', ...
'BackgroundColor', [1 1 1]);
rangeLbl = uilabel(panel, ...
'Text', 'range: 0 - 250 °C', ...
'FontSize', 10, ...
'FontColor', [0.3 0.3 0.3]);
sendBtn = uibutton(panel, ...
'Text', 'Send', ...
'ButtonPushedFcn', @(b,e) sendOvenSetpoint(app, spnr));
```
```matlab
% --- Callback ---
function sendOvenSetpoint(app, spnr)
oldVal = app.CurrentOvenSetpoint;
newVal = spnr.Value;
if newVal == oldVal
return % nothing to do
end
msg = sprintf(['Write OvenTemp setpoint:\n\n' ...
' node: OvenTemp\n' ...
' old: %d °C\n' ...
' new: %d °C\n' ...
' range: 0 - 250 °C'], oldVal, newVal);
sel = uiconfirm(app.UIFigure, msg, 'Confirm setpoint', ...
'Options', {'Apply', 'Cancel'}, ...
'DefaultOption', 'Cancel', ...
'CancelOption', 'Cancel', ...
'Icon', 'warning');
if sel == "Apply"
try
writeValue(app.UAClient, app.OvenSetpointNode, newVal);
app.CurrentOvenSetpoint = newVal;
flashFeedback(spnr, [0.7 1 0.7]); % green flash
catch ME
spnr.Value = oldVal; % revert UI
flashFeedback(spnr, [1 0.7 0.7]); % red flash
uialert(app.UIFigure, ME.message, 'Write failed');
end
else
spnr.Value = oldVal; % cancel reverts UI
end
end
```
## Pattern B — Visual feedback flash
```matlab
function flashFeedback(component, flashColor)
originalColor = component.BackgroundColor;
component.BackgroundColor = flashColor;
drawnow;
pause(0.4);
component.BackgroundColor = originalColor;
end
```
For a non-blocking variant, use a one-shot `timer`:
```matlab
function flashFeedbackAsync(component, flashColor)
originalColor = component.BackgroundColor;
component.BackgroundColor = flashColor;
t = timer('ExecutionMode','singleShot','StartDelay',0.4, ...
'TimerFcn', @(~,~) revert(component, originalColor), ...
'StopFcn', @(self,~) delete(self));
start(t);
end
function revert(component, color)
if isvalid(component)
component.BackgroundColor = color;
end
end
```
Prefer the async variant if the callback shouldn't block — under high-frequency setpoint writes the synchronous `pause` stalls the event loop.
## Pattern C — Apply-all with diff summary
When the operator changes multiple setpoints and presses one Apply button, the confirm dialog shows the **diff** of every changed value, not a single line.
```matlab
function applyAllSetpoints(app)
pending = struct();
pending.OvenTemp = struct('Old', app.CurrentOvenSetpoint, ...
'New', app.OvenSpinner.Value, ...
'Units', '°C', ...
'Node', app.OvenSetpointNode);
pending.RobotSpeed = struct('Old', app.CurrentRobotSpeed, ...
'New', app.RobotSpeedSpinner.Value, ...
'Units', '%', ...
'Node', app.RobotSpeedNode);
% ...etc
fields = fieldnames(pending);
changed = fields(arrayfun(@(i) pending.(fields{i}).New ~= pending.(fields{i}).Old, ...
1:numel(fields)));
if isempty(changed)
return
end
lines = arrayfun(@(i) sprintf(' %s: %g → %g %s', changed{i}, ...
pending.(changed{i}).Old, ...
pending.(changed{i}).New, ...
pending.(changed{i}).Units), ...
1:numel(changed), 'UniformOutput', false);
msg = sprintf('Apply %d changes:\n\n%s', numel(changed), strjoin(lines, newline));
sel = uiconfirm(app.UIFigure, msg, 'Apply setpoints', ...
'Options', {'Apply All', 'Cancel'}, ...
'DefaultOption', 'Cancel', 'CancelOption', 'Cancel', 'Icon', 'warning');
if sel == "Apply All"
for i = 1:numel(changed)
p = pending.(changed{i});
writeValue(app.UAClient, p.Node, p.New);
app.(['Current' changed{i}]) = p.New;
end
flashFeedbackAsync(app.ApplyButton, [0.7 1 0.7]);
end
end
```
## Pattern D — Safety-critical actuation (E-Stop, motor toggle)
E-Stop is the canonical example. **Confirmation is required even though it feels redundant** — accidental clicks on a touchscreen are the threat, not malice.
```matlab
estopBtn = uibutton(panel, 'state', ...
'Text', 'EMERGENCY STOP', ...
'BackgroundColor', [0.85 0 0], ...
'FontColor', [1 1 1], ...
'FontWeight', 'bold', ...
'ValueChangedFcn', @(b,e) onEStopToggle(app, b, e));
function onEStopToggle(app, btn, evt)
if evt.Value % pressed
sel = uiconfirm(app.UIFigure, ...
'Trigger EMERGENCY STOP? All actuators will halt.', ...
'Confirm E-Stop', ...
'Options', {'STOP', 'Cancel'}, ...
'DefaultOption', 'Cancel', ...
'CancelOption', 'Cancel', ...
'Icon', 'error');
if sel == "STOP"
writeValue(app.UAClient, app.EStopNode, true);
else
btn.Value = false; % revert toggle
end
else % released
sel = uiconfirm(app.UIFigure, ...
'Release E-Stop and resume?', 'Confirm release', ...
'Options', {'Resume', 'Cancel'}, ...
'DefaultOption', 'Cancel', ...
'CancelOption', 'Cancel', ...
'Icon', 'warning');
if sel == "Resume"
writeValue(app.UAClient, app.EStopNode, false);
else
btn.Value = true; % revert toggle (stay stopped)
end
end
end
```
## Disable writes when the system can't accept them
When E-Stop is active, the disconnected, or the alarm state forbids writes, **disable the controls** rather than letting them fail mid-write:
```matlab
function refreshWriteEnable(app)
canWrite = app.IsConnected && ~app.EStopActive;
app.OvenSpinner.Enable = canWrite;
app.RobotSpeedSpinner.Enable = canWrite;
app.ApplyButton.Enable = canWrite;
end
```
Call this in the connection state-change handler and the E-Stop callback.
## Common mistakes specific to writes
| Mistake | Fix |
|---------|-----|
| Single Apply button writes all 4 setpoints with no confirm | One Apply button + confirm dialog showing the diff |
| `Limits` set on the spinner but no adjacent range label | Add `range: lo - hi units` `uilabel` next to every writable field |
| Write succeeds but operator can't tell — no UI feedback | Desaturated background flash that reverts after ~0.4 s: `[0.7 1 0.7]` ok, `[1 0.7 0.7]` fail (or a `Status: Sent` label). Never saturated green `[0 0.6 0]` / red `[0.85 0 0]` — reserved, and a face left recolored reads as status |
| Catch error, swallow it silently | `uialert` with the underlying message + revert UI to the old value |
| E-Stop toggles without confirm | Confirm both engage and release |
| Reading `Value` from the writable spinner to display the live node value | Live readouts and setpoints are separate widgets |
----
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 |