mcu: Support multi-mcu homing

Support endstops and probes attached to a different micro-controller
than their associated steppers.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

docs/Config_Reference.md

@@ -119,7 +119,9 @@ different names for the stepper (eg, `stepper_x` vs `stepper_a`).
 Below are common stepper definitions.
 
 See the [rotation distance document](Rotation_Distance.md) for
-information on calculating the `rotation_distance` parameter.
+information on calculating the `rotation_distance` parameter. See the
+[Multi-MCU homing](Multi_MCU_Homing.md) document for information on
+homing using multiple micro-controllers.
 
 ```
 [stepper_x]
@@ -152,8 +154,10 @@ microsteps:
 #   distance the axis travels for one full rotation of the final gear.
 #   The default is to not use a gear ratio.
 endstop_pin:
-#   Endstop switch detection pin. This parameter must be provided for
-#   the X, Y, and Z steppers on cartesian style printers.
+#   Endstop switch detection pin. If this endstop pin is on a
+#   different mcu than the stepper motor then it enables "multi-mcu
+#   homing". This parameter must be provided for the X, Y, and Z
+#   steppers on cartesian style printers.
 #position_min: 0
 #   Minimum valid distance (in mm) the user may command the stepper to
 #   move to.  The default is 0mm.
@@ -1611,7 +1615,9 @@ stepper_z config section.
 ```
 [probe]
 pin:
-#   Probe detection pin. This parameter must be provided.
+#   Probe detection pin. If the pin is on a different microcontroller
+#   than the Z steppers then it enables "multi-mcu homing". This
+#   parameter must be provided.
 #deactivate_on_each_sample: True
 #   This determines if Klipper should execute deactivation gcode
 #   between each probe attempt when performing a multiple probe

docs/Multi_MCU_Homing.md

@@ -0,0 +1,42 @@
+# Multiple Micro-controller Homing and Probing
+
+Klipper supports a mechanism for homing with an endstop attached to
+one micro-controller while its stepper motors are on a different
+micro-controller. This support is referred to as "multi-mcu
+homing". This feature is also used when a Z probe is on a different
+micro-controller than the Z stepper motors.
+
+This feature can be useful to simplify wiring, as it may be more
+convenient to attach an endstop or probe to a closer micro-controller.
+However, using this feature may result in "overshoot" of the stepper
+motors during homing and probing operations.
+
+The overshoot occurs due to possible message transmission delays
+between the micro-controller monitoring the endstop and the
+micro-controllers moving the stepper motors. The Klipper code is
+designed to limit this delay to no more than 25ms. (When multi-mcu
+homing is activated, the micro-controllers send periodic status
+messages and check that corresponding status messages are received
+within 25ms.)
+
+So, for example, if homing at 10mm/s then it is possible for an
+overshoot of up to 0.250mm (10mm/s * .025s == 0.250mm). Care should be
+taken when configuring multi-mcu homing to account for this type of
+overshoot. Using slower homing or probing speeds can reduce the
+overshoot.
+
+Stepper motor overshoot should not adversely impact the precision of
+the homing and probing procedure. The Klipper code will detect the
+overshoot and account for it in its calculations. However, it is
+important that the hardware design is capable of handling overshoot
+without causing damage to the machine.
+
+Should Klipper detect a communication issue between micro-controllers
+during multi-mcu homing then it will raise a "Communication timeout
+during homing" error.
+
+Note that an axis with multiple steppers (eg, `stepper_z` and
+`stepper_z1`) need to be on the same micro-controller in order to use
+multi-mcu homing. For example, if an endstop is on a separate
+micro-controller from `stepper_z` then `stepper_z1` must be on the
+same micro-controller as `stepper_z`.

docs/Overview.md

@@ -41,18 +41,19 @@ communication with the Klipper developers.
     using adxl345 accelerometer hardware to measure resonance.
 - [Pressure advance](Pressure_Advance.md): Calibrate extruder
   pressure.
-- [Slicers](Slicers.md): Configure "slicer" software for Klipper.
+- [G-Codes](G-Codes.md): Information on commands supported by Klipper.
 - [Command Templates](Command_Templates.md): G-Code macros and
   conditional evaluation.
   - [Status Reference](Status_Reference.md): Information available to
     macros (and similar).
 - [TMC Drivers](TMC_Drivers.md): Using Trinamic stepper motor drivers
   with Klipper.
+- [Multi-MCU Homing](Multi_MCU_Homing.md): Homing and probing using multiple micro-controllers.
+- [Slicers](Slicers.md): Configure "slicer" software for Klipper.
 - [Skew correction](skew_correction.md): Adjustments for axes not
   perfectly square.
 - [PWM tools](Using_PWM_Tools.md): Guide on how to use PWM controlled
   tools such as lasers or spindles.
-- [G-Codes](G-Codes.md): Information on commands supported by Klipper.
 
 ## Developer Documentation
 

docs/_klipper3d/mkdocs.yml

@@ -94,14 +94,15 @@ nav:
       - Resonance_Compensation.md
       - Measuring_Resonances.md
     - Pressure_Advance.md
-    - Slicers.md
+    - G-Codes.md
     - Command templates:
       - Command_Templates.md
       - Status_Reference.md
     - TMC_Drivers.md
+    - Multi_MCU_Homing.md
+    - Slicers.md
     - skew_correction.md
     - Using_PWM_Tools.md
-    - G-Codes.md
   - Developer Documentation:
     - Code_Overview.md
     - Kinematics.md