Switch

Category: Controls · Sends commands: yes · Reads data: no

Mental model

A Switch is a light switch. It holds a state — on or off — and sends a command each time you flip it. Unlike a Button (a one-shot), a Switch represents a persistent state your device should be in.

When to use it

Turn something on and keep it on (a relay, a fan, a mode)
Any binary state the user sets and the device holds

Settings

General

Widget Title / ID
Initial state — ON or OFF at load
ON text / OFF text · ON label / OFF label — the state text and labels
Show text labels · show icon · icon size

Style

Status color, label color, container shape (pill / rounded / square), plus the common border/font/background controls.

Triggers

A Switch usually needs two triggers — one for on, one for off. Events:

Event	Fires when
`on`	Toggled on
`off`	Toggled off
`toggle`	Either direction (carries the new boolean)
`change`	State changed
`click`	Pressed
(common)	`load`, `ready`, `destroy`, `update`, `visible`, `hidden`

Example — toggle a relay

Triggers:

Trigger 1:  WHEN on  → Current Device → Operate → ON   { "relay": 1 }
Trigger 2:  WHEN off → Current Device → Operate → OFF  { "relay": 1 }

Firmware (Arduino):

device.setUserCommandHandler([](JsonObject &msg) {
  if (!device.findAction(msg, "Operate", "ON").isNull())  digitalWrite(RELAY, HIGH);
  if (!device.findAction(msg, "Operate", "OFF").isNull()) digitalWrite(RELAY, LOW);
});

Reflecting real device state

To make the Switch show the device’s actual state (not just what the user tapped), push the state back from firmware to the Switch’s widget ID:

device.updateWidget(targetId, "relaySwitch", String(isOn ? "on" : "off"));

Script API example

The same interactions from a dashboard script:

widget.on('relaySwitch', 'toggle', (isOn) => {
  widget.setText('stateLabel', isOn ? 'ON' : 'OFF');
  ws.send(context.deviceId, { relay: isOn ? 1 : 0 });
});

Triggers in full

Wiring the on/off commands.

Button

For one-shot actions instead of state.

Designer

Widget Reference

Mental model

When to use it

Settings

General

Style

Triggers

Example — toggle a relay

Reflecting real device state

Script API example

Triggers in full

Button

​Mental model

​When to use it

​Settings

​General

​Style

​Triggers

​Example — toggle a relay

​Reflecting real device state

​Script API example

Triggers in full

Button

Mental model

When to use it

Settings

General

Style

Triggers

Example — toggle a relay

Reflecting real device state

Script API example