# 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/`, `/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_`), 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`.