diff --git a/README.md b/README.md index 30a63f3..7579f26 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ everything below, grouped by topic. Comment out what you do not use there. Firmware update scripts for all MCUs (Klipper and Katapult). They contain this printer's CAN UUIDs and serial IDs: see [scripts/README.md](scripts/README.md) before using them on another printer. `twist_check.py` is the axis twist -calibration behind `TWIST_CALIBRATE`. +calibration behind `TWIST_CALIBRATE`: see [scripts/twist_check.md](scripts/twist_check.md). ### Tools (`tools/`) diff --git a/scripts/README.md b/scripts/README.md index 937ab56..53353ec 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,8 +1,8 @@ # Scripts `twist_check.py` is the axis twist calibration: start it with the macro -`TWIST_CALIBRATE` in Mainsail, or see the top of the file for the shell -commands. The rest of this page is about the firmware scripts. +`TWIST_CALIBRATE` in Mainsail, and see [twist_check.md](twist_check.md) for how +to use it. The rest of this page is about the firmware scripts. # MCU firmware update scripts diff --git a/scripts/twist_check.md b/scripts/twist_check.md new file mode 100644 index 0000000..b7e1832 --- /dev/null +++ b/scripts/twist_check.md @@ -0,0 +1,146 @@ +# 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__.html` | Report with verdict and charts: download it from Mainsail and open it in a browser | +| `twist__.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/.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://: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