Files
klipper-macros/README.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

15 KiB
Raw Blame History

klipper-macros

My Klipper macros, the small Klipper modules they need, and helper scripts, from a Voron 2.4 (350) with an AFC Box Turtle (5 lanes), Blobifier, Beacon, Nitehawk-SB toolboard, bd_pressure, bdwidth and an iHeater chamber heater.

Installs with one script and updates through Moonraker's update manager.

Contents

Macros (macros/)

printer.cfg includes only macros/klipper-macros.cfg; that file includes everything below, grouped by topic. Comment out what you do not use there.

File Macros Needs
save_variables.cfg the one [save_variables] for all macros (file bd_pa_variables.cfg in the config folder) —
messages.cfg _ERROR, _WARN: errors and warnings shown in the console and on the display (M117, the status line in Mainsail and KlipperScreen); PAUSE shows AFC's error, RESUME, CANCEL_PRINT and PRINT_WARMUP clear the display —
blobifier/
blobifier.cfg BLOBIFIER, BLOBIFIER_CLEAN, BLOBIFIER_PARK, BLOBIFIER_SHAKE_BUCKET, ...: purge bucket and nozzle brush for AFC (Turtleblobifier, heavily modified) Blobifier hardware, AFC
blobifier_hw.cfg servo and bucket switch pins —
print/
print_start_end.cfg PRINT_WARMUP, PRINT_START, PRINT_END; _FIRST_LAYER_FAULT_DETECTION: AFC buffer fault detection less sensitive during the first layer (needs one line in the slicer's layer change G-code, see the macro) Beacon, AFC, Blobifier, HEAT_SOAK, iHeater, bd_pressure PA macros (bdwidth is no longer enabled while printing)
pause_resume.cfg PAUSE, RESUME, CANCEL_PRINT, M600 (RESUME also handles a running HEAT_SOAK, and after a PAUSE purges 40 mm with BLOBIFIER_CHECKED first: a failed check keeps the print paused, RESUME PURGE=0 skips the purge; CANCEL_PRINT runs the same cleanup as PRINT_END) heating/heat_soak.cfg, leds/, blobifier/, afc/purge_check.cfg
filament.cfg LOAD_FILAMENT, UNLOAD_FILAMENT —
homing.cfg HOME: X/Y, then Z always with Beacon contact (also when already homed); _Z_CHECK: stops the print when Klipper's Z and the Beacon reading differ (run in PRINT_START after the soak) Beacon
nozzle_guard.cfg [bdp_guard], _GUARD_ON PHASE=<name>, _GUARD_OFF: bd_pressure watches the nozzle force during print-start moves where nothing should touch it (QGL, Z homing, mesh); mode: stop shuts Klipper down on a touch (the brush runs log-only), mode: log only reports the peak per phase bdp_guard.py from the bd_pressure repo + its load-check firmware
test_speed.cfg TEST_SPEED: skipped-steps test for speed and acceleration —
idle_timeout.cfg [idle_timeout]: heaters, chamber heater and motors off iHeater macros
heating/
heat_soak.cfg HEAT_SOAK, STOP_HEAT_SOAK, CANCEL_HEAT_SOAK, HEAT_SOAK_RESUME, RESUME —
soak_my_bed.cfg SOAK_MY_BED (homes and levels first) soak-my-bed
bed_fans.cfg Bed fans through SET_HEATER_TEMPERATURE/M190/M140/TURN_OFF_HEATERS overrides; off during a print without a heated chamber (PRINT_WARMUP CHAMBER= 30 or less), on during the cooldown after any print [fan_generic BedFans]
chamber_iheater.cfg iHeater MCU, heater and sensors, M141, M191, iHEATER_ON, iHEATER_OFF iHeater chamber heater
filament_drying.cfg START_DRYING, STOP_DRYING, STATUS_DRYING bed fans, chamber heater (optional)
afc/
xy_safety_check.cfg AFC_XY_SAFETY_CHECK, _AFC_STORE_HOME_REFERENCE, AFC_XY_RESUME: lost-step check around tool changes extras/xy_drift.py (CoreXY)
lane_tools.cfg LANE_FEED_UNTIL_HUB_OPEN, LANE_FEED_ABORT AFC
purge_check.cfg BLOBIFIER_CHECKED: checks every AFC purge with bd_pressure (and optionally bdwidth motion); a bd_pressure that does not answer fails the check, PURGE_CHECK_IGNORE_SENSOR lets the current print finish without it; when the previous filament (saved nozzle_last_temp) needs more than 10°C above the new one, the purge runs at the previous filament's temperature and the nozzle cools back afterwards, so its leftover melts out Blobifier, AFC, bdpressure_check.py from the bd_pressure repo + its load-check firmware, extras/bdwidth_status.py
flex_lanes.cfg Lanes holding TPU/TPE (material from Spoolman) get slower long moves (50 mm/s, AFC's minimum) through the tube; back to the configured speed when the lane holds something else. Polls every 5 s, reapplies after a restart. The last stretch into the extruder (tool_load_speed) stays as configured AFC
purge_until_empty.cfg PURGE_UNTIL_EMPTY: purges a snapped filament out until there is no more nozzle pressure same as purge_check.cfg
pressure_advance/
bd_pressure.cfg [bdpressure bd_pa] (I2C on the Nitehawk) and the vendor macros PA_CALIBRATE, PA_E, PA_RESET, PA_STATE; PA_CALIBRATE no longer sets Z back to a value read before the test (wrong after a Z hop in G28 XY) bdpressure.py from the bd_pressure repo
bd_pa_spoolman.cfg LANE_CALIBRATE_PA, PA_CALIBRATE_ALL_LANES, LANE_RECAL_PA, SET_SPOOL_ID, PA_STATUS, SET_NOZZLE: pressure advance per nozzle and spool, saved on the printer; run SET_NOZZLE SIZE=0.2 after a swap (a print start stops if the slicer profile has another size); each nozzle has its own test flow and PA range (0.4: 25 mm³/s, 0–0.098, about 2 min a lane; 0.2: 5 mm³/s, 0–0.196, about 9 min, not measured yet); before a calibration the lane's spool is assigned again so a temperature just changed in Spoolman is used; flexible materials (TPU/TPE) calibrate at a lower flow (8 mm³/s) and over a wider PA range (0–0.196 in 0.004 steps instead of 0–0.098); a calibration with no result, a pause during the test or too few/stuck sensor readings is rejected and not saved bd_pressure, AFC, Spoolman through AFC
spoolman/
active_spool.cfg SET_ACTIVE_SPOOL, CLEAR_ACTIVE_SPOOL Spoolman in Moonraker
leds/
stealthburner_leds.cfg Stealthburner logo status (_STATUS STATE=...: heating and print progress as a filling logo, paused, error flash from _ERROR, part ready once the bed is cool, dim when idle and nobody is near) and the nozzle light led_effect, neopixel:bt_logo and rainbow_turtle from AFC
sensors/
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 | | bed_scan_check.cfg | BED_SCAN_CHECK [BUMP=0.03] [RANGE=0.30]: levels, scans and warns about bumps, dips or too much height range, without heating or touching the bed. In PRINT_START a failed check pauses before the nozzle heats and moves the toolhead away: clean the plate and Resume, which runs PRINT_START again from QGL with a new scan and check. BED_CHECK_IGNORE, then Resume: the next failed check only warns | extras/mesh_check.py, Beacon, AFC |

Klipper modules (extras/)

File For
xy_drift.py AFC_XY_SAFETY_CHECK: measures lost XY steps from the stepper step counts at the endstop triggers (CoreXY). The toolhead position after homing cannot show lost steps.
bdwidth_status.py exposes bdwidth's motion counter and width to macros (present: False with neutral values when no bdwidth is configured, so the macros also work without it), and keeps a USB dropout of bdwidth (port: usb) from shutting down Klipper: the read is retried every 10 s and the port reopened
bdp_touch.py BDP_TOUCH: lowers the nozzle in one slow continuous move (drip mode, like a homing move) while reading the bd_pressure force as fast as I2C allows (its endstop output is not wired), stops at a force limit (default 60) or 0.5 mm below the start, then lifts back; it must be one quick press, because the sensor re-zeros itself while the force looks steady; reports the height where the force reaches the threshold and the zero-force height from a line fit, and logs the whole curve to klippy.log. _TOUCH_COMPARE: alternates that with Beacon's contact probe. Refuses while the bdp_guard is armed or the sensor is in PA mode. Needs the load-check firmware.
mesh_check.py BED_MESH_CHECK: fits a smooth surface to the loaded mesh and reports the height range and every area further from it than the limit, with its position. Only reads the mesh. Needs numpy (Beacon needs it too).

The bd_pressure load check (bdpressure_check.py: BDP_CHECK_START/STOP/QUERY, pa_points/pa_distinct) and nozzle guard (bdp_guard.py: BDP_GUARD_ARM/DISARM/QUERY) moved to the bd_pressure repo (https://github.com/MangaValk/bd_pressure, folder klipper/, docs in klipper/load_check/README.md). Install that repo with its klipper/install.sh and its own [update_manager bd_pressure] entry; the macros here (purge_check.cfg, nozzle_guard.cfg, bd_pa_spoolman.cfg) still use them.

Scripts (scripts/)

MCU firmware: Klipper on the MCUs is updated with aldis, included as a git submodule in external/aldis (pinned to the release in use; on the Pi run the released program in ~/aldis). Install and use: scripts/README.md. The old Klipper update script is in scripts/archive/; the Katapult script (update_katapult_all_mcus.sh, this printer's CAN UUIDs and serial IDs) is still used for the bootloaders. twist_check.py is the axis twist calibration behind TWIST_CALIBRATE: see scripts/twist_check.md.

Tools (tools/)

effective_config.py builds the config Klipper gets from klipper-macros.cfg (includes expanded, duplicate sections merged) and compares it between git refs, for example python tools/effective_config.py HEAD after a change. CLAUDE.md has the notes for working on this repo with Claude Code.

Install

On the Klipper host:

cd ~ && git clone https://mangavalk.com/mangavalk/klipper-macros.git
~/klipper-macros/install.sh

install.sh:

  • links extras/*.py into ~/klipper/klippy/extras/ (and hides them from Klipper's update manager),
  • links macros/ to ~/printer_data/config/klipper-macros and scripts/ to ~/printer_data/config/klipper-macros-scripts, so the files show up in Mainsail/Fluidd and can be edited there,
  • makes the shell scripts executable,
  • adds this section to moonraker.conf (once, with a backup):
[update_manager klipper-macros]
type: git_repo
path: ~/klipper-macros
origin: https://mangavalk.com/mangavalk/klipper-macros.git
primary_branch: main
managed_services: klipper
install_script: install.sh

Then:

  1. In printer.cfg, after [include mainsail.cfg] and after the AFC includes ([include AFC/*.cfg]):
    [include klipper-macros/klipper-macros.cfg]
    
    bd_pa_spoolman.cfg wraps AFC's SET_SPOOL_ID with rename_existing, which only works when AFC is loaded first; otherwise Klipper stops with Existing command 'SET_SPOOL_ID' not found in gcode_macro rename.
  2. Restart the Klipper service (sudo systemctl restart klipper, or Mainsail → services → klipper → restart). A RESTART or FIRMWARE_RESTART does not load new or changed Python modules.
  3. Restart Moonraker once, so the update manager shows klipper-macros.

Updates then come through Moonraker; it re-runs install.sh and restarts Klipper.

Adapting to another printer

These are the settings of one printer. Before using a file, check:

  • Names: fila_width_0 (bdwidth), bd_pa (bd_pressure), sb_leds, caselight, BedFans, iHeater_H, lane names lane1..lane5.
  • Pins and serial IDs: blobifier/blobifier_hw.cfg (PC1, PC3), sensors/motion_sensor.cfg (PC0), heating/chamber_iheater.cfg (serial ID).
  • Positions: the bed centre X175 Y175 (350 mm bed) in print/homing.cfg and print/print_start_end.cfg. AFC_XY_SAFETY_CHECK uses the axis limits from your config.
  • Settings at the top of a file (variable_...): afc/purge_check.cfg (mode: "enforce", motion_check: False because this printer's bdwidth motion reading is unreliable), pressure_advance/bd_pa_spoolman.cfg (nozzle_test), heating/bed_fans.cfg, heating/filament_drying.cfg.
  • xy_drift.py is for CoreXY only.

Comment out files you do not need in klipper-macros.cfg.

Uninstall

~/klipper-macros/install.sh --uninstall

Then remove the include from printer.cfg and the [update_manager klipper-macros] section from moonraker.conf, and restart the Klipper service.

Credits

Some files started from other projects and were modified here; their original licenses apply to those parts:

File Based on
blobifier/ Turtleblobifier (AFC version of Dendrowen/Blobifier)
leds/stealthburner_leds.cfg tanaes/whopping_Voron_mods (Rainbow Barf logo LEDs)
heating/bed_fans.cfg Ellis' bed fan macros (ellis3dp.com)
heating/heat_soak.cfg community HEAT_SOAK macro
heating/chamber_iheater.cfg iHeater vendor configuration
heating/filament_drying.cfg community filament drying macro
pressure_advance/bd_pressure.cfg bd_pressure klipper/bd_pressure.cfg
print/test_speed.cfg Ellis' TEST_SPEED
print/pause_resume.cfg, print/filament.cfg KlipperScreen recommended macros
external/aldis aldis by mjonuschat, GPL-3.0 (git submodule, unchanged)
scripts/ Voron docs: automating MCU updates, Esoterical's CANBus guide

Uses: Klipper, AFC-Klipper-Add-On, bd_pressure, bdwidth, klipper-led_effect, soak-my-bed, Spoolman.