axis_twist_compensation: Add X twist compensation module (#6149)

Implements AxisTwistCompensation, and Calibrater

Supports calibration of z-offsets caused by x gantry twist

Modify PrinterProbe._probe function to check if the probed z value should be adjusted
based on axis_twist_compensation's configuration

Add documentation for [axis_twist_compensation] module

Signed-off-by: Jeremy Tan <jeremytkw98@gmail.com>

docs/Axis_Twist_Compensation.md

@@ -0,0 +1,50 @@
+# Axis Twist Compensation
+
+This document describes the [axis_twist_compensation] module.
+
+Some printers may have a small twist in their X rail which can skew the results
+of a probe attached to the X carriage.
+This is common in printers with designs like the Prusa MK3, Sovol SV06 etc and is
+further described under [probe location
+bias](Probe_Calibrate.md#location-bias-check). It may result in
+probe operations such as [Bed Mesh](Bed_Mesh.md),
+[Screws Tilt Adjust](G-Codes.md#screws_tilt_adjust),
+[Z Tilt Adjust](G-Codes.md#z_tilt_adjust) etc returning inaccurate
+representations of the bed.
+
+This module uses manual measurements by the user to correct the probe's results.
+Note that if your axis is significantly twisted it is strongly recommended to
+first use mechanical means to fix it prior to applying software corrections.
+
+**Warning**: This module is not compatible with dockable probes yet and will
+try to probe the bed without attaching the probe if you use it.
+
+## Overview of compensation usage
+
+> **Tip:** Make sure the [probe X and Y offsets](Config_Reference.md#probe) are
+> correctly set as they greatly influence calibration.
+
+1. After setting up the [axis_twist_compensation] module,
+perform `AXIS_TWIST_COMPENSATION_CALIBRATE`
+* The calibration wizard will prompt you to measure the probe Z offset at a few
+points along the bed
+* The calibration defaults to 3 points but you can use the option
+`SAMPLE_COUNT=` to use a different number.
+2. [Adjust your Z offset](Probe_Calibrate.md#calibrating-probe-z-offset)
+3. Perform automatic/probe-based bed tramming operations, such as
+[Screws Tilt Adjust](G-Codes.md#screws_tilt_adjust),
+[Z Tilt Adjust](G-Codes.md#z_tilt_adjust) etc
+4. Home all axis, then perform a [Bed Mesh](Bed_Mesh.md) if required
+5. Perform a test print, followed by any
+[fine-tuning](Axis_Twist_Compensation.md#fine-tuning) as desired
+
+> **Tip:** Bed temperature and nozzle temperature and size do not seem to have
+> an influence to the calibration process.
+
+## [axis_twist_compensation] setup and commands
+
+Configuration options for [axis_twist_compensation] can be found in the
+[Configuration Reference](Config_Reference.md#axis_twist_compensation).
+
+Commands for [axis_twist_compensation] can be found in the
+[G-Codes Reference](G-Codes.md#axis_twist_compensation)

docs/Config_Reference.md

@@ -1959,6 +1959,35 @@ z_offset:
 #   See the "probe" section for more information on the parameters above.
 ```
 
+### [axis_twist_compensation]
+
+A tool to compensate for inaccurate probe readings due to twist in X gantry. See
+the [Axis Twist Compensation Guide](Axis_Twist_Compensation.md) for more
+detailed information regarding symptoms, configuration and setup.
+
+```
+[axis_twist_compensation]
+#speed: 50
+#   The speed (in mm/s) of non-probing moves during the calibration.
+#   The default is 50.
+#horizontal_move_z: 5
+#   The height (in mm) that the head should be commanded to move to
+#   just prior to starting a probe operation. The default is 5.
+calibrate_start_x: 20
+#   Defines the minimum X coordinate of the calibration
+#   This should be the X coordinate that positions the nozzle at the starting
+#   calibration position. This parameter must be provided.
+calibrate_end_x: 200
+#   Defines the maximum X coordinate of the calibration
+#   This should be the X coordinate that positions the nozzle at the ending
+#   calibration position. This parameter must be provided.
+calibrate_y: 112.5
+#   Defines the Y coordinate of the calibration
+#   This should be the Y coordinate that positions the nozzle during the
+#   calibration process. This parameter must be provided and is recommended to
+#   be near the center of the bed
+```
+
 ## Additional stepper motors and extruders
 
 ### [stepper_z1]

docs/G-Codes.md

@@ -1339,6 +1339,17 @@ print.
 #### SDCARD_RESET_FILE
 `SDCARD_RESET_FILE`: Unload file and clear SD state.
 
+### [axis_twist_compensation]
+
+The following commands are available when the
+[axis_twist_compensation config
+section](Config_Reference.md#axis_twist_compensation) is enabled.
+
+#### AXIS_TWIST_COMPENSATION_CALIBRATE
+`AXIS_TWIST_COMPENSATION_CALIBRATE [SAMPLE_COUNT=<value>]`: Initiates the X
+twist calibration wizard. `SAMPLE_COUNT` specifies the number of points along
+the X axis to calibrate at and defaults to 3.
+
 ### [z_thermal_adjust]
 
 The following commands are available when the

docs/Overview.md

@@ -35,6 +35,8 @@ communication with the Klipper developers.
     locations.
   - [Endstop phase](Endstop_Phase.md): Stepper assisted Z endstop
     positioning.
+  - [Axis Twist Compensation](Axis_Twist_Compensation.md): A tool to compensate
+    for inaccurate probe readings due to twist in X gantry.
 - [Resonance compensation](Resonance_Compensation.md): A tool to
   reduce ringing in prints.
   - [Measuring resonances](Measuring_Resonances.md): Information on

docs/_klipper3d/mkdocs.yml

@@ -101,6 +101,7 @@ nav:
       - Manual_Level.md
       - Bed_Mesh.md
       - Endstop_Phase.md
+      - Axis_Twist_Compensation.md
     - Resonance Compensation:
       - Resonance_Compensation.md
       - Measuring_Resonances.md