Unlike Marlin and most traditional printer firmwares, homing in Klipper is orchestrated by the host, not by the microcontroller firmware. This follows Klipper’s general architecture: the Python host code (klippy/) handles kinematics, motion planning and all G-code-level behavior, while the MCU firmware only executes precisely-timed step commands it has been instructed to generate.
How it works
The relevant code lives in the host-side klippy package:
klippy/extras/homing.pyimplementshoming_move(), which drives the actual homing sequence: it moves the toolhead toward the endstop, handles retract and second-probe speeds, and settles on the final position.klippy/extras/endstop.pyprovides theMCU_endstopobject, which registers the endstop pin with the MCU and subscribes to atrsynctrigger. When the pin fires, the MCU reports the exact step clock time at which it triggered, and the host converts that back into a real axis position.- On the MCU side,
src/stepper.cand thetrsyncmechanism only do one thing: watch the pin and timestamp the event. All sequencing decisions — move direction, speeds, retries, multi-endstop squaring (e.g. dual Z) — are made in Python on the host. G28itself is just a host-side G-code command/macro (seeklippy/extras/homing_override.pyfor the classichoming_override/G28override mechanism), so even the entry point to homing never touches firmware-specific code.
Consequences
Because homing is a host-driven sequence of moves, it depends on live host↔MCU communication:
- A communication hiccup during a homing move aborts the move — this is why you see
Communication timeout during homingerrors when the USB/UART link to the MCU is flaky. - Homing features that would require firmware changes in other ecosystems — sensorless homing thresholds,
homing_positive_dir,homing_retract_dist, multi-MCU endstop synchronization — are all just config options parsed on the host. No firmware reflash needed. - The MCU gains no real autonomy: if the host goes away mid-print or mid-home, the MCU simply stops receiving step commands and eventually shuts down.
In short: the MCU detects the endstop event with tight timing, but homing is a host algorithm. Klipper’s firmware is deliberately a dumb, deterministic step executor.
See the Klipper homing configuration reference for the available homing_* parameters.