Files
klipper-macros/scripts/twist_check.md
T
2026-11-03 22:55:55 +01:00

7.1 KiB

Axis twist calibration (TWIST_CALIBRATE)

Written 2026-11-03. Tested against a simulated printer and saved runs; the first real run on the printer is still to come, so stay near the emergency stop for that one.

What it is for

Beacon sits 20 mm behind the nozzle. If the toolhead rolls slightly as it moves along the X rail, the nozzle and Beacon disagree about the bed height, by an amount that depends on where the toolhead is. Levelling and meshes inherit that error, so first layers come out thinner on one side. Klipper's [axis_twist_compensation] corrects it, and this tool measures the values.

Run it:

  • after work on the X rail, X carriage, toolhead, belts or Beacon mount
  • when first layers differ between left and right

There is no need to run it on a schedule.

Step by step

  1. Run TWIST_CALIBRATE in Mainsail and choose Measure (25 min).
  2. Go through the checklist: nothing on the bed, nozzle clean, hands out of the printer. Nothing moves until you press All checked, start.
  3. You can close the window; the run continues. Progress is on the status line, and running TWIST_CALIBRATE again shows a progress bar and a Stop button.
  4. A window opens with the verdict. If it says new values recommended:
    1. Open twist_data/twist_suggested.cfg in Mainsail (Machine page, config files) and copy its contents.
    2. Make a backup copy of printer.cfg.
    3. In printer.cfg, replace the whole [axis_twist_compensation] block with the copied one. New values replace the old ones; do not add them together. If there is no block yet, paste it after [beacon], outside the SAVE_CONFIG section at the bottom.
    4. Save and restart.
  5. Run TWIST_CALIBRATE again and choose Verify (17 min).

The calibration clears the active bed mesh (saved profiles stay). PRINT_START makes a new one by itself.

What the run does

It heats the nozzle to 150 C, homes, runs QGL and sets Z by contact. It then visits each point twice, the second pass in reverse order to cancel slow drift. The nozzle touches the bed at every point. At the end it lifts to Z10 and turns the nozzle heater off. The bed heater is not touched.

  • Measure: compares Beacon proximity with nozzle contact on rows y 55, 175 and 295 (x 25-325) and on a line along Y at x=175. Compensation may be active: Beacon adds the same correction to both readings, so the difference is still the raw error.
  • Verify: compares compensated Beacon proximity with BDP_TOUCH on rows y 175 and 295. bd_pressure takes Z from the stepper and is not compensated, so it is an independent check.

Reading the result

Verdict Meaning What to do
Measure: new values recommended The active values are off by 0.01 mm or more, or none are active Apply them as above, then Verify
Measure: no change needed The active values are still right Nothing
Measure or Verify: run it again The two passes disagree Clean the nozzle and bed, run it again
Measure: do not apply The error is above 0.3 mm, or does not split into an X and a Y part Check the X rail, belts, toolhead and Beacon mount
Verify: compensation is good The readings are flat along X Nothing
Verify: acceptable Slightly less flat than ideal, but usable Check a first layer
Verify: compensation is off Not flat along X Run Measure and apply the new values; if it stays, check the mechanics

The limits, all in mm:

Check Limit
Each X row against the mean of the rows 0.015
Error left by the X+Y correction 0.015
Same point in the two passes no more than one point above 0.02, none above 0.04
Smaller change than this: leave the values 0.01
Verify, range along one row good up to 0.025, usable up to 0.035

They are set so the good runs of 2026-11-02 pass (constants at the top of twist_check.py).

When it stops or refuses

Nothing in the configuration changes when this happens. Unless a print has started or Klipper is down, it lifts the nozzle and turns the heater off.

Message Likely cause What to do
A print is running or paused Refused at the start Try again after the print
Another twist run is active A run is active, or one died without clearing its flag TWIST_STOP stops it and clears the flag
Klipper is not ready Klipper is in an error state FIRMWARE_RESTART, then start again
Not found in Klipper: ... The macros are not up to date or loaded Update klipper-macros and restart Klipper
Beacon sees the bed at ... Something on the bed, or the plate not seated Clear the bed and start again
Nozzle and Beacon differ by ... A blob on the nozzle, or a loose toolhead or Beacon Clean the nozzle; if it stays, check the mounts
... gave no reading, ... failed A probe or sensor command failed Read the message; Verify also needs the bd_pressure load-check firmware
A print started during the run Stopped, and the printer is left alone Start again after the print

TWIST_STOP stops a run and shows Stopped. It waits for the command that is running, which can take about a minute during homing or QGL. In a real emergency use the emergency stop.

Klipper shutdown: travel moves run under the nozzle guard, so hitting something shuts Klipper down, and very occasionally the guard trips falsely. No window can open then. Clear the cause, run FIRMWARE_RESTART, look in twist_run.log for what happened, and start again.

Restarting the Klipper service, which a Moonraker update also does, ends a run that was started from Mainsail.

Files

Everything is in config/twist_data/ (on the Pi ~/printer_data/config/twist_data/):

File Contents
twist_<mode>_<date>.html Report with verdict and charts: download it from Mainsail and open it in a browser
twist_<mode>_<date>.jsonl The raw readings
twist_suggested.cfg The latest recommended block. Not loaded by anything until you paste it into printer.cfg
twist_run.log All messages of all runs. Look here when a run ended without a window

From a shell

Over SSH, use tmux so the run does not depend on the connection:

python3 ~/klipper-macros/scripts/twist_check.py measure
python3 ~/klipper-macros/scripts/twist_check.py verify
python3 ~/klipper-macros/scripts/twist_check.py analyse ~/printer_data/config/twist_data/<file>.jsonl

Ctrl-C stops a run the same way TWIST_STOP does. analyse prints the result of a saved run again and writes its report next to the file; it does not move the printer. From another computer, add --host http://<printer>:7125 (Moonraker's own port, because nginx ends requests after 60 s). The data folder is then on that computer, under its own home directory.

Requirements

  • Mainsail with [respond], for the windows
  • gcode_shell_command, to start the script from a macro
  • Beacon, used in contact and proximity mode
  • Python 3 on the Pi (standard library only), and Moonraker trusting localhost
  • For Verify: [bdp_touch] and the bd_pressure load-check firmware
  • [axis_twist_compensation] is not needed for the first Measure; the result tells you to add it