PR: Add universal screw parameters to screws_tilt_adjust with backward compatibility

docs/Config_Reference.md

@@ -1486,10 +1486,34 @@ information.
 #screw_thread: CW-M3
 #   The type of screw used for bed leveling, M3, M4, or M5, and the
 #   rotation direction of the knob that is used to level the bed.
-#   Accepted values: CW-M3, CCW-M3, CW-M4, CCW-M4, CW-M5, CCW-M5, CW-M8, CCW-M8.
-#   Default value is CW-M3 which most printers use. A clockwise
-#   rotation of the knob decreases the gap between the nozzle and the
+#   Accepted values: CW-M3, CCW-M3, CW-M4, CCW-M4, CW-M5, CCW-M5,
+#   CW-M6, CCW-M6, CW-M8, CCW-M8.
+#   A clockwise rotation of the knob decreases the gap between the nozzle and the
 #   bed. Conversely, a counter-clockwise rotation increases the gap.
+#   This option cannot be used together with 'screw_pitch' or
+#   'screw_direction'. Either this option must be specified, or both
+#   'screw_pitch' and 'screw_direction' must be specified.
+#screw_pitch:
+#   The thread pitch (in mm) of the bed leveling screw. This allows
+#   using any screw size, not just the predefined ones in
+#   'screw_thread'. This option cannot be used together with 'screw_thread'.
+#   Must be specified together with 'screw_direction' if 'screw_thread'
+#   is not used.
+#   Calculation: screw_pitch is the bed movement for one full turn of
+#   the leveling screw. For most single-start metric screws, this is
+#   the thread pitch itself (for example, M3x0.5 -> 0.5, M4x0.7 -> 0.7,
+#   M5x0.8 -> 0.8). For multi-start screws, use the lead
+#   (lead = pitch * number_of_starts).
+#   Relation to adjustment output: required turns are calculated as
+#   abs(z_error) / screw_pitch, then shown as full turns and minutes
+#   (01:20 = 1 turn + 20/60 turn).
+#   Note: this is not the same as a stepper's 'rotation_distance' value
+#   unless your manual bed screw is exactly that same screw/lead.
+#screw_direction:
+#   The rotation direction of the knob used to level the bed. Accepted
+#   values: CW, CCW. Rotation in this direction decreases the gap between the nozzle and the bed. This option
+#   cannot be used together with 'screw_thread'. Must be specified
+#   together with 'screw_pitch' if 'screw_thread' is not used.
 #use_probe_xy_offsets: False
 #   If True, apply the `[probe]` XY offsets to the probed positions. The
 #   default is False.

klippy/extras/screws_tilt_adjust.py

@@ -8,6 +8,20 @@
 
 from . import probe
 
+# Screw thread mapping: thread_name -> (pitch, direction)
+SCREW_THREAD_MAP = {
+    "CW-M3": (0.5, "CW"),
+    "CCW-M3": (0.5, "CCW"),
+    "CW-M4": (0.7, "CW"),
+    "CCW-M4": (0.7, "CCW"),
+    "CW-M5": (0.8, "CW"),
+    "CCW-M5": (0.8, "CCW"),
+    "CW-M6": (1.0, "CW"),
+    "CCW-M6": (1.0, "CCW"),
+    "CW-M8": (1.25, "CW"),
+    "CCW-M8": (1.25, "CCW"),
+}
+
 
 class ScrewsTiltAdjust:
     def __init__(self, config):
@@ -30,21 +44,40 @@ def __init__(self, config):
             raise config.error(
                 "screws_tilt_adjust: Must have at least three screws"
             )
-        self.threads = {
-            "CW-M3": 0,
-            "CCW-M3": 1,
-            "CW-M4": 2,
-            "CCW-M4": 3,
-            "CW-M5": 4,
-            "CCW-M5": 5,
-            "CW-M6": 6,
-            "CCW-M6": 7,
-            "CW-M8": 8,
-            "CCW-M8": 9,
-        }
-        self.thread = config.getchoice(
-            "screw_thread", self.threads, default="CW-M3"
-        )
+        # Screw parameters: support both legacy 'screw_thread' and
+        # universal 'screw_pitch'/'screw_direction' options.
+        screw_thread = config.get("screw_thread", None)
+        screw_pitch = config.getfloat("screw_pitch", None, above=0.0)
+        if screw_thread is not None:
+            if (
+                screw_pitch is not None
+                or config.get("screw_direction", None) is not None
+            ):
+                raise config.error(
+                    "screws_tilt_adjust: 'screw_thread' cannot be used "
+                    "together with 'screw_pitch' or 'screw_direction'"
+                )
+            screw_thread_result = SCREW_THREAD_MAP.get(screw_thread.upper())
+            if screw_thread_result is None:
+                raise config.error(
+                    "screws_tilt_adjust: Invalid screw_thread '%s'. "
+                    "Accepted values: %s"
+                    % (screw_thread, ", ".join(sorted(SCREW_THREAD_MAP.keys())))
+                )
+            self.screw_pitch, self.screw_direction = screw_thread_result
+        else:
+            if (
+                screw_pitch is None
+                or config.get("screw_direction", None) is None
+            ):
+                raise config.error(
+                    "screws_tilt_adjust: Must specify either 'screw_thread' "
+                    "or both 'screw_pitch' and 'screw_direction'"
+                )
+            self.screw_pitch = screw_pitch
+            self.screw_direction = config.getchoice(
+                "screw_direction", {"CW": "CW", "CCW": "CCW"}
+            )
         # Initialize ProbePointsHelper
         points = [coord for coord, name in self.screws]
         self.probe_helper = probe.ProbePointsHelper(
@@ -89,21 +122,7 @@ def get_status(self, eventtime):
     def probe_finalize(self, offsets, positions):
         self.results = {}
         self.max_diff_error = False
-        # Factors used for CW-M3, CCW-M3, CW-M4, CCW-M4, CW-M5, CCW-M5, CW-M6
-        # and CCW-M6
-        threads_factor = {
-            0: 0.5,
-            1: 0.5,
-            2: 0.7,
-            3: 0.7,
-            4: 0.8,
-            5: 0.8,
-            6: 1.0,
-            7: 1.0,
-            8: 1.25,
-            9: 1.25,
-        }
-        is_clockwise_thread = (self.thread & 1) == 0
+        is_clockwise_thread = self.screw_direction == "CW"
         screw_diff = []
         # Process the read Z values
         if self.direction is not None:
@@ -146,7 +165,7 @@ def probe_finalize(self, offsets, positions):
                 if abs(diff) < 0.001:
                     adjust = 0
                 else:
-                    adjust = diff / threads_factor.get(self.thread, 0.5)
+                    adjust = diff / self.screw_pitch
                 if is_clockwise_thread:
                     sign = "CW" if adjust >= 0 else "CCW"
                 else: