Mode control

Mode control

A set of buttons for one device’s mode — Cool, Heat, Fan, Dry, Auto, Off, or any set you define. It follows the device live through its own subscription and writes the mode you pick back to the same attribute, or sends it as a one-way RPC command.

Features

• Any set of modes, each with its own label, the value the device actually receives, an icon and a colour
• Four ways to draw them: buttons with labels, round or square icon buttons, or a switch between two modes
• Subscribes to the device, so a change made by a schedule, a rule chain or a wall panel shows up without the card asking
• Buttons size themselves and rearrange to fill the card; a label that will not fit gives way to its icon rather than being cut
• Writes a device attribute or sends a one-way RPC command, shaped by a preset or your own function
• Optional queueing for an offline device, with retries
• Read-only mode

Target device

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

One attribute, read and written, in one scope. The name and the scope are configurable; the table shows the defaults.

Attribute	Type	Read as	Written when
mode	string or number	whatever the device reports, matched against the mode values	a mode is picked

The match is on the value, not its type: a mode whose value is the number 2 still matches a device reporting the string "2". If the device reports something that is not on the list, no button is shown as selected and nothing is written.

Attribute scope offers Shared — the scope a device subscribes to — and Server, which keeps the value on the platform for a rule chain to act on. Client scope is deliberately not offered: only the device itself can write there.

RPC method

Used when What a change does is set to Send a one-way RPC command, the shipped default.

Method	Type	Parameters	Sent when
setMode	one-way	the value of the mode picked	a mode is picked

What the device receives shapes the parameters:

Option	Sent
An object	{"value": "heat"} — the parameter name is configurable
The value alone	"heat"
A function of yours	whatever it returns

The function receives one argument, value: the value of the mode being sent. Returning nothing, or throwing, is treated as a failed change — nothing is sent and the reason is reported. A function that will not 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.

Modes

Each mode carries four things:

Field	What it is
Value sent to the device	Exactly what the firmware expects. Numbers work too
Button label	What the card shows. Independent of the value — a button reading Fan can send FAN_mode
Icon	Any icon from the picker, including the mdi: set
Colour when selected	Empty falls back to the widget accent

A mode with no value is ignored and a duplicate value is dropped. If nothing usable is left, the shipped set comes back rather than leaving a card with no buttons.

Some sets that suit this widget:

• Air conditioner — cool / heat / fan / dry / auto / off, which is what it ships with
• Door or gate — open / closed: two modes, so the switch appearance fits
• Fan — off / low / medium / high, sending 0 1 2 3
• Alarm panel — disarmed / home / away
• Water heater — eco / comfort / boost / off
• Lighting scene — bright / relax / movie / night
• Blind — open / half / closed
• Irrigation valve — manual / schedule / rain delay
• Pump — auto / manual / off
• EV charger — idle / charge / limited

How the buttons are arranged

Layout is a preference, not a rule. The widget works out how many buttons fit across the card and how many lines fit down it, and only departs from the layout you asked for when the buttons would otherwise be clipped: six stacked buttons on a card too short for them spread over two or three columns instead of disappearing off the bottom.

Round and square buttons take their size from the card, and their icons grow with them. When the card gets too small, the captions are dropped first, then the device name, before the buttons themselves are allowed near their minimum.

The switch needs exactly two modes. With any other number the widget falls back to buttons.

Configuration

Every explanation sits behind the question mark beside its field. Fields that cannot apply are hidden: choose an attribute and the RPC method, payload shape, timeout, queueing and retries all disappear; hide the device name and the settings that only paint it go with it.

Command

Setting	Default	What it does
What a change does	Send a one-way RPC command	RPC command, or attribute write
RPC method	setMode	Handler the device implements
What the device receives	An object	Payload shape
Parameter name	value	Field the value is sent under
Payload function(value)	return { value: value };	Used only for the custom payload shape
Request timeout (ms)	5000	100 ms to two minutes
Queue the command for an offline device	off	The platform holds the command until the device connects
Retries	0	Up to ten; only sent for a queued command
Read only	off	Shows the mode but refuses every tap

Attribute

Setting	Default	What it does
Attribute holding the mode	mode	Subscribed to, and written back to
Attribute scope	Shared	Shared or Server, for both directions

Modes

Setting	Default	What it does
Modes	six air-conditioner modes	The list itself: value, label, icon and colour each
Show labels	on	A label that will not fit its button is dropped anyway
Show icons on the buttons	on	Only modes that have an icon show one

Layout

Setting	Default	What it does
How the modes are drawn	Buttons with a label	Buttons, round icons, square icons, or a switch
Button style	Outlined	Outlined, filled, text only or underlined — the selected button is always filled with its own colour
Layout	Across the card	Across the card, or one under another

Appearance

Setting	Default	What it does
Show the device name	on	Hiding it also hides the three settings below that only serve it
Name shown on the card	empty	Empty uses the device’s label, then its name
Accent — the selected button	empty	Empty follows the ThingsBoard theme’s primary colour
Unselected button	#FFFFFF	The fill behind a mode that is not active. Clear it to leave those buttons transparent
Text on the card	#212121	The device name and the labels on unselected buttons
Device name font	15px Roboto 400	Size, family, weight, style and line height
Button label font	13px Roboto 500	The same, for the button labels and the captions under icons
Device name after a failed change	#C62828	With the name hidden, a failed change is only reported as a message

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.