Level actuators

A Level actuator takes a percentage from 0% to 100% and drives a proportional (PWM) output. Use it whenever "on/off" isn't enough and you need to set how much.

Catalog types that use this control kind:

All wire up as a PWM output (gpio-pwm).

Add one

1. Devices → Add device → Actuator, pick a type from the Dimming family.
2. Choose the gateway and accept the suggested PWM-capable pin.
3. Save. The Control panel shows a 0–100% slider.

Connection fields

Pick the right frequency. LED drivers are happy at ~1 kHz; some motors and lamps flicker or whine at low frequencies — raise frequencyHz if you hear or see it.

Control it

• Device page / dashboard — drag the slider. It commits on release (one command per gesture, not per pixel), and snaps to the confirmed value when the gateway acks. On a dashboard, add the Actuator widget.
• The command is { op: 'level', pct: 0..100 }. The gateway converts the percentage to a PWM duty (duty = round(pct × 255 / 100)), so 100% = full on, 0% = off.

Pulse

Level actuators also support pulse — e.g. set to a level for N ms then return to 0:

{ op: 'pulse', value: 80, durationMs: 5000 }

Automate it

• Rules — when room-temp > 28°C, set the fan to 70%.
• Macros — use the PWM write step for ramps and sequences (e.g. fade an LED up over several steps).

Safety

• On connection loss the output falls back to defaultDuty (usually 0).
• A maximum on-time can be applied so a proportional load doesn't run indefinitely.

Troubleshooting

• Flicker / whine → increase frequencyHz.
• Slider has no effect below a point → some drivers have a minimum usable duty; the load may stay dark/stationary until a threshold. Map your usable range with a quick test.
• Wrong pin → only PWM-capable pins work; the pin recommender avoids strapping/input-only pins.

See also the actuators overview and On/Off actuators.