Comprehensive BLTouch implementation

Marlin/Configuration.h

@@ -825,17 +825,47 @@
  */
 //#define BLTOUCH
 #if ENABLED(BLTOUCH)
-  //#define BLTOUCH_DELAY 375   // (ms) Enable and increase if needed
-
   /**
-   * BLTouch V3.0 and newer smart series
-   * For genuine BLTouch 3.0 sensors. Clones may be confused by 3.0 command angles. YMMV.
-   * If the pin trigger is not detected, first try swapping the black and white wires then toggle this.
+   * For all BLTouch probes and clones:
+   */
+  //#define BLTOUCH_DEBUG_MSGS  // Produce some debugging messages when commands are issued to the probe
+  //#define BLTOUCH_DELAY 375   // (ms) Allow the servo signal to settle for this long before the next command
+                                // Note: This is the sane default. Some setups will tolerate lower values.
+
+  /**
+   * For BLTouch V2.0 and newer probes which support SW mode. Some clones do too.
+   * Set the probe into SW mode, producing a longer pulse when triggered, useful when there
+   * is noise or high capacitance on the signal pin.
+   * If your probe works fine without this, don't turn it on, as it slows down probing
+   * Note: Performing a STOW and then setting this mode in the LCD BLTouch configuration menu
+   *       manually will alloy you to check the wiring with a M119 command. You don't need to enable
+   *       this in order to be able to do that.
+   */
+  //#define BLTOUCH_FORCE_SW_MODE
+
+  /**
+   * For BLTouch V3.0 and newer probes:
+   * If you want the new functions of the BLTouch V3 or you need 5V mode (see below), enable this.
+   * This adds the special V3 commands (5V and OD modes) to the LCD configuration menu for BLTouch
    */
   //#define BLTOUCH_V3
-  #if ENABLED(BLTOUCH_V3)
+  #if ENABLED(BLTOUCH_V3)  
+    /**
+     * These probes default to OPEN DRAIN mode. All other probes are in 5V mode per default.
+     * If you have a BLTouch V3.0 or newer and explicitely want 5V mode, use this define - this
+     * makes it more compatible with previous probe versions.
+     * Warning: Make sure your controller boards input pin is 5V tolerant.
+     */
     //#define BLTOUCH_FORCE_5V_MODE
-    //#define BLTOUCH_FORCE_OPEN_DRAIN_MODE
+    /**
+     * Advanced users who fervently believe in the reliability of their BLTouch probes can
+     * activate the HIGH SPEED mode for their unit. This will reduce the timing so far that
+     * DEPLOY and STOW failures are only captured on the NEXT such command to be issued.
+     * The result is faster probing but much less surety of catching and identifying errors.
+     * NOT RECOMMENDED for novice users and in unstable environments. As homing and probing are
+     * not done so often, the speed gain is nice but not really life changing.
+     */
+    //#define BLTOUCH_HS_MODE
   #endif
 #endif
 

Marlin/src/feature/bltouch.cpp

@@ -35,18 +35,8 @@ void stop();
 #define DEBUG_OUT ENABLED(DEBUG_LEVELING_FEATURE)
 #include "../core/debug_out.h"
 
-void BLTouch::command(const BLTCommand cmd) {
-  //SERIAL_ECHOLNPAIR("BLTouch Command :", cmd);
-  MOVE_SERVO(Z_PROBE_SERVO_NR, cmd);
-  safe_delay(BLTOUCH_DELAY);
-}
-
-void BLTouch::init() {
-  reset();                            // Clear all BLTouch error conditions
-  stow();
-}
-
 bool BLTouch::triggered() {
+  // Used in the main loop to check the pin state when probing and internally here
   return (
     #if ENABLED(Z_MIN_PROBE_USES_Z_MIN_ENDSTOP_PIN)
       READ(Z_MIN_PIN) != Z_MIN_ENDSTOP_INVERTING
@@ -56,41 +46,138 @@ bool BLTouch::triggered() {
   );
 }
 
-bool BLTouch::set_deployed(const bool in_deploy) {
-  if (in_deploy && triggered()) {     // If BLTouch says it's triggered
-    reset();                          //  try to reset it.
-    _deploy(); _stow();               // Deploy and stow to clear the "triggered" condition.
-    safe_delay(1500);                 // Wait for internal self-test to complete.
-                                      //  (Measured completion time was 0.65 seconds
-                                      //   after reset, deploy, and stow sequence)
-    if (triggered()) {                // If it still claims to be triggered...
-      SERIAL_ERROR_MSG(MSG_STOP_BLTOUCH);
-      stop();                         // punt!
-      return true;
-    }
+void BLTouch::init() {
+  // This is called by marlin.cpp on initialization
+  // SET_5V_MODE (if enabled). OD_MODE is the default on power on.
+  // This mode will stay active until manual SET_OD_MODE or power cycle
+  #if ENABLED(BLTOUCH_FORCE_5V_MODE)         
+    _set_5V_mode();                          // Set 5V mode if explicitely demanded (V3 upwards)
+  #endif
+  clear();
+  // There really should be no alarm outstanding now, and no triggered condition. But if there is,
+  // there is no need to worry people here on init right at the start of the printer.
+}
+
+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
+               // ANTClabs <-- CODE ERROR
+  _stow();     // STOW will pull up the pin and clear any triggered condition unless it fails, don't care
+  _deploy();   // DEPLOY to test the probe. Could fail, don't care
+  _stow();     // STOW to be ready for meaningful work. Could fail, don't care
+}
+
+bool BLTouch::command(const BLTCommand cmd, millis_t ms) {
+  #if ENABLED(BLTOUCH_DEBUG_MSGS)
+    SERIAL_ECHOLNPAIR("BLTouch Command :", cmd);
+  #endif
+  MOVE_SERVO(Z_PROBE_SERVO_NR, cmd);
+  // If BLTOUCH_DELAY is higher than the desired ms delay, it will override
+  if (BLTOUCH_DELAY > ms) {
+    ms = BLTOUCH_DELAY;
+  }
+  // Don't wait longer than necessary if an ALARM pops up. Check trigger
+  // in increments of 50ms to catch the ALARM right away.
+  // Instead of using safe_delay in the following loop, we could use delay
+  // and do the calling of the temperature-manager ourself. See safe_delay() for
+  // details. TODO
+  while (ms > 50) {
+    ms -= 50;
+    safe_delay(50);
+    if (cmd == BLTOUCH_RESET) continue;
+    if (triggered()) return true;
   }
+  safe_delay(ms);
+  return triggered();
+}
 
-  #if ENABLED(BLTOUCH_V3)
-    #if  EITHER(BLTOUCH_FORCE_5V_MODE, ENDSTOPPULLUPS) \
-      || ALL(Z_MIN_PROBE_USES_Z_MIN_ENDSTOP_PIN, ENDSTOPPULLUP_ZMIN) \
-      || (USES_Z_MIN_PROBE_ENDSTOP && ENABLED(ENDSTOPPULLUP_ZMIN_PROBE))
-      set_5V_mode();  // Assume 5V DC logic level if endstop pullup resistors are enabled
-    #elif true || ENABLED(BLTOUCH_FORCE_OPEN_DRAIN_MODE)
-      set_OD_mode();
+bool BLTouch::deploy_wrapper() {
+  // Do a DEPLOY
+  #if ENABLED(BLTOUCH_DEBUG_MSGS)
+    SERIAL_ECHOLN("BLTouch DEPLOY requested");
+  #endif
+
+  // Attempt to DEPLOY, wait for DEPLOY_DELAY or ALARM
+  if (_deploy_query_alarm()) {                      
+    // The deploy might have failed or the probe is already triggered (nozzle too low?)
+    #if ENABLED(BLTOUCH_DEBUG_MSGS)
+      SERIAL_ECHOLN("BLTouch ALARM or TRIGGER after DEPLOY, recovering");
     #endif
+
+    clear();                               // Get the probe into start condition
+
+    // Last attempt to DEPLOY      
+    if (_deploy_query_alarm()) {                
+      // The deploy might have failed or the probe is actually triggered (nozzle too low?) again
+      #if ENABLED(BLTOUCH_DEBUG_MSGS)
+        SERIAL_ECHOLN("BLTouch ALARM or TRIGGER after DEPLOY, recovery failed");
+      #endif
+
+      SERIAL_ERROR_MSG(MSG_STOP_BLTOUCH);  // Tell the user something is wrong, needs action
+      stop();                              // but i'ts not too bad, no need to kill, allow restart
+
+      return true;                         // Tell our caller we goofed in case he cares to know
+    }                    
+  }
+
+  // The BLTouch V3 (and V2) and some clones can be used in "SWITCH" mode. When triggered, 
+  // instead of a 10ms pulse, there is an indefinetly long trigger condition, until 
+  // reset by the STOW as soon as this "very very long" pulse is registered. Might help in cases
+  // where the trigger pulse is difficult to register (noise, caps on the signal)
+  // Entering this mode manually also enables M119 display of the probe pin state.
+  #if ENABLED(BLTOUCH_FORCE_SW_MODE) 
+    _set_SW_mode();                        // If explicitely demanded, RESET into SW mode
   #endif
 
-  if (in_deploy) {
-    _deploy();
-    #if ENABLED(BLTOUCH_V3)
-      set_SW_mode();
+  // Now the probe is ready to issue a 10ms pulse (or longer, if in SW mode) when the pin goes up.
+  // The trigger STOW (see motion.cpp for example) will pull up the probes pin as soon as the pulse
+  // is registered.
+
+  if (DEBUGGING(LEVELING)) DEBUG_ECHOLNPAIR("bltouch.deploy_wrapper()");
+
+  return false; // report success to caller
+}
+
+bool BLTouch::stow_wrapper() {
+  // Do a STOW
+  #if ENABLED(BLTOUCH_DEBUG_MSGS)
+    SERIAL_ECHOLN("BLTouch STOW requested");
+  #endif
+
+  // A STOW will clear a triggered condition in the probe (10ms pulse or the "very very long" pulse
+  // in SW mode).
+  // At the moment that we come in here, we might (pulse) or will (SW mode) see the trigger on the pin.
+  // So even though we know a STOW will be ignored if an ALARM condition is active, we will STOW.
+  // Note: If the probe is deployed AND in an ALARM condition, this STOW will not pull up the pin 
+  // and the ALARM condition will still be there. --> ANTClabs should change this behaviour maybe
+
+  // Attempt to STOW, wait for STOW_DELAY or ALARM
+  if (_stow_query_alarm()) {               
+    // The stow might have failed
+    #if ENABLED(BLTOUCH_DEBUG_MSGS)
+      SERIAL_ECHOLN("BLTouch ALARM or TRIGGER after STOW, recovering");
     #endif
+
+    _reset();                              // This RESET will then also pull up the pin. If it doesn't
+                                           // work and the pin is still down, there will no longer be
+                                           // an ALARM condition though.
+                                           // But one more STOW will catch that
+    // Last attempt to STOW
+    if (_stow_query_alarm()) {             // so if there is now STILL an ALARM condition:
+      #if ENABLED(BLTOUCH_DEBUG_MSGS)
+        SERIAL_ECHOLN("BLTouch ALARM or TRIGGER after STOW, recovery failed");
+      #endif
+
+      SERIAL_ERROR_MSG(MSG_STOP_BLTOUCH);  // Tell the user something is wrong, needs action
+      stop();                              // but it's not too bad, no need to kill, allow restart
+
+      return true;                         // Tell our caller we goofed in case he cares to know
+    }
   }
-  else _stow();
 
-  if (DEBUGGING(LEVELING)) DEBUG_ECHOLNPAIR("bltouch.set_deployed(", in_deploy, ")");
+  if (DEBUGGING(LEVELING)) DEBUG_ECHOLNPAIR("bltouch.stow_wrapper()");
 
-  return false;
+  return false; // report success to caller
 }
 
 #endif // BLTOUCH

Marlin/src/feature/bltouch.h

@@ -26,37 +26,71 @@
 // BLTouch commands are sent as servo angles
 typedef unsigned char BLTCommand;
 
-#define BLTOUCH_DEPLOY    10
-#define BLTOUCH_SW_MODE   60
-#define BLTOUCH_STOW      90
-#define BLTOUCH_SELFTEST 120
-#define BLTOUCH_5V_MODE  140
-#define BLTOUCH_OD_MODE  150
-#define BLTOUCH_RESET    160
+#define BLTOUCH_DEPLOY          10
+#define BLTOUCH_SW_MODE         60
+#define BLTOUCH_STOW            90
+#define BLTOUCH_SELFTEST       120
+#define BLTOUCH_5V_MODE        140
+#define BLTOUCH_OD_MODE        150
+#define BLTOUCH_RESET          160
+
+// Note: BLTOUCH_DELAY from configuration.h will override these values IF it is larger.
+// See command() in bltouch.cpp for more details
+// Delay for all commands other then the exceptions below
+#define BLTOUCH_CMDMIN_DELAY   150
+// The following delays are needed for some of the commands, instead of the CMDMIN_DELAY
+#define BLTOUCH_RESET_DELAY    500
+#define BLTOUCH_SET5V_DELAY   2000 // This is according to ANTClabs. Seems a bit high???
+#define BLTOUCH_SETOD_DELAY   2000 // Probably also according to ANTClabs. Seems a bit high???
+
+// Set the following to zero for highspeed probing mode. Works fine, but does not catch deploy or stow
+// errors after the command - instead the error catching is deferred to the subsequent command. Printer
+// won't stop, instead it will skip the failed probes. If you consider your probe to be reliable beyond
+// a doubt, you can run this way. Not recommended but YMMV
+#if ENABLED(BLTOUCH_HS_MODE)
+  // So we probably won't recognize DEPLOY fails right away
+  #define BLTOUCH_DEPLOY_DELAY BLTOUCH_CMDMIN_DELAY 
+  #define BLTOUCH_STOW_DELAY   BLTOUCH_CMDMIN_DELAY
+  #undef BLTOUCH_DELAY
+  #define BLTOUCH_DELAY        BLTOUCH_CMDMIN_DELAY
+#else
+  // So that we can recognize DEPLOY fails
+  #define BLTOUCH_DEPLOY_DELAY 750 
+  #define BLTOUCH_STOW_DELAY   750
+#endif
 
 class BLTouch {
 public:
-  static void init();
-  static void command(const BLTCommand cmd);
-  static bool triggered();
+  static bool triggered();         // used by menu_advanced.cpp
+  static void init();              // used by main.cpp
 
-  FORCE_INLINE static void reset()       { command(BLTOUCH_RESET); }
-  FORCE_INLINE static void selftest()    { command(BLTOUCH_SELFTEST); }
+  // DEPLOY and STOW are wrapped for error handling - these are used by homing and by probing
+  FORCE_INLINE static bool deploy()              { return deploy_wrapper(); }
+  FORCE_INLINE static bool stow()                { return stow_wrapper(); }
 
-  FORCE_INLINE static void set_5V_mode() { command(BLTOUCH_5V_MODE); }
-  FORCE_INLINE static void set_OD_mode() { command(BLTOUCH_OD_MODE); }
-  FORCE_INLINE static void set_SW_mode() { command(BLTOUCH_SW_MODE); }
+  // Native BLTouch commands ("Underscore"...), used in lcd menus and internally
+  FORCE_INLINE static void _reset()              { command(BLTOUCH_RESET, BLTOUCH_RESET_DELAY); }
 
-  FORCE_INLINE static bool deploy()      { return set_deployed(true); }
-  FORCE_INLINE static bool stow()        { return set_deployed(false); }
+  FORCE_INLINE static void _selftest()           { command(BLTOUCH_SELFTEST, BLTOUCH_CMDMIN_DELAY); }
 
-  FORCE_INLINE static void _deploy()     { command(BLTOUCH_DEPLOY); }
-  FORCE_INLINE static void _stow()       { command(BLTOUCH_STOW); }
+  FORCE_INLINE static void _set_SW_mode()        { command(BLTOUCH_SW_MODE, BLTOUCH_CMDMIN_DELAY); }
+  FORCE_INLINE static void _set_5V_mode()        { command(BLTOUCH_5V_MODE, BLTOUCH_SET5V_DELAY); }
+  FORCE_INLINE static void _set_OD_mode()        { command(BLTOUCH_OD_MODE, BLTOUCH_SETOD_DELAY); }
+
+  FORCE_INLINE static void _deploy()             { command(BLTOUCH_DEPLOY, BLTOUCH_DEPLOY_DELAY); }
+  FORCE_INLINE static void _stow()               { command(BLTOUCH_STOW, BLTOUCH_STOW_DELAY); }
 
 private:
-  static bool set_deployed(const bool deploy);
+  FORCE_INLINE static bool _deploy_query_alarm() { return command(BLTOUCH_DEPLOY, BLTOUCH_DEPLOY_DELAY); }
+  FORCE_INLINE static bool _stow_query_alarm()   { return command(BLTOUCH_STOW, BLTOUCH_STOW_DELAY); }
+
+  static void clear();
+  static bool command(const BLTCommand cmd, millis_t ms);
+  static bool deploy_wrapper();
+  static bool stow_wrapper();
 };
 
+// This transfers the two needed angle values to the servo.cpp/servo.h routine
 #define BLTOUCH_ANGLES { BLTOUCH_DEPLOY, BLTOUCH_STOW }
 
 extern BLTouch bltouch;

Marlin/src/gcode/calibrate/G28.cpp

@@ -238,7 +238,8 @@ void GcodeSuite::G28(const bool always_home_all) {
   #endif
 
   #if ENABLED(BLTOUCH)
-    bltouch.init();
+    // It is safer to home with a stowed probe
+    bltouch.stow();
   #endif
 
   // Always home with tool 0 active

Marlin/src/gcode/calibrate/G34_M422.cpp

@@ -112,7 +112,6 @@ void GcodeSuite::G34() {
     #endif
 
     #if ENABLED(BLTOUCH)
-      bltouch.reset();
       bltouch.stow();
     #endif
 

Marlin/src/lcd/language/language_en.h

@@ -898,7 +898,7 @@
   #define MSG_BLTOUCH_DEPLOY                  _UxGT("Deploy BLTouch")
 #endif
 #ifndef MSG_BLTOUCH_SW_MODE
-  #define MSG_BLTOUCH_SW_MODE                 _UxGT("SW Deploy BLTouch")
+  #define MSG_BLTOUCH_SW_MODE                 _UxGT("BLTouch SW Mode")
 #endif
 #ifndef MSG_BLTOUCH_5V_MODE
   #define MSG_BLTOUCH_5V_MODE                 _UxGT("BLTouch 5V Mode")

Marlin/src/lcd/menu/menu_configuration.cpp

@@ -174,14 +174,15 @@ static void lcd_factory_settings() {
   void menu_bltouch() {
     START_MENU();
     MENU_BACK(MSG_MAIN);
-    MENU_ITEM(function, MSG_BLTOUCH_RESET, bltouch.reset);
-    MENU_ITEM(function, MSG_BLTOUCH_SELFTEST, bltouch.selftest);
-    MENU_ITEM(function, MSG_BLTOUCH_DEPLOY, bltouch._deploy);
+    // We offer the NATIVE, unwrapped BLTouch commands to the user
+    MENU_ITEM(function, MSG_BLTOUCH_RESET, bltouch._reset);
+    MENU_ITEM(function, MSG_BLTOUCH_SELFTEST, bltouch._selftest);
     MENU_ITEM(function, MSG_BLTOUCH_STOW, bltouch._stow);
+    MENU_ITEM(function, MSG_BLTOUCH_DEPLOY, bltouch._deploy);
+    MENU_ITEM(function, MSG_BLTOUCH_SW_MODE, bltouch._set_SW_mode);
     #if ENABLED(BLTOUCH_V3)
-      MENU_ITEM(function, MSG_BLTOUCH_SW_MODE, bltouch.set_SW_mode);
-      MENU_ITEM(function, MSG_BLTOUCH_5V_MODE, bltouch.set_5V_mode);
-      MENU_ITEM(function, MSG_BLTOUCH_OD_MODE, bltouch.set_OD_mode);
+      MENU_ITEM(function, MSG_BLTOUCH_5V_MODE, bltouch._set_5V_mode);
+      MENU_ITEM(function, MSG_BLTOUCH_OD_MODE, bltouch._set_OD_mode);
     #endif
     END_MENU();
   }