ZOOC - Z-offset open calibration

ZOOC is a Klipper extra module that automatically calibrates Z-offset by compensating for thermal expansion of the print bed and extruder. This ensures a perfect first layer. The calibration is performed in an open loop, requiring no hardware modifications.

Additionally, the Z-offset can be fine-tuned directly from the slicer based on filament type, build surface, and other print-specific settings.

For context, a typical print bed expanding from room temperature to 100℃ can change the Z-height by as much as 0.07mm, which is 35% of a standard 0.2mm layer.

Table of Contents

• How it works
• Requirements
• Installation
• Uninstall
• Configuration
  • Run the automatic calibration
  • Predefined calibration
  • printer.cfg (PRINT_START)
• Usage
  • Profiles
  • G-Codes
• Contributing
  • Support my work
• Other plugins
• Troubleshooting
• Disclaimer

How it works

ZOOC operates in two main phases: a one-time calibration (or manual adjustment) and automatic adjustments during printing.

1. Calibration
First, you run a calibration process where ZOOC automatically probes the Z-distance across a range of bed and extruder temperatures using the standard PROBE command. This process measures how thermal expansion affects your specific printer and saves the data. Alternatively, you can adjust the calibration data manually.

2. Automatic Z-Offset Adjustment
At the beginning of each print, ZOOC uses the saved calibration data to calculate the precise Z-offset needed for your target bed and extruder temperatures. It interpolates between the measured data points to ensure a smooth and accurate offset for any temperature combination. The adjustment is applied using the SET_GCODE_OFFSET command.

Profiles
ZOOC supports custom profiles, which allows adjusting the z-offset by e.g. build surface or filament type. See Profiles.

Important Considerations

• ZOOC only manages the relative Z-offset caused by temperature changes. You still need to perform a conventional Z-endstop calibration to set your printer's baseline.
• You can still make manual Z-offset adjustments using SET_GCODE_OFFSET. ZOOC tracks its own adjustments separately, so your manual changes will be applied on top of the automatic compensation.
• Frame expansion has a similar effect on Z-offset. ZOOC focuses on the first layer and does not (yet) compensate for this. See Other plugins for frame expansion.

Extruder's heat expansion
While ZOOC can compensate for both bed and extruder heat expansion, automatic calibration is most reliable for the bed. This is because the probe measures the toolhead's position, not the nozzle's direct distance to the bed.

It is recommended to run the calibration with only the bed temperature varying, as the extruder's thermal expansion has a minimal impact on the total Z-offset.

If you want to account for extruder expansion, you can manually determine the offset at different extruder temperatures and adjust the calibration data accordingly.

Requirements

ZOOC is primarily tested on a Voron 2.4 (250mm) running the latest versions of Klipper and OctoPrint. However, it should work on any printer that meets the requirements below.

• A 3D printer that uses both a Z-endstop and a Z-probe for Z-axis calibration (e.g., Voron 2.4).
• Klipper v0.13.0 or later
• Python 3.12 or later

Installation

Upgrade Klipper if needed (Check G-code M115)
Klipper installation / KIAUH - Klipper update helper.

1. Install ZOOC
   Choose the latest release .

   cd ~
   git clone --branch v1.0.0 --depth 1 https://github.com/sah0la/klipper-zooc
   ~/klippy-env/bin/pip install ./klipper-zooc
   

2. Enable the module

   You can enable ZOOC using one of the following methods:

   • Post-install script (recommended):

     Run the following command to automatically create the necessary configuration files:

     ~/klippy-env/bin/zooc-setup
     

   • Manual installation (alternative):

     • Copy zooc/src/extras/zooc.py to ~/klipper/klippy/extras/.
     • Copy src/zooc/config/zooc.cfg to ~/klipper_config/zooc.cfg.
     • Include the configuration in your printer.cfg by adding the following line:
       [include klipper_config/zooc.cfg]

3. Restart Klipper

Uninstall

To uninstall ZOOC, run the following commands:

~/klippy-env/bin/zooc-teardown
~/klippy-env/bin/pip uninstall klipper-zooc

Then, remove the zooc.cfg file and the corresponding [include] line from your printer.cfg.

Configuration

ZOOC settings are stored in ~/klipper_config/zooc.cfg, which includes default values that should work well for most users. Default configuration is shown in zooc.cfg.

To set up calibration data, choose one the two options:

a) Run the automatic calibration

1. (Optional) Configure the ZOOC_RUN options in zooc.cfg and restart Klipper.
2. Run ZOOC_RUN to perform the calibration. This may take several minutes.
3. Run SAVE_CONFIG to make the calibration permanent.

b) Predefined calibration

1. Comment offset_data= in zooc.cfg and adjust values as needed for your printer. Restart Klipper.

Finally, run ZOOC_ADJUST to test the Z-offsets at various temperatures, for example:
ZOOC_ADJUST BED_TEMP=60 EXTRUDER_TEMP=200 DRY_RUN=TRUE.

printer.cfg (PRINT_START)

To apply the calibration automatically at the beginning of each print, you'll need to call ZOOC_ADJUST in your PRINT_START macro.

1. Configure your slicer to call the PRINT_START macro and pass the bed and extruder temperatures. See PRINT_START.

2. Add ZOOC_ADJUST to your PRINT_START macro.
   Here are a few examples:

   [gcode_macro PRINT_START]
   gcode:
     {% set EXTRUDER = params.EXTRUDER|default(200)|float %}
     {% set BED = params.BED_TEMP|default(60)|float %}
   
     # Example a) Adjust Z-offset using the provided temperatures
     ZOOC_ADJUST BED_TEMP={BED} EXTRUDER_TEMP={EXTRUDER}
   
     # Example b) Adjust Z-offset using the current temperatures
     # ZOOC_ADJUST
   
     # Example c) Adjust Z-offset with profiles and temperatures
     # {% set Z_PROFILE = params.Z_PROFILE|default('default') %}
     # {% set MATERIAL = params.MATERIAL|default('') %}
     # ZOOC_ADJUST FIXED_OFFSETS={Z_PROFILE},{MATERIAL} BED_TEMP={BED} EXTRUDER_TEMP={EXTRUDER}
   

3. Start printing!

Usage

Profiles

Profiles allow you to apply additional, fixed Z-offset adjustments for specific printing scenarios. For example, you can create profiles to account for different build surfaces (e.g., PEI, glass) or to fine-tune the first layer adhesion for certain filaments (e.g., ASA, TPU).

You can define profiles in the fixed_offsets= section of your zooc.cfg file. To apply one or more profiles during a print, pass them as a comma-separated list to the FIXED_OFFSETS parameter of the ZOOC_ADJUST command.

G-Codes

ZOOC provides several G-code commands to manage Z-offset calibration. For a quick overview of the available commands and their parameters, you can use the HELP command in your Klipper console.

ZOOC_RUN
This command runs the automatic calibration process, probing the Z-offset at various bed (and extruder) temperatures. The resulting data is saved to the [zooc] section of your Klipper configuration. Note that this process can take several minutes to complete.

ZOOC_SHOW
This command displays the current calibration data loaded by ZOOC.

ZOOC_ADJUST [BED_TEMP] [EXTRUDER_TEMP] [FIXED_OFFSETS] [DRY_RUN]
This command calculates and applies the Z-offset for the specified bed and extruder temperatures.

Parameter	Description
BED_TEMP	The target bed temperature. If not provided, the current bed temperature is used.
EXTRUDER_TEMP	The target extruder temperature. If not provided, the current extruder temperature is used.
FIXED_OFFSETS	A comma-separated list of profiles to apply. The Z-offsets from the specified profiles are added to the final calculated offset. See Profiles
DRY_RUN	If TRUE, the Z-offset is calculated and printed to the console but not applied. This is useful for testing and verification.

Example: Calculate the Z-offset for bed temperature 60℃ and extruder temperature 200℃, and increase the adhesion by 50µm profiles:
ZOOC_ADJUST BED_TEMP=60 EXTRUDER_TEMP=200 FIXED_OFFSETS=squish_05 DRY_RUN=TRUE

Contributing

See the CONTRIBUTING file for details on how to contribute to, develop, and test this project.

Support my work

If you find this project useful, consider supporting my work by buying me a coffee. It helps keep the development going and motivates me to create more useful plugins.

Other plugins

ZOOC targets to compensate the fast bed and extruder expansion occurring during the 1st layer, and without any custom parts. There are several other great projects for Z-offset calibration for Z-endstop calibration and slow frame expansion.

• Voron-Tap
• Auto-Z-calibration-for-RRF-3.3-or-later-and-Klicky-Probe
• klipper_z_calibration
• z_thermal_adjust

Troubleshooting

• If you get an error like this in klippy.log:

  configparser.Error: Option 'fixed_offsets' is not valid in section 'zooc'

  Make sure you have run the post-install script or manually copied the zooc.py file to the extras directory.

• If you see a Python version error like this:

  zooc-setup: error: This script requires Python 3.12 or later.

  Make sure you are using Python 3.12 or later. You can check the version with:
  ~/klippy-env/bin/python --version

  If needed, upgrade your Python version and the klippy-env virtual environment with:
  python3 -m venv --upgrade ~/klippy-env

Disclaimer

Use ZOOC at your own risk. While it includes checks to ensure the Z-offset is within reasonable limits, it's possible for an incorrect offset to be applied, which could cause the nozzle to hit the bed.

Always run ZOOC_ADJUST with DRY_RUN=TRUE first to ensure the calculated offset is reasonable.

Make sure the offset works correctly before printing with a low layer height, as this leaves less room for error.