Skip to content

Home

Jump to bottom
Titus Meyer edited this page Jun 4, 2026 · 5 revisions

Automatic Z-Calibration for Klipper

This wiki documents the z_calibration plugin for Klipper and Kalico. The plugin measures the relationship between a nozzle-contact Z endstop, a detachable magnetic switch probe, and the print surface, then applies the result. By default it uses Klipper's SET_GCODE_OFFSET; custom setups can use offset_gcode to apply the result differently.

The goal is to make the first layer less sensitive to nozzle changes, flex plate changes, printhead changes, temperature changes, and small shifts in the Z endstop position. You should still start from a reasonable manual Z offset before relying on automatic calibration.

Start Here

Use this path if you are setting up the plugin for the first time:

Step Page Goal
1 Requirements Confirm the printer has the required endstop and probe setup.
2 How It Works Understand what the plugin measures.
3 Installation Install the plugin and update manager entry.
4 Configuration Add and tune [z_calibration].
5 Configuration Examples Adapt a short template to your printer.
6 Testing and Tuning Verify the calculated offset safely.
7 Usage Add CALIBRATE_Z to the print start flow.

If calibration behaves unexpectedly, check Known Limitations and Troubleshooting before changing multiple settings at once.

Quick Setup Checklist

  • Hardware uses a physical nozzle-contact Z endstop.
  • Magnetic probe attaches, docks, and triggers reliably.
  • Normal homing works.
  • QGL, Z tilt, or the equivalent leveling routine works if the printer uses one.
  • Plugin is installed and Klipper or Kalico has been restarted.
  • [z_calibration] has a valid switch position, bed position, and positive switch_offset.
  • CALIBRATE_Z has been verified with slow manual moves before printing.
  • Print start macro does not home Z after CALIBRATE_Z.

Main Concepts

The plugin needs two independent references:

  • The nozzle touches a physical Z endstop. This records the nozzle height.
  • The magnetic probe touches the print surface. This records the bed height.

The plugin also probes the body of the magnetic probe switch on the Z endstop. With the configured switch_offset, it can calculate the current nozzle-to-bed correction and apply it through the default G-code offset path or a custom offset_gcode hook.

The most important tuning rule is:

A smaller switch_offset moves the nozzle farther away from the bed. A larger switch_offset moves the nozzle closer to the bed.

Safety

Use this plugin at your own risk. Incorrect printer configuration can damage hardware.

Before using automatic calibration in a print:

  • Make sure normal homing works.
  • Make sure the probe attaches, docks, and triggers reliably.
  • Verify the result slowly with manual moves.
  • Remove other offset commands that would conflict with calibration.
  • Do not leave the printer unattended while printing.

For constraints that affect setup and print start macros, read Known Limitations.

Wiki Map

Start

Concepts

Project

Clone this wiki locally