Files
klipper-macros/CLAUDE.md
T
mangavalkandClaude Opus 5.5 19c70ebeb8 Purge check: stop an infinite spool swap when the check fails
An AFC swap pauses and resumes the file without the PAUSE and RESUME macros
and only stops on AFC's own error state. A failed check called PAUSE, so the
swap went on and restarted the print while the printer counted as paused.

During a swap (file paused, pause_resume not paused) the check now raises an
error at the end of BLOBIFIER_CHECKED, after the temperature and sensor
cleanup. CHANGE_TOOL catches it and pauses through AFC_error. AFC's remap is
skipped, so the message names the SET_MAP command. Other failed checks still
call PAUSE.

Read from AFC 5ea84ea and Klipper 0cee841; render tests only, not yet run on
the printer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 20:58:17 +01:00

7.4 KiB

klipper-macros

Klipper macros, Klipper modules and scripts for one printer, installed on the printer's Raspberry Pi with install.sh and updated through Moonraker. See README.md for the user-facing description.

The printer

Voron 2.4 350, Klipper + Moonraker + Mainsail on a Raspberry Pi 4 (http://mainsailos.local, Moonraker API on port 80). AFC Box Turtle with 5 lanes, Blobifier purge bucket, Beacon (Z homing and probing), Nitehawk-SB toolboard (USB), Leviathan mainboard as USB-CAN bridge, bd_pressure (load-check firmware, branch load-check-extension in D:\Claude\bd_pressure-load-check\bd_pressure), bdwidth (CCD width/motion sensor on USB; switched off: its motion reading stays at 0, its width compensation made the flow jump 77-119% and a USB dropout once shut down Klipper. The macros work with or without [bdwidth fila_width_0]; clogs and breaks are caught by AFC's buffer fault detection, filament_error_sensitivity), iHeater chamber heater.

Working with the printer

  • Read freely through Moonraker: GET /server/files/config/<path>, /server/files/logs/klippy.log, /printer/objects/query?..., /server/gcode_store. The merged config Klipper loaded is in klippy.log after ===== Config file =====.
  • Do not change anything on the printer (upload files, edit config, send G-code, restart services) unless the user asks for that specific action. Prepare files here and let the user upload them.
  • Never run anything that moves the printer or heats while a print may be running; check print_stats.state first.

Repo layout

  • macros/klipper-macros.cfg is the only file printer.cfg includes; it includes everything else. It must be included after [include AFC/*.cfg] (a rename_existing of an AFC command only works if AFC loaded first). 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) 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.

Rules for macro changes

  • Never define the same [gcode_macro X] in two files. Klipper merges sections with the same name and the later file wins completely (this is how heat_soak.cfg's RESUME silently replaced the real RESUME). Include order in klipper-macros.cfg matters for this.
  • RESUME and PAUSE are defined only in print/pause_resume.cfg. AFC renames PAUSE/RESUME at startup and wraps them: PAUSE -> AFC_PAUSE -> PAUSE -> PAUSE_BASE, RESUME -> AFC_RESUME -> RESUME -> HEAT_SOAK_RESUME -> _RESUME_PRINT -> RESUME_BASE. After a PAUSE, _RESUME_PRINT first purges with BLOBIFIER_CHECKED (_RESUME_PURGE); a failed check raises an error, which aborts the whole chain (AFC_RESUME's restore too), so the printer stays paused.
  • A failed bed check in PRINT_START (calibration/bed_scan_check.cfg) pauses with _BED_CHECK_STATE.pending set: PAUSE then only pauses, and RESUME calls _BED_CHECK_RETRY, which sets the print file back to the PRINT_START line (M26) and resumes. Everything after the check belongs in _PRINT_START_FINISH: a pause does not stop a running macro.
  • An AFC infinite spool swap pauses and resumes the file without the PAUSE and RESUME macros and only stops on AFC's own error state, so PAUSE cannot stop it. During a swap print_stats.state is paused with pause_resume.is_paused False; a failed purge check then raises an error (_PURGE_CHECK_SWAP_STOP).
  • Only one [save_variables], in macros/save_variables.cfg.
  • PA values are saved per nozzle and spool (pa_value_0_4_spool_<id>), the fitted size in pa_nozzle (SET_NOZZLE). The slicer's NOZZLE= on PRINT_WARMUP must match, or the print stops. A new size needs an entry in _PA_CFG.nozzle_test.
  • PRINT_END and CANCEL_PRINT share _PRINT_CLEANUP (heaters including iHEATER_OFF, fan, M221 S100, bdwidth off). Anything that must happen at the end of every print goes there. RESTORE_GCODE_STATE restores the flow (M221), so reset flow after it, not before.
  • Do not use G10/G11 in macros: Klipper's G10 retracts only once until a G11, and nothing on this printer sends G11. Use _NOZZLE_RETRACT (remembered in the saved variable nozzle_retract); PRINT_START undoes it over the bucket with _NOZZLE_UNRETRACT.
  • Inside gcode: use ; for comments on G-code lines; # lines are stripped by the config parser. Never put a comment on an M117 line: M117 shows the raw rest of the line, comment included.
  • Errors and warnings go through _ERROR / _WARN (macros/messages.cfg), not action_raise_error / RESPOND TYPE=error, so they also show on the display. action_raise_error aborts while rendering, so an M117 in the same macro would never run. No double quotes in MSG/DISPLAY.
  • Nozzle guard (print/nozzle_guard.cfg, extras/bdp_guard.py): wrap only moves where nothing may touch the nozzle in _GUARD_ON PHASE=x / _GUARD_OFF. Never leave it on across contact homing, extrusion, purges, the Blobifier park or AFC cuts and loads: in mode: stop that is an instant shutdown.
  • After a refactor run python tools/effective_config.py HEAD and check that only the intended sections changed.
  • Render-test macros with Jinja2 using Klipper's delimiters (jinja2.Environment('{%', '%}', '{', '}')) and mocked printer objects.

Rules for the Python modules (extras/)

  • Klipper only loads changed .py files when the Klipper service restarts (sudo systemctl restart klipper); RESTART and FIRMWARE_RESTART keep the old code in memory.
  • Event handlers must never raise: an exception in a handler shuts Klipper down. Example: Beacon sends homing:home_rails_end with rails=[] and a homing state whose get_trigger_position raises.
  • Keep them read-only wrappers where possible (look up the other module's object, do not patch third-party files).

Reference values

  • Purge check (150 mm Blobifier purge): good load = longest pressure 13-18 s, peak 64-246 (ASA at 250-260C peaks highest); empty nozzle about 30 ms. A real failed load in a print start (AFC reported the lane loaded, nothing reached the nozzle): longest 1915 ms, peak 45, caught by the 5000 ms limit.
  • Nozzle guard (bdp_guard): peaks 1-8 in home_xy, QGL, Z homing, mesh and the Z check; the brush scrub 47 (4 reads above 30 in a row, so it runs in log mode); a light finger push on the cold nozzle gives 41 (threshold 30).
  • Z check after a contact homing: Beacon vs Klipper Z about 0.06 mm.
  • Bed check (mesh_check, limits 0.03 and 0.30 mm): clean plate, worst deviation 0.016 mm cold and on a hot PLA print, range 0.12-0.17. Residue on the plate: 0.06-0.09 mm with the mesh ending at its edge, 0.30 mm with the mesh over it.
  • XY drift check: endstop noise about 0.01-0.02 mm; limit 0.1 mm (one motor skipping one cycle = 0.4 mm shows as 0.2 mm in X and Y).

Git

  • LF line endings everywhere (.gitattributes); the files run on Linux.
  • Commit only when the user says so; never push without asking. Remote: https://mangavalk.com/mangavalk/klipper-macros.git.