Nothing answers on the serial port

1. Is another program holding the port? (Arduino serial monitor, a browser tab with Web Serial, another script). Only one process can own it.
2. Tools → USB CDC On Boot: Enabled was set when flashing?
3. Open a serial monitor at 115200 — do you see # boot lines? If yes, the board is fine and the problem is on the host side (port name, permissions — on Linux add yourself to the dialout group).
4. After very high run current continuous motion, USB CDC has been seen to drop (/dev/ttyACM0 gone). Power-cycle USB / 24 V and use ~70% current for long duty.

discover() returns an empty dict

• Wrong port, or the port was opened but the node's telemetry is off (slow_rate_hz = 0 and nothing answers the ping): power-cycle and watch for the boot banner.
• If you're bridging through node A but expecting node B: is the CAN wiring between them intact and terminated?

Motor is silent and free-spinning

• node.enable() was called? (enable_on_boot may be 0.)
• 24 V rail present? USB alone runs the logic, not the motor.
• run_current reasonable (30–50 % for light bring-up; ~70% for high-speed closed loop on a 1.2 A NEMA17).

Motor stalls or loses position at speed

• Closed-loop (fw ≥1.2) uses a trapezoid with cruise cl_max_speed and accel cl_max_accel. Prefer SpreadCycle, 8 microsteps, and ~70% current for continuous duty:

node.configure_closed_loop_speed(4800.0, run_current=70, microsteps=8,
                                 stealthchop=False, persist=True)

• Measured on PR42HS40-1204AF-02 @ 24 V: open-loop ~1200 RPM, closed-loop cruise ~1000 RPM max / 800 RPM production. Full tables: Closed-loop speed tuning.
• 100% current can hit high speed in short bursts but has caused USB disconnects when hammered continuously — prefer 70% for long soaks.
• Check no progress in get_pid_status() — blocked axis or wrong invert_dir (node.set_direction(True) so +command increases encoder).
• StealthChop is quiet but weak at speed — use SpreadCycle (stealthchop=False).

Closed loop runs away or faults with no progress

• Commanded positive direction must increase encoder angle. Toggle node.set_direction(True), retest slowly, then save_config().
• Confirm firmware ≥1.2 for trap + feedforward closed loop.

Closed loop slower than open-loop run()

Expected for position moves: they must accelerate, decelerate, and settle. Open-loop velocity never settles. On long moves, closed-loop 1.2 still cruises near the physical ceiling — raise cl_max_speed (see tuning page).

Encoder angle is noisy, jumps, or counts backwards

• Magnet centering and air gap (1–2 mm) over the MT6701.
• The boot banner prints an encoder self-check; raw=0x000000 or all-ones means a wiring/CS problem, not a tuning problem.
• STATUS bit 0x40 clear means the most recent SSI frame was invalid. The controller holds the last good sample through an isolated CRC error, but sustained feedback loss still latches encoder fault 1; fix the magnet or wiring before tuning PID.

Two boards, dead bus

• 120 Ω termination at both ends?
• node.get_can_health(): tx_error_count near 128 with zero received frames means nobody is ACKing — the other node is unpowered or CANH/CANL are swapped.
• A node that sat alone in bus-off recovers automatically; recovery_count tells you it happened.

Board won't boot with the endstop wired

IO8 is a strapping pin and was LOW at power-on. Use a normally-open switch to GND, or wire NC switches through a series diode. Details in the hardware guide.

Follower lags or drifts

• get_follow_status() — synced true? If not, the follower never saw a leader POSITION frame: check the leader's fast_rate_hz is not 0.
• Encoder-corrected mode (default) absorbs missed steps; open-loop follower mode accumulates them — prefer encoder-corrected unless you have a reason.
• After manually moving either shaft, call follow_sync() to re-capture the offset.

Homing times out

• homing_timeout_ms too short for the travel distance at the homing speed.
• StallGuard homing: threshold too low (never triggers) — raise stall_threshold; or speed too low for load measurement — home at 15–30 deg/s.
• Endstop homing: polarity (endstop_active_high) wrong, so the firmware believes the switch is already pressed or never pressed.