docs: Add BLTouch.md section describing clone config options

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

config/example-extras.cfg

@@ -610,7 +610,8 @@
 #   not run any special G-Code commands on deactivation.
 
 # BLTouch probe. One may define this section (instead of a probe
-# section) to enable a BLTouch probe. A virtual
+# section) to enable a BLTouch probe. See the docs/BLTouch.md guide
+# for further information on configuring a BLTouch. A virtual
 # "probe:z_virtual_endstop" pin is also created (see the "probe"
 # section above for the details).
 #[bltouch]
@@ -632,11 +633,13 @@
 #pin_up_reports_not_triggered: True
 #   Set if the BLTouch consistently reports the probe in a "not
 #   triggered" state after a successful "pin_up" command. This should
-#   be True for all genuine BLTouch devices. The default is True.
+#   be True for all genuine BLTouch devices. Read the directions in
+#   docs/BLTouch.md before setting this to False. The default is True.
 #pin_up_touch_mode_reports_triggered: True
 #   Set if the BLTouch consistently reports a "triggered" state after
 #   the commands "pin_up" followed by "touch_mode". This should be
-#   True for all genuine BLTouch devices. The default is True.
+#   True for all genuine BLTouch devices. Read the directions in
+#   docs/BLTouch.md before setting this to False. The default is True.
 #set_output_mode:
 #   Request a specific sensor pin output mode on the BLTouch V3.0 (and
 #   later). This setting should not be used on other types of probes.

docs/BLTouch.md

@@ -78,26 +78,11 @@ printer, to avoid damage, if it doesn't stop when you touch the pin.
 If that was successful, do another `G28` but this time let it touch
 the bed as it should.
 
-Calibrating the BL-Touch offsets
-================================
-
-Follow the directions in the [Probe Calibrate](Probe_Calibrate.md)
-guide to set the x_offset, y_offset, and z_offset config parameters.
-
-It's a good idea to verify that the Z offset is close to 1mm. If not,
-then you probably want to move the probe up or down to fix this. You
-want it to trigger well before the nozzle hits the bed, so that
-possible stuck filament or a warped bed doesn't affect any probing
-action. But at the same time, you want the retracted position to be as
-far above the nozzle as possible to avoid it touching printed parts.
-If an adjustment is made to the probe position, then rerun the probe
-calibration steps.
-
 BL-Touch gone bad
 =================
 
-Once the BL-Touch is in inconsistent state, it starts blinking
+Once the BL-Touch is in inconsistent state, it starts blinking red.
-red. You can force it to leave that state by issuing:
+You can force it to leave that state by issuing:
 
  BLTOUCH_DEBUG COMMAND=reset
 
@@ -116,6 +101,59 @@ right position so it is able to lower and raise the pin and the red
 light turns on and of. Use the `reset`, `pin_up` and `pin_down`
 commands to achieve this.
 
+BL-Touch "clones"
+=================
+
+Many BL-Touch "clone" devices work correctly with Klipper using the
+default configuration. However, some "clone" devices may require
+configuration of `pin_up_reports_not_triggered` or
+`pin_up_touch_mode_reports_triggered`.
+
+Important! Do not configure `pin_up_reports_not_triggered` or
+`pin_up_touch_mode_reports_triggered` to False without first following
+these directions. Do not configure either of these to False on a
+genuine BL-Touch. Incorrectly setting these to False can increase
+probing time and can increase the risk of damaging the printer.
+
+Some "clone" devices are unable to perform Klipper's internal sensor
+verification test. On these devices, attempts to home or probe can
+result in Klipper reporting a "BLTouch failed to verify sensor state"
+error. If this occurs, then manually run the steps to confirm the
+sensor pin is working as described in the
+[initial tests section](#initial-tests). If the `QUERY_PROBE` commands
+in that test always produce the expected results and "BLTouch failed
+to verify sensor state" errors still occur, then it may be necessary
+to set `pin_up_touch_mode_reports_triggered` to False in the Klipper
+config file.
+
+A rare number of old "clone" devices are unable to report when they
+have successfully raised their probe. On these devices Klipper will
+report a "BLTouch failed to raise probe" error after every home or
+probe attempt. One can test for these devices - move the head far from
+the bed, run `BLTOUCH_DEBUG COMMAND=pin_down`, verify the pin has
+moved down, run `QUERY_PROBE`, verify that command reports "probe:
+open", run `BLTOUCH_DEBUG COMMAND=pin_up`, verify the pin has moved
+up, and run `QUERY_PROBE`. If the pin remains up, the device does not
+enter an error state, and the first query reports "probe: open" while
+the second query reports "probe: TRIGGERED" then it indicates that
+`pin_up_reports_not_triggered` should be set to False in the Klipper
+config file.
+
+Calibrating the BL-Touch offsets
+================================
+
+Follow the directions in the [Probe Calibrate](Probe_Calibrate.md)
+guide to set the x_offset, y_offset, and z_offset config parameters.
+
+It's a good idea to verify that the Z offset is close to 1mm. If not,
+then you probably want to move the probe up or down to fix this. You
+want it to trigger well before the nozzle hits the bed, so that
+possible stuck filament or a warped bed doesn't affect any probing
+action. But at the same time, you want the retracted position to be as
+far above the nozzle as possible to avoid it touching printed parts.
+If an adjustment is made to the probe position, then rerun the probe
+calibration steps.
+
 BL-Touch output mode
 ====================
 
@@ -158,12 +196,6 @@ BL-Touch output mode
 Troubleshooting
 ===============
 
-* If you are sure the wiring of the BL-Touch is correct and every
-  attempt to probe with the BL-Touch reports "BLTouch failed to verify
-  sensor state" then it may be necessary to add
-  `pin_up_touch_mode_reports_triggered: False` to the bltouch config
-  section. The BL-Touch v3 and many clones require this setting.
-
 * A BL-Touch v3 may not work correctly when its signal wire is
   connected to the Z end-stop pin on some printer boards. The symptoms
   of this problem are: the BL-Touch probe deploys, the printer