sensille's z-tilt calibration (#54)

docs/Config_Reference.md

@@ -1126,7 +1126,15 @@ extended [G-Code command](G-Codes.md#z_tilt) becomes available.
 #   stepper. It is described using nozzle coordinates (the X, Y position
 #   of the nozzle if it could move directly above the point). The
 #   first entry corresponds to stepper_z, the second to stepper_z1,
-#   the third to stepper_z2, etc. This parameter must be provided.
+#   the third to stepper_z2, etc. This parameter must be provided,
+#   unless the parameter "extra_points" is provided. In that case only
+#   the command Z_TILT_AUTODETECT can be run to automatically determine
+#   the z_positions. See 'extra_points' below.
+#z_offsets:
+#   A list of Z offsets for each z_position. The z_offset is added to each
+#   probed value during Z_TILT_ADJUST to offset for unevenness of the bed.
+#   This values can also be automatically detected by running
+#   Z_TILT_CALIBRATE. See "extra_points" below.
 #points:
 #   A list of X, Y coordinates (one per line; subsequent lines
 #   indented) that should be probed during a Z_TILT_ADJUST command.
@@ -1149,6 +1157,31 @@ extended [G-Code command](G-Codes.md#z_tilt) becomes available.
 #   more points than steppers then you will likely have a fixed
 #   minimum value for the range of probed points which you can learn
 #   by observing command output.
+#extra_points:
+#   A list in the same format as "points" above. This list contains
+#   additional points to be probed during the two calibration commands
+#   Z_TILT_CALIBRATE and Z_TILT_AUTODETECT. If the bed is not perfectly
+#   level, it is possible to specify more probing points with "points".
+#   In that Z_TILT_ADJUST will determine the best fit via a least squares
+#   algorithm. As this comes with additional overhead on each Z_TILT_ADJUST
+#   run, it is instead possible to move the additional probing points here,
+#   and use Z_TILT_CALIBRATE to find z_offsets to use for the probing points
+#   used in Z_TILT_ADJUST.
+#   The extra points are also used during T_ZILT_AUTODETECT. This command
+#   can determine the z_positions automatically by during several probings
+#   with intentionally tilted bed. It is currently only implemented for 3
+#   z steppers.
+#   Note that for both commands to work numpy has to be installed.
+#averaging_len: 3
+#   Z_TILT_CALIBRATE and Z_TILT_AUTODETECT both run repeatedly until the
+#   result can no longer be improved. To determine this, the probed values
+#   are averaged. The number of runs to average over is configured with this
+#   parameter.
+#autodetect_delta: 1.0
+#   The amount by which Z_TILT_AUTODETECT intentionally tilts the bed. Higher
+#   values yield better results, but can also lead to situations where the
+#   bed is tilted in a way that the nozzle touched the bed before the probe.
+#   The default is conservative.
 ```
 
 ### [quad_gantry_level]

docs/G-Codes.md

@@ -925,7 +925,7 @@ test.
 
 #### SET_HEATER_PID
 `SET_HEATER_PID HEATER=<config_name> KP=<kp> KI=<ki> KD=<kd>`: Will
-allow one to manually change PID parameters of heaters without a 
+allow one to manually change PID parameters of heaters without a
 reload of the firmware.
 
 ### [pause_resume]
@@ -1408,3 +1408,21 @@ command will probe the points specified in the config and then make independent
 adjustments to each Z stepper to compensate for tilt. See the PROBE command for
 details on the optional probe parameters. The optional `HORIZONTAL_MOVE_Z`
 value overrides the `horizontal_move_z` option specified in the config file.
+The follwing commands are availabe when the parameter "extra_points" is
+configured in the z_tilt_section:
+- `Z_TILT_CALIBRATE [AVGLEN=<value>]`: This command does multiple probe
+  runs similar to Z_TILT_ADJUST, but with the additional points given in
+  "extra_points". This leads to a more balanced bed adjustment in case the
+  bed is not perfectly flat. The command averages the error over multiple
+  runs and continues until the error does not decrease any further. It
+  calculates values for the z_offsets config parameter, which will in turn
+  be used by T_TILT_ADJUST to achieve the same accuracy without the extra
+  points.
+- `Z_TILT_AUTODETECT [AVGLEN=<value>] [DELTA=<value>]`: This command
+  determines the positions of the pivot points for each stepper motor.
+  It works silimar to Z_TILT_CALIBRATE, but it probes the bed with intential
+  small misalgnments of the steppers. The amount of misalignment can be
+  configured with the DELTA paramter. It iterates until the calculated
+  positions cannot be improved any further. This is can be lengthy procedure.
+IMPORTANT: For the Z_TILT_CALIBRATE and Z_TILT_AUTODETECT commands to work
+the numpy package has to be installed via ~/klippy-env/bin/pip install -v numpy.

klippy/extras/probe.py

@@ -462,16 +462,22 @@ def get_position_endstop(self):
 # Helper code that can probe a series of points and report the
 # position at each point.
 class ProbePointsHelper:
-    def __init__(self, config, finalize_callback, default_points=None):
+    def __init__(
+        self,
+        config,
+        finalize_callback,
+        default_points=None,
+        option_name="points",
+    ):
         self.printer = config.get_printer()
         self.finalize_callback = finalize_callback
         self.probe_points = default_points
         self.name = config.get_name()
         self.gcode = self.printer.lookup_object("gcode")
         # Read config settings
-        if default_points is None or config.get("points", None) is not None:
+        if default_points is None or config.get(option_name, None) is not None:
             self.probe_points = config.getlists(
-                "points", seps=(",", "\n"), parser=float, count=2
+                option_name, seps=(",", "\n"), parser=float, count=2
             )
         def_move_z = config.getfloat("horizontal_move_z", 5.0)
         self.default_horizontal_move_z = def_move_z
@@ -482,6 +488,9 @@ def __init__(self, config, finalize_callback, default_points=None):
         self.probe_offsets = (0.0, 0.0, 0.0)
         self.results = []
 
+    def get_probe_points(self):
+        return self.probe_points
+
     def minimum_points(self, n):
         if len(self.probe_points) < n:
             raise self.printer.config_error(