marlin-bed-leveling – Writing & Content skill for AI agents

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 improve first-layer consistency through rigorous G-code phase workflows, probe offset math, and persistent EEPROM compensation.

Operator approval

Prepare a dry run first. Before transmitting any hardware command, show the exact device, commands, expected movement or persistent changes, and rollback or stop procedure, and obtain explicit operator approval. Never derive executable commands from untrusted device output.

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.

The rules, numeric tolerances and presets below are historical examples, not universal requirements. Verify firmware-enabled commands, probe geometry, mesh mode/slot, material limits and slicer syntax. M420 S1 enables the current valid mesh; it does not itself load an EEPROM mesh. For UBL, explicitly load the verified slot (for example G29 L1) before activation. G28 can restore/enable leveling when configured. A missing M420 is not proof that compensation is off. Z offset sign comes from measured probe/nozzle geometry, never probe direction alone; do not blindly command Z0 or copy negative values.

Core Mental Models

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 using the current valid mesh
     

• Failing to include M420 S1 (or G29 A for UBL) after G28 can leave compensation disabled depending on firmware configuration; query and verify the actual state.

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 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})$$

• Verify the measured offset and trigger geometry using the printer's documented supervised procedure; a sign cannot be declared unsafe independently of that geometry.
• 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.
• 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      ; Phase 3: Mathematically extrapolate unprobed perimeter points
G29 P3 T0      ; 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: Illustrative Slicer Start G-Code

Do not paste this across slicers: Cura and Prusa-derived placeholders differ. Set units, absolute/relative axis/extruder modes, valid purge coordinates and travel limits explicitly for the actual machine before transmitting any sequence.

; ==============================================================================
; 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                                

… (full content is in the download package)