klipper-macros/README.md

# 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/`, included through `klipper-macros.cfg`)

| File | Macros | Needs |
|---|---|---|
| `macros.cfg` | `PRINT_WARMUP`, `PRINT_START`, `PRINT_END`, `SOAK_MY_BED`, `[idle_timeout]` | Beacon, AFC, Blobifier, `HEAT_SOAK`, iHeater, bdwidth, bd_pressure PA macros, soak-my-bed |
| `afc_macros.cfg` | `AFC_XY_SAFETY_CHECK`, `_AFC_STORE_HOME_REFERENCE`, `AFC_XY_RESUME`, `LANE_FEED_UNTIL_HUB_OPEN`, `LANE_FEED_ABORT`, `HOME`, `SET_ACTIVE_SPOOL`, `CLEAR_ACTIVE_SPOOL` | AFC, `extras/xy_drift.py` (CoreXY) |
| `purge_check.cfg` | `BLOBIFIER_CHECKED`: checks every AFC purge with bd_pressure (and optionally bdwidth motion) | Blobifier, AFC, `extras/bdpressure_check.py` + bd_pressure load-check firmware, `extras/bdwidth_status.py` |
| `purge_until_empty.cfg` | `PURGE_UNTIL_EMPTY`: purges a snapped filament out until there is no more nozzle pressure | same as `purge_check.cfg` |
| `bd_pa_afc_spoolman.cfg` + `bd_pa_*.sh` | `LANE_CALIBRATE_PA`, `PA_CALIBRATE_ALL_LANES`, `LANE_RECAL_PA`, `SET_SPOOL_ID`, `PA_STATUS`: pressure advance per lane/spool with bd_pressure, cached locally and in Spoolman | bd_pressure, AFC, Spoolman, `gcode_shell_command` |
| `motion.cfg` | PIR motion sensor (`[gcode_button am312]`) switching the case light | motion sensor on a pin, `[output_pin caselight]` |
| `drying.cfg` | `START_DRYING`, `STOP_DRYING`, `STATUS_DRYING`: dry filament on the heated bed | bed fans macros, chamber heater (optional) |
| `bedfans.cfg` | Bed fan control through `SET_HEATER_TEMPERATURE`/`M190`/`M140` overrides | `[fan_generic BedFans]` |
| `heatsoak.cfg` | `HEAT_SOAK`, `STOP_HEAT_SOAK`, `CANCEL_HEAT_SOAK`, `HEAT_SOAK_RESUME`, `RESUME` | — |
| `iHeater.cfg` | iHeater MCU, heater, sensors, `M141`, `M191`, `iHEATER_ON`, `iHEATER_OFF` | iHeater chamber heater |
| `stealthburner_led_effects_barf.cfg` | Stealthburner LED status macros (`_status_*`) | `led_effect`, `[neopixel sb_leds]` |
| `macros_klipperscreen.cfg` | `PAUSE`, `RESUME`, `CANCEL_PRINT`, `LOAD_FILAMENT`, `UNLOAD_FILAMENT`, `M600` | — |

### 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 |
| `bdpressure_check.py` | bd_pressure load check (`BDP_CHECK_START/STOP/QUERY`). Needs the load-check firmware from the bd_pressure `load-check-extension` branch; on stock firmware it reports "not available" and does nothing. |

### Scripts (`scripts/`)

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.

## Install

On the Klipper host:

```bash
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`, so the files show
  up in Mainsail/Fluidd under `klipper-macros/`,
- makes the shell scripts executable,
- adds this section to `moonraker.conf` (once, with a backup):

```ini
[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]`:
   ```ini
   [include klipper-macros/klipper-macros.cfg]
   ```
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.

### Switching from copies in the config folder

If these macros already exist as files in your config folder (as on the
original printer: `Macros/*.cfg` and `bd_pa_afc_spoolman.cfg`), remove those
includes when adding `klipper-macros.cfg`, otherwise the macros are defined
twice and the old copy may win:

- remove `[include bd_pa_afc_spoolman.cfg]` from `printer.cfg`,
- replace `[include ./Macros/macros.cfg]` with
  `[include klipper-macros/klipper-macros.cfg]`,
- keep including what is not in this repo yourself, for example
  `[include Macros/timelapse.cfg]` and `[include Macros/TEST_SPEED.cfg]`.

`bd_pa_variables.cfg` (saved PA values) stays where it is, in the config
folder; it is data, not part of the repo.

## 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:** `motion.cfg` (`PC0`), `iHeater.cfg` (serial ID).
- **Positions:** the bed centre `X175 Y175` (350 mm bed) in `HOME`
  (`afc_macros.cfg`) and in `PRINT_WARMUP`/`PRINT_START` (`macros.cfg`).
  `AFC_XY_SAFETY_CHECK` uses the axis limits from your config.
- **Settings at the top of a file** (`variable_...`): `purge_check.cfg`
  (`mode: "enforce"`, `motion_check: False` because this printer's bdwidth
  motion reading is unreliable), `bd_pa_afc_spoolman.cfg` (`spoolman_url`),
  `bedfans.cfg`, `drying.cfg`.
- `xy_drift.py` is for CoreXY only.

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

## Uninstall

```bash
~/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 |
|---|---|
| `stealthburner_led_effects_barf.cfg` | [tanaes/whopping_Voron_mods](https://github.com/tanaes/whopping_Voron_mods) (Rainbow Barf logo LEDs) |
| `bedfans.cfg` | Ellis' bed fan macros ([ellis3dp.com](https://ellis3dp.com/Print-Tuning-Guide/)) |
| `heatsoak.cfg` | community `HEAT_SOAK` macro |
| `iHeater.cfg` | iHeater vendor configuration |
| `drying.cfg` | community filament drying macro |
| `macros_klipperscreen.cfg` | [KlipperScreen recommended macros](https://klipperscreen.readthedocs.io/en/latest/macros/#recommended) |
| `scripts/` | [Voron docs: automating MCU updates](https://docs.vorondesign.com/community/howto/drachenkatze/automating_klipper_mcu_updates.html), [Esoterical's CANBus guide](https://canbus.esoterical.online/) |

Uses: [Klipper](https://github.com/Klipper3d/klipper),
[AFC-Klipper-Add-On](https://github.com/ArmoredTurtle/AFC-Klipper-Add-On),
[Blobifier](https://github.com/Dendrowen/Blobifier),
[bd_pressure](https://github.com/markniu/bd_pressure),
[bdwidth](https://github.com/markniu/bdwidth),
[klipper-led_effect](https://github.com/julianschill/klipper-led_effect),
[soak-my-bed](https://github.com/marcofailli/soak-my-bed),
[Spoolman](https://github.com/Donkie/Spoolman).