better documentation

Marlin/Configuration.h

@@ -335,21 +335,44 @@ const bool Z_MAX_ENDSTOP_INVERTING = true; // set to true to invert the logic of
 
 #ifdef ENABLE_AUTO_BED_LEVELING
 
-// Enable auto bed leveling at any 3 points that aren't colinear
-#define AUTO_BED_LEVELING_ANY_POINTS
+// There are 3 different ways to pick the X and Y locations to probe:
+// 1. Basic 3-point probe at left-back, left-front, and right-front corners of a rectangle
+// 2. Probe all points of a 2D lattice, defined by a rectangle and ACCURATE_BED_LEVELING_POINTS
+// 3. 3-point probe at 3 arbitrary points that don't form a line.
 
-#ifdef AUTO_BED_LEVELING_ANY_POINTS
-  #define ABL_PROBE_PT_1_X -11
-  #define ABL_PROBE_PT_1_Y -15
-  #define ABL_PROBE_PT_2_X -11
-  #define ABL_PROBE_PT_2_Y 75
-  #define ABL_PROBE_PT_3_X 121
-  #define ABL_PROBE_PT_3_Y -15
+// To enable mode 1:
+//   - #define ENABLE_AUTO_BED_LEVELING
+//   - Set the XXXX_PROBE_BED_POSITION values below
+//   - Don't define AUTO_BED_LEVELING_ANY_POINTS or ACCURATE_BED_LEVELING
+
+// To enable mode 2:
+//  - #define ENABLE_AUTO_BED_LEVELING
+//  - Set the XXXX_PROBE_BED_POSITION values below
+//  - #define ACCURATE_BED_LEVELING
+//  - Set the ACCURATE_BED_LEVELING_POINTS to your desired density
+
+// To enable mode 3:
+//  - #define ENABLE_AUTO_BED_LEVELING
+//  - #define AUTO_BED_LEVELING_ANY_POINTS
+//  - Set the ABL_PROBE_PT_XXXX values below
+//  - Comment out (undefine) ACCURATE_BED_LEVELING since that is incompatible
 
 
+
+// Mode 3: Enable auto bed leveling at any 3 points that aren't colinear
+// #define AUTO_BED_LEVELING_ANY_POINTS
+#ifdef AUTO_BED_LEVELING_ANY_POINTS
+  #define ABL_PROBE_PT_1_X 15
+  #define ABL_PROBE_PT_1_Y 15
+  #define ABL_PROBE_PT_2_X 25
+  #define ABL_PROBE_PT_2_Y 75
+  #define ABL_PROBE_PT_3_X 125
+  #define ABL_PROBE_PT_3_Y 25
 #else // not AUTO_BED_LEVELING_ANY_POINTS
 
-  // these are the positions on the bed to do the probing
+  // Modes 1 & 2:
+  //   For mode 1, probing happens at left-back, left-front, and right-front corners
+  //   For mode 2, probing happens at lattice points within this rectangle (see ACCURATE_BED_LEVELING_POINTS)
   #define LEFT_PROBE_BED_POSITION 15
   #define RIGHT_PROBE_BED_POSITION 170
   #define BACK_PROBE_BED_POSITION 180
@@ -398,8 +421,11 @@ const bool Z_MAX_ENDSTOP_INVERTING = true; // set to true to invert the logic of
   // with accurate bed leveling, the bed is sampled in a ACCURATE_BED_LEVELING_POINTSxACCURATE_BED_LEVELING_POINTS grid and least squares solution is calculated
   // Note: this feature occupies 10'206 byte
   #define ACCURATE_BED_LEVELING
-
+  // Mode 2 only
   #ifdef ACCURATE_BED_LEVELING
+    #ifdef AUTO_BED_LEVELING_ANY_POINTS
+      #error AUTO_BED_LEVELING_ANY_POINTS is incompatible with ACCURATE_BED_LEVELING
+    #endif
      // I wouldn't see a reason to go above 3 (=9 probing points on the bed)
     #define ACCURATE_BED_LEVELING_POINTS 2
   #endif

Marlin/Marlin_main.cpp

@@ -1433,7 +1433,7 @@ void process_commands()
       break;
 
 #ifdef ENABLE_AUTO_BED_LEVELING
-    case 29: // G29 Detailed Z-Probe, probes the bed at 3 points.
+    case 29: // G29 Detailed Z-Probe, probes the bed at 3 or more points.
         {
             #if Z_MIN_PIN == -1
             #error "You must have a Z_MIN endstop in order to enable Auto Bed Leveling feature!!! Z_MIN_PIN must point to a valid hardware pin."
@@ -1463,6 +1463,7 @@ void process_commands()
 
             feedrate = homing_feedrate[Z_AXIS];
 #ifdef ACCURATE_BED_LEVELING
+            // probe at the points of a lattice grid
 
             int xGridSpacing = (RIGHT_PROBE_BED_POSITION - LEFT_PROBE_BED_POSITION) / (ACCURATE_BED_LEVELING_POINTS-1);
             int yGridSpacing = (BACK_PROBE_BED_POSITION - FRONT_PROBE_BED_POSITION) / (ACCURATE_BED_LEVELING_POINTS-1);
@@ -1545,6 +1546,7 @@ void process_commands()
 
 
   #ifdef AUTO_BED_LEVELING_ANY_POINTS
+            // Probe at 3 arbitrary points
             // probe 1
             float z_at_pt_1 = probe_pt(ABL_PROBE_PT_1_X, ABL_PROBE_PT_1_Y, Z_RAISE_BEFORE_PROBING);
 
@@ -1558,14 +1560,14 @@ void process_commands()
 
             set_bed_level_equation_any_pts(z_at_pt_1, z_at_pt_2, z_at_pt_3);
   #else // not AUTO_BED_LEVELING_ANY_POINTS
-
-            // prob 1
+            // probe at 3 corners of a rectangle
+            // probe 1
             float z_at_xLeft_yBack = probe_pt(LEFT_PROBE_BED_POSITION, BACK_PROBE_BED_POSITION, Z_RAISE_BEFORE_PROBING);
 
-            // prob 2
+            // probe 2
             float z_at_xLeft_yFront = probe_pt(LEFT_PROBE_BED_POSITION, FRONT_PROBE_BED_POSITION, current_position[Z_AXIS] + Z_RAISE_BETWEEN_PROBINGS);
 
-            // prob 3
+            // probe 3
             float z_at_xRight_yFront = probe_pt(RIGHT_PROBE_BED_POSITION, FRONT_PROBE_BED_POSITION, current_position[Z_AXIS] + Z_RAISE_BETWEEN_PROBINGS);
 
             clean_up_after_endstop_move();