Three homing methods

All three run inside the firmware — the host just starts them and waits for the done/failed event.

node.home(method="endstop", direction=-1, speed_deg_s=30.0)

The homing sequence for endstop and stallguard:

1. Optionally drop to homing_current (parameter; 0 keeps run current).
2. Move at the commanded speed and direction until the trigger, bounded by homing_timeout_ms.
3. Hard stop. The trigger point becomes 0°.
4. Back off by homing_backoff degrees.
5. Restore current, emit HOMING_DONE, set the homed status flag.

A timeout emits HOMING_FAILED and raises HomingFailed on the host.

Endstop homing

node.configure_endstop(enabled=True, active_high=False, action=1)
node.configure_homing(current_percent=30, backoff_deg=5.0, timeout_ms=20000)
node.home(method="endstop", direction=-1, speed_deg_s=20.0)

Wiring rules (IO8 is a strapping pin!) are in the hardware guide.

Sensorless (StallGuard) homing

The TMC2209 measures motor load; when the axis hits the hard stop, load spikes and the DIAG pin fires. Two tuning knobs:

node.set_stall_threshold(60)   # 0-255, HIGHER = more sensitive
node.home(method="stallguard", direction=-1, speed_deg_s=20.0)

Tuning tips:

• Use a reduced homing current (25–40 %) so the crash is gentle.
• StallGuard needs some speed to measure load — very slow homing (below roughly 10 deg/s on a typical NEMA17) triggers poorly.
• Too-high threshold = false triggers during acceleration; too low = the motor grinds against the stop. Start around 50 and adjust.

Endstop as a safety input

Independent of homing, an enabled endstop can guard normal motion via endstop_action:

Every edge also emits ENDSTOP_HIT / ENDSTOP_RELEASED events you can subscribe to on the host.

Axis-level homing (millimetres)

Axis.home() converts units and applies per-axis defaults:

axis = Axis(node, rotation_distance=8.0, require_homing=True)
axis.home(method="stallguard", direction=-1, speed=5.0,
          current_percent=25, backoff=2.0)     # all in mm

With require_homing=True, motion before a successful home raises NotHomed — a cheap way to keep unreferenced axes from crashing.