Skip to content

matlab/matlab-agentic-toolkit / skills-catalog/test-and-measurement/matlab-build-industrial-hmi

matlab-build-industrial-hmi

Verified

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.

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.

----
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall