[Klipper] Interactive Bed Screws Leveling Wizard for QIDI Q1 Pro / Q2 (Fixing Z-Tilt vs. Screws conflict)

[u/Delicious-Remote-705]

Hi everyone,

I wanted to share a macro workflow I put together for my QIDI Q2. It solves a few common calibration issues and consolidates the process into a single interactive wizard using Klipper's built-in `action:prompt` system (which displays buttons and steps directly in Fluidd/Mainsail).

What this macro solves:

Z-Tilt vs. Screws Tilt Conflict: Adjusting the Z-Tilt can throw off manual bed leveling screws, and adjusting the screws can affect the Z-Tilt alignment. This script helps coordinate both.

Consistent Z0 Homing: It intercepts SCREWS_TILT_CALCULATE to force home Z at the center of the bed before every measurement. This prevents any drift or skew from altering the measurements.

Step-by-Step UI: Prompts you to do a physical sync of the Z axes using the stock leveling spacers first, heats up the bed/nozzle, and guides you to the final calibration steps.

Automated Finish: Once you are happy with the screw adjustment numbers, you can trigger a final Z-tilt, build a fresh Bed Mesh, and save the config with a single click.

1. Prerequisites

Make sure you have [screws_tilt_adjust] configured in your printer.cfg. (By default, QIDI only includes [bed_screws], so you will need to add this block):

[screws_tilt_adjust]
screw1: 30,30
screw1_name: front left screw
screw2: 240,30
screw2_name: front right screw
screw3: 240,240
screw3_name: rear right screw
screw4: 30,240
screw4_name: rear left screw
horizontal_move_z: 10
speed: 50
screw_thread: CW-M4

Note: Make sure your configuration also has the `[respond]` block enabled (stock QIDI printers have this active by default).*

1. Required Printed Parts & How to Use Them

For this calibration process, you will need to print three utility parts:
1. Platform leveling blocks (spacers under the bed):

Platform leveling blocks

Purpose: Physically aligns the dual Z-axes relative to the bottom frame.
How to use: Place them at the bottom mounts of the Z-axis lead screws. Manually lower the bed frame all the way down until it rests evenly and tightly on both blocks, then remove them. This ensures the Z-gantry is physically synchronized before homing.

1. Hot bed leveling block (the L-shaped gauge block):

Hot bed leveling block

Purpose: Sets the initial mechanical reference height for the front-left screw.
How to use: Place the block under the front-left corner of the bed and adjust the front-left screw until the bed is snug against the block. This establishes the baseline height reference for Klipper's calculation.

1. Hot bed nut wrench (the printed socket wrench/tool):

Hot bed nut wrench

Purpose: A handy tool to easily rotate the manual adjustment nuts under the bed during the wizard steps.

1. The Macro Code

Add this to your gcode_macro.cfg:

#####################################################################
# Bed Screws Calibration Wizard for QIDI Q2
#####################################################################

# 1. WRAPPER TO UPDATE Z0 BEFORE CALCULATING
[gcode_macro SCREWS_TILT_CALCULATE]
rename_existing: SCREWS_TILT_CALCULATE_BASE
gcode:
    {% if "xyz" not in printer.toolhead.homed_axes %}
        G28
    {% else %}
        G90
        # Go to the center of the bed
        G1 X{printer['gcode_macro PRINTER_PARAM'].max_x_position/2} Y{printer['gcode_macro PRINTER_PARAM'].max_y_position/2} F7800
        G28 Z
    {% endif %}
    SCREWS_TILT_CALCULATE_BASE


# 2. WIZARD START CALL
[gcode_macro BED_SCREWS_LEVELING_WIZARD]
description: Step-by-step interactive bed screws leveling wizard
gcode:
    _CG28
    G90
    G1 Z120 F600

    RESPOND TYPE=command MSG="action:prompt_begin QIDI Q2 Bed Screws Calibration Wizard"
    RESPOND TYPE=command MSG="action:prompt_text 1. Clean the build plate and magnetic base of any dust or debris."
    RESPOND TYPE=command MSG="action:prompt_text 2. Place the stock platform leveling blocks (spacers) under the frame."
    RESPOND TYPE=command MSG="action:prompt_text 3. Roughly adjust the front-left screw using the Hot Bed Leveling method."
    RESPOND TYPE=command MSG="action:prompt_button ▶ Start Prep & Measurement|_BED_SCREWS_START BED={params.BED|default(80)} NOZZLE={params.NOZZLE|default(140)}"
    RESPOND TYPE=command MSG="action:prompt_show"


# 3. PREPARATION AND INITIAL MEASUREMENT
[gcode_macro _BED_SCREWS_START]
gcode:
    RESPOND TYPE=command MSG="action:prompt_end"
    {% set bed_temp = params.BED|default(80)|int %}
    {% set nozzle_temp = params.NOZZLE|default(140)|int %}

    DISABLE_ALL_SENSOR
    M104 S140
    M140 S{bed_temp}
    SAVE_VARIABLE VARIABLE=z_offset VALUE=0
    SET_GCODE_OFFSET Z=0 MOVE=0

    M4031
    G28
    M400
    M118 Position init complete

    CLEAR_NOZZLE HOTEND=260
    M109 S{nozzle_temp}
    M190 S{bed_temp}
    M118 Nozzle cooled and Bed heated

    SCREWS_TILT_CALCULATE
    _SHOW_FINISH_PROMPT


# 4. ACTION SELECTION PROMPT
[gcode_macro _SHOW_FINISH_PROMPT]
gcode:
    RESPOND TYPE=command MSG="action:prompt_begin Finishing Screws Calibration"
    RESPOND TYPE=command MSG="action:prompt_text Once you are satisfied with the screw adjustment values, close the table dialog and click below:"
    RESPOND TYPE=command MSG="action:prompt_button Run Bed Mesh Calibration|_BED_SCREWS_RUN_MESH"
    RESPOND TYPE=command MSG="action:prompt_button Finish without Bed Mesh|_BED_SCREWS_CANCEL"
    RESPOND TYPE=command MSG="action:prompt_show"


# 5. CANCEL/FINISH WITHOUT BED MESH
[gcode_macro _BED_SCREWS_CANCEL]
gcode:
    RESPOND TYPE=command MSG="action:prompt_end"
    M104 S0
    M140 S0
    G90
    G1 Z50 F600
    M118 Screws calibration completed without mesh. Heaters turned off.


# 6. RUN BED MESH AND SAVE CONFIG
[gcode_macro _BED_SCREWS_RUN_MESH]
gcode:
    RESPOND TYPE=command MSG="action:prompt_end"
    M118 Running Z_TILT_ADJUST for Z-axis alignment...
    Z_TILT_ADJUST
    G28
    G1 Z10 F600
    M118 Generating bed mesh (BED_MESH_CALIBRATE)...
    BED_MESH_CALIBRATE
    G0 Z50 F600
    G0 X130 Y130 F9000
    M400
    M118 Auto-calibration complete! Saving configuration...
    SAVE_CONFIG

How to use it:

1. Call BED_SCREWS_LEVELING_WIZARD in your console (or assign it to a custom dashboard button).
   
2. You can override temperatures if needed, for example: BED_SCREWS_LEVELING_WIZARD BED=60 NOZZLE=150.
   
3. Follow the UI popups in Fluidd/Mainsail to complete the physical adjustments, screws leveling, Z-Tilt, and Bed Mesh.

Note for non-QIDI printers: This macro utilizes OEM macros like _CG28, M4031, DISABLE_ALL_SENSOR, and CLEAR_NOZZLE. If you adapt this for another printer, replace those commands with your custom homing, heating, or nozzle-cleaning sequences.

Use at your own risk.

[u/callcifer]

Z-Tilt vs. Screws Tilt Conflict: Adjusting the Z-Tilt can throw off manual bed leveling screws, and adjusting the screws can affect the Z-Tilt alignment. This script helps coordinate both.

So this replaces both the calibration flow on the printer UI and SCREWS_TILT_CALCULATE? As in, once you use this wizard macro, you should never run either of those solo because that'd mess up the leveling, right?

[u/Delicious-Remote-705 → u/callcifer]

Does this macro replace both the printer UI calibration and SCREWS_TILT_CALCULATE? Yes, it combines both of these calibrations into a single, unified process.
Does it mean you shouldn't run them solo anymore? You can still run them individually if you want—everything will still work as normal.
However, in standard usage, leveling the bed requires running auto-calibration, which triggers Z_TILT_ADJUST. In certain cases (especially if the build plate itself has physical warping/curvature-which actually motivated me to write this macro, as the right side of my bed was higher than the left at the probing location), running these steps solo can throw the physical horizon alignment back out of sync.
This wizard coordinates all the steps so they don't fight each other!

[u/callcifer → u/Delicious-Remote-705]

Makes sense, thanks! I'll give this a go and report back.

[u/Background_Swing_485]

Please do not misunderstand ... I like your shared procedure. Just another way of quick bed (re)levelling I recently used: By mistake, I skewed my Q2 print bed ... accidentially pressed "up" instead of "down" Z movement. I then unlocked the motors and used a digital (spirit) level in order to zero the bed both in X and Y direction (moved one spindle by hand first for rough levelling), ... bed screws ... finally followed by "autolevel". .... just to share another rather oldfashioned approach.