Control cards let an operator act from a board: start a pump, switch a light, change a set point, save a group of thresholds. A control sends a command from the device profile’s command catalogue. This page explains how to set one up, which commands a board may send, and what the operator sees.
What a board may send
A board sends commands through Send a command to a device. The rules are strict on purpose:
| Rule | Detail |
|---|---|
| Catalogue commands only | The command must be in the device profile’s Commands catalogue. A raw method is refused: “This command is not in the device profile’s catalogue, so it cannot be sent from a board.” |
| Basic tier only | A Privileged or Critical command, and any high-impact command, is refused: “This command cannot be sent from a board: send it from the device console.” |
| Permissions | The operator needs Run widget commands and the permission to send basic commands, and must be allowed to read the device’s telemetry. Otherwise: “You do not have permission to use this control.” |
| Rate limit | At most 30 commands a minute per person. Then: “Too many commands; try again in a minute.” |
| Display screens | Controls are inactive on a display link. |
To add a command to a profile and choose its tier, see Sending commands to devices.
Set up a control
- Customise the board and add a Button, Switch, Slider, Set point or Form.
- In the settings drawer, open the actions (When this control is used, or When Apply is pressed for a set point and a form) and add Run a command.
- Pick the Device (or take it from a board parameter), the Command from that device’s catalogue, and the Control and Value the command takes.
- Choose where each command parameter comes from: A fixed value, A dashboard parameter, The control’s value, The control’s value, scaled, A value map, A form field, or The clicked row’s column.
- For a switch, slider or set point, bind the Current value (or Current state) slot to the device value the command changes, so the card shows what the device has now.
- Select Save.
Until a command is chosen the card says “Choose a command in this widget’s settings (When this card is clicked → Run a command).”
The controls
| Control | Does | Main settings |
|---|---|---|
| Button | Runs its actions when pressed: a command, or any other action such as opening a page. | Layout Button, Tile with icon, Round icon, Floating pill; Button text; Icon; Description (a line saying what it does); style Filled, Outlined, Plain, Underlined; size S, M, L |
| Switch | Reads an on/off value and sends a command on toggle. | Layout; Show the state as Large text, Status pill or Nothing; On text, Off text, Unknown text; an icon per state |
| Slider | Reads a number and sends the new one once, on release. | Minimum 0, Maximum 100, Step 1; horizontal or vertical; tick marks; value position |
| Set point | A number input with Apply, a stepper or a dial. Out-of-range entries are a field error and send nothing. | Type and apply, Minus and plus buttons, Dial with minus and plus; range and step; Show the current value; Apply button text |
| Form | Several fields saved together with one command. | Fields (up to 40): Key, Label, Kind (Number, On / off, Text, One of a list), range, unit, Only when on, Required, Show only, Section; Take the fields from the source; Save button text; Show a reset button |
A form’s command reads the saved values by key: {"$field": "lowThreshold"} in the command’s parameters. Take the fields from the source edits every field the bound record describes when you list no fields.
Toggle buttons
A Button can show as pressed while a condition holds (Pressed when parameter, Pressed when column…), for example a “Manual mode” button that stays pressed while the board’s mode parameter is manual. Not a toggle is the default. A button can also be Enabled only when a parameter matches.
Disable on old data
Disable the control when (switch, slider, set point, form) is The reading is old by default, and can also be The state is unknown. The reason shows in a tooltip. The server still checks everything when the command runs.
Confirmation
A device command from a board asks first, by default. Each Run a command entry has Ask before running, on by default. The operator then sees a dialog “Run
A command can also demand a typed confirmation: the dialog then adds “Type “
Wording: Confirmation question and Confirm button in the control’s settings change the words of the dialog, not the text to type.
Feedback and read-back
| The card shows | Meaning |
|---|---|
| “Sending…” | The command is on its way. |
| “Done.” or “Done: | The device answered; its reply is shown as text. |
| “Sent; waiting for the device.” | The command is queued, for example for a device that is offline with a persistent command. |
| “No answer after 30 seconds. The command may still run; check its target before you try again.” | No answer within 30 seconds. |
| “The command failed.” / “The command was refused.” | The device or the server said no; the reason follows when there is one. |
| “Current: | What the device reports now, from the bound current value. |
Read the current value back from the device rather than trusting the control: a switch that shows On after a toggle shows the device’s reported state once it arrives. Every run is written to the audit log; the command also appears in the device’s command History as sent by A dashboard control.
Commands from tables and drawings
- A table’s Row buttons can run a command that uses a column of the clicked row. See Tables and lists.
- A process drawing’s symbols can run commands. See Commands on symbols.
- A card click never runs a command. Commands run only from controls, row buttons and symbols, behind their confirmation.
Troubleshooting
| What you see | Fix |
|---|---|
| The command is not in the list | It is not in the device profile’s catalogue, or it is not of the Basic tier. |
| “This control is not connected to the device yet.” | The current value slot is empty. Bind it. |
| The control is greyed out | The reading is old or the state unknown (Disable the control when), or you lack the permission. |
| The device never reacts | See Commands do not reach the device. |