Add & control actuators
An actuator is a device you control rather than just read — a relay, solid-state relay, solenoid valve, pump, heater, fan, light, LED dimmer, variable-speed motor, servo, motorized valve, stepper, or DC motor. You add it like any other device, and the platform gives you the right control automatically.
Add an actuator
- Go to Devices → Add device and choose Actuator.
- Pick the actuator from the catalog (grouped by family: Switching, Dimming, Positioning, Motion). The catalog sets the right wiring type for you.
- Choose the gateway it's wired to and accept the suggested pins (you can change them — conflicts are flagged).
- Save. The actuator appears in your device list with a Control panel on its detail page.
Each catalog type maps to a control kind, which determines how you drive it. Follow a link for the wiring fields, calibration, and per-type tips:
| Control kind | Examples | What you send |
|---|---|---|
| On / Off | relay, SSR, solenoid, valve, pump, heater, fan, light, buzzer | On or Off |
| Level % | LED dimmer, dimmable lamp, variable-speed fan/motor, PWM | 0–100% |
| Position ° | servo, motorized valve, damper, linear actuator | an angle |
| Move | stepper motor, linear stage / slider | a number of units, forward or reverse |
| Speed % | DC motor (H-bridge), conveyor | −100…100% (sign = direction) |
Servos and DC motors need gateway firmware 1.4.0 or newer. Update the gateway (Gateways → Update firmware) before adding them.
Control it
- From the device page — the Control panel shows a toggle, slider, or move buttons matching the actuator. State updates live and is confirmed once the gateway acknowledges the command.
- From a dashboard — add the Actuator widget and point it at the actuator; it renders the right control automatically (toggle, slider, dial, or move buttons) and confirms each command live. Great for one-tap control alongside your readings.
- Pulse — switching and dimming actuators support a timed pulse ("on for N seconds, then off automatically") — useful for irrigation bursts, door strikes, etc.
Automate it
- Rules — add a Control an actuator action to any rule: when temperature > 30 °C, turn on the fan or set the dimmer to 80%. No webhook or macro needed.
- Macros — drive actuators inside a programmable sequence (digital out, PWM, servo, stepper move) for multi-step automations that keep running on the gateway even if the cloud connection drops.
With or without a gateway
Most actuators are wired to a gateway. You can also control an actuator directly over MQTT without a gateway — see the actuator MQTT command contract to build your own MQTT-capable actuator.
Safety
If a gateway loses its connection, its outputs return to their configured safe (default) state. For switching actuators you can also set a maximum on-time so a load can't be left on indefinitely.