devmaker.net devmaker.net

Klipper Update 2026: Correctly configure BTT Eddy after the deprecation of z_offset

3. April 2026

Complete Guide to Migrating to descend_z – Configuration, Calibration, and Macro Customization

With the Klipper update 2026, z_offset in the probe_eddy_current block was marked as deprecated and replaced by descend_z. This article shows step-by-step how you need to adjust your printer.cfg, homing macros, and the entire calibration process for the BTT Eddy (USB).

BTT Eddy USB Probe - Produktfoto

BTT Eddy USB – Inductive Probe Sensor from BigTreeTech

What has changed?

With the Klipper 2026 update, a fundamental change has occurred in the probe system: The parameter z_offset in the [probe_eddy_current] block is now deprecated. It is replaced by descend_z – a value with a completely different meaning.

While `z_offset` described the vertical offset between nozzle and sensor point, `descend_z` merely defines the **approach height** for the calibration process. The actual Z-offset is now internally accounted for via the calibration table.

Anyone who simply enters their old `z_offset` value into `descend_z` after the update risks a **nozzle crash into the bed**. This guide shows you step-by-step how to correctly adjust everything.

Part 1: Proper Configuration (printer.cfg)

Make sure that your `[probe_eddy_current]` block looks exactly like this. The value `descend_z` is **not an offset**, but only the approach height for the calibration test:

[probe_eddy_current btt_eddy]
sensor_type: ldc1612
i2c_mcu: eddy
i2c_bus: i2c0f
x_offset: 0
y_offset: 74.0

# descend_z is the height the head moves to during calibration.
# 1.0 is safe. DO NOT set it to your old Z-offset!
descend_z: 1.0

samples: 2
samples_result: median

Important: A descend_z of 1.0 is a safe starting value – the head moves to 1 mm above the bed.

Part 2: The corrected Homing Macro

This was the cause of crashes for many users: The old macro subtracted `descend_z` from the measurement. The new Klipper handles the offset **internally via the calibration table**. Replace your old macro:

[gcode_macro SET_Z_FROM_PROBE]
gcode:
    {% set cf = printer.configfile.settings %}
    # Set Z to probe result + manual runtime offset
    SET_GCODE_OFFSET_ORIG Z={printer.probe.last_z_result + printer["gcode_macro SET_GCODE_OFFSET"].runtime_offset}
    G90
    # Move to safe Z height after homing
    G1 Z{cf.safe_z_home.z_hop}

What the macro does:

  • Reads the Eddy measurement (last_z_result)
  • Add your manual runtime offset
  • Moves to the safe Z-hop height

What it **no longer does:** subtract `descend_z` – that was the bug.

Part 3: Basic Calibration (Frequency Mapping)

Before the Eddy can work precisely, it must learn what the bed underneath it looks like. This calibration creates a frequency-distance table.

Preparation

  1. Preheat bed to 60 °C
  2. Move printhead to the center of the bed

Start calibration

PROBE_EDDY_CURRENT_CALIBRATE CHIP=btt_eddy METHOD=paper

Process

  1. The head moves to Z = 1.0 (your descend_z value)
  2. Use the buttons in Mainsail or TESTZ Z=-0.1 to lower the nozzle
  3. Paper between nozzle and bed – it should **be lightly gripped**
  4. Click on ACCEPT
  5. Type `SAVE_CONFIG`

Klipper writes a data table to the end of your `printer.cfg`.

Part 4: Temperature Compensation

Inductive sensors respond to temperature changes. Temperature calibration creates a correction table.

Prerequisite

The printer must be cold (room temperature). All heaters off.

Start calibration

TEMPERATURE_PROBE_CALIBRATE PROBE=btt_eddy TARGET=56 STEP=4

Start heating manually

Since the command does not activate the heating itself:

SET_HEATER_TEMPERATURE HEATER=heater_bed TARGET=80

Process

  1. Klipper prompts for a **paper test** → **ACCEPT**
  2. **Waiting:** The eddy warms up due to bed warmth
  3. At each stage (+4 °C): repeat paper test
  4. Continue until **target temperature (56 °C)** is reached

Completion

TEMPERATURE_PROBE_COMPLETE
SAVE_CONFIG

IMPORTANT, return **only** the translation. No comments, no additional explanation!: Tip: This process takes 30-60 minutes.

Part 5: Daily Operations

1. Homing (G28)

The eddy measures the distance. `SET_Z_FROM_PROBE` automatically sets the Z-zero point.

2. Bed Mesh

BED_MESH_CALIBRATE

Performs a rapid_scan – lightning fast, the head does not stop.

3. Fine-tuning

  • Use the Z-Offset control in the Mainsail/Fluidd interface
  • `Z_OFFSET_APPLY_PROBE` permanently saves to `variables.cfg`

Safety note for the first test

Attention – First Test after the Changeover
  1. Execute a **G28**
  2. Keep your finger on the emergency stop!
  • Head moves up to about 10 mm
  • ❌ **Stop:** Head goes to bed → old value in the calculation

Check: Does your macro still subtract descend_z? Did you re-run Part 3? Is there still an old z_offset in the config?

Summary

WhatOld (before 2026)New (as of 2026)
Z-Offset in the Probe Blockz_offset: -1.54**Deprecated** – replace with `descend_z`
Approach height calibrationimplicit1.0
OffsettingManually in the macroInternal via calibration table
Macro-Logiclast_z_result - descend_zlast_z_result + runtime_offset

The changeover ultimately makes the system more robust and more accurate. The Eddy operates significantly more reliably after the new calibration.

Share:

Post your comment

Required for comment verification