Plastic left on the nozzle sets the contact Z too high and squeezes away during the run. The first real Verify (2026-11-04, about an hour after a PLA print) saw bd_pressure and Beacon contact sink by about 0.004 mm per point while proximity held within 0.006 mm, so it asked for a re-run. That cause is likely but not yet confirmed. Same order as PRINT_START: QGL, G28 Z, BLOBIFIER_CLEAN with the guard in log mode, then the contact step. Refuses to start without BLOBIFIER_CLEAN or _GUARD_ON. Tested against the simulated printer only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.2 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
- Run
TWIST_CALIBRATEin Mainsail and choose Measure (25 min). - Go through the checklist: nothing on the bed, nozzle clean, hands out of the printer. Nothing moves until you press All checked, start.
- You can close the window; the run continues. Progress is on the status line,
and running
TWIST_CALIBRATEagain shows a progress bar and a Stop button. - A window opens with the verdict. If it says new values recommended:
- Open
twist_data/twist_suggested.cfgin Mainsail (Machine page, config files) and copy its contents. - Make a backup copy of
printer.cfg. - 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 theSAVE_CONFIGsection at the bottom. - Save and restart.
- Open
- Run
TWIST_CALIBRATEagain 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, wipes the nozzle on the Blobifier brush 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_TOUCHon 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
- The Blobifier macros (
BLOBIFIER_CLEAN) and the nozzle guard (_GUARD_ON) - 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