BLTouch::z_extra_clearance() use probe offset instead of full travel

Using the full probe stroke defeats some of the speed advantage for
using high speed mode, only use full probe stroke if the nozzle offset
isn't available.

Author: dfries

Marlin/Configuration.h

@@ -1621,6 +1621,12 @@
 #define Z_CLEARANCE_MULTI_PROBE     5 // Z Clearance between multiple probes
 //#define Z_AFTER_PROBING           5 // Z position after probing is done
 
+#if ENABLED(BLTOUCH_HS_MODE)
+// Probe offset is trigger point to nozzle. This need to be large enough to
+// get the probe pin off the bed or it will drag.
+#define Z_CLEARANCE_BLTOUCH_HS      3 // Extra Z Clearance
+#endif
+
 #define Z_PROBE_LOW_POINT          -2 // Farthest distance below the trigger-point to go before stopping
 
 // For M851 give a range for adjusting the Z probe offset

Marlin/src/feature/bltouch.cpp

@@ -84,6 +84,31 @@ void BLTouch::init(const bool set_voltage/*=false*/) {
     mode_conv_proc(ENABLED(BLTOUCH_SET_5V_MODE));
 }
 
+#ifdef BLTOUCH_HS_MODE
+float BLTouch::z_extra_clearance()
+{
+  // In BLTOUCH HS mode, the probe travels in a deployed state, set the
+  // clearance to raise Z to accommodate the deployed state.  Use probe
+  // offset + margin or if not available, the length of the deployed pin
+  // (BLTOUCH stroke < 7mm).
+  if(high_speed_mode)
+  {
+    // Only use probe offset option if a margin value is available.  Otherwise
+    // raising by the offset would give 0 clearance and probe offset is the
+    // trigger point, not the contact point.  Expect a minimum of 1mm before
+    // the probe pin lifts off the surface.
+    #if defined(Z_CLEARANCE_BLTOUCH_HS) && Z_CLEARANCE_BLTOUCH_HS > 0
+    // negative is expected and means probe is lower
+    if(probe.offset.z < 0)
+      return -probe.offset.z + Z_CLEARANCE_BLTOUCH_HS;
+    #endif
+    // offset not set or positive (invalid), use BLTOUCH stroke
+    return 7;
+  }
+  return 0;
+}
+#endif
+
 void BLTouch::clear() {
   _reset();    // RESET or RESET_SW will clear an alarm condition but...
                // ...it will not clear a triggered condition in SW mode when the pin is currently up

Marlin/src/feature/bltouch.h

@@ -72,12 +72,12 @@ class BLTouch {
 
   #ifdef BLTOUCH_HS_MODE
     static bool high_speed_mode;  // Initialized by settings.load, 0 = Low Speed; 1 = High Speed
+    static float z_extra_clearance();
   #else
     static constexpr bool high_speed_mode = false;
+    static float z_extra_clearance() { return 0; }
   #endif
 
-  static float z_extra_clearance() { return high_speed_mode ? 7 : 0; }
-
   // DEPLOY and STOW are wrapped for error handling - these are used by homing and by probing
   static bool deploy()              { return deploy_proc(); }
   static bool stow()                { return stow_proc(); }

Marlin/src/inc/Conditionals_post.h

@@ -3202,8 +3202,17 @@
   #ifndef Z_CLEARANCE_MULTI_PROBE
     #define Z_CLEARANCE_MULTI_PROBE Z_CLEARANCE_BETWEEN_PROBES
   #endif
-  #if ENABLED(BLTOUCH) && !defined(BLTOUCH_DELAY)
-    #define BLTOUCH_DELAY 500
+  #if ENABLED(BLTOUCH)
+    #if ENABLED(BLTOUCH_HS_MODE)
+      #if !defined(Z_CLEARANCE_BLTOUCH_HS) || Z_CLEARANCE_BLTOUCH_HS <= 0
+        // High speed mode moves with the probe deployed, this is to avoid
+        // dragging the probe after raising the probe to nozzle offset.
+        #warning "BLTOUCH_HS_MODE with a positive Z_CLEARANCE_BLTOUCH_HS will use the full probe stroke."
+      #endif
+    #endif
+    #if !defined(BLTOUCH_DELAY)
+      #define BLTOUCH_DELAY 500
+    #endif
   #endif
 #endif