Mode control

Who it’s for

Dashboard authors and installers who want one tap to change a device’s mode ask “how do I let someone switch this to Heat without opening a raw attribute editor?” They are often handing the dashboard to an operator or a tenant, who should be able to change the mode without learning about attribute scopes, and should never have to type a raw value.

What it does

An air conditioner reporting mode:"2" shows Heat selected. Tapping Fan sends setMode with the value configured for Fan. If a schedule changes the mode a minute later, the button follows the device back on its own.

• Any set of modes, each with its own label, the value the device actually receives, an icon and a color — ships as a six-mode air conditioner, but works for anything with a fixed set of states
• Four ways to draw them — buttons with labels, round icon buttons, square icon buttons, or a switch between two modes
• Follows the device live through its own subscription, so a change made by a schedule, a rule chain or a wall panel shows up without the card asking
• Buttons size and arrange themselves to fill the card; a label that won’t fit gives way to its icon instead of being cut off
• Writes a device attribute or sends a one-way RPC command, shaped by a built-in preset or a function of your own
• Optional queueing for an offline device, with retries
• Switches one device between modes; it doesn’t schedule them or keep a history of who changed what

How to set up

Data keys

This is a control widget: it takes no data keys. Choose a Target device in the widget configuration — everything the widget reads and writes goes to that one device.

Attribute	Scope	Operation	Description
Attribute holding the mode (mode by default)	Shared or Server	Read + Write	Subscribed to live, so the card follows the device, and written back when a mode is picked. Matched by value, not type — a device reporting the string "2" still matches a mode configured with the number 2

Method	Direction	Parameters	Sent when
RPC method (setMode by default)	One-way	The value of the mode picked, shaped by What the device receives	A mode is picked

If the device reports a value that isn’t on the mode list, no button is shown as selected and nothing is written until a mode is picked here. If the attribute has never been written at all, every button stays enabled and the first tap sets it.

What the device receives shapes the RPC parameter: an object like {"value": "heat"} with a parameter name you set, the value alone, or a custom Payload function(value). The function receives one argument, value — the value of the mode being sent — and returns the object or value to send. Returning nothing, or throwing, is treated as a failed change: nothing is sent and the reason is reported. A function that won’t compile is caught when the card loads rather than on first use.

A one-way command nobody answers is not an error, so a device with no matching handler will appear to accept the change and do nothing. If your device works through shared attributes, switch What a change does over.

Command

Setting	Default	Effect
What a change does	Send a one-way RPC command	RPC command, or attribute write
Request timeout (ms)	5000	Between 100 ms and two minutes. RPC mode only
Queue the command for an offline device	Off	The platform holds the command until the device connects. RPC mode only
Retries	0	Up to ten; only used for a queued command
Read only	Off	Shows the current mode but refuses every tap. Nothing is ever sent

Modes

Setting	Default	Effect
Modes	Six air conditioner modes (cool, heat, fan, dry, auto, off)	The list itself — each entry’s value, label, icon and color. A mode with no value is ignored and a duplicate value is dropped; if nothing usable is left, the shipped set comes back instead of leaving a card with no buttons

Each mode’s Value sent to the device is exactly what the firmware expects — numbers work too. Button label is independent of it, so a button reading “Fan” can send a value of FAN_mode. Colour when selected falls back to the widget’s accent when left empty. Other sets that suit this widget: a door or gate (open/closed, which fits the two-mode switch layout), a fan (off/low/medium/high sending 0 1 2 3), an alarm panel (disarmed/home/away), a water heater (eco/comfort/boost/off), a lighting scene (bright/relax/movie/night), a blind (open/half/closed), an irrigation valve (manual/schedule/rain delay), a pump (auto/manual/off), or an EV charger (idle/charge/limited).

How to customize

Layout & display

• To change how the modes are drawn — set How the modes are drawn: buttons with labels, round icons, square icons, or a switch. The switch needs exactly two modes; with any other number the widget falls back to buttons.
• To restyle the buttons — set Button style: outlined, filled, text only or underlined. The selected button is always filled with its own color, whichever style the rest use.
• To stack the buttons instead of laying them across the card — set Layout. It’s a preference, not a rule: the widget only departs from it when the buttons would otherwise be clipped, spreading over more columns or rows instead of running off the card.
• To hide the labels or the icons — turn off Show labels or Show icons on the buttons. A label that won’t fit its button is dropped anyway, even with this on.

Appearance

• To hide the device name above the buttons — turn off Show the device name; this also hides the three settings below that only serve it.
• To change the name shown on the card — edit Name shown on the card; empty uses the device’s label, then its name.
• To match your dashboard’s color scheme — set Accent — the selected button, Unselected button (clear it to leave those buttons transparent), and Text on the card.
• To recolor the device name after a failed change — set Device name after a failed change; with the name hidden, a failed change is only reported as a toast message instead.
• To match your dashboard’s fonts — set Device name font and Button label font; the button font also applies to the captions under round and square icons.

The card draws no title of its own. The widget’s own Appearance tab still controls the title, background, padding and drop shadow.

What the card shows while a change is in flight

The button moves as soon as you tap it, not once the device confirms — so the card can be ahead of the device for as long as the request takes. If the change fails, the device name turns red until a later one succeeds, and the reason is reported.

Tips

• Two modes with How the modes are drawn set to the switch reads better than two buttons for a simple open/closed or on/off control.
• Give each mode its own color on a climate card — blue for cool, orange for heat — so the active mode is readable at a glance without reading the label.
• A device that’s often offline is a better fit for Write an attribute than a queued RPC command — the attribute waits for it, and nothing has to be queued.
• If a device reports modes your list doesn’t cover, add them rather than leaving the card unable to show a selection for a state the device is actually in.