Firmware ≥1.11 plans a rest-to-rest 7-segment S-curve and tracks it with velocity + acceleration feedforward plus a light PID on the encoder (optional 200-step MT6701 LUT from fw 1.10). This page is the user-facing guide: how it works, what to set, and the error / RPM numbers from hardware.

How closed-loop motion works (fw ≥1.11)

Each closed-loop MOVE_ABS / MOVE_REL:

1. Plan an S-curve with vmax = min(max_speed, cl_max_speed), amax = cl_max_accel, and jerk = cl_max_jerk (0 = auto amax/0.05 s).
2. Every 5 ms: reference r(t), v_ff(t), a_ff(t).
3. Command: v = v_ff + Ka·a_ff + Kp·(r − encoder) + Ki·∫ − Kd·v_meas.
4. Settle when the plan is done, error ≤ pid_tolerance, and speed is low.

Calibrate the LUT once (node.calibrate_encoder_lut()) so detent INL is linearized. Firmware 1.12 ships the precision defaults measured below.

Why open-loop can look faster

Open-loop run() never has to decelerate to a target or wait for encoder settle. Closed-loop does. The physical open-loop ceiling on this motor is about 3000 RPM; 5000 RPM is not reachable (back-EMF / torque, not the profiler).

One-shot setup (precision)

node.set_direction(True)   # if closed loop ran away (polarity)
node.calibrate_encoder_lut()
node.configure_closed_loop_speed(
    720.0,                  # 120 RPM cruise
    accel_deg_s2=1440.0,
    run_current=40,
    microsteps=8,
    stealthchop=False,      # SpreadCycle
    persist=True,
)
node.enable()
node.set_zero()
node.move_to(180.0, blocking=True)

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

From a PLC, the same knobs are CANopen objects (REAL32): 0x200F Kp, 0x2010 Ki, 0x2011 Kd, 0x201A Ka, 0x2012 tolerance, 0x6081 velocity, 0x6083 accel. Procedure: Tune gains from the PLC.

Cooling for high-speed duty

High continuous current + high cl_max_speed (especially multi-node hops) heats the TMC2209. A heatsink is strongly recommended for production or soak-style tests.

Watch node.get_driver_status().otpw / .over_temp_shutdown (fw ≥1.4). See Hardware cooling and Troubleshooting OTPW/OT.

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.11 (confirmation) / 1.12 (factory defaults), supply 24.0 V, node 3, SpreadCycle for high-speed tests, 200-step LUT on.

Open-loop vs closed-loop ceilings

Cruise is cl_max_speed. Host USB dpos/dt inflates peaks — use node.get_motion() firmware velocity. 100% current can match 3000 RPM briefly, then TMC OT (fault=4). Restore 40% / 8 µstep after speed tests.

Confirmation error table (2026-10-08, fw 1.11, LUT on)

Hold at 0° for 2 s: 0.000° p-p. 9/9 closed-loop moves settled.

Median |err| 0.125°, max 0.286°. Trap-only 180° used to overshoot ~43°; S-curve + Ka=0.04 + LUT brought that move to 0.000° overshoot.

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 (historical fw 1.2): trap + v_ff at 70% / 4800 was solid for continuous duty. Current production positioning uses the fw 1.11 S-curve precision tune in the error table above.

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

Use node.get_driver_status() (fw ≥1.4) during high-current soaks to watch OTPW before a full OT shutdown. MCU temperature is still get_env()[0]. Without a heatsink, OTPW (and occasional OT) under high-speed multi-node hops is expected — cool the TMC first, then re-tune current/speed.

Related

• Quickstart
• Python library
• Protocol — parameter IDs and DRIVER bit layout
• Troubleshooting — OTPW / OT checklist
• Repo docs/closed_loop_tuning.md — full engineer notes (same content source)