klipper-macros/scripts/README.md

MCU firmware update scripts

Script	Does
update_all_mcus.sh	Pulls Klipper, builds and flashes Klipper to every MCU, prints a summary, restarts Klipper
update_katapult_all_mcus.sh	Builds and flashes Katapult (the bootloader) to every MCU

Based on the Voron guide to automating MCU updates and Esoterical's CANBus guide.

Run them on the Klipper host, between prints:

~/klipper-macros/scripts/update_all_mcus.sh

They stop Klipper while flashing (and need sudo for that).

These scripts are for one printer

They contain the original printer's boards, build configs, CAN UUIDs and serial IDs:

Board	Name in the script	Connection	Build config (KCONFIG_CONFIG=)
LDO Leviathan (CAN bridge)	Main MCU	CAN 5a2b9f704f54	leviathan
BoxTurtle MC (Pi Pico)	MC_1 (BoxTurtle)	CAN acc4091027b4	BoxTurtleMC
BTT EBB42	EBB42	CAN 4b5324a91849	EBB42
AFC-Lite (Box Turtle)	Turtle_1	CAN 59a2feeada77	Turtle_1
LDO Nitehawk-SB	NHK	USB usb-Klipper_stm32g0b1xx_550039000A50315058393320-if00	nhk
iHeater	iHeater	USB usb-Klipper_stm32f042x6_0C0020000E43304754393320-if00	iHeater

Running them unchanged on another printer will not work, and flashing the wrong firmware to a board can leave it unusable until it is reflashed by hand.

Adapting them to your printer

install.sh links this folder into the config folder as klipper-macros-scripts/, so you can edit the scripts in Mainsail/Fluidd. Edits change files in the git repo: Moonraker then shows the repo as modified ("dirty") and will not update it until you commit or discard them (git -C ~/klipper-macros stash before updating, stash pop after).

1. Make one build config per board. In ~/klipper (and in ~/katapult for the Katapult script), run make menuconfig KCONFIG_CONFIG=<name> for each board, with the settings from your board's documentation. The file <name> is saved in that folder and the script uses it to build.

2. Find your IDs.

   • CAN boards: ~/katapult/scripts/flashtool.py -i can0 -q, or the canbus_uuid values in printer.cfg.
   • USB boards: ls /dev/serial/by-id/, or the serial: values in printer.cfg.

3. Edit the flash blocks. Each board has one block like this:

   printf "Update EBB42 firmware\n"
   make clean
   make clean KCONFIG_CONFIG=EBB42
   make KCONFIG_CONFIG=EBB42
   flash_device "EBB42" python3 ~/katapult/scripts/flashtool.py -i can0 -f ~/klipper/out/klipper.bin -u 4b5324a91849
   

   For each of your boards, set the name, the KCONFIG_CONFIG and the flash command:

   • CAN board via Katapult: ... flashtool.py -i can0 -f <bin> -u <uuid>
   • USB board via Katapult: ... flashtool.py -f <bin> -d /dev/serial/by-id/<id>
   • USB board via Klipper's own flashing: make flash KCONFIG_CONFIG=<name> FLASH_DEVICE=/dev/serial/by-id/<id>

   Delete the blocks of boards you do not have.

4. Keep the CAN bridge last. If your mainboard is a USB-to-CAN bridge, flash it after all CAN boards: while it reboots, the CAN bus is gone.

5. Update the names in print_summary. The list for name in "Main MCU" "MC_1 (BoxTurtle)" ... must contain the same names as your flash_device calls, otherwise they show as SKIPPED.

6. Katapult script: Katapult can only replace itself if you build it as a deployment application ("Build Katapult deployment application" in make menuconfig); a normal Katapult build flashed through Katapult overwrites the application slot instead. Check the Katapult docs for your board before using that script, and keep a way to flash over USB/DFU.

The CAN_DEVICES / CAN_DEVICE_ORDER lists at the top of the scripts are not used by the flashing itself; they only document the UUIDs.

Known differences between the two scripts

update_katapult_all_mcus.sh ends after the last board: it does not print the summary and does not start Klipper again. Run sudo systemctl start klipper afterwards, or add the last lines of update_all_mcus.sh (print_summary and the restart) to it.