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.

1. 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.

1. 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.

1. 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).

1. 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.
• Set fade height to M420 Z10.0 (fades compensation smoothly over the first 10mm of print height). Setting Z0 disables fade (perpetuating bed ripples to the top of the model); setting Z > 25 is unnecessary ballast.

Named Sins & Anti-Patterns (Что категорически ЗАПРЕЩЕНО)

| Anti-Pattern | Manifestation in Code/Workflow | Mandatory Production Counter-Rule |
| :--- | :--- | :--- |
| The Forgotten M420 S1 | G28 followed immediately by print moves. | Always place M420 S1 (or G29 A) immediately after G28. |
| Cold Bed Mesh Probing | Running G29 P1 with bed heater at 20°C. | Heat bed to printing temperature and soak for $\ge 5$ minutes first. |
| Positive Z-Probe Offset | Setting M851 Z+1.5 on a BLTouch probe. | Downward-deploying probes MUST have a negative Z-offset (M851 Z-...). |
| Unsaved Mesh Discard | Probing a 7x7 mesh without running M500. | Always commit mesh to EEPROM via G29 S1 followed by M500. |
| Software-Fixing Physical Tilt | Compensating for a 2.5mm physical gantry tilt with UBL. | Physically tram bed corners (G35 or thumb screws) before probing. |
| Blind Unchecked Extrapolation | Running G29 P3 without verifying boundary values. | Inspect extrapolated border points with M420 V or G29 T. |
| Cold Extruder G26 Validation | Running G26 test without nozzle heating. | Heat nozzle to printing temperature (G26 B60 H210 F1.75). |
| Loose Probe Mount Blindness | Probing while BLTouch bracket has physical wobble. | Check physical probe mount rigidity; probe repeatability requires $s \le 0.005\text{mm}$ (M48). |
| Excessive Fade Height | Setting M420 Z0 or M420 Z50. | Use M420 Z10.0 to smoothly transition from warped bed to true flat geometry. |
| Blind Point Over-Editing | Manually offsetting a single mesh point by 0.5mm via M421. | Clean the build plate or check for debris under PEI sheet before altering matrix. |

Concrete Archetypes / Presets

Archetype 1: End-to-End Unified Bed Leveling (UBL) Calibration Macro

; ==============================================================================
; MARLIN 2.x UBL FULL CALIBRATION SEQUENCE
; ==============================================================================
M140 S60         ; Start heating bed to 60°C
M190 S60         ; Wait for bed to reach 60°C
G4 S300          ; Thermal soak for 300 seconds (5 minutes)

G28              ; Home all axes
M117 Probing Reachable Points...
G29 P1           ; Phase 1: Automated probe of reachable grid points

M117 Extrapolating Mesh Edges...
G29 P3 T0.0      ; Phase 3: Mathematically extrapolate unprobed perimeter points
G29 P3 T0.0      ; Second pass to ensure corner fill

G29 T            ; Print ASCII topology matrix to terminal for verification
G29 S1           ; Save calibrated mesh to EEPROM slot 1
G29 A            ; Activate UBL leveling system
M500             ; Save EEPROM permanently to board flash
M117 UBL Mesh 1 Saved and Activated!

Archetype 2: Production Slicer Start G-Code (Cura / PrusaSlicer / Orca)

; ==============================================================================
; PRODUCTION SLICER START G-CODE (MARLIN UBL / BILINEAR)
; ==============================================================================
M140 S[first_layer_bed_temperature]    ; Start heating bed
M104 S150                              ; Pre-heat nozzle to 150°C (prevent oozing)
M190 S[first_layer_bed_temperature]    ; Wait for bed to stabilize

G28                                    ; Home all axes (turns leveling OFF)
M420 S1 Z10.0                          ; Restore mesh from EEPROM & set 10mm fade
; (OR for UBL: G29 A followed by G29 L1)

G1 Z50 F3000                           ; Move nozzle up to safe clearance
M109 S[first_layer_temperature]        ; Heat nozzle to final printing temp

; Priming Purge Line on bed edge
G92 E0                                 ; Reset extruder
G1 X0.1 Y20 Z0.28 F5000.0              ; Move to start position
G1 X0.1 Y200.0 Z0.28 F1500.0 E15       ; Draw first purge line
G1 X0.4 Y200.0 Z0.28 F5000.0           ; Move to side
G1 X0.4 Y20 Z0.28 F1500.0 E30          ; Draw second purge line
G92 E0                                 ; Reset extruder
G1 Z2.0 F3000                          ; Z-hop before moving to print

Archetype 3: Probe Repeatability & Offset Verification (M48 & M851)

; ==============================================================================
; PROBE REPEATABILITY & Z-OFFSET CALIBRATION
; ==============================================================================
G28                     ; Home axes
G1 X117.5 Y117.5 Z10 F5000 ; Move to center of 235x235 bed
M48 P10 X117.5 Y117.5 V2 E L2 ; Run 10-point repeatability test
; Standard deviation must be <= 0.005 mm. If > 0.010 mm, tighten probe mount!

; Manual Z-Offset adjustment with paper feeler gauge:
; 1. Move to Z=0: G1 Z0 F1000
; 2. Baby-step Z until paper drags with slight friction
; 3. If nozzle moved down 0.15mm: M851 Z-1.85 (subtract 0.15 from current -1.70)
; 4. Commit: M500

The Pre-Emit Quality Gate Checklist

Before emitting any Marlin leveling advice, macro, or slicer start code:

• [ ] Post-Homing Verification: M420 S1 (or G29 A) placed strictly after G28 in the execution flow.
• [ ] Thermal Soak Pre-Flight: Bed heating and 5-minute soak mandated prior to G29 probing.
• [ ] Negative Offset Math: Downward-deploying probes have verified negative M851 Z-... values.
• [ ] EEPROM Commit: G29 S1 followed immediately by M500 to preserve the mesh.
• [ ] Fade Height Limit: M420 Z10.0 configured for smooth transition to flat geometry.
• [ ] Physical Tramming Precedence: Confirmed that manual corner leveling is performed before software compensation.
• [ ] Probe Repeatability: Confirmed that M48 probe standard deviation is $\le 0.005\text{mm}$.

Self-Correction & Verification Loop

Bad (Vibe-Coded AI Slop Output):

"Put G29 before G28 in your start G-code. If your BLTouch is scraping, set M851 Z1.5. You don't need to heat the bed during leveling because Marlin compensates for it automatically."

Problems: Fatal G28 homing wipes out the preceding G29 mesh, positive Z-offset crashes nozzle into bed, dangerous cold probing advice.

Good (Production Marlin Bed Leveling Output):

1. Tram the four bed corners manually using G35 or thumb screws to get mechanical variance under $\pm 0.1\text{mm}$.

2. Heat bed to 60°C and nozzle to 150°C; let soak for 5 minutes so thermal expansion stabilizes.

3. Verify probe repeatability using M48 P10 (standard deviation must be $\le 0.005\text{mm}$).

4. Probe grid with G29 P1, extrapolate unprobed corners with G29 P3 T0.0, save to slot 1 with G29 S1, and commit to flash with M500.

5. In your slicer start G-code, place M420 S1 Z10.0 immediately after G28 to restore the active mesh with a 10mm fade height.