docs: Add a Manual_Probe.md document

Add information on calibrating the bed on traditional printers with a
Z endstop and bed screws.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

5 files changed, 346 insertions, 10 deletions

diff --git a/docs/Bed_Level.md b/docs/Bed_Level.md
index 4fd28f23..47d4f8ad 100644
--- a/docs/Bed_Level.md
+++ b/docs/Bed_Level.md
@@ -35,7 +35,9 @@ leveling.
 For printers with an "automatic Z probe" be sure to calibrate the
 probe following the directions in the
 [Probe Calibrate](Probe_Calibrate.md) document. For delta printers,
-see the [Delta Calibrate](Delta_Calibrate.md) document.
+see the [Delta Calibrate](Delta_Calibrate.md) document. For printers
+with bed screws and traditional Z endstops, see the
+[Manual Level](Manual_Level.md) document.
 
 During calibration it may be necessary to set the printer's Z
 `position_min` to a negative number (eg, `position_min = -2`). The
diff --git a/docs/Manual_Level.md b/docs/Manual_Level.md
new file mode 100644
index 00000000..f9636932
--- /dev/null
+++ b/docs/Manual_Level.md
@@ -0,0 +1,135 @@
+This document describes tools for calibrating a Z endstop and for
+performing adjustments to bed leveling screws.
+
+# Calibrating a Z endstop
+
+An accurate Z endstop position is critical to obtaining high quality
+prints.
+
+Note, though, the accuracy of the Z endstop switch itself can be a
+limiting factor. If one is using Trinamic stepper motor drivers then
+consider enabling [endstop phase](Endstop_Phase.md) detection to
+improve the accuracy of the switch.
+
+To perform a Z endstop calibration, home the printer, move the head to
+a position near the center of the bed, navigate to the OctoPrint
+terminal tab, and run:
+```
+Z_ENDSTOP_CALIBRATE
+```
+Then perform the ["paper test"](Bed_Level.md#the-paper-test) steps to
+determine the actual height at the given position. One can then
+`ACCEPT` the position and save the results to the config file with:
+```
+SAVE_CONFIG
+```
+
+It's preferable to use a Z endstop switch on the opposite end of the Z
+axis from the bed. (Homing away from the bed is more robust as then it
+is generally always safely to home the Z.) However, if one must home
+towards the bed it is recommended to adjust the endstop so that it
+triggers a small distance (eg, .5mm) above the bed. Almost all endstop
+switches can safely be depressed a small distance beyond their trigger
+point. When this is done, one should find that the
+`Z_ENDSTOP_CALIBRATE` command reports a small positive value (eg,
+.5mm) for the Z position_endstop. Triggering the endstop while it is
+still some distance from the bed reduces the risk of inadvertent bed
+crashes.
+
+Some printers have the ability to manually adjust the location of the
+physical endstop switch. However, it's recommended to perform Z
+endstop positioning in software with Klipper - once the physical
+location of the endstop is in a convenient location, one can make any
+further adjustments by running Z_ENDSTOP_CALIBRATE or by manually
+updating the Z position_endstop in the configuration file.
+
+# Adjusting bed leveling screws
+
+The secret to getting good bed leveling with bed leveling screws is to
+utilize the printer's high precision motion system during the bed
+leveling process itself. This is done by commanding the nozzle to a
+position nearest each bed screw and then adjusting that screw until
+the bed is a set distance from the nozzle. Klipper has a tool to
+assist with this. In order to use the tool it is necessary to specify
+each screw XY location.
+
+This is done by creating a `[bed_screws]` config section. For example,
+it might look something similar to:
+```
+[bed_screws]
+screw1: 100,50
+screw2: 100,150
+screw3: 150,100
+```
+
+If a bed screw is under the bed, then specify the XY position directly
+above the screw. If the screw is outside the bed then specify an XY
+position closest to the screw that is still within the range of the
+bed.
+
+Once the config file is ready, run `RESTART` to load that config, and
+then one can start the tool by running:
+```
+BED_SCREWS_ADJUST
+```
+
+This tool will move the printer's nozzle to each screw XY location and
+then move the nozzle to a Z=0 height. At this point one can use the
+"paper test" to adjust the bed screw directly under the nozzle. See
+the information described in
+["the paper test"](Bed_Level.md#the-paper-test), but adjust the bed
+screw instead of commanding the nozzle to different heights. Adjust
+the bed screw until there is a small amount of friction when pushing
+the paper back and forth.
+
+Once the screw is adjusted so that a small amount of friction is felt,
+run either the `ACCEPT` or `ADJUSTED` command. Use the `ADJUSTED`
+command if the bed screw needed an adjustment (typically anything more
+than about 1/8th of a turn of the screw). Use the `ACCEPT` command if
+no significant adjustment is necessary. Both commands will cause the
+tool to proceed to the next screw. (When an `ADJUSTED` command is
+used, the tool will schedule an additional cycle of bed screw
+adjustments; the tool completes successfully when all bed screws are
+verified to not require any significant adjustments.) One can use the
+`ABORT` command to exit the tool early.
+
+This system works best when the printer has a flat printing surface
+(such as glass) and has straight rails. Upon successful completion of
+the bed leveling tool the bed should be ready for printing.
+
+## Fine grained bed screw adjustments
+
+If the printer uses three bed screws and all three screws are under
+the bed, then it may be possible to perform a second "high precision"
+bed leveling step. This is done by commanding the nozzle to locations
+where the bed moves a larger distance with each bed screw adjustment.
+
+For example, consider a bed with screws at locations A, B, and C:
+
+![bed_screws](img/bed_screws.svg.png)
+
+For each adjustment made to the bed screw at location C, the bed will
+swing along a pendulum defined by the remaining two bed screws (shown
+here as a green line). In this situation, each adjustment to the bed
+screw at C will move the bed at position D a further amount than
+directly at C. It is thus possible to make an improved C screw
+adjustment when the nozzle is at position D.
+
+To enable this feature, one would determine the additional nozzle
+coordinates and add them to the config file. For example, it might
+look like:
+```
+[bed_screws]
+screw1: 100,50
+screw1_fine_adjust: 0,0
+screw2: 100,150
+screw2_fine_adjust: 300,300
+screw3: 150,100
+screw3_fine_adjust: 0,100
+```
+
+When this feature is enabled, the `BED_SCREWS_ADJUST` tool will first
+prompt for coarse adjustments directly above each screw position, and
+once those are accepted, it will prompt for fine adjustments at the
+additional locations. Continue to use `ACCEPT` and `ADJUSTED` at each
+position.
diff --git a/docs/Overview.md b/docs/Overview.md
index 30b3c768..5d1e4136 100644
--- a/docs/Overview.md
+++ b/docs/Overview.md
@@ -12,15 +12,12 @@ The Klipper configuration is stored in a simple text file on the host
 machine. The [config/example.cfg](../config/example.cfg) file serves
 as a reference for the config file. See the [Slicers](Slicers.md)
 document for information on configuring a slicer with Klipper. See the
-[Endstop Phase](Endstop_Phase.md) document for information on
-Klipper's "stepper phase adjusted endstop" system. See the
-[Bed Level](Bed_Level.md) document for information on bed leveling
-with Klipper. See the [Probe Calibrate](Probe_Calibrate.md) document
-for information on calibrating automatic Z probes. See the
-[Delta Calibrate](Delta_Calibrate.md) document for information on
-calibrating delta printers. The
-[Pressure Advance](Pressure_Advance.md) document contains information
-on tuning the pressure advance config.
+[Bed Level](Bed_Level.md), [Endstop Phase](Endstop_Phase.md),
+[Probe Calibrate](Probe_Calibrate.md),
+[Delta Calibrate](Delta_Calibrate.md), and
+[Manual Level](Manual_Level.md) documents for information on bed
+leveling with Klipper. The [Pressure Advance](Pressure_Advance.md)
+document contains information on tuning the pressure advance config.
 
 The [kinematics](Kinematics.md) document provides some technical
 details on how Klipper implements motion. The [FAQ](FAQ.md) answers
diff --git a/docs/img/bed_screws.svg b/docs/img/bed_screws.svg
new file mode 100644
index 00000000..631af81e
--- /dev/null
+++ b/docs/img/bed_screws.svg
@@ -0,0 +1,202 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="210mm"
+   height="297mm"
+   viewBox="0 0 210 297"
+   version="1.1"
+   id="svg8"
+   sodipodi:docname="bed_screws.svg"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   inkscape:export-filename="/home/kevin/src/reprap/firmware/klipper/docs/img/bed_screws.svg.png"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96">
+  <defs
+     id="defs2" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="2.0149341"
+     inkscape:cx="209.05542"
+     inkscape:cy="598.47875"
+     inkscape:document-units="mm"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1920"
+     inkscape:window-height="1030"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata5">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <rect
+       style="opacity:1;fill:#ffffff;fill-opacity:0.96456695;stroke:#ffffff;stroke-width:0.39099997;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect928"
+       width="74.716049"
+       height="98.089432"
+       x="70.776711"
+       y="87.033455"
+       inkscape:export-xdpi="96"
+       inkscape:export-ydpi="96" />
+    <rect
+       style="opacity:1;fill:#c8c8c8;fill-opacity:1;stroke:#030000;stroke-width:0.39099997;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect815"
+       width="65.011902"
+       height="88.446426"
+       x="75.595238"
+       y="91.380951"
+       inkscape:export-xdpi="96"
+       inkscape:export-ydpi="96" />
+    <rect
+       style="opacity:1;fill:#00ff00;fill-opacity:0;stroke:#00ff00;stroke-width:0.39099997;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect844"
+       width="0.22808908"
+       height="92.832253"
+       x="103.55245"
+       y="89.324898" />
+    <g
+       id="g947"
+       transform="translate(0,4.4645794)">
+      <g
+         transform="translate(8.8954742,-0.79831178)"
+         id="g848">
+        <ellipse
+           style="opacity:1;fill:#fd0000;fill-opacity:0;stroke:#ff0000;stroke-width:0.39099997;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+           id="path817"
+           cx="94.828026"
+           cy="114.18661"
+           rx="0.85533404"
+           ry="0.79831177" />
+        <ellipse
+           style="opacity:1;fill:#000000;fill-opacity:0;stroke:#ff0000;stroke-width:0.391;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+           id="path817-3"
+           cx="94.771011"
+           cy="144.97864"
+           rx="0.85533404"
+           ry="0.79831183" />
+      </g>
+      <text
+         inkscape:export-ydpi="96"
+         inkscape:export-xdpi="96"
+         id="text858"
+         y="112.47593"
+         x="105.26311"
+         style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;line-height:125%;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         xml:space="preserve"><tspan
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.26458332px"
+           y="112.47593"
+           x="105.26311"
+           id="tspan856"
+           sodipodi:role="line">A</tspan><tspan
+           id="tspan860"
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.26458332px"
+           y="116.00371"
+           x="105.26311"
+           sodipodi:role="line" /></text>
+      <text
+         inkscape:export-ydpi="96"
+         inkscape:export-xdpi="96"
+         id="text864"
+         y="142.81177"
+         x="105.14907"
+         style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;line-height:125%;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         xml:space="preserve"><tspan
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.26458332px"
+           y="142.81177"
+           x="105.14907"
+           id="tspan862"
+           sodipodi:role="line">B</tspan></text>
+      <g
+         inkscape:export-ydpi="96"
+         inkscape:export-xdpi="96"
+         transform="translate(-42.652658,1.5966236)"
+         id="g876">
+        <ellipse
+           style="opacity:1;fill:#000000;fill-opacity:0;stroke:#ff0000;stroke-width:0.391;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+           id="path817-6"
+           cx="125.56304"
+           cy="127.41576"
+           rx="0.85533404"
+           ry="0.79831183" />
+        <text
+           xml:space="preserve"
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;line-height:125%;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+           x="126.93158"
+           y="126.5034"
+           id="text868"><tspan
+             sodipodi:role="line"
+             id="tspan866"
+             x="126.93158"
+             y="126.5034"
+             style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.26458332px">C</tspan><tspan
+             sodipodi:role="line"
+             x="126.93158"
+             y="130.03117"
+             style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.26458332px"
+             id="tspan870" /></text>
+      </g>
+    </g>
+    <g
+       id="g952"
+       transform="translate(-0.26262232,4.2019571)">
+      <path
+         inkscape:export-ydpi="96"
+         inkscape:export-xdpi="96"
+         inkscape:transform-center-y="-0.024320163"
+         inkscape:transform-center-x="-0.059466795"
+         d="m 138.45007,129.24048 -0.43835,-0.37484 -0.55729,0.14861 0.22103,-0.53273 -0.31355,-0.4841 0.57496,0.0456 0.36351,-0.44779 0.13432,0.56091 0.53821,0.20734 -0.49196,0.30107 z"
+         inkscape:randomized="0"
+         inkscape:rounded="0"
+         inkscape:flatsided="false"
+         sodipodi:arg2="1.7942231"
+         sodipodi:arg1="1.1659045"
+         sodipodi:r2="0.43426865"
+         sodipodi:r1="0.86853731"
+         sodipodi:cy="128.44217"
+         sodipodi:cx="138.10794"
+         sodipodi:sides="5"
+         id="path878"
+         style="opacity:1;fill:#00ff00;fill-opacity:0;stroke:#0000ff;stroke-width:0.39099997;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         sodipodi:type="star" />
+      <text
+         inkscape:export-ydpi="96"
+         inkscape:export-xdpi="96"
+         id="text882"
+         y="126.33394"
+         x="137.52043"
+         style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;line-height:125%;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         xml:space="preserve"><tspan
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:2.82222223px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.26458332px"
+           y="126.33394"
+           x="137.52043"
+           id="tspan880"
+           sodipodi:role="line">D</tspan></text>
+    </g>
+  </g>
+</svg>
diff --git a/docs/img/bed_screws.svg.png b/docs/img/bed_screws.svg.png
new file mode 100644
index 00000000..d2dda545
--- /dev/null
+++ b/docs/img/bed_screws.svg.png