2026-11-03 22:55:55 +01:00
|
|
|
# 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
|
|
|
|
|
|
2026-11-04 00:47:04 +01:00
|
|
|
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.
|
2026-11-03 22:55:55 +01:00
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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
|
2026-11-04 00:47:04 +01:00
|
|
|
- The Blobifier macros (`BLOBIFIER_CLEAN`) and the nozzle guard (`_GUARD_ON`)
|
2026-11-03 22:55:55 +01:00
|
|
|
- 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
|