BLTouch v3 / 3DTouch Interoperability & performance (#13814)

Marlin/Configuration.h

@@ -828,18 +828,14 @@
  */
 //#define BLTOUCH
 #if ENABLED(BLTOUCH)
-  //#define BLTOUCH_DELAY 375   // (ms) Enable and increase if needed
+  //#define BLTOUCH_DELAY 500   // Minimum Command delay (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.
    */
-  //#define BLTOUCH_V3
-  #if ENABLED(BLTOUCH_V3)
-    //#define BLTOUCH_FORCE_5V_MODE
-    //#define BLTOUCH_FORCE_OPEN_DRAIN_MODE
-  #endif
+  //#define BLTOUCH_FORCE_5V_MODE
 #endif
 
 // A probe that is deployed and stowed with a solenoid pin (SOL1_PIN)

Marlin/src/feature/bltouch.cpp

@@ -35,15 +35,32 @@ 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);
+bool BLTouch::command(const BLTCommand cmd, const millis_t &ms) {
+  if (DEBUGGING(LEVELING)) SERIAL_ECHOLNPAIR("BLTouch Command :", cmd);
   MOVE_SERVO(Z_PROBE_SERVO_NR, cmd);
-  safe_delay(BLTOUCH_DELAY);
+  safe_delay(MAX(ms, BLTOUCH_DELAY)); // BLTOUCH_DELAY is also the *minimum* delay
+  return triggered();
 }
 
 void BLTouch::init() {
-  reset();                            // Clear all BLTouch error conditions
-  stow();
+  // 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::triggered() {
@@ -56,41 +73,92 @@ 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;
+bool BLTouch::deploy_proc() {
+  // Do a DEPLOY
+  if (DEBUGGING(LEVELING)) DEBUG_ECHOLN("BLTouch DEPLOY requested");
+
+  // 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 (DEBUGGING(LEVELING)) DEBUG_ECHOLN("BLTouch ALARM or TRIGGER after DEPLOY, recovering");
+
+    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 (DEBUGGING(LEVELING)) DEBUG_ECHOLN("BLTouch Recovery Failed");
+
+      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
     }
   }
 
-  #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();
-    #endif
-  #endif
+  // Now the probe is ready to issue a 10ms pulse 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 (in_deploy) {
-    _deploy();
-    #if ENABLED(BLTOUCH_V3)
-      set_SW_mode();
-    #endif
+  if (DEBUGGING(LEVELING)) DEBUG_ECHOLN("bltouch.deploy_proc() end");
+
+  return false; // report success to caller
+}
+
+bool BLTouch::stow_proc() {
+  // Do a STOW
+  if (DEBUGGING(LEVELING)) DEBUG_ECHOLN("BLTouch STOW requested");
+
+  // A STOW will clear a triggered condition in the probe (10ms pulse).
+  // 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 (DEBUGGING(LEVELING)) DEBUG_ECHOLN("BLTouch ALARM or TRIGGER after STOW, recovering");
+
+    _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 (DEBUGGING(LEVELING)) DEBUG_ECHOLN("BLTouch Recovery Failed");
+
+      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_ECHOLN("bltouch.stow_proc() end");
+
+  return false; // report success to caller
+}
+
+bool BLTouch::status_proc() {
+  /**
+   * Return a TRUE for "YES, it is DEPLOYED"
+   * This function will ensure switch state is reset after execution
+   * This may change pin position in some scenarios, specifically
+   * if the pin has been triggered but not yet stowed.
+   */
+
+  if (DEBUGGING(LEVELING)) DEBUG_ECHOLN("BLTouch STATUS requested");
+
+  _set_SW_mode();
+  const bool tr = triggered(); // If triggered in SW mode, the pin is up, it is STOWED
+
+  if (DEBUGGING(LEVELING)) DEBUG_ECHOLNPAIR("BLTouch is ", (int)tr);
 
-  return false;
+  _reset();                         // turn off the SW Mode
+  if (tr) _stow(); else _deploy();  // and reset any triggered signal, restore state
+  return !tr;
 }
 
 #endif // BLTOUCH

Marlin/src/feature/bltouch.h

@@ -26,37 +26,75 @@
 // 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
+
+/**
+ * The following commands may require different delays.
+ *
+ * ANTClabs recommends 2000ms for 5V/OD commands. However it is
+ * not common for other commands to immediately follow these,
+ * and testing has shown that these complete in 500ms reliably.
+ *
+ * AntClabs recommends 750ms for Deploy/Stow, otherwise you will
+ * not catch an alarm state until the following move command.
+ */
+
+#ifndef BLTOUCH_SET5V_DELAY
+  #define BLTOUCH_SET5V_DELAY   BLTOUCH_DELAY
+#endif
+#ifndef BLTOUCH_SETOD_DELAY
+  #define BLTOUCH_SETOD_DELAY   BLTOUCH_DELAY
+#endif
+#ifndef BLTOUCH_DEPLOY_DELAY
+  #define BLTOUCH_DEPLOY_DELAY   750
+#endif
+#ifndef BLTOUCH_STOW_DELAY
+  #define BLTOUCH_STOW_DELAY     750
+#endif
+#ifndef BLTOUCH_RESET_DELAY
+  #define BLTOUCH_RESET_DELAY    BLTOUCH_DELAY
+#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_proc(); }
+  FORCE_INLINE static bool stow()                { return stow_proc(); }
+  FORCE_INLINE static bool status()              { return status_proc(); }
 
-  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_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_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, const millis_t &ms);
+  static bool deploy_proc();
+  static bool stow_proc();
+  static bool status_proc();
 };
 
+// Deploy/stow angles for use by servo.cpp / servo.h
 #define BLTOUCH_ANGLES { BLTOUCH_DEPLOY, BLTOUCH_STOW }
 
 extern BLTouch bltouch;

Marlin/src/gcode/calibrate/G34_M422.cpp

@@ -112,8 +112,7 @@ void GcodeSuite::G34() {
     #endif
 
     #if ENABLED(BLTOUCH)
-      bltouch.reset();
-      bltouch.stow();
+      bltouch.init();
     #endif
 
     // Always home with tool 0 active

Marlin/src/inc/Conditionals_LCD.h

@@ -465,9 +465,6 @@
     #undef SERVO_DELAY
     #define SERVO_DELAY { 50 }
   #endif
-  #ifndef BLTOUCH_DELAY
-    #define BLTOUCH_DELAY 375
-  #endif
 
   // Always disable probe pin inverting for BLTouch
   #undef Z_MIN_PROBE_ENDSTOP_INVERTING

Marlin/src/inc/Conditionals_post.h

@@ -1578,6 +1578,9 @@
   #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
+  #endif
 #endif
 
 #ifndef __SAM3X8E__ //todo: hal: broken hal encapsulation

Marlin/src/inc/SanityCheck.h

@@ -210,6 +210,10 @@
   #error "UBL_MESH_EDITING is now G26_MESH_VALIDATION. Please update your configuration."
 #elif defined(BLTOUCH_HEATERS_OFF)
   #error "BLTOUCH_HEATERS_OFF is now PROBING_HEATERS_OFF. Please update your configuration."
+#elif defined(BLTOUCH_V3)
+  #error "BLTOUCH_V3 is obsolete. Please update your configuration."
+#elif defined(BLTOUCH_FORCE_OPEN_DRAIN_MODE)
+  #error "BLTOUCH_FORCE_OPEN_DRAIN_MODE is obsolete. Please update your configuration."
 #elif defined(BEEPER)
   #error "BEEPER is now BEEPER_PIN. Please update your pins definitions."
 #elif defined(SDCARDDETECT)
@@ -1018,6 +1022,14 @@ static_assert(Y_MAX_LENGTH >= Y_BED_SIZE, "Movement bounds (Y_MIN_POS, Y_MAX_POS
     #endif
   #endif
 
+  #if ENABLED(BLTOUCH)
+    #if BLTOUCH_DELAY < 200
+      #error "BLTOUCH_DELAY less than 200 is unsafe and is not supported."
+    #elif DISABLED(BLTOUCH_FORCE_5V_MODE) && NONE(ENDSTOPPULLUPS, ENDSTOPPULLUP_ZMIN, ENDSTOPPULLUP_ZMIN_PROBE)
+      #error "BLTOUCH without BLTOUCH_FORCE_5V_MODE requires ENDSTOPPULLUPS, ENDSTOPPULLUP_ZMIN or ENDSTOPPULLUP_ZMIN_PROBE."
+    #endif
+  #endif
+
   #if ENABLED(RACK_AND_PINION_PROBE) && !(defined(Z_PROBE_DEPLOY_X) && defined(Z_PROBE_RETRACT_X))
     #error "RACK_AND_PINION_PROBE requires Z_PROBE_DEPLOY_X and Z_PROBE_RETRACT_X."
   #endif

Marlin/src/lcd/language/language_en.h

@@ -904,7 +904,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,15 +174,13 @@ 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_RESET, bltouch._reset);
+    MENU_ITEM(function, MSG_BLTOUCH_SELFTEST, bltouch._selftest);
     MENU_ITEM(function, MSG_BLTOUCH_DEPLOY, bltouch._deploy);
     MENU_ITEM(function, MSG_BLTOUCH_STOW, bltouch._stow);
-    #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);
-    #endif
+    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);
     END_MENU();
   }
 

Marlin/src/module/endstops.cpp

@@ -40,6 +40,10 @@
   #include "printcounter.h" // for print_job_timer
 #endif
 
+#if ENABLED(BLTOUCH)
+  #include "../feature/bltouch.h"
+#endif
+
 Endstops endstops;
 
 // private:
@@ -381,6 +385,9 @@ static void print_es_state(const bool is_hit, PGM_P const label=NULL) {
 }
 
 void _O2 Endstops::M119() {
+  #if ENABLED(BLTOUCH)
+    bltouch._set_SW_mode();
+  #endif
   SERIAL_ECHOLNPGM(MSG_M119_REPORT);
   #define ES_REPORT(S) print_es_state(READ(S##_PIN) != S##_ENDSTOP_INVERTING, PSTR(MSG_##S))
   #if HAS_X_MIN
@@ -457,6 +464,10 @@ void _O2 Endstops::M119() {
       }
     #endif
   #endif
+  #if ENABLED(BLTOUCH)
+    bltouch._reset();
+    if (enabled_globally) bltouch._stow();
+  #endif
 } // Endstops::M119
 
 // The following routines are called from an ISR context. It could be the temperature ISR, the