Firmware ≥1.2 plans a rest-to-rest trapezoidal position move and tracks it with velocity feedforward plus a light PID on the encoder. This page is the user-facing guide: how it works, what to set, and what we measured on real hardware.

How closed-loop motion works (fw ≥1.2)

Each closed-loop MOVE_ABS / MOVE_REL:

1. Plan a trap (or triangle if short) with
   vmax = min(max_speed, cl_max_speed) and amax = cl_max_accel.
2. Every 5 ms: reference r(t), feedforward v_ff(t).
3. Command: v = v_ff + Kp·(r − encoder) + Ki·∫ − Kd·v_meas.
4. Settle when the plan is done, error ≤ pid_tolerance, and speed is low.

There is no S-curve (jerk limit) yet — constant acceleration only.

Why open-loop can look faster

Open-loop run() never has to decelerate to a target or wait for encoder settle. Closed-loop does. On long moves, closed-loop cruise still reaches a large fraction of the continuous open-loop ceiling (see measured RPM below).

Pre-1.1 pure PID (no planned deceleration) overshot hard at high cl_max_speed and often never settled — that architectural gap is what 1.2 fixes.

One-shot setup

node.set_direction(True)   # if closed loop ran away (polarity)
node.configure_closed_loop_speed(
    4800.0,                 # trap cruise deg/s (÷6 = RPM)
    run_current=70,
    microsteps=8,
    stealthchop=False,      # SpreadCycle — required at high speed
    persist=True,
)
node.enable()
node.set_zero()
node.move_to(720.0, blocking=True)

PID gains do not set cruise speed — cl_max_speed does. PID only trims lag.

Measured max RPM (characterization motor)

Motor under test

All numbers below were taken on this motor unless noted:

Drive stack: Grafito CANStepper (ESP32-C3 + TMC2209 + MT6701), firmware 1.2, supply 24.0 V, node 1, invert_dir=1, SpreadCycle for high-speed tests.

Open-loop vs closed-loop ceilings

Peaks during a closed-loop move can exceed the cruise setting briefly (encoder samples during accel); cruise is the number you configure with cl_max_speed.

Hardware matrix (observations)

Default conditions: fw 1.2, 24 V, 8 µstep unless noted, tracking PID as above.

Current × closed-loop cruise

At 40–85% current, closed-loop settled through 6000 deg/s on long moves. 70% is the preferred continuous setting.

100% current:

• Can reach OL ~7200 and CL 6000 in short tests with cool-downs between moves (including a 5× burst at 6000 all OK).
• Aggressive continuous 100% duty has dropped USB (CDC brownout / /dev/ttyACM0 gone). Prefer 70% for long runs; use 100% only for short high-torque bursts.

Microsteps

StealthChop vs SpreadCycle

10-minute closed-loop soak

Continuous reversing position moves at the production tune:

Verdict: closed-loop trap + v_ff at 70% / 4800 is solid for continuous duty on this NEMA 17.

Tuning procedure

1. Fix polarity: if closed loop runs away, node.set_direction(True) then save_config().
2. Baseline: SpreadCycle, 8 µstep, 70% current, 24 V.
3. Ladder tools from the repo:

   python3 tools/cl_speed_validate.py /dev/ttyACM0 1 70 8
   python3 examples/closed_loop_speed.py /dev/ttyACM0 1 4800
   python3 tools/cl_matrix.py /dev/ttyACM0 1 --quick

4. Pick a cruise with margin (if 6000 works, ship 4800).
5. Persist with configure_closed_loop_speed(..., persist=True).
6. Optional: multi-minute soak before locking production config.

If settle fails

Firmware history

Related

• Quickstart
• Python library
• Protocol — parameter IDs
• Troubleshooting
• Repo docs/closed_loop_tuning.md — full engineer notes (same content source)