# 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](https://docs.vorondesign.com/community/howto/drachenkatze/automating_klipper_mcu_updates.html)
and [Esoterical's CANBus guide](https://canbus.esoterical.online/).

Run them on the Klipper host, between prints:

```bash
~/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

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:

   ```bash
   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.