Clarify that mechanical_advantage should be manually folded into rotation_distance

Author: tobbelobb

docs/Config_Reference.md

@@ -795,7 +795,9 @@ rotation_distance:
 #   moves towards the cable winch for each full rotation of the
 #   stepper motor. This parameter must be provided.
 #   For buildup compensation, set this to the effective distance at the
-#   origin, which is 2*pi times the effective spool radius.
+#   origin. If winch_mechanical_advantage is used, divide the physical
+#   origin circumference by that factor (for example, a 2:1 tackle halves
+#   the configured value for the same spool radius).
 #   There is no separate spool_radius config option; Klipper derives the
 #   internal radius from rotation_distance.
 #   If the spool itself is geared, use the regular stepper gear_ratio

test/klippy/test_winch.py

@@ -94,7 +94,7 @@ def spool_lengths(self, helper, pos):
     def expected_motor_to_line_pos(self, motor_pos, rotation_distance,
                                    steps_per_rotation, buildup_factor,
                                    mechanical_advantage=1):
-        radius = rotation_distance / (2.0 * math.pi)
+        radius = rotation_distance * float(mechanical_advantage) / (2.0 * math.pi)
         steps_per_mm = steps_per_rotation / rotation_distance
         k2 = -float(buildup_factor) * float(mechanical_advantage)
         if abs(k2) <= 1.0e-12 or steps_per_mm <= 0.0:
@@ -159,6 +159,23 @@ def test_buildup_model_matches_closed_form_with_gearing(self):
             motor_pos, rotation_distance, steps_per_rotation, buildup, 1)
         self.assertAlmostEqual(actual, expected, places=12)
 
+    def test_buildup_model_scales_with_mechanical_advantage(self):
+        buildup = 0.6366197723675814
+        rotation_distance = 123.10
+        steps_per_rotation = 3200.0 * 12.75
+        helper = self.build_helper(((0.0, 0.0, 0.0),),
+                                   mover_weight=0.0,
+                                   spring=0.0,
+                                   target=0.0,
+                                   buildup_factor=buildup,
+                                   mechanical_advantage=[2])
+        helper.set_spool_params(0, rotation_distance, steps_per_rotation)
+        motor_pos = 18.5
+        actual = helper.motor_to_line_pos(0, motor_pos)
+        expected = self.expected_motor_to_line_pos(
+            motor_pos, rotation_distance, steps_per_rotation, buildup, 2)
+        self.assertAlmostEqual(actual, expected, places=12)
+
     def test_four_anchor_near_singularity(self):
         helper = self.build_helper(FOUR_ANCHORS_PROBLEM)
         origin_lengths, _, _ = self.spool_lengths(helper, (0.0, 0.0, 0.0))