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

147 lines
7.1 KiB
Markdown

# 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:
```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
- 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