Files
klipper-macros/CLAUDE.md
T
mangavalkandClaude Opus 5.5 bcb1a53b2a MCU firmware: aldis as a submodule, old Klipper update script archived
aldis (https://github.com/mjonuschat/aldis, GPL-3.0) replaces
scripts/update_all_mcus.sh: it discovers the MCUs from Moonraker and builds
and flashes only outdated ones with the Kconfig each MCU reports. Its source
is a submodule in external/aldis pinned to v0.4.0, the release installed on
the Pi in ~/aldis (Moonraker does not fetch submodules, so it stays empty
there). The old script moves to scripts/archive/; the Katapult script stays,
aldis does not update bootloaders. scripts/README.md: install, setup, use
and the checks for this printer (all MCUs report mcu_kconfig, all use
Katapult). README and CLAUDE.md point to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 22:37:45 +01:00

7.7 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; bdpressure.py, bdpressure_check.py and bdp_guard.py come from the fork https://github.com/MangaValk/bd_pressure, local clone D:\Claude\bd_pressure, branch main, installed on the Pi in ~/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/.
  • MCU firmware: aldis (external/aldis, git submodule pinned to the release in use, v0.4.0; the Pi runs the released binary in ~/aldis). Bump the submodule when the Pi's aldis is updated.
  • scripts/ Katapult update script (printer-specific IDs), the archived Klipper update script in scripts/archive/, 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, bdp_guard.py in the bd_pressure repo): 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.