docs: Add stow_on_each_sample description to BL-Touch.md

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

config/example-extras.cfg

@@ -626,9 +626,8 @@
 #stow_on_each_sample: True
 #   This determines if Klipper should command the pin to move up
 #   between each probe attempt when performing a multiple probe
-#   sequence. Setting this to False can allow for faster probing, but
+#   sequence. Read the directions in docs/BLTouch.md before setting
-#   using this mode requires careful tuning of probing speed
+#   this to False. The default is True.
-#   parameters. The default is True.
 #probe_with_touch_mode: False
 #   If this is set to True then Klipper will probe with the device in
 #   "touch_mode". The default is False (probing in "pin_down" mode).

docs/BLTouch.md

@@ -168,6 +168,37 @@ probe. If configuring this value on a "clone" or older BL-Touch
 device, be sure to test the probe accuracy before and after setting
 this value (use the `PROBE_ACCURACY` command to test).
 
+Multi-probing without stowing
+=============================
+
+By default, Klipper will deploy the probe at the start of each probe
+attempt and then stow the probe afterwards. This repetitive deploying
+and stowing of the probe may increase the total time of calibration
+sequences that involve many probe measurements. Klipper supports
+leaving the probe deployed between consecutive probes, which can
+reduce the total time of probing. This mode is enabled by configuring
+`stow_on_each_sample` to False in the config file.
+
+Important! Setting `stow_on_each_sample` to False can lead to Klipper
+making horizontal toolhead movements while the probe is deployed. Be
+sure to verify all probing operations have sufficient Z clearance
+prior to setting this value to False. If there is insufficient
+clearance then a horizontal move may cause the pin to catch on an
+obstruction and result in damage to the printer.
+
+Important! It is recommended to use `probe_with_touch_mode` configured
+to True when using `stow_on_each_sample` configured to False. Some
+"clone" devices may not detect a subsequent bed contact if
+`probe_with_touch_mode` is not set. On all devices, using the
+combination of these two settings simplifies the device signaling,
+which can improve overall stability.
+
+Note, however, that some "clone" devices and the BL-Touch v2.0 (and
+earlier) may have reduced accuracy when `probe_with_touch_mode` is set
+to True. On these devices it is a good idea to test the probe accuracy
+before and after setting `probe_with_touch_mode` (use the
+`PROBE_ACCURACY` command to test).
+
 Calibrating the BL-Touch offsets
 ================================