Skip to content

Commit

Permalink
docs: update docs to katapult transition
Browse files Browse the repository at this point in the history
Signed-off-by: Joshua Schlicker <[email protected]>
  • Loading branch information
docgalaxyblock committed Mar 6, 2024
1 parent 17d1b14 commit a8ae0ee
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 46 deletions.
13 changes: 6 additions & 7 deletions docs/Bootloader_Entry.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ This method also applies to devices operating in
#### Katapult's flashtool.py

```shell
python3 ./katapult/scripts/flashtool.py -i <CAN_IFACE> -u <UUID> -r
python3 ~/katapult/scripts/flashtool.py -i <CAN_IFACE> -u <UUID> -r
```

Where `<CAN_IFACE>` is the can interface to use. If using `can0`, both the `-i`
Expand All @@ -99,13 +99,12 @@ for information on finding the CAN UUID of your devices.

When klipper receives one of the above bootloader requests:

If Katapult (formerly known as CANBoot) is available, klipper will request that
Katapult stay active on the next boot, then reset the MCU (therefore entering
Katapult).
If [Katapult (formerly known as CANBoot)](Bootloaders.md#katapult-bootloader-lpc176x-stm32-rp2040)
is available, klipper will request that Katapult stay active on the next boot,
then reset the MCU (therefore entering Katapult).

If Katapult is not available, klipper will then try to enter a
platform-specific bootloader, such as STM32's DFU
mode([see note](#stm32-dfu-warning)).
If Katapult is not available, klipper will then try to enter a platform-specific
bootloader, such as STM32's DFU mode ([see note](#stm32-dfu-warning)).

In short, Klipper will reboot to Katapult if installed, then a hardware specific
bootloader if available.
Expand Down
79 changes: 40 additions & 39 deletions docs/Bootloaders.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,47 @@ application. This document is not an authoritative reference; it is
intended as a collection of useful information that the Klipper
developers have accumulated.

## AVR micro-controllers
## katapult bootloader (LPC176x, STM32, RP2040)

The [katapult](https://github.com/Arksine/katapult) (formerly known as CANBoot)
bootloader provides an option for uploading Klipper firmware over the CANBUS,
Serial and USB. The bootloader itself is derived from Klipper's source code.
Currently katapult supports the LPC176x, STM32, and RP2040.

It is recommended to use a ST-Link Programmer to flash katapult, however it
should be possible to flash using `stm32flash` on STM32F103 devices, and
`dfu-util` on STM32F042/STM32F072 devices. See the
[STM32](#stm32f103-micro-controllers-blue-pill-devices) sections in this
document for instructions on these flashing methods, substituting `katapult.bin`
for the file name where appropriate. The linked katapult repository provides
instructions for building the bootloader.

The first time katapult has been flashed it should detect that no application
is present and enter the bootloader. If this doesn't occur it is possible to
enter the bootloader by pressing the reset button twice in succession.

The `flash_can.py` utility supplied in the `lib/canboot` folder may be used to
upload Klipper firmware. The device UUID is necessary to flash. If you do not
have a UUID it is possible to query nodes currently running the bootloader:
``` shell
python3 flash_can.py -q
```

This will return UUIDs for all connected nodes not currently assigned a UUID.
This should include all nodes currently in the bootloader.

Once you have a UUID, you may upload firmware with following command:
``` shell
python3 flash_can.py -i can0 -f ../../out/klipper.bin -u aabbccddeeff
```

Where `aabbccddeeff` is replaced by your UUID. Note that the `-i` and `-f`
options may be omitted, they default to `can0` and `../../out/klipper.bin`
respectively.

When building Klipper for use with katapult, select the 8 KiB Bootloader option.

## AVR micro-controllers

In general, the Arduino project is a good reference for bootloaders
and flashing procedures on the 8-bit Atmel Atmega micro-controllers.
Expand Down Expand Up @@ -451,44 +490,6 @@ The bootloader can be activated by pressing the reset button of the board twice.
As soon as the bootloader is activated, the board appears as a USB flash drive
onto which the klipper.bin file can be copied.

### STM32F103/STM32F0x2 with CanBoot bootloader

The [CanBoot](https://github.com/Arksine/CanBoot) bootloader provides an option
for uploading Klipper firmware over the CANBUS. The bootloader itself is
derived from Klipper's source code. Currently CanBoot supports the STM32F103,
STM32F042, and STM32F072 models.

It is recommended to use a ST-Link Programmer to flash CanBoot, however it
should be possible to flash using `stm32flash` on STM32F103 devices, and
`dfu-util` on STM32F042/STM32F072 devices. See the previous sections in this
document for instructions on these flashing methods, substituting `canboot.bin`
for the file name where appropriate. The CanBoot repository linked above provides
instructions for building the bootloader.

The first time CanBoot has been flashed it should detect that no application
is present and enter the bootloader. If this doesn't occur it is possible to
enter the bootloader by pressing the reset button twice in succession.

The `flash_can.py` utility supplied in the `lib/canboot` folder may be used to
upload Klipper firmware. The device UUID is necessary to flash. If you do not
have a UUID it is possible to query nodes currently running the bootloader:
```
python3 flash_can.py -q
```
This will return UUIDs for all connected nodes not currently assigned a UUID.
This should include all nodes currently in the bootloader.

Once you have a UUID, you may upload firmware with following command:
```
python3 flash_can.py -i can0 -f out/klipper.bin -u aabbccddeeff
```

Where `aabbccddeeff` is replaced by your UUID. Note that the `-i` and `-f`
options may be omitted, they default to `can0` and `out/klipper.bin`
respectively.

When building Klipper for use with CanBoot, select the 8 KiB Bootloader option.

## STM32F4 micro-controllers with DFU bootloader

STM32F4 micro-controllers come equipped with a built-in system bootloader
Expand Down

0 comments on commit a8ae0ee

Please sign in to comment.