Marlin Bed Leveling: Deterministic Calibration & First-Layer Mesh Engineering

Master Marlin 2.x bed leveling architectures (Unified Bed Leveling UBL, Bilinear ABL, Manual Mesh MBL) to guarantee flawless first-layer adhesion through rigorous G-code phase workflows, probe offset math, and persistent EEPROM compensation.

When to Use This Skill

Activate this skill when:

• Calibrating, tuning, or troubleshooting automatic bed leveling on Marlin 2.x 3D printers (Ender 3, CR-10, Prusa clones, custom CoreXY / Cartesian machines).
• The user asks: "How do I set up UBL in Marlin?", "My printer homes with G28 and ignores the mesh", "Calculate BLTouch Z-probe offset", "Generate G26 validation print G-code", or "Edit warped mesh points with M421".
• Diagnosing first-layer defects: nozzle dragging across PEI sheets, corner detachment, uneven squish, or compensation disabling after homing.
• Sizing slicer start G-code sequences (Cura, PrusaSlicer, OrcaSlicer, Bambu Studio) with thermal soaking and mesh restoration.

Do NOT use this skill when:

• Calibrating Klipper or RepRapFirmware printers (different firmware syntax and mesh compensation systems).
• Fixing gross mechanical skew: loose V-slot rollers, bent Z leadscrews, or wobbly gantry arms (hardware faults cannot be solved by software leveling).
• Delta printer kinematics setup requiring radius and tower endstop adjustments before mesh probing.

Core Mental Models & Non-Negotiable Rules

1. The Post-Homing Enable Mandate (G28 Disables Leveling):

   • In Marlin firmware, executing G28 (Home All Axes) automatically DISABLES bed leveling compensation by default (RESTORE_LEVELING_AFTER_G28 is often disabled in vendor firmware).
   • In every print start G-code, the leveling restoration command MUST be issued strictly AFTER G28:

     G28      ; Home all axes (silently turns leveling OFF)
     M420 S1  ; Re-enable bed leveling compensation from EEPROM mesh
     

   • Failing to include M420 S1 (or G29 A for UBL) after G28 causes the printer to execute the entire print with zero leveling compensation.

2. The 5-Phase UBL Calibration Loop: Unified Bed Leveling (UBL) is a state machine requiring five sequential phases:

   • Phase 1 (Probe Reachable Grid): G29 P1 probes all coordinates physically reachable by the probe offset.
   • Phase 2 (Manual Edge Probing): G29 P2 uses a paper feeler gauge for points the BLTouch cannot reach due to gantry geometry.
   • Phase 3 (Mathematical Extrapolation): G29 P3 T0.0 fills unprobed edge coordinates by extrapolating slopes from adjacent measured points.
   • Phase 4 (Validation & Micro-Tuning): G26 B60 H210 F1.75 prints a single-layer validation test pattern; inspect and edit coordinates with M421 I... J... Q....
   • Phase 5 (Storage & Activation): G29 S1 saves to EEPROM mesh slot 1; G29 A activates UBL; M500 commits to permanent EEPROM storage.

3. Thermal Equilibrium Pre-Flight Invariant:

   • Aluminum build plates, magnetic stickers, and spring-steel PEI sheets expand and warp non-linearly under thermal expansion.
   • Probing a bed at room temperature (20°C) and then printing at 60°C or 100°C bakes a $0.08\text{--}0.20\text{mm}$ error into every mesh point.
   • Mandatory Pre-Flight: Beds MUST be heated to target operating temperature and soaked for $\ge 5\text{ minutes}$ prior to running G29 probing.

4. Z-Probe Offset Sign Convention (M851 Z...):

   • For downward-deploying probes (BLTouch, CRTouch, inductive sensors) where the probe trigger point triggers below the nozzle tip: $$\mathbf{Z\text{-}Offset\ is\ strictly\ NEGATIVE}\ (e.g.,\ \text{M851 Z-1.85})$$
   • A positive Z-offset on a downward-deploying probe instructs the firmware that the nozzle is lower than the probe trigger, driving the nozzle directly into the bed on the first move.
   • Adjusting Z-offset with paper gauge:
     • More resistance / tighter squish $\implies$ more negative (e.g., -1.80 $\to$ -1.85).
     • Less resistance / looser gap $\implies$ less negative (e.g., -1.80 $\to$ -1.75).

5. Mesh Fade Height Geometry (M420 Z...):

   • Leveling compensation must gradually fade out as Z-height increases so top surface layers print geometrically flat rather than conforming to the bed warp.

…