Files
klipper-macros/scripts/README.md
T

156 lines
6.9 KiB
Markdown
Raw Normal View History

# Scripts
`twist_check.py` is the axis twist calibration: start it with the macro
`TWIST_CALIBRATE` in Mainsail, and see [twist_check.md](twist_check.md) for how
to use it. The rest of this page is about MCU firmware updates.
# MCU firmware updates: aldis
Klipper firmware on the MCUs is updated with
[aldis](https://github.com/mjonuschat/aldis) (GPL-3.0). It finds every MCU in
the running Klipper/Moonraker setup, compares its firmware with the Klipper
checkout in `~/klipper`, and builds and flashes only the ones that are out of
date, using the build config each MCU reports itself. It stops Klipper only
for the flash, and shows its plan first. It also updates Beacon's firmware.
Its source is included as a git submodule in `external/aldis`, pinned to the
release in use (v0.4.0). On the Pi you run the released program instead,
installed in `~/aldis`; the submodule stays empty there (Moonraker does not
fetch submodules), which is fine. To get the source on a PC:
`git submodule update --init`.
## Install (once, on the Pi)
```bash
mkdir -p ~/aldis && curl -fL "https://github.com/mjonuschat/aldis/releases/latest/download/aldis-$(uname -m)-linux.tar.xz" | tar xJ -C ~/aldis --strip-components=1 && chmod +x ~/aldis/aldis
```
```bash
sudo ~/aldis/aldis setup
```
`setup` installs udev rules for the USB bootloaders and a narrow sudo rule so
aldis can stop and start Klipper. `sudo ~/aldis/aldis setup --check` verifies
them. Optional: `sudo ~/aldis/aldis setup --agent` runs it as a service that
the web UI can manage (restart Moonraker once afterwards).
## Use (between prints only)
```bash
~/aldis/aldis status
```
```bash
~/aldis/aldis update
```
- `status`: which MCUs it found and whether their firmware is current (reads only).
- `update`: builds and flashes the outdated MCUs, asking per MCU.
`update --pull` also pulls Klipper first; `update <mcu>` limits it.
- `self-update`: installs a newer aldis release (`--check` only reports).
Notes for this printer (checked 2026-11-07):
- All Klipper MCUs (`mcu` Leviathan, `Turtle_1`, `MC_1`, `EBB42`, `nhk`,
`iHeater`) run `v0.13.0-777`, and Beacon 2.1.0; all report `mcu_kconfig`,
which aldis needs (Klipper `v0.13.0-753` or newer).
- Every board has Katapult (CAN or USB), which aldis supports.
- Flashing the Leviathan (USB-CAN bridge) resets the CAN bus.
- aldis writes each MCU's build config to `~/klipper/.config`. The named build
configs used by the old script (`leviathan`, `EBB42`, ...) are not touched.
- Not covered: the bd_pressure sensor (not a Klipper MCU; it has its own
`stm32flash` procedure in the bd_pressure repo) and Katapult itself (see below).
# Old scripts
| Script | Does |
|---|---|
| `archive/update_all_mcus.sh` | **Archived 2026-11-07, replaced by aldis.** 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. Still in use: aldis does not update bootloaders |
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_katapult_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:
```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 `archive/update_all_mcus.sh`
(`print_summary` and the restart) to it.