Device dashboard components

A dashboard for one device model combines the same parts every time: pages under one header with live controls, two polling cohorts, a banner when the device connection is down, and trends of the main readings. @overvis/hmi-workspace-ui exports these parts. The steps to combine them, with examples, are in Build a dashboard for one device model. The live-value hooks they build on are in Live data in dashboards.

API	Responsibility
DevicePresetLayout	Header, live controls, page tabs, connection banner, and diagnostics around a page
useDevicePresetValues	Fast (1 s) and slow (30 s) cohorts for one device, combined summary, and Retry
splitEndpointDiagnostic	Separate the device’s endpoint failure from the rest; used by the hook
DevicePresetHeader	Optional device image, title, subtitle, and a slot for live controls
ParameterLiveControls	variant="compact": one pill with a live dot, last update time, and pause/resume
DeviceEndpointUnavailable	Connection-down banner with Retry or Resume and a link to the endpoint status page
ParameterStateText	A boolean reading as text; with fault, a true value turns destructive
ParameterTrendChart	Hoverable trend of one to four readings in one unit with an optional reference
useParameterUnit	The unit of a bound parameter in the dashboard language
DeviceCommandButton	A command: confirmation, then ordered writes; disabled without write access
useDeviceReadings	Numbers read together, only when all are known, with when the oldest went stale
DeviceSettingsSection	One section of device settings: drafts, checks, confirmation, and ordered writes
DeviceSettingsPage	Settings sections with an index, an intro, and Read again
ThresholdGauge	A live reading against one threshold, such as a trip current
WindowGauge	Live readings against a low and a high limit, either of which may be off
DeviceSettingOutcome	What draft settings do, in a sentence, with an optional gauge
DeviceRelayTest	Switch the device’s output relays from the dashboard to check them
ColdRoomCard	One refrigerated room on any controller
DevicePanel	A card for one part of a page: icon, title, description, action, content
DeviceStatusBar	One row of DeviceStatusBadges for the whole device, with an aside
DeviceKeyFigure	A headline: one value with its last minute, or the three phases side by side
DevicePhaseTable	L1, L2, L3 and an optional total, one row per quantity
DeviceReadingList	Readings as name and value rows, level with the rows of a phase table
DeviceSeriesSwatch	The color of trend series N, so a phase looks the same in tables and charts

The components take their generic copy from the host catalogs (device_preset_* and cold_room_* keys), which dashboards can read with t from @overvis/hmi-workspace-ui/i18n. The catalogs hold no device names, reading labels, or mode names. Device writes follow the write rules and write confirmations.

Layout and polling

DevicePresetLayout takes pages: each has an id, a path within the dashboard (so browser Back returns to the previous page), a tab label, and the readings (fastIds) and settings (slowIds) it polls while open. The first page is home, and an unknown path links to it. The children function renders the open page and receives page, connected, false while the device’s endpoint is down, and readAgain, which reads the open page’s values again.

• optionalIds lists registers that some firmware versions lack. When the device answers a read of only these registers with Modbus exception 2, the layout leaves that failure out of the diagnostics, and isUnsupportedParameterValue(state) is true for those readings. The same answer for any other parameter, such as one bound to the wrong register, is still reported.
• notices renders banners that apply on every page, above the open page, such as a device mode the operator should end. The layout polls only the open page’s fastIds and slowIds, so the values a notice reads must be in every page’s lists.

DevicePresetLayout is built from useDevicePresetValues, DevicePresetHeader with the compact ParameterLiveControls, DashboardPageTabs, DeviceEndpointUnavailable, and ParameterDiagnostics, which are exported separately for a dashboard that needs another frame.

useDevicePresetValues covers one device. fastIntervalMs and slowIntervalMs override the default cadences, and the required live option is the dashboard’s pause state: false disables both cohorts. The connection banner stands for the device’s endpoint; diagnostics of other endpoints stay in otherDiagnostics, so a reading bound to the wrong endpoint is still reported.

Readings and trends

ParameterValueDisplay without children shows a reading as its parameter formats it. useParameterUnit(parameterId, locale) returns the parameter’s unit in the dashboard language; it is empty while the parameter loads and for a parameter without a unit.

ParameterTrendChart takes:

• series: one to four, each a label and useParameterValueHistory points. parameterTrendSeriesList(series) takes the first four of a list, or null for none.
• unit, an accessible label, and an optional reference (value, label), such as a setpoint.
• colorIndex on a series, so it keeps its color when the operator hides others; emphasis, the index of one series to draw bolder while the others are dimmed.
• windowMs (default 60 seconds), fractionDigits (default 1), and gapThresholdMs (default 5 seconds): a longer gap breaks the line.
• followClock (required): when true, the window keeps moving while no samples arrive, so a stalled reading shows as a trailing gap; when false, the window ends at the latest sample.
• summary={false} leaves out the row of latest values above the chart.

Hovering shows the nearest sample of each series. For keyboard and screen reader users the plot is a slider: arrow keys, Home, and End step through samples, and Escape returns to the latest values.

Overview cards

An overview page is a column of cards under a status bar.

• DeviceStatusBar (label, optional aside such as the uptime) holds DeviceStatusBadges. A badge’s tone is ok, warning, fault, off, or unknown; a title mutes it and says, for example, when a stale state was read.
• DeviceKeyFigure shows a headline in a small card: with parameterId, one large value and its unit, plus a sparkline of the last minute with trend; with phases, the values of L1, L2, and L3 side by side. A non-empty unit replaces the parameter’s unit.
• DevicePanel frames other content with an icon, a title, an optional description, and an action at the end of the header. Its id names the card for the assistant.
• DevicePhaseTable takes rows (key, label, the three phases parameter IDs, an optional total, and fractionDigits), a label and a quantityLabel for screen readers, and, with totalLabel, a shaded total column. Tables with the same columns line up.
• DeviceReadingList lists readings with their units as rows of the same height. Values follow the parameter’s formatting unless fractionDigits is given, and show a dash while they cannot be read.

Phases L1, L2, and L3 are trend series 1 to 3: tables, key figures, and ParameterTrendChart mark them with the same DeviceSeriesSwatch colors.

Commands

DeviceCommandButton takes a label, the locale, and steps (paramId and value, written in order; { items } sends several writes in one step). It opens the confirmation of ParameterWriteSequenceDialog.

• children explains the command in the confirmation in place of the list of steps, and secretParameterIds masks values such as a password in that list.
• unlock adds a password field and writes the typed password in a step before the others; see secret in write confirmations.
• steps can be a function, called when the confirmation opens and again when the command is sent, for a value that must be current when written, such as a clock set to the time of sending.
• pressed marks a command whose state the device is already in.
• disabled turns off the button and an open confirmation while the device would not act on the command. A command already being sent reports its result while the button stays mounted.

Device settings

DeviceSettingsSection edits one group of a device’s settings. It takes the setting keys, their bindings (parameter IDs), names in labels, and a specs entry for each key: deviceSettingNumber(min, max, decimals) or deviceSettingChoice(...codes). It shows the values the dashboard already polls and starts no polling of its own. Its children function builds the rows with the section’s row helpers; rows must be built during that call, because the section resets the edits of rows it did not see.

Rows

• number draws a field with the parameter’s unit and the allowed range.
• choice draws segmented buttons or, with style: "select", a drop-down. An option marked readOnly, such as a code set only on the device’s keypad, is shown while it is the device value and never offered.
• switch draws an on/off switch for a setting with two codes (on 1 and off 0 unless given).
• switched puts a choice whose code 0 turns a group off in the group’s header and builds the group’s rows only while it is on.
• readOnly shows the device value with the reason it cannot be changed here.
• custom(key, options, control) renders the dashboard’s own control, such as a time entered in seconds for a setting stored in milliseconds. The control receives value, onChange, onBlur, disabled, invalid, and the id the row’s label points to. layout: "stacked" puts it under the label, and invalidText replaces the generic message.
• keep(key) keeps a setting that the layout writes without a row of its own, such as phases that follow one “same for all phases” entry.

Rows take a hint, and disabledReason disables a setting that the current drafts make irrelevant. optionLabel says how a value reads in the confirmation; its third argument reads the other settings on the same side. units replaces the parameters’ units by key, such as °F while the device displays Fahrenheit.

The children context also has draft(key) (a valid draft or null, for previews), unit(key), changed(key), editable (write access and freshly read device values), and setDraft(key, value), which replaces a draft as if it were typed. onDraftsChange receives draft whenever a draft changes, for another section that follows it.

Checks and confirmation

• Only edits are checked, so a device value outside the range, such as a factory default, does not block other changes. A comma is accepted as the decimal separator.
• validate checks settings against each other, such as a lower limit below an upper one. It returns a message by setting key; messages show on the rows once something is edited and block the confirmation.
• A change bar counts the edits and offers Discard and a confirmation that lists the changes as old → new values.
• While a read of the section’s settings, or of a value named in pendingRead, is in progress, edits continue but cannot be confirmed. A newer reading of a reviewed setting asks for a new review.
• A hidden setting, such as one in a group switched off, returns to the device value, so hidden drafts are never written. While any setting in the section is kept from an earlier read, the section is read-only with a note to read it again.
• A setting whose register the device does not have (Modbus exception 2) shows “Not supported by this device’s firmware”, does not hold back the other settings, and is never written.

Writing

Confirming writes the changes in one request; a failed setting keeps its draft and error. onWritten receives the settings the write acknowledged; the section reads only those again, so a write that changes other settings, such as a mode that resets them, needs its own read.

A device that needs its writes in order takes a plan. It receives the changes (key and item, in the order of keys) and returns steps, each sent as one request and acknowledged before the next. A step that writes none of the changes, such as an unlock or a save to device memory, needs a label, which the confirmation lists in its place without its values. defaultDeviceSettingsWritePlan(changes) is the single step used without a plan. The writes stop at the first step that is not acknowledged: earlier changes count as written, that step’s changes show their failures, and later changes keep their drafts. Before writing, the confirmation checks that every parameter in the plan is writable.

unlock takes the same secret as ParameterWriteSequenceDialog: a masked password field written in a step before the plan. With optional, an empty field adds no step. initialValue prefills the field, and onSent receives the typed text. The section does not store the password.

A device can acknowledge a write and ignore it, for example while it is locked. After a write, the section reads the written settings again and marks a setting whose reading still differs with notKeptMessage, so the message can say how to unlock the device. onVerified receives the settings the device kept and those it did not, and complete: whether every step was acknowledged.

Page, outcome, and gauges

DeviceSettingsPage puts sections beside an index of links (id, title, and icon of each), with the page’s intro and a Read again button (onReadAgain, disabled while not connected). Sections given an unavailable reason are listed under that reason instead of being shown. Without canWrite, the intro says that the operator’s role cannot change values. Inside an @container, the index moves above the sections when the container is narrow.

DeviceSettingOutcome states what the drafts do, next to the settings. Its gauge can show the live reading they act on: ThresholdGauge (a reading, a limit, and a limitLabel) or WindowGauge (readings between optional low and high limits, with noLimitsText when both are off). useDeviceReadings(parameterIds) returns values only when every reading is known, keeps the last complete set while some fail, and returns staleSince when any is kept from an earlier read; a gauge given staleSince shows the reading muted with its time. formatQuantity(value, unit, locale) formats a number with its unit, and formatFixedNumber(value, locale, fractionDigits) at exactly that many places. ParameterStateText and ParameterBooleanBadge with flag also accept a register that reports 0 or 1.

Relay test

DeviceRelayTest lets an installer switch a device’s output relays from the dashboard, through the device’s remote relay control, to check the relays and their wiring. It takes:

• relays: each a key, a label, the boolean stateParameterId of the relay’s state, the commandParameterId that switches it, and optional onLabel and offLabel;
• remote: the setting that hands the relays over (parameterId, testValue, and the normalValue to restore when the previous code is unknown);
• title, description, and the device’s warning for the start confirmation;
• storageKey: required and unique per dashboard and workspace.

The rules an author needs:

• The component starts no polling. Poll the remote setting and every relay’s state and command register while the test is shown.
• Start test needs write access, a connection, fresh readings with no write under way, and a browser that can keep data. It is refused while the relays are already under remote control, since another master may be using it. Starting holds each relay in its current position; the confirmation warns that a relay may switch briefly.
• End test restores the device’s previous remote-control code and each relay’s command register. When the device leaves remote control by itself, the test ends with a note and the command registers are still restored.
• The browser keeps a running test under storageKey, so a reload brings it back with only End test offered. Leaving the page asks to end the test first.
• useDeviceRelayTestActive(storageKey) tells whether this page runs a test, so a page-wide remote-control notice in notices can stay out of its way.

deviceRelayTestStartSteps, deviceRelayTestEndItem, deviceRelayTestAvailability, deviceRelayTestHandedOver, and deviceRelayTestRemoteAcknowledged expose the same rules as functions.

Cold room card

ColdRoomCard shows one refrigerated room on any controller: the room temperature against its setpoint and alarm limits, evaporator and auxiliary probes, compressor, defrost, fan and door states, active alarms under their parameter names, and defrost and on/stand-by commands. It takes name, locale, and bindings, validated by the exported TypeBox coldRoomBindingsType (ColdRoomBindings):

Binding	Meaning
temperature, setpoint	Required: the room probe and the control setpoint
evaporatorTemperature, auxiliaryTemperature	Further probes
compressor, defrost, fans	Equipment states, shown as On or Off
door, standby	True while the door is open; true while the controller is off
heating	True or non-zero in heating mode: a running compressor then reads as heating
alarms	Up to 32 alarm flags; an active one is listed under its parameter name
setpointMinimum, setpointMaximum, differential	Settings for the dashboard’s own editor; the card does not show them
highAlarm, lowAlarm, alarmThresholdsRelative	Alarm thresholds, and the flag that makes them offsets from the setpoint
commands.defrost, commands.on, commands.off	Ordered write steps (parameterCommandStepType from @overvis/hmi-shared/parameter)

Every binding except the first two is optional, and an absent one hides its reading, state, limit, or button, so one card fits controllers with different probes and outputs. Units and number formats come from the parameters; temperatureUnit replaces the temperature unit. The card reads values but does not poll them: coldRoomParameterIds(bindings) returns the readings and states as fastIds and the settings as slowIds for useDevicePresetValues.

A command opens ParameterWriteSequenceDialog with its steps in order, so an unlock or a command timer that a controller needs is a step before the command. Commands are disabled without write access and while the room temperature is missing or stale. On and off follow the stand-by state: only the applicable one is offered once that state is known.

The card’s parts are exported for dashboards that draw their own view: coldRoomStatus ("standby", "defrost", "cooling", "heating", "idle", or null) and coldRoomStatusLabel, coldRoomAlarmLimits and coldRoomAlarmLimitsFromStates (relative thresholds resolved as setpoint plus offset), coldRoomActiveAlarms, coldRoomCommandSteps, coldRoomCommandsAvailable, coldRoomOfferedCommands, and ColdRoomCommands.

Related

• Build a dashboard for one device model
• Live data in dashboards
• Dashboard UI and forms