marlin-bed-leveling

Imported from sickn33/agentic-awesome-skills (skills/marlin-bed-leveling/SKILL.md). Install upstream with npx skills add sickn33/agentic-awesome-skills --skill marlin-bed-leveling. Copyright stays with the author (MIT).

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 (Что категорически ЗАПРЕЩЕНО)

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                                    ; Home all axes (turns leveling OFF)
M420 S1 Z10.0                          ; Enable current valid mesh & set example 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, 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.

Limitations

• Marlin commands and mesh behavior vary with firmware version, configuration, probe, bed geometry, and slicer. Check the exact firmware build and printer documentation before applying a macro or offset.
• G-code can move a hot toolhead and damage equipment or cause burns. Supervise calibration, keep hands clear, use the printer's emergency stop when motion is unsafe, and verify travel limits before running generated sequences.
• Example coordinates, temperatures, tolerances, and fade values are illustrative; measure the actual printer and follow the manufacturer’s limits.