How to Level a Bed With BLTouch: Marlin and Klipper Guide

To level a bed with a BLTouch, tram the bed by hand at print temperature, then probe a mesh: in Marlin send G28, G29 and M500, and put M420 S1 after G28 in your start G-code; in Klipper run BED_MESH_CALIBRATE and load the profile in PRINT_START. Then set the Z-offset: negative M851 Z in Marlin, positive z_offset in Klipper.

Mesh leveling and the Z-offset are separate jobs. The mesh maps the bed’s imperfections; the offset tells the printer how far the nozzle sits from where the probe triggers. Skip the offset and a perfect mesh still crashes the nozzle into glass or prints half a millimeter above the bed.

What the BLTouch Actually Measures

A BLTouch is a mechanical probe. A solenoid pushes a pin down (engineering plastic since V2.0, per ANTCLABS), the pin contacts the bed, a Hall-effect sensor inside the body registers the moment that contact pushes the pin back up, and the probe then retracts the pin. During a bed leveling routine the firmware moves this probe to a grid of points across the bed and records the trigger height at each one. That data becomes a mesh — a 3D map of every dip, bow, and high spot on your bed surface, which Marlin then uses to adjust Z height on the fly as the nozzle moves (Marlin Firmware, Automatic Bed Leveling).

The mesh does not tell you where the nozzle tip is relative to that surface: the probe pin and the nozzle are different points, several millimeters apart. That gap is the Z-offset, set separately from the mesh.

Verify the Probe Before You Trust It

A BLTouch that deploys but never reports a trigger will drive the nozzle straight into the bed on the first homing move. Two minutes of verification is what stands between a working setup and a cracked glass sheet, which is why the Klipper BL-Touch docs put a manual check sequence ahead of any probing.

On Klipper, run the checks in this order:

1. BLTOUCH_DEBUG COMMAND=pin_down, then pin_up. The pin should physically move and the LED should follow.
2. With the pin deployed, run QUERY_PROBE and confirm it reports probe: open. Push the pin up by hand and confirm it flips to probe: TRIGGERED.
3. Run G28 and, as Z descends, touch the pin with a fingernail. Motion must stop instantly.

If step 2 never changes state, suspect the wiring before the probe. Klipper needs a pull-up on the sensor pin, written as a ^ prefix (sensor_pin: ^PC14); a missing ^ or a swapped sensor and control wire accounts for most “dead probe” reports. Marlin users can do the equivalent check with M119 after deploying the pin, watching the z_min endstop state change.

The unit also self-tests at power-up and before each probing cycle. A pin that cycles and then flashes an alarm has failed that test — usually a bent pin, a bad crimp, or a marginal 5 V rail, since per ANTCLABS the sensor draws under 15 mA at standby but up to 300 mA while moving the pin. That alarm is a feature: it fails closed instead of quietly feeding bad numbers into the mesh.

Mechanical Tramming Comes First

Run bed leveling before you’ve trammed the bed by hand and you’re just measuring a bad starting position more precisely. A BLTouch mesh compensates for minor waviness across the print area — it is not a substitute for getting the bed roughly parallel to the X gantry. The split between what tramming fixes and what a probe fixes is set out in bed leveling manual vs auto. Snug the leveling knobs with the paper-drag test at the four corners and center before any automated probe cycle; asking the mesh to correct a badly tilted bed pushes the compensation to its limits and eats into usable Z range.

Tram hot, not cold. Aluminium beds grow measurably as they heat, so bring the bed to your normal print temperature (60 °C for PLA) and let it soak before the paper-drag pass. Five minutes of tramming is the difference between a mesh with a 0.1 mm range and a mesh spending its whole correction budget fighting a 1 mm wedge.

On Klipper the probe can do the corner measuring. List the bed screws in a [screws_tilt_adjust] section and SCREWS_TILT_CALCULATE probes at each one and prints the correction as a clock face, where adjust CW 01:15 means one full turn plus a quarter, clockwise (Klipper manual leveling docs).

A perfect mesh will still give a poor first layer if the extrusion feeding it is wrong, so run e-step calibration before blaming the probe for a squashed or starved bottom layer.

Wiring and Firmware Basics

A BLTouch has five wires carrying four functions. Per ANTCLABS’s V3.1 page and wiring guide, orange is the servo control signal (Marlin’s SERVO0 pin, Klipper’s control_pin), white is the trigger output to Z-min or the probe input (Klipper’s sensor_pin), red is +5 V, and black and brown are the same ground.

Most current mainboards have a dedicated BLTouch header that maps these correctly. On some boards a large capacitor on the Z-min input interferes with the fast trigger signal: ANTCLABS names C7 on Melzi and Ender-3 boards and C45 on Anet boards, and recommends removing it over the fallback of a roughly 1 kΩ pull-up between red and white, which costs precision. Check your board’s BLTouch wiring notes before you assume a bad probe is a bad sensor.

In Marlin, enabling the probe means uncommenting BLTOUCH in Configuration.h, setting NOZZLE_TO_PROBE_OFFSET to your measured X/Y offset (Z gets tuned live, covered below), and picking a leveling method (compared below). If you’re running pre-built firmware from your board vendor, this is usually already compiled in and exposed through the LCD menu instead.

In Klipper the same job is config rather than a recompile. printer.cfg needs a [bltouch] section with sensor_pin (with the ^ pull-up) and control_pin, endstop_pin: probe:z_virtual_endstop in [stepper_z] so the probe becomes the Z endstop, and a [safe_z_home] block so homing happens over the bed rather than off the front-left corner where the probe has nothing to touch.

If QUERY_PROBE behaves but the toolhead does not always stop during G28, or a V3.1 errors after a successful probe, the Klipper docs’ workaround is probe_with_touch_mode: True, at the cost of slower deploys.

BLTouch Manual Essentials: Specs and Mount Height

ANTCLABS keeps every manual from the Classic V1.0 (March 2016) to the Smart V3.1 in its manual archive; download the one matching your unit before printing a bracket. The Smart V3.1 figures that matter during setup:

Output and stroke are ANTCLABS figures (V3.1, V3.0); voltage, weight and cable come from an Anodas listing, and mount height from Bondtech’s installation guide. ANTCLABS also requires the probe mounted perpendicular to the ground.

Marlin G29: Running the Mesh

With the probe wired and firmware flashed, home all axes and run:

G28
G29
M500

G28 homes the printer, G29 runs the probing routine and builds the mesh, and M500 writes it to EEPROM so it survives a power cycle. What G29 does depends on the leveling system compiled in:

Marlin’s ABL docs advise AUTO_BED_LEVELING_BILINEAR unless you know the bed is very flat; the UBL row is its documented setup sequence. The bilinear grid is GRID_MAX_POINTS_X by GRID_MAX_POINTS_Y, both 3 in stock Marlin 2.1.x Configuration.h, so a default build probes nine points. Useful bilinear parameters: L, R, F and B bound the grid (G29 L50 R150 F50 B150 V4 probes only X50–150, Y50–150, verbosely), D probes without replacing the stored mesh, and J discards the mesh and turns compensation off.

Marlin also supports a fade height, which tapers the correction down to zero above a set Z so the mesh only affects the first several layers rather than warping tall prints. The stock config sets 10 mm; M420 Z10 sets it live and M420 Z0 applies full correction to every layer.

MIN_PROBE_EDGE Is Now PROBING_MARGIN

Marlin renamed MIN_PROBE_EDGE to PROBING_MARGIN. A current build given an old Configuration.h stops with MIN_PROBE_EDGE is now called PROBING_MARGIN. and also rejects LEFT_PROBE_BED_POSITION and its siblings in favor of per-side overrides such as PROBING_MARGIN_LEFT (Marlin issue #27747, on 2.1.2.5). The stock margin keeps probe points 10 mm in from each bed edge.

The margin is only half the limit: the probe can only reach where the nozzle can travel, shifted by NOZZLE_TO_PROBE_OFFSET (a probe right of or behind the nozzle is positive). A BLTouch 40 mm left of the nozzle, on a printer whose X travel ends at 300, can never probe past X 260. Klipper sidesteps the margin: mesh_min and mesh_max are set directly, in probe coordinates (Klipper Bed Mesh).

Klipper Bed Leveling: BED_MESH_CALIBRATE

Klipper’s [bed_mesh] section defines the probing area and density. Per the Klipper Bed Mesh docs the minimum is 3 points per axis, and the documented example uses probe_count: 5, 3 on a 250 x 220 mm bed for 15 points. On a typical 220 x 220 mm bed, probe_count: 5, 5 (25 points) is a sensible density; going denser mostly buys probing time unless the surface is genuinely warped.

Build and store it with:

BED_MESH_CALIBRATE
BED_MESH_PROFILE SAVE=default
SAVE_CONFIG

For a per-print mesh, BED_MESH_CALIBRATE ADAPTIVE=1 probes only the area of the bed used by the objects being printed, which is faster on small jobs.

The Trap: A Saved Mesh That Never Loads

This is the failure that produces a textbook calibration and a terrible first layer, and it exists in both firmwares in slightly different shapes.

On Klipper, current versions do not load the default mesh profile at startup. The docs say to call BED_MESH_PROFILE LOAD=default yourself, normally in your PRINT_START macro right after G28. Skip it and every print runs with zero compensation while the saved mesh sits on disk unused, which is why a fresh BLTouch install so often appears to change nothing.

On Marlin, G29 builds the mesh and M500 stores it, but bed leveling still has to be switched back on after each home. Add M420 S1 to your start G-code after G28 — or set ENABLE_LEVELING_AFTER_G28 in firmware — or the stored mesh is loaded and then ignored.

Setting the Z-Offset

This is the step that actually determines first-layer squish, and it’s where most BLTouch setups go wrong. The offset is the vertical distance between where the probe triggers and where the nozzle tip touches the bed — set with M851:

M851 Z-2.50
M500

Negative because the probe pin, mounted below and behind the nozzle, triggers before the nozzle would reach the bed. The exact value depends entirely on your mount geometry, so there’s no universal number to copy — you tune it live.

The practical method: home so the probe sets Z=0, then move the nozzle down in 0.05–0.1 mm steps with a sheet of standard printer paper underneath. Stop when the paper drags with light, consistent resistance, the same feel used for manual corner leveling. If BABYSTEP_ZPROBE_OFFSET is enabled, you can do this live during the first layer of an actual print and save the result directly (Teaching Tech calibration guide). Whatever value you land on, run M500 to commit it to EEPROM — an offset that isn’t saved disappears on the next reboot.

The Klipper Equivalent, and Its Opposite Sign

Klipper defines z_offset as the distance above the nozzle tip at which the probe triggers, so it is a positive number where Marlin’s M851 Z is negative. Copying a Marlin value across firmwares, sign included, is a reliable way to bury the nozzle. The Klipper docs suggest sanity-checking that the result lands near 1 mm: far enough that the probe fires before the nozzle arrives, retracted enough to clear printed parts.

With the bed at print temperature:

1. G28, then PROBE_CALIBRATE. Klipper probes once and parks the nozzle over that same point.
2. Slide plain printer paper (roughly 0.1 mm) under the nozzle and step down with TESTZ Z=-0.1, dropping to TESTZ Z=-0.05 as the drag comes up.
3. When the paper drags with light, even resistance, run ACCEPT, then SAVE_CONFIG. Klipper writes the value into printer.cfg and restarts.

To tune during a real first layer instead, babystep the Z offset, then run Z_OFFSET_APPLY_PROBE and SAVE_CONFIG; Klipper subtracts the babystep from the probe’s z_offset (Klipper G-codes).

Verifying It Worked

On an Ender-3-class printer with a stock 0.4 mm nozzle, print a first-layer test pattern (five 25 mm squares, one per corner plus centre) at 0.2 mm layer height (see layer height for a 0.4 mm nozzle for the usable range), your normal material settings (200 °C nozzle and 60 °C bed for PLA), and 20–30 mm/s on the first layer. Success looks like: a slightly flattened, evenly squished line with no visible gaps between adjacent lines and no scraping or dragging by the nozzle. If lines are too flat and translucent, the nozzle is too close. If lines are round and don’t adhere or separate under light finger pressure, the nozzle is too far. Adjust in 0.02–0.05 mm increments and reprint the test rather than committing a full print to the guess.

The five-square layout separates the two variables. All five squares matching each other is the mesh working; the overall squish level across all of them is the Z-offset. One bad corner points at the mesh or at tramming, uniform bad squish points at the offset. A corner that lifts later in the print is warping, not the mesh.

If squares vary run to run rather than corner to corner, the problem is repeatability, not calibration. ANTCLABS rates the BLTouch at a standard deviation around 0.005 mm while conceding that real installs on flexible machines land anywhere from 0.001 to 0.05 mm — a loose bracket or a wobbly gantry swamps the sensor’s own precision. Marlin can measure this directly with the M48 probe repeatability test: ten probes with a standard deviation above roughly 0.01 mm points at the mount, the wiring, or a counterfeit unit (genuine boards carry a QR code on the PCB per ANTCLABS). Klipper’s PROBE_ACCURACY also takes 10 samples by default, and its probe calibration guide calls a range above 0.025 mm not accurate enough for leveling.

When the Offset Drifts

BLTouch offsets aren’t permanent. Bed thermal expansion, a slightly loose probe bracket, or a nozzle swap all shift the real distance the offset represents, and the printer keeps using the old number with total confidence. The failure shows up as a gradually worse first layer over weeks rather than a sudden crash. Recalibrate the Z-offset any time you change nozzles (including swapping the brass nozzle on an Ender 3 V2), swap the print surface, or re-seat the BLTouch bracket. If the surface itself changed, the bed surface reference covers how much each material shifts the probe’s reading.

The bracket geometry is the offset. Touch the bracket and the stored number is stale, whichever firmware holds it.

With the mesh and Z-offset settled, the next stage is extruder e-steps calibration, and the sequence after that (drying, temperature, flow ratio, pressure advance, retraction) is laid out in the 3D printer calibration order. Doing probe work after those means redoing them, because every later test print is measured on the first layer the Z-offset sets. For what ABL is and is not solving, see bed levelling explained: manual vs auto.

FAQ

Do I need to run G29 before every print?

No. Marlin’s G29 notes say to save the mesh with M500, then replace G29 in your slicer’s start G-code with M420 S1, which re-enables the stored mesh and saves time and machine wear. Re-probe after re-tramming, changing the bed surface or moving the probe bracket. In Klipper, load the saved profile or run an adaptive mesh.

How high should a BLTouch be mounted above the nozzle?

For a BLTouch Smart V3.1, Bondtech’s installation guide puts the probe tip 2.3 to 4.3 mm above the nozzle tip with the pin stowed. ANTCLABS also requires the probe to be mounted perpendicular to the ground. Use a rigid bracket: flex does not throw an error, it shows up later as poor repeatability in M48 or PROBE_ACCURACY.

Why is my BLTouch blinking?

A blinking BLTouch has failed its self-test or raised an alarm, usually because of a bent pin, a bad crimp or a weak 5 V supply. Fix the cause first, then clear the alarm with M280 P0 S160 in Marlin or BLTOUCH_DEBUG COMMAND=reset in Klipper, and repeat the pin down, pin up and trigger checks before probing again.

Does a BLTouch clone work with Klipper?

Usually. Klipper’s BL-Touch documentation says many clones work with the default [bltouch] configuration, but some do not support QUERY_PROBE and some need pin_up_reports_not_triggered or pin_up_touch_mode_reports_triggered set. Run the pin and QUERY_PROBE checks first, and leave BLTOUCH_STORE alone, since it writes an output mode to a BLTouch V3.1’s EEPROM.

Related across the network

• Creality CR Touch Not Probing: Diagnosis and Fixes — crealityreviews.com