On/Off actuators

An On/Off actuator is the simplest control kind: the output is either on or off. It covers most "switch a load" hardware.

Catalog types that use this control kind:

Type	Typical use
Relay / Switch	Switch any load on or off
Solid-State Relay (SSR)	Silent, fast switching for resistive / AC loads
Contactor	High-current motors and heavy loads
Solenoid	Latch, lock, or actuate a coil
Solenoid Valve	Open/close water, air or gas
Pump	Turn a pump on or off
Heater	On/off heating element
Fan	On/off fan or blower
Light / Lamp	Switch a light
Buzzer / Siren	Audible alert

All of these wire up as a single digital output (gpio-digital-out).

Add one

Devices → Add device → Actuator, then pick the type from the Switching family.
Choose the gateway it's wired to and accept the suggested output pin (conflicts are flagged; you can change it).
Save. The device gets a Control panel with an On/Off toggle.

Connection fields

Field	Meaning	Default
`pinNumber`	GPIO pin driving the relay/transistor	from pin recommendation
`activeHigh`	`true` = pin HIGH turns the load on; `false` for active-low boards	`true`
`defaultState`	Safe state to fall back to (0 = off)	`0`

Many relay boards are active-low (a LOW input energises the relay). If your relay turns on when you command off, flip activeHigh to false.

Control it

Device page / dashboard — flip the toggle. The state updates optimistically and shows confirmed once the gateway acknowledges the command. On a dashboard, add the Actuator widget and point it at the device.
The command sent under the hood is { op: 'set', value: 0 | 1 } to POST /devices/:id/command.

Timed pulse

On/Off actuators support a pulse — turn on (or off) for a set time, then revert automatically:

{ op: 'pulse', value: 1, durationMs: 3000 }

The platform schedules the inverse command after durationMs, so the load can't be left in the pulsed state if the app closes. Great for irrigation bursts, door strikes, dispensers, and momentary buzzers.

Automate it

Rules — add a Control an actuator action: when soil-moisture < 20%, turn the pump on, or pulse it for 5 s.
Macros — use the digital write step inside a sequence for multi-step logic that keeps running on the gateway even if the cloud link drops.

Safety

On MQTT/Wi-Fi loss the gateway drives the output to its defaultState.
Set a maximum on-time (maxOnMs) on the device so a load (heater, pump) can't be left on indefinitely — a watchdog turns it off automatically.

Troubleshooting

Toggle flips back → the gateway didn't acknowledge; check it's online and the pin is correct.
Inverted behaviour → set activeHigh to match your relay board.
Nothing happens → confirm the actuator is wired to the pin shown on the device page and the gateway firmware is current.

See also the actuators overview and Level / dimming actuators.