Move actuators

A Move actuator performs a relative motion: step N units forward or reverse. Unlike a position actuator it has no absolute angle — each command is a one-shot move from wherever it currently is.

Catalog types that use this control kind:

Type	Typical use
Stepper Motor	Step a motor a number of units in a direction
Linear Stage / Slider	Stepper-driven linear slider (camera rig, CNC axis)

Both wire up as a stepper output (gpio-stepper) via a step/direction driver (A4988, DRV8825, TMC2208, …).

Add one

Devices → Add device → Actuator, pick a type from the Motion family.
Choose the gateway and accept the suggested STEP / DIR pins.
Save. The Control panel shows a units field + Reverse / Forward buttons.

Connection fields

Field	Meaning	Default
`stepPin` / `dirPin`	Driver STEP and DIR pins	from pin recommendation
`stepsPerUnit`	Driver steps per "unit" you command	`1`
`maxSpeedUs` / `minSpeedUs`	Fastest / slowest step interval (µs) during the ramp	`800` / `2500`
`rampSteps`	Steps spent accelerating and decelerating	`200`

stepsPerUnit is your gearing. Set it so "1 unit" means something physical — e.g. with a 200-step motor at 1/16 microstepping driving a 8 mm-pitch leadscrew, set stepsPerUnit so one unit = 1 mm. Then "move 50 forward" travels 50 mm.

Control it

Device page / dashboard — type the number of units and press Forward or Reverse. There's no persistent state to "set" — each press fires a move. On a dashboard, add the Actuator widget.
The command is { op: 'move', units: <n>, dir: 0 | 1 } (0 = reverse, 1 = forward). The gateway converts units to steps (steps = units × stepsPerUnit) and runs a ramped move (accelerate over rampSteps, cruise, decelerate), acknowledging when the move completes.

Automate it

Rules — when a limit switch trips, move 100 units reverse to retract.
Macros — the move step is the heart of multi-axis sequences (camera sliders, dosing, indexing tables); chain moves with waits between them.

Safety

A move runs to completion on the gateway, so a brief cloud hiccup won't leave it half-done.
Steppers can lose steps if commanded faster than the load allows — if you see missed steps, slow the ramp (raise minSpeedUs/maxSpeedUs) or increase rampSteps.

Troubleshooting

Motor buzzes but doesn't turn → STEP/DIR swapped, driver current too low, or maxSpeedUs too aggressive (ramp too fast).
Moves the wrong way → swap the dir meaning by flipping the two coil wires or inverting the direction in your unit math.
Travel doesn't match units → recompute stepsPerUnit.

See also the actuators overview and Position actuators.