Fix usage, commentary of MANUAL_PROBE_START_Z, Z_AFTER_PROBING (#21692)

Co-authored-by: Scott Lahteine <thinkyhead@users.noreply.github.com>

Marlin/Configuration.h

  * or (with LCD_BED_LEVELING) the LCD controller.
  */
 //#define PROBE_MANUALLY
-//#define MANUAL_PROBE_START_Z 0.2
 
 /**
  * A Fix-Mounted Probe either doesn't deploy or needs manual deployment.
  */
 //#define DEBUG_LEVELING_FEATURE
 
+#if ANY(MESH_BED_LEVELING, AUTO_BED_LEVELING_UBL, PROBE_MANUALLY)
+  // Set a height for the start of manual adjustment
+  #define MANUAL_PROBE_START_Z 0.2  // (mm) Comment out to use the last-measured height
+#endif
+
 #if ANY(MESH_BED_LEVELING, AUTO_BED_LEVELING_BILINEAR, AUTO_BED_LEVELING_UBL)
   // Gradually reduce leveling correction until a set height is reached,
   // at which point movement will be level to the machine's XY plane.

Marlin/src/feature/bedlevel/bedlevel.cpp

 
   void _manual_goto_xy(const xy_pos_t &pos) {
 
+    // Get the resting Z position for after the XY move
     #ifdef MANUAL_PROBE_START_Z
-      constexpr float startz = _MAX(0, MANUAL_PROBE_START_Z);
-      #if MANUAL_PROBE_HEIGHT > 0
-        do_blocking_move_to_xy_z(pos, MANUAL_PROBE_HEIGHT);
-        do_blocking_move_to_z(startz);
-      #else
-        do_blocking_move_to_xy_z(pos, startz);
-      #endif
-    #elif MANUAL_PROBE_HEIGHT > 0
-      const float prev_z = current_position.z;
-      do_blocking_move_to_xy_z(pos, MANUAL_PROBE_HEIGHT);
-      do_blocking_move_to_z(prev_z);
+      constexpr float finalz = _MAX(0, MANUAL_PROBE_START_Z); // If a MANUAL_PROBE_START_Z value is set, always respect it
     #else
-      do_blocking_move_to_xy(pos);
+      #warning "It's recommended to set some MANUAL_PROBE_START_Z value for manual leveling."
+    #endif
+    #if Z_CLEARANCE_BETWEEN_MANUAL_PROBES > 0     // A probe/obstacle clearance exists so there is a raise:
+      #ifndef MANUAL_PROBE_START_Z
+        const float finalz = current_position.z;  // - Use the current Z for starting-Z if no MANUAL_PROBE_START_Z was provided
+      #endif
+      do_blocking_move_to_xy_z(pos, Z_CLEARANCE_BETWEEN_MANUAL_PROBES); // - Raise Z, then move to the new XY
+      do_blocking_move_to_z(finalz);              // - Lower down to the starting Z height, ready for adjustment!
+    #elif defined(MANUAL_PROBE_START_Z)           // A starting-Z was provided, but there's no raise:
+      do_blocking_move_to_xy_z(pos, finalz);      // - Move in XY then down to the starting Z height, ready for adjustment!
+    #else                                         // Zero raise and no starting Z height either:
+      do_blocking_move_to_xy(pos);                // - Move over with no raise, ready for adjustment!
     #endif
-
-    current_position = pos;
 
     TERN_(LCD_BED_LEVELING, ui.wait_for_move = false);
   }
 
-#endif
+#endif // MESH_BED_LEVELING || PROBE_MANUALLY
 
 #endif // HAS_LEVELING

Marlin/src/gcode/bedlevel/mbl/G29.cpp

       // For each G29 S2...
       if (mbl_probe_index == 0) {
         // Move close to the bed before the first point
-        do_blocking_move_to_z(MANUAL_PROBE_START_Z);
+        do_blocking_move_to_z(0.4f
+          #ifdef MANUAL_PROBE_START_Z
+            + (MANUAL_PROBE_START_Z) - 0.4f
+          #endif
+        );
       }
       else {
         // Save Z for the previous mesh position
         _manual_goto_xy({ mbl.index_to_xpos[ix], mbl.index_to_ypos[iy] });
       }
       else {
-        // One last "return to the bed" (as originally coded) at completion
-        current_position.z = MANUAL_PROBE_HEIGHT;
+        // Move to the after probing position
+        current_position.z = (
+          #ifdef Z_AFTER_PROBING
+            Z_AFTER_PROBING
+          #else
+            Z_CLEARANCE_BETWEEN_MANUAL_PROBES
+          #endif
+        );
         line_to_current_position();
         planner.synchronize();
 

Marlin/src/inc/Conditionals_LCD.h

   #endif
 #endif // FILAMENT_RUNOUT_SENSOR
 
-#if EITHER(MESH_BED_LEVELING, AUTO_BED_LEVELING_UBL)
-  #undef PROBE_MANUALLY
-#endif
-
-#if ANY(HAS_BED_PROBE, PROBE_MANUALLY, MESH_BED_LEVELING)
-  #define PROBE_SELECTED 1
-#endif
-
 #if HAS_BED_PROBE
   #if DISABLED(NOZZLE_AS_PROBE)
     #define HAS_PROBE_XY_OFFSET 1
     #define PLANNER_LEVELING 1
   #endif
 #endif
-#if EITHER(HAS_ABL_OR_UBL, Z_MIN_PROBE_REPEATABILITY_TEST)
-  #define HAS_PROBING_PROCEDURE 1
-#endif
 #if !HAS_LEVELING
-  #undef PROBE_MANUALLY
   #undef RESTORE_LEVELING_AFTER_G28
   #undef ENABLE_LEVELING_AFTER_G28
 #endif
+#if !HAS_LEVELING || EITHER(MESH_BED_LEVELING, AUTO_BED_LEVELING_UBL)
+  #undef PROBE_MANUALLY
+#endif
+#if ANY(HAS_BED_PROBE, PROBE_MANUALLY, MESH_BED_LEVELING)
+  #define PROBE_SELECTED 1
+#endif
 
 #ifdef GRID_MAX_POINTS_X
   #define GRID_MAX_POINTS ((GRID_MAX_POINTS_X) * (GRID_MAX_POINTS_Y))

Marlin/src/inc/Conditionals_post.h

     #define Z_CLEARANCE_BETWEEN_PROBES Z_HOMING_HEIGHT
   #endif
   #if Z_CLEARANCE_BETWEEN_PROBES > Z_HOMING_HEIGHT
-    #define MANUAL_PROBE_HEIGHT Z_CLEARANCE_BETWEEN_PROBES
+    #define Z_CLEARANCE_BETWEEN_MANUAL_PROBES Z_CLEARANCE_BETWEEN_PROBES
   #else
-    #define MANUAL_PROBE_HEIGHT Z_HOMING_HEIGHT
+    #define Z_CLEARANCE_BETWEEN_MANUAL_PROBES Z_HOMING_HEIGHT
   #endif
   #ifndef Z_CLEARANCE_MULTI_PROBE
     #define Z_CLEARANCE_MULTI_PROBE Z_CLEARANCE_BETWEEN_PROBES
   #endif
 #endif
 
-#if !defined(MANUAL_PROBE_START_Z) && defined(Z_CLEARANCE_BETWEEN_PROBES)
-  #define MANUAL_PROBE_START_Z Z_CLEARANCE_BETWEEN_PROBES
+// Define a starting height for measuring manual probe points
+#ifndef MANUAL_PROBE_START_Z
+  #if EITHER(MESH_BED_LEVELING, PROBE_MANUALLY)
+    // Leave MANUAL_PROBE_START_Z undefined so the prior Z height will be used.
+    // Note: If Z_CLEARANCE_BETWEEN_MANUAL_PROBES is 0 there will be no raise between points
+  #elif ENABLED(AUTO_BED_LEVELING_UBL) && defined(Z_CLEARANCE_BETWEEN_PROBES)
+    #define MANUAL_PROBE_START_Z Z_CLEARANCE_BETWEEN_PROBES
+  #endif
 #endif
 
 #ifndef __SAM3X8E__ //todo: hal: broken hal encapsulation

Marlin/src/lcd/menu/menu_bed_leveling.cpp

   // and allow the command queue to be processed.
   //
   // When G29 finishes the last move:
-  // - Raise Z to the "manual probe height"
+  // - Raise Z to the "Z after probing" height
   // - Don't return until done.
   //
   // ** This blocks the command queue! **
   //
   void _lcd_level_bed_done() {
     if (!ui.wait_for_move) {
-      #if MANUAL_PROBE_HEIGHT > 0 && DISABLED(MESH_BED_LEVELING)
+      #if Z_AFTER_PROBING > 0 && DISABLED(MESH_BED_LEVELING)
         // Display "Done" screen and wait for moves to complete
-        line_to_z(MANUAL_PROBE_HEIGHT);
+        line_to_z(Z_AFTER_PROBING);
         ui.synchronize(GET_TEXT(MSG_LEVEL_BED_DONE));
       #endif
       ui.goto_previous_screen_no_defer();