screws_tilt_adjust: Add DIRECTION parameter to SCREWS_TILT_CALCULATE (#4357)

Signed-off-by: Matthew Lloyd <github@matthewlloyd.net>

2 files changed, 20 insertions, 9 deletions

diff --git a/docs/G-Codes.md b/docs/G-Codes.md
index 0bf8099b..026b93ec 100644
--- a/docs/G-Codes.md
+++ b/docs/G-Codes.md
@@ -456,12 +456,13 @@ The following commands are available when the
 [screws_tilt_adjust config section](Config_Reference.md#screws_tilt_adjust)
 is enabled (also see the
 [manual level guide](Manual_Level.md#adjusting-bed-leveling-screws-using-the-bed-probe)):
-- `SCREWS_TILT_CALCULATE [<probe_parameter>=<value>]`: This command
-  will invoke the bed screws adjustment tool. It will command the
+- `SCREWS_TILT_CALCULATE [DIRECTION=CW|CCW] [<probe_parameter>=<value>]`:
+  This command will invoke the bed screws adjustment tool. It will command the
   nozzle to different locations (as defined in the config file)
   probing the z height and calculate the number of knob turns to
-  adjust the bed level. See the PROBE command for details on the
-  optional probe parameters.
+  adjust the bed level. If DIRECTION is specified, the knob turns will all
+  be in the same direction, clockwise (CW) or counterclockwise (CCW).
+  See the PROBE command for details on the optional probe parameters.
   IMPORTANT: You MUST always do a G28 before using this command.
 
 ## Z Tilt
diff --git a/docs/Manual_Level.md b/docs/Manual_Level.md
index a50e6daf..ac75a868 100644
--- a/docs/Manual_Level.md
+++ b/docs/Manual_Level.md
@@ -163,17 +163,18 @@ screw_thread: CW-M3
 ```
 
 The screw1 is always the reference point for the others, so the system
-assumes that screw1 is in the correct height. Always run `G28` first
+assumes that screw1 is at the correct height. Always run `G28` first
 and then run `SCREWS_TILT_CALCULATE` - it should produce output
 similar to:
 ```
 Send: G28
 Recv: ok
 Send: SCREWS_TILT_CALCULATE
-Recv: // front left screw (Base): X -5.0, Y 30.0, Z 2.48750
-Recv: // front right screw : X 155.0, Y 30.0, Z 2.36000 : Adjust -> CW 01:15
-Recv: // rear right screw : X 155.0, Y 190.0, Z 2.71500 : Adjust -> CCW 00:50
-Recv: // read left screw : X -5.0, Y 190.0, Z 2.47250 : Adjust -> CW 00:02
+Recv: // 01:20 means 1 full turn and 20 minutes, CW=clockwise, CCW=counter-clockwise
+Recv: // front left screw (base) : x=-5.0, y=30.0, z=2.48750
+Recv: // front right screw : x=155.0, y=30.0, z=2.36000 : adjust CW 01:15
+Recv: // rear right screw : y=155.0, y=190.0, z=2.71500 : adjust CCW 00:50
+Recv: // read left screw : x=-5.0, y=190.0, z=2.47250 : adjust CW 00:02
 Recv: ok
 ```
 This means that:
@@ -198,3 +199,12 @@ the mesh was created. For example, `SCREWS_TILT_CALCULATE MAX_DEVIATION=0.01`
 can be added to the custom start gcode of the slicer before the mesh is loaded.
 It will abort the print if the configured limit is exceeded (0.01mm in this
 example), giving the user a chance to adjust the screws and restart the print.
+
+The `DIRECTION` parameter is useful if you can turn your bed adjustment
+screws in one direction only. For example, you might have screws that start
+tightened in their lowest (or highest) possible position, which can only be
+turned in a single direction, to raise (or lower) the bed. If you can only
+turn the screws clockwise, run `SCREWS_TILT_CALCULATE DIRECTION=CW`. If you can
+only turn them counter-clockwise, run `SCREWS_TILT_CALCULATE DIRECTION=CCW`.
+A suitable reference point will be chosen such that the bed can be leveled
+by turning all the screws in the given direction.