Compare commits

..
3 Commits
Author SHA1 Message Date
mangavalkandClaude Opus 5.5 7bee9a1ecd Add a user guide for the axis twist calibration
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 22:55:55 +01:00
mangavalkandClaude Opus 5.5 2592030cb4 twist_check: survive a closed SSH window and unexpected errors
A closed terminal made print() raise and any unexpected exception skipped the
cleanup, leaving the nozzle low and hot. Both now end in the normal stop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 22:55:55 +01:00
mangavalkandClaude Opus 5.5 92d86d6bfd TWIST_CALIBRATE: axis twist calibration from Mainsail
scripts/twist_check.py runs on the Pi and measures or verifies the nozzle vs
Beacon offset; windows explain each step, show progress and give a verdict,
with an HTML report in config/twist_data/. It refuses to start during a print,
stops on unexpected readings and never changes printer.cfg.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 22:53:48 +01:00
7 changed files with 1010 additions and 2 deletions

No files matched your search

+4 -1
View File
@@ -37,7 +37,10 @@ detection, `filament_error_sensitivity`), iHeater chamber heater.
On the Pi, `macros/` is linked as `~/printer_data/config/klipper-macros/`
and `scripts/` as `~/printer_data/config/klipper-macros-scripts/`.
- `extras/*.py` are linked into `~/klipper/klippy/extras/`.
- `scripts/` MCU firmware update scripts (printer-specific IDs).
- `scripts/` MCU firmware update scripts (printer-specific IDs) and
`twist_check.py` (axis twist calibration, runs on the Pi and talks to
Moonraker on localhost; started by `TWIST_CALIBRATE` in
`macros/calibration/twist_check.cfg`, results in `config/twist_data/`).
- `tools/effective_config.py` expands the includes like Klipper and compares
the result between git refs.
+5 -1
View File
@@ -51,6 +51,9 @@ everything below, grouped by topic. Comment out what you do not use there.
| `motion_sensor.cfg` | PIR motion sensor: case light and nozzle LEDs on while someone is near (timeout from the last motion), `CASELIGHT MODE=AUTO\|ON\|OFF`; runs outside the G-code queue, so the lights also react during heat waits and AFC loads | `extras/motion_lights.py`, sensor on a pin, `[output_pin caselight]`, `leds/stealthburner_leds.cfg` |
| `touch_compare.cfg` | `[bdp_touch]`, `TOUCH_COMPARE [N=10] [X] [Y] [TEMP=150]`: nozzle to 150C, `HOME`, then N pairs of a Beacon contact probe and a bd_pressure touch at one spot; reports mean, spread and range of each and of the difference | `extras/bdp_touch.py` + bd_pressure load-check firmware, Beacon |
| **calibration/** | | |
| `twist_check.cfg` + `scripts/twist_check.py` | `TWIST_CALIBRATE`: axis twist calibration from Mainsail with windows that explain each step. Measure (25 min) says whether new `[axis_twist_compensation]` values are needed, Verify (17 min) checks them with bd_pressure. Progress on the status line, result in a window, HTML report with charts in `config/twist_data/`. Never changes `printer.cfg`. `TWIST_STOP` stops a run. | Beacon, `[axis_twist_compensation]`, `gcode_shell_command`, Mainsail prompts; Verify also `bdp_touch.py` |
### Klipper modules (`extras/`)
| File | For |
@@ -65,7 +68,8 @@ 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.
before using them on another printer. `twist_check.py` is the axis twist
calibration behind `TWIST_CALIBRATE`: see [scripts/twist_check.md](scripts/twist_check.md).
### Tools (`tools/`)
+115
View File
@@ -0,0 +1,115 @@
# Axis twist calibration from Mainsail: run TWIST_CALIBRATE and follow the
# windows. Starts scripts/twist_check.py (see there) in the background: inside
# a macro it would deadlock, because the macro holds the G-code queue that the
# script needs.
#
# TWIST_CALIBRATE the start: explains, checks, shows progress while running
# TWIST_STOP stop a run: lifts the nozzle, nozzle heater off. It waits
# for the command that is running (homing, QGL: up to a
# minute); use the emergency stop in a real emergency.
#
# While running: progress on the status line (M117) and in TWIST_CALIBRATE,
# logo as for Z calibration, the result opens a window. Reports and the
# values to apply are in config/twist_data/. Nothing here changes printer.cfg.
#
# Started from Klipper, so restarting the Klipper service ends the run.
[gcode_shell_command _twist_start]
command: bash -c 'setsid nohup python3 "$HOME/printer_data/config/klipper-macros-scripts/twist_check.py" "$1" >/dev/null 2>&1 </dev/null &' twist
timeout: 5.0
verbose: False
# [t]: otherwise pkill also matches this bash command itself
[gcode_shell_command _twist_stop]
command: bash -c 'pkill -TERM -f "[t]wist_check.py (measure|verify)" || true'
timeout: 5.0
verbose: False
# Set by the script; a RESTART clears it
[gcode_macro _TWIST_STATE]
variable_running: 0
variable_mode: ''
variable_done: 0
variable_total: 0
gcode:
[gcode_macro _TWIST_CLOSE]
description: Close the twist calibration window
gcode:
RESPOND TYPE=command MSG="action:prompt_end"
[gcode_macro TWIST_CALIBRATE]
description: Axis twist calibration (nozzle vs Beacon): explains the steps, starts them, shows progress
gcode:
{% set st = printer['gcode_macro _TWIST_STATE'] %}
{% if st.running %}
{% set pct = (100 * st.done / st.total)|int if st.total else 0 %}
{% set n = pct // 5 %}
RESPOND TYPE=command MSG="action:prompt_begin Twist {st.mode} is running"
RESPOND TYPE=command MSG="action:prompt_text Point {st.done} of {st.total}"
RESPOND TYPE=command MSG="action:prompt_text [{'=' * n}{'.' * (20 - n)}] {pct} percent"
RESPOND TYPE=command MSG="action:prompt_text You can close this window: the run continues. The status line shows the progress, and a window opens with the result."
RESPOND TYPE=command MSG="action:prompt_footer_button Stop the run|TWIST_STOP|error"
RESPOND TYPE=command MSG="action:prompt_footer_button Close|_TWIST_CLOSE|secondary"
RESPOND TYPE=command MSG="action:prompt_show"
{% elif printer.print_stats.state in ("printing", "paused") %}
RESPOND TYPE=command MSG="action:prompt_begin Not during a print"
RESPOND TYPE=command MSG="action:prompt_text The calibration moves the nozzle onto the bed. Start it when the print has finished."
RESPOND TYPE=command MSG="action:prompt_footer_button Close|_TWIST_CLOSE|secondary"
RESPOND TYPE=command MSG="action:prompt_show"
{% else %}
RESPOND TYPE=command MSG="action:prompt_begin Axis twist calibration"
RESPOND TYPE=command MSG="action:prompt_text Checks that the nozzle and the Beacon agree across the bed. Run it after work on the X rail, carriage, toolhead, belts or Beacon mount, or when first layers differ left vs right."
RESPOND TYPE=command MSG="action:prompt_text Measure (25 min): measures and tells you whether new values are needed. Start here."
RESPOND TYPE=command MSG="action:prompt_text Verify (17 min): checks the active values with bd_pressure. Run it after applying new values."
RESPOND TYPE=command MSG="action:prompt_button Measure|_TWIST_CHECKLIST MODE=measure|primary"
RESPOND TYPE=command MSG="action:prompt_button Verify|_TWIST_CHECKLIST MODE=verify|secondary"
RESPOND TYPE=command MSG="action:prompt_footer_button Close|_TWIST_CLOSE|secondary"
RESPOND TYPE=command MSG="action:prompt_show"
{% endif %}
[gcode_macro _TWIST_CHECKLIST]
description: Twist calibration: what to check before starting
gcode:
{% set mode = params.MODE|default('measure')|lower %}
{% set bed = printer.heater_bed.temperature %}
RESPOND TYPE=command MSG="action:prompt_begin Before you start {mode}"
RESPOND TYPE=command MSG="action:prompt_text 1. Nothing on the bed: no parts, no tools, plate seated."
RESPOND TYPE=command MSG="action:prompt_text 2. Nozzle clean, no blob: it touches the bed at every point."
RESPOND TYPE=command MSG="action:prompt_text 3. Keep hands out of the printer while it runs."
{% if bed > 40 %}
RESPOND TYPE=command MSG="action:prompt_text Note: the bed is at {bed|int} C. The reference runs were on a cold bed, so wait for it to cool unless you want this on purpose."
{% endif %}
RESPOND TYPE=command MSG="action:prompt_text It heats the nozzle to 150 C, homes, levels and takes {'25' if mode == 'measure' else '17'} minutes. The configuration is not changed."
RESPOND TYPE=command MSG="action:prompt_footer_button Back|TWIST_CALIBRATE|secondary"
RESPOND TYPE=command MSG="action:prompt_footer_button All checked, start|_TWIST_START MODE={mode}|primary"
RESPOND TYPE=command MSG="action:prompt_show"
[gcode_macro _TWIST_START]
description: Start the twist script in the background (use TWIST_CALIBRATE)
gcode:
{% set mode = params.MODE|default('')|lower %}
{% if mode not in ("measure", "verify") %}
_ERROR MSG="_TWIST_START: MODE must be measure or verify"
{% elif printer.print_stats.state in ("printing", "paused") %}
_ERROR MSG="Twist calibration: a print is running" DISPLAY="Twist: not during a print"
{% elif printer['gcode_macro _TWIST_STATE'].running %}
_ERROR MSG="Twist calibration is already running. TWIST_CALIBRATE shows it, TWIST_STOP stops it." DISPLAY="Twist: already running"
{% else %}
M117 Twist {mode}: starting
RESPOND TYPE=command MSG="action:prompt_begin Twist {mode} started"
RESPOND TYPE=command MSG="action:prompt_text You can close this window: the run continues. The status line shows the progress, and a window opens with the result."
RESPOND TYPE=command MSG="action:prompt_footer_button Stop the run|TWIST_STOP|error"
RESPOND TYPE=command MSG="action:prompt_footer_button Close|_TWIST_CLOSE|secondary"
RESPOND TYPE=command MSG="action:prompt_show"
RUN_SHELL_COMMAND CMD=_twist_start PARAMS={mode}
{% endif %}
[gcode_macro TWIST_STOP]
description: Stop a running twist calibration: lifts the nozzle, nozzle heater off
gcode:
RESPOND TYPE=command MSG="action:prompt_end"
M117 Twist: stopping
RUN_SHELL_COMMAND CMD=_twist_stop
# Also clears the flag when a run has died without clearing it itself
SET_GCODE_VARIABLE MACRO=_TWIST_STATE VARIABLE=running VALUE=0
+3
View File
@@ -51,3 +51,6 @@
[include leds/stealthburner_leds.cfg]
[include sensors/motion_sensor.cfg]
[include sensors/touch_compare.cfg] # TOUCH_COMPARE: Beacon contact vs bd_pressure (needs extras/bdp_touch.py)
# Calibration
[include calibration/twist_check.cfg] # TWIST_CALIBRATE: axis twist compensation, with windows in Mainsail (runs scripts/twist_check.py)
+6
View File
@@ -1,3 +1,9 @@
# Scripts
`twist_check.py` is the axis twist calibration: start it with the macro
`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
| Script | Does |
+146
View File
@@ -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_<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
+731
View File
@@ -0,0 +1,731 @@
#!/usr/bin/env python3
"""Nozzle vs Beacon offset across the bed (axis twist compensation).
Beacon sits 20 mm behind the nozzle (y_offset 20). If the toolhead rolls as
it moves (X rail twist), Beacon's proximity reading and the nozzle disagree
by an amount that depends on X (and a little on Y). Beacon meshes and QGL
inherit that error; Klipper's [axis_twist_compensation] corrects it.
Normally started from Mainsail with the macro TWIST_CALIBRATE, which explains
each step (macros/calibration/twist_check.cfg). From a shell on the Pi:
python3 ~/klipper-macros/scripts/twist_check.py measure
python3 ~/klipper-macros/scripts/twist_check.py verify
python3 ~/klipper-macros/scripts/twist_check.py analyse <file.jsonl>
Modes:
measure ~25 min. Proximity (nozzle at x, y-20, so Beacon sees bed x,y), then
Beacon contact with the nozzle moved onto x,y. Rows y 55/175/295
and a Y line at x=175. Works with or without compensation active:
Beacon adds the same correction to proximity and contact, so
contact - proximity is the raw error. New values replace the old
ones. Result: apply, leave it, or re-run. It never changes
printer.cfg; a ready block is saved in twist_suggested.cfg.
verify ~17 min. Proximity (compensated), then BDP_TOUCH at x,y (bd_pressure,
Z from the stepper, not compensated), then Beacon contact. Rows
y 175/295. With good compensation, bdp - proximity is flat along X.
Both: BED_MESH_CLEAR (the active mesh only; saved profiles stay), nozzle 150C,
HOME, QGL, contact Z, 2 passes (second in reverse order to cancel slow drift),
then Z10 and nozzle off. The bed heater is not touched.
Safety: refuses to start when Klipper is not ready, a print runs or another
run is active. Travel moves run under the nozzle guard. Every reading is
checked before the nozzle goes low, and anything unexpected stops the run. A
stop (TWIST_STOP, Ctrl-C, an error) lifts the nozzle and switches its heater
off, except when a print has started: then it leaves the printer alone.
Writes twist_<mode>_<date>.jsonl and .html (report with charts) in
~/printer_data/config/twist_data/, plus twist_run.log with all messages.
"""
import argparse
import datetime
import html
import json
import os
import re
import signal
import statistics as st
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
XS = [25, 75, 125, 175, 225, 275, 325]
YS = [55, 95, 135, 175, 215, 255, 295]
PASSES = 2
TRIGGER = 2.0 # [beacon] trigger_distance: proximity result - 2 = bed
BDP_ABOVE = 0.15 # BDP_TOUCH start height above the expected bed
# Result checks (mm)
# Set so the good 2026-11-02 runs pass: rows 0.012, residual 0.012, one point
# with pass spread 0.031 (the next 0.012, median 0.004), verify flat 0.022.
ROWS_AGREE = 0.015 # each X row vs the mean: else X and Y are not separable
RESIDUAL = 0.015 # worst error left by the X+Y model
PASS_SPREAD = 0.02 # same point in the two passes: dirty nozzle or bed when
PASS_OUTLIERS = 1 # more points than this are above it,
PASS_WORST = 0.04 # or any point above this
MIN_CHANGE = 0.01 # smaller differences to the active values: leave it
MAX_COMP = 0.3 # larger: something is mechanically wrong, do not correct
FLAT_GOOD = 0.025 # verify: bdp - proximity range along one row
FLAT_MAX = 0.035
# Reading checks during the run (mm); outside these the run stops
PROX_LIMIT = 0.5 # bed height from Beacon vs Z 0: something on the bed?
CONTACT_LIMIT = 0.25 # nozzle contact vs Beacon: blob on the nozzle?
BED_WARN = 40 # C: all reference runs were on a cold bed
DATA_DIR = os.path.expanduser("~/printer_data/config/twist_data")
LOG = None
class Problem(Exception):
"""Something the user has to look at; the run stops."""
class Stopped(Exception):
"""TWIST_STOP or Ctrl-C."""
def log(text):
line = "%s %s" % (time.strftime("%H:%M:%S"), text)
try:
print(line, flush=True)
except OSError:
pass # SSH window closed: the run continues, the log file stays
if LOG:
LOG.write(line + "\n")
LOG.flush()
def clean(text):
# Double quotes end a G-code parameter and ; starts a comment
return str(text).replace('"', "'").replace(";", ",")
class Printer:
def __init__(self, host):
self.host = host
def get(self, path, timeout=10):
try:
with urllib.request.urlopen(self.host + path,
timeout=timeout) as r:
return json.load(r)["result"]
except (OSError, ValueError, KeyError) as e:
raise Problem("No answer from Moonraker at %s (%s)"
% (self.host, e))
def query(self, *objects):
path = "/printer/objects/query?" + "&".join(
urllib.parse.quote(o) for o in objects)
return self.get(path)["status"]
def gcode(self, script, timeout=900):
t0 = time.time()
url = (self.host + "/printer/gcode/script?script="
+ urllib.parse.quote(script))
req = urllib.request.Request(url, method="POST")
try:
urllib.request.urlopen(req, timeout=timeout).read()
except urllib.error.HTTPError as e:
raise Problem(self.error_text(e, script))
except OSError as e:
raise Problem("Lost the connection during %s (%s)" % (script, e))
store = self.get("/server/gcode_store?count=40")["gcode_store"]
return [e["message"] for e in store
if e["time"] >= t0 - 1 and e["type"] == "response"]
def error_text(self, e, script):
try:
text = json.load(e)["error"]["message"]
except (ValueError, KeyError, TypeError):
text = "HTTP %d" % e.code
return "%s failed: %s" % (script.split()[0], text)
def say(self, text):
log(text)
self.gcode('RESPOND MSG="Twist: %s"' % clean(text), timeout=60)
def dialog(self, title, lines, buttons=()):
# Mainsail shows this as a window (needs [respond])
out = ["action:prompt_begin " + title]
out += ["action:prompt_text " + line for line in lines]
out += ["action:prompt_button %s|%s|%s" % b for b in buttons]
out += ["action:prompt_footer_button Close|_TWIST_CLOSE|secondary",
"action:prompt_show"]
self.gcode("\n".join('RESPOND TYPE=command MSG="%s"' % clean(m)
for m in out), timeout=60)
def state(self, running, mode=None, done=None, total=None):
cmd = "SET_GCODE_VARIABLE MACRO=_TWIST_STATE VARIABLE=%s VALUE=%s"
out = [cmd % ("running", running)]
if mode is not None:
out.append(cmd % ("mode", "\"'%s'\"" % mode))
if done is not None:
out.append(cmd % ("done", done))
if total is not None:
out.append(cmd % ("total", total))
return "\n".join(out)
def logo(self, status):
# The Stealthburner logo: visible from across the room
objects = self.get("/printer/objects/list")["objects"]
if status == "error":
if "gcode_macro _STATUS_FLASH" in objects:
return "_STATUS_FLASH STATE=error"
elif "gcode_macro _STATUS" in objects:
return "_STATUS STATE=" + status
return ""
def num(lines, pattern, what):
for line in reversed(lines):
m = re.search(pattern, line)
if m:
return float(m.group(1))
raise Problem("%s gave no reading (expected %s in the answer)"
% (what, pattern))
def print_active(p):
s = p.query("print_stats", "pause_resume", "virtual_sdcard")
return (s["print_stats"]["state"] in ("printing", "paused")
or s["pause_resume"]["is_paused"]
or s["virtual_sdcard"]["is_active"])
def check_ready(p):
info = p.get("/printer/info")
if info["state"] != "ready":
raise Problem("Klipper is not ready (%s): %s"
% (info["state"], info.get("state_message", "").strip()))
def preflight(p, mode):
check_ready(p)
if print_active(p):
raise Problem("A print is running or paused. Try again afterwards.")
objects = p.get("/printer/objects/list")["objects"]
settings = p.query("configfile")["configfile"]["settings"]
missing = [m for m in ("HOME", "_NOZZLE_CONTACT_TEMP", "_TWIST_STATE")
if "gcode_macro " + m not in objects]
missing += [s for s in ["beacon"] + (["bdp_touch"] * (mode == "verify"))
if s not in settings]
if missing:
raise Problem("Not found in Klipper: %s. Is klipper-macros up to "
"date and Klipper restarted?" % ", ".join(missing))
if p.query("gcode_macro _TWIST_STATE")[
"gcode_macro _TWIST_STATE"]["running"]:
raise Problem("Another twist run is active. TWIST_STOP stops it (and "
"clears this flag if that run has died).")
bed = p.query("heater_bed")["heater_bed"]["temperature"]
if bed > BED_WARN:
p.say("Note: bed at %d C. The reference runs were on a cold bed."
% bed)
def bar(done, total, width=20):
n = width * done // total if total else 0
return "[%s%s]" % ("=" * n, "." * (width - n))
def eta(start, done, total):
if not done:
return ""
left = (time.time() - start) / done * (total - done)
return ", ~%d min left" % (left // 60 + 1)
def travel(p, x, y):
# Nothing may touch the nozzle here: an object on the bed stops Klipper
p.gcode("_GUARD_ON PHASE=twist_travel\nG1 X%d Y%d Z5 F9000\n_GUARD_OFF"
% (x, y))
def measure_point(p, mode, x, y):
r = {"x": x, "y": y, "t": time.time()}
travel(p, x, y - 20)
r["prox"] = num(p.gcode("PROBE PROBE_METHOD=proximity"),
r"z=(-?[\d.]+)", "Beacon proximity")
bed = r["prox"] - TRIGGER
if abs(bed) > PROX_LIMIT:
raise Problem("Beacon sees the bed at %+.3f mm at x=%d y=%d (limit "
"%.1f). Is something on the bed, or the plate not "
"seated?" % (bed, x, y, PROX_LIMIT))
p.gcode("G1 Z5 F600")
travel(p, x, y)
if mode == "verify":
p.gcode("G1 Z%.3f F300" % (bed + BDP_ABOVE))
r["bdp"] = num(p.gcode("BDP_TOUCH FLOOR=0.7"), r"fit z (-?[\d.]+)",
"BDP_TOUCH")
p.gcode("G1 Z5 F600")
r["contact"] = num(p.gcode("PROBE PROBE_METHOD=contact SAMPLES=1"),
r"z=(-?[\d.]+)", "Beacon contact")
p.gcode("G1 Z5 F600")
if abs(r["contact"] - bed) > CONTACT_LIMIT:
raise Problem("Nozzle and Beacon differ by %.3f mm at x=%d y=%d (limit"
" %.2f). Clean the nozzle; if it stays, check the "
"toolhead and Beacon mount."
% (abs(r["contact"] - bed), x, y, CONTACT_LIMIT))
return r
def run_points(p, mode, path):
if mode == "measure":
pts = [(x, y) for y in (55, 175, 295) for x in XS]
pts += [(175, y) for y in YS if y not in (55, 175, 295)]
else:
pts = [(x, y) for y in (175, 295) for x in XS]
total = len(pts) * PASSES
p.gcode(p.state(1, mode, 0, total))
p.gcode("M117 Twist %s: heating, homing, QGL" % mode)
p.say("%s started: heating the nozzle to 150C, homing, levelling" % mode)
p.gcode("BED_MESH_CLEAR")
p.gcode("_NOZZLE_CONTACT_TEMP WAIT=1")
p.gcode("HOME")
p.gcode("QUAD_GANTRY_LEVEL")
p.gcode("G28 Z METHOD=CONTACT CALIBRATE=1")
p.gcode("G90")
p.say("%d points, %d passes. The nozzle will touch the bed at each one."
% (len(pts), PASSES))
done = 0
start = time.time()
with open(path, "w") as out:
for rep in range(PASSES):
for (x, y) in (pts if rep == 0 else pts[::-1]):
check_ready(p)
if print_active(p):
raise Problem("A print started during the run.")
r = measure_point(p, mode, x, y)
r["rep"] = rep
out.write(json.dumps(r) + "\n")
out.flush()
done += 1
text = "%s %d%% %s%s" % (mode, 100 * done // total,
bar(done, total, 10),
eta(start, done, total))
p.gcode(p.state(1, done=done) + "\nM117 Twist " + clean(text))
log("%d/%d %s" % (done, total, r))
if done % 10 == 0:
p.say(text)
def load(path):
groups = {}
with open(path) as f:
for line in f:
r = json.loads(line)
groups.setdefault((r["x"], r["y"]), []).append(r)
return groups
def mean(groups, key, fn):
out = {}
for k, rs in groups.items():
v = [fn(r) for r in rs if r.get(key) is not None
and r.get("prox") is not None]
if v:
out[k] = (st.mean(v), max(v) - min(v))
return out
def noisy_passes(spreads):
return (max(spreads) > PASS_WORST
or sum(v > PASS_SPREAD for v in spreads) > PASS_OUTLIERS)
def analyse_verify(groups):
rows = sorted({y for x, y in groups}, reverse=True)
prox = mean(groups, "bdp", lambda r: r["bdp"] - (r["prox"] - TRIGGER))
cont = mean(groups, "bdp", lambda r: r["bdp"] - r["contact"])
spreads = [v[1] for v in prox.values()] + [v[1] for v in cont.values()]
spread = max(spreads)
flat = {y: max(prox[(x, y)][0] for x in XS)
- min(prox[(x, y)][0] for x in XS) for y in rows}
worst = max(flat.values())
res = {"mode": "verify", "rows": rows,
"series": {y: [prox[(x, y)][0] for x in XS] for y in rows},
"contact": {y: [cont[(x, y)][0] for x in XS] for y in rows},
"block": None}
facts = ["Flat along X: worst row varies %.3f mm (good: up to %.3f)."
% (worst, FLAT_GOOD),
"Same point between passes: up to %.3f mm." % spread]
if noisy_passes(spreads):
res.update(level="bad", title="Verify: run it again", lines=facts + [
"The two passes disagree: clean the nozzle and bed, then run "
"Verify again."], retry="verify")
elif worst <= FLAT_GOOD:
res.update(level="good", title="Verify: compensation is good",
lines=facts + ["Nothing to do. PRINT_START makes a new "
"mesh by itself."])
elif worst <= FLAT_MAX:
res.update(level="warn", title="Verify: acceptable", lines=facts + [
"Slightly more than ideal but usable. Check a first layer."])
else:
res.update(level="bad", title="Verify: compensation is off",
lines=facts + ["Run Measure again and apply the new "
"values. If it stays, check the X rail, "
"belts and Beacon mount."], retry="measure")
return res
def analyse_measure(groups, current):
full = mean(groups, "contact",
lambda r: r["contact"] - (r["prox"] - TRIGGER))
d = {k: v[0] for k, v in full.items()}
spreads = [v[1] for v in full.values()]
spread = max(spreads)
xrows = [y for y in (55, 175, 295) if all((x, y) in d for x in XS)]
if not xrows or not all((175, y) in d for y in YS):
raise Problem("Not all points were measured; nothing to conclude.")
rel = {y: [d[(x, y)] - d[(175, y)] for x in XS] for y in xrows}
xprof = [st.mean(rel[y][i] for y in xrows) for i in range(len(XS))]
yprof = [d[(175, y)] - d[(175, 175)] for y in YS]
agree = max(abs(rel[y][i] - xprof[i]) for y in xrows
for i in range(len(XS)))
worst = 0.
for y in xrows:
for i, x in enumerate(XS):
left = d[(x, y)] - d[(175, 175)] - xprof[i] - yprof[YS.index(y)]
worst = max(worst, abs(left))
biggest = max(abs(v) for v in xprof + yprof)
change = None
if current and (current.get("z_compensations") or [])[:1] != []:
old_x = current.get("z_compensations") or []
old_y = current.get("zy_compensations") or []
if len(old_x) == len(XS) and len(old_y) == len(YS):
change = max(abs(a - b) for a, b in zip(xprof + yprof,
old_x + old_y))
fmt = lambda vals: ", ".join("%.4f" % (v + 0.) for v in vals)
block = """[axis_twist_compensation]
# Measured %s with scripts/twist_check.py measure:
# nozzle contact vs Beacon proximity, 0 at 175,175
calibrate_start_x: %d
calibrate_end_x: %d
calibrate_y: 175
z_compensations: %s
compensation_start_x: %d
compensation_end_x: %d
calibrate_start_y: %d
calibrate_end_y: %d
calibrate_x: 175
zy_compensations: %s
compensation_start_y: %d
compensation_end_y: %d
""" % (datetime.date.today().isoformat(), XS[0], XS[-1], fmt(xprof), XS[0],
XS[-1], YS[0], YS[-1], fmt(yprof), YS[0], YS[-1])
res = {"mode": "measure", "xprof": xprof, "yprof": yprof, "rel": rel,
"block": None, "suggested": block}
facts = [
"Largest error: %.3f mm. The rows agree within %.3f (limit %.3f)."
% (biggest, agree, ROWS_AGREE),
"Left after correction: %.3f (limit %.3f). Passes: up to %.3f."
% (worst, RESIDUAL, spread)]
if noisy_passes(spreads):
res.update(level="bad", title="Measure: run it again", lines=facts + [
"The two passes disagree: clean the nozzle and bed, then run "
"Measure again. Nothing changed."], retry="measure")
elif biggest > MAX_COMP:
res.update(level="bad", title="Measure: do not apply", lines=facts + [
"This error is too large to correct safely. Check the X rail, "
"belts, toolhead and Beacon mount. Nothing changed."])
elif agree > ROWS_AGREE or worst > RESIDUAL:
res.update(level="bad", title="Measure: do not apply", lines=facts + [
"The error does not split into an X and a Y part, so this "
"compensation cannot correct it. Check the mechanics first. "
"Nothing changed."])
elif change is not None and change < MIN_CHANGE:
res.update(level="good", title="Measure: no change needed",
lines=facts + ["The active values are still right (largest"
" difference %.3f mm). Nothing to do."
% change])
else:
how = ("Largest difference to the active values: %.3f mm." % change
if change is not None else "No compensation is active yet.")
res.update(level="warn", title="Measure: new values recommended",
block=block, lines=facts + [
how,
"1. Open twist_data/twist_suggested.cfg in Mainsail "
"(Machine, config files) and copy it.",
"2. In printer.cfg replace the [axis_twist_compensation"
"] block with it (a backup copy of printer.cfg first).",
"3. Save and Restart, then run Verify here."])
return res
def analyse(path, current=None):
groups = load(path)
if any("bdp" in r for rs in groups.values() for r in rs):
res = analyse_verify(groups)
else:
res = analyse_measure(groups, current)
res["file"] = os.path.basename(path)
return res
def report_console(res):
print()
if res["mode"] == "verify":
print("bdp fit - proximity (flat = compensation good):")
for y in res["rows"]:
print("y=%3d " % y + " ".join("%+.3f" % v
for v in res["series"][y]))
print("bdp fit - Beacon contact (shows Beacon's contact correction):")
for y in res["rows"]:
print("y=%3d " % y + " ".join("%+.3f" % v
for v in res["contact"][y]))
else:
print("contact - proximity, each row minus its own x=175:")
for y, vals in res["rel"].items():
print("y=%3d " % y + " ".join("%+.3f" % v for v in vals))
print("X profile:", " ".join("%+.4f" % v for v in res["xprof"]))
print("Y profile:", " ".join("%+.4f" % v for v in res["yprof"]))
print("\n" + res["title"].upper())
for line in res["lines"]:
print(" " + line)
if res["block"]:
print("\n" + res["block"])
COLORS = ["#2a78c6", "#d95f02", "#1b9e77", "#7570b3"]
def chart(title, xs, series, xlabel):
# series: list of (name, values); a plain SVG line chart in mm
w, h, ml, mr, mt, mb = 640, 300, 62, 16, 54, 44
vals = [v for _, vs in series for v in vs]
lo, hi = min(vals + [-0.02]), max(vals + [0.02])
pad = (hi - lo) * 0.1
lo, hi = lo - pad, hi + pad
px = lambda x: ml + (x - xs[0]) * (w - ml - mr) / (xs[-1] - xs[0])
py = lambda v: mt + (hi - v) * (h - mt - mb) / (hi - lo)
out = ['<svg viewBox="0 0 %d %d" role="img" aria-label="%s">'
% (w, h, html.escape(title)),
'<text x="%d" y="20" class="t">%s</text>' % (ml, html.escape(title))]
step = 0.01 if hi - lo < 0.08 else (0.02 if hi - lo < 0.16 else 0.05)
v = int(lo / step) * step
while v <= hi:
if v >= lo:
out.append('<line x1="%d" x2="%d" y1="%.1f" y2="%.1f" class="%s"/>'
% (ml, w - mr, py(v), py(v),
"z" if abs(v) < step / 2 else "g"))
out.append('<text x="%d" y="%.1f" class="l" text-anchor="end">'
'%+.2f</text>' % (ml - 6, py(v) + 4, v + 0.))
v += step
for x in xs:
out.append('<text x="%.1f" y="%d" class="l" text-anchor="middle">%d'
'</text>' % (px(x), h - mb + 16, x))
out.append('<text x="%d" y="%d" class="l" text-anchor="middle">%s (mm)'
'</text>' % ((ml + w - mr) // 2, h - 8, xlabel))
for i, (name, vs) in enumerate(series):
c = COLORS[i % len(COLORS)]
pts = " ".join("%.1f,%.1f" % (px(x), py(v)) for x, v in zip(xs, vs))
out.append('<polyline points="%s" fill="none" stroke="%s" '
'stroke-width="2"/>' % (pts, c))
out += ['<circle cx="%.1f" cy="%.1f" r="3" fill="%s"><title>%s, %d: '
'%+.3f mm</title></circle>'
% (px(x), py(v), c, html.escape(name), x, v)
for x, v in zip(xs, vs)]
out.append('<text x="%d" y="%d" class="l" fill="%s" style="fill:%s">'
'%s</text>' % (ml + i * 70, 40, c, c, html.escape(name)))
out.append("</svg>")
return "\n".join(out)
def report_html(res, path):
if res["mode"] == "verify":
charts = [
chart("bdp fit - proximity: should be a flat line", XS,
[("y=%d" % y, res["series"][y]) for y in res["rows"]], "X"),
chart("bdp fit - Beacon contact: minus the correction", XS,
[("y=%d" % y, res["contact"][y]) for y in res["rows"]], "X")]
else:
charts = [
chart("Error along X, per row: lines should overlap", XS,
[("y=%d" % y, v) for y, v in res["rel"].items()]
+ [("mean", res["xprof"])], "X"),
chart("Error along Y at x=175", YS, [("Y", res["yprof"])], "Y")]
block = res["block"] or res.get("suggested") or ""
page = """<!doctype html>
<html><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Twist %s</title>
<style>
:root{--bg:#fff;--fg:#1c2024;--dim:#5f6b76;--grid:#e3e6e8;--box:#f4f5f6}
@media (prefers-color-scheme:dark){:root{--bg:#16191c;--fg:#e6e8ea;
--dim:#98a2ab;--grid:#2c3136;--box:#212529}}
body{margin:0 auto;max-width:720px;padding:16px;background:var(--bg);
color:var(--fg);font:16px/1.5 system-ui,sans-serif}
.v{padding:12px 16px;border-radius:8px;border-left:6px solid;
background:var(--box);margin:12px 0}
.good{border-color:#1b9e77}.warn{border-color:#e6a100}.bad{border-color:#d62728}
h1{font-size:1.3em;margin:0 0 6px}p{margin:4px 0}svg{width:100%%;margin:12px 0}
.t{font-size:14px;font-weight:600;fill:var(--fg)}
.l{font-size:12px;fill:var(--dim)}.g{stroke:var(--grid)}.z{stroke:var(--dim)}
pre{background:var(--box);padding:12px;overflow-x:auto;font-size:13px}
small{color:var(--dim)}
</style></head><body>
<div class="v %s"><h1>%s</h1>%s</div>
%s
%s
<small>%s, written %s</small>
</body></html>
""" % (res["mode"], res["level"], html.escape(res["title"]),
"".join("<p>%s</p>" % html.escape(s) for s in res["lines"]),
"\n".join(charts),
("<pre>%s</pre>" % html.escape(block)) if block else "",
html.escape(res["file"]),
datetime.datetime.now().strftime("%Y-%m-%d %H:%M"))
with open(path, "w", encoding="utf-8") as f:
f.write(page)
def cleanup(p):
# Never fight a print that has started, and do not raise from here
try:
check_ready(p)
if print_active(p):
log("A print is active: leaving the printer alone.")
return True
homed = p.query("toolhead")["toolhead"]["homed_axes"]
p.gcode("_GUARD_OFF", timeout=120)
if "z" in homed:
p.gcode("G90\nG1 Z10 F600", timeout=120)
p.gcode("M104 S0", timeout=120)
return True
except Exception as e:
log("Could not finish cleanly: %s" % e)
log("Check the printer: the nozzle heater may still be on until "
"Klipper restarts.")
return False
def on_signal(signum, frame):
raise Stopped()
def run(mode, host):
global LOG
os.makedirs(DATA_DIR, exist_ok=True)
LOG = open(os.path.join(DATA_DIR, "twist_run.log"), "a")
p = Printer(host)
stamp = datetime.datetime.now().strftime("%Y%m%d_%H%M")
path = os.path.join(DATA_DIR, "twist_%s_%s.jsonl" % (mode, stamp))
report = path[:-len(".jsonl")] + ".html"
log("=== %s, writing %s" % (mode, path))
failure = None
res = None
started = False
signal.signal(signal.SIGTERM, on_signal)
signal.signal(signal.SIGINT, on_signal)
if hasattr(signal, "SIGHUP"):
# A closed SSH window must not end the run halfway
signal.signal(signal.SIGHUP, signal.SIG_IGN)
try:
preflight(p, mode)
started = True
p.gcode(p.logo("calibrating_z") or "M400")
run_points(p, mode, path)
res = analyse(path, p.query("configfile")["configfile"]["settings"]
.get("axis_twist_compensation"))
except Stopped:
failure = ("Stopped", ["Stopped on request. The result is not used "
"and nothing changed."])
except Problem as e:
failure = ("Twist %s stopped" % mode, [
str(e), "Nothing changed in the configuration. "
"Fix this, then start again with TWIST_CALIBRATE."])
except Exception as e:
# Whatever went wrong, the nozzle must still be lifted and switched off
failure = ("Twist %s stopped" % mode, [
"Unexpected error: %r" % e, "Nothing changed in the configuration."
" See twist_data/twist_run.log."])
signal.signal(signal.SIGTERM, signal.SIG_IGN)
signal.signal(signal.SIGINT, signal.SIG_IGN)
if started:
cleanup(p)
if res:
try:
if res["block"]:
with open(os.path.join(DATA_DIR, "twist_suggested.cfg"),
"w") as f:
f.write(res["block"])
report_html(res, report)
report_console(res)
except Exception as e:
log("Could not write the report: %r" % e)
log(res["title"])
return finish(p, res, failure, os.path.basename(report), started)
def finish(p, res, failure, report_name, started):
# Klipper may be down here; the log and the shell keep the message
try:
if res:
buttons = []
if res.get("retry"):
buttons.append(("Run %s again" % res["retry"],
"_TWIST_CHECKLIST MODE=%s" % res["retry"],
"primary"))
elif res["level"] == "warn" and res["mode"] == "measure":
buttons.append(("Run Verify (after restart)",
"_TWIST_CHECKLIST MODE=verify", "primary"))
p.gcode(p.state(0))
logo = p.logo("error" if res["level"] == "bad" else "ready")
p.gcode(logo or "M400")
p.gcode("M117 %s" % clean(res["title"]))
for line in res["lines"]:
p.say(line)
p.dialog(res["title"], res["lines"] + [
"Report with charts: twist_data/" + report_name], buttons)
else:
title, lines = failure
# Refused at the start: an active run or print keeps its flag,
# status line and logo
if started:
p.gcode(p.state(0))
logo = p.logo("error" if title != "Stopped" else "ready")
p.gcode(logo or "M400")
p.gcode("M117 %s" % clean(title))
p.dialog(title, lines)
except Exception as e:
log("Could not show the result in Mainsail: %s" % e)
if failure:
log(failure[0] + ": " + " ".join(failure[1]))
return 1
return 0 if res["level"] != "bad" else 2
def main():
ap = argparse.ArgumentParser(
description="Measure and verify axis twist compensation (nozzle vs "
"Beacon). Normally started with the macro TWIST_CALIBRATE.")
ap.add_argument("mode", choices=("measure", "verify", "analyse"))
ap.add_argument("file", nargs="?", help="analyse: a saved .jsonl")
ap.add_argument("--host", default="http://localhost:7125",
help="Moonraker (its own port: nginx ends requests after "
"60 s)")
a = ap.parse_args()
if a.mode != "analyse":
return run(a.mode, a.host.rstrip("/"))
if not a.file:
ap.error("analyse needs a file")
current = None
try:
current = Printer(a.host.rstrip("/")).query("configfile")[
"configfile"]["settings"].get("axis_twist_compensation")
except Problem:
print("Printer not reachable: not comparing with the active values")
res = analyse(a.file, current)
report_console(res)
report = os.path.splitext(a.file)[0] + ".html"
report_html(res, report)
print("\nReport:", report)
return 0
if __name__ == "__main__":
sys.exit(main())