✨ Katapult bootloader entry (M997) and upload - #28535
Open
thisiskeithb wants to merge 3 commits into
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add opt-in Katapult support for STM32: bootloader entry from
M997, plus a PlatformIO upload target that flashes through Katapult from VSCode orpio run -t upload.Katapult is the standard bootloader in the Klipper ecosystem, and several boards Marlin supports ship with it or have vendor instructions to install it (BTT Manta and Octopus, LDO Leviathan). Marlin already honors its flash offset through the
board_build.offsetenvs, but getting into the bootloader still takes a BOOT/RESET press, and boards without an SD socket have no card flashing to fall back on.M997With
BOOTLOADER_KATAPULTdefined, the STM32 HAL'sflashFirmware()requests the bootloader the way Klipper'sarmcm_reset.cdoes: check Katapult's"CanBoot!"signature, stored 8 bytes before its reset handler and located through the vector table atFLASH_BASE, write the request key0x5984E3FA6CA1589Bto the 8 bytes at the bootloader's initial stack pointer, then reset. Katapult sees the key and stays resident, so firmware can be flashed with no button presses. On Cortex-M7 the write is followed bySCB_CleanDCache_by_Addr()so it lands in SRAM before the reset.If the signature check fails, because no bootloader is installed or something else lives at
FLASH_BASE,M997falls back tohal.reboot(), so the define is harmless on a bare board.Boards opt in per env with
-DBOOTLOADER_KATAPULTon the env whoseboard_build.offsetmatches the installed Katapult's offset, andbuild_unflagsit inno_bootloadervariants. Any stock Katapult build works.Upload
buildroot/share/scripts/katapult_upload.pyregisters an upload callback, same pattern as the_xferenvs'upload.py:1d50:6177) is already enumerated, from a first install or an interrupted flash, flash it directly.M997, and wait for the board to come back as Katapult.flashtool.pyto upload and SHA-verify, after which Katapult jumps to the new firmware.flashtool.pyis downloaded once from a pinned Katapult commit, SHA-256 verified (Katapult is GPLv3 like Marlin), and cached under.pio/. SetKATAPULT_FLASHTOOLto use a local checkout instead.Three envs are included for the boards most often shipped with Katapult, each keeping its parent's existing
board_build.offset:STM32F446ZE_btt_katapult0x8000STM32F429ZG_btt_katapult0x8000STM32H723ZE_btt_katapult0x20000Other boards need the same three lines:
-DBOOTLOADER_KATAPULT, thepre:script, andupload_protocol = custom.Notes
flashtool.pyimportstermios/fcntl, so uploads need POSIX (Linux / macOS / WSL). The script errors out early on native Windows.-DD_CACHE_DISABLED, soSCB_CleanDCache_by_Addr()is a no-op there. It's in for anyone running with the cache on.Tested on a handful of boards with stock Katapult at 0x0 and Marlin at 0x8000:
STM32F446ZE_btt_katapultSTM32F446ZE_btt_katapultSTM32F429ZG_btt_katapultSTM32H723ZE_btt_katapultOn the four Octopus boards with Katapult built for a matching offset (32KiB on F4, 128KiB on H7) and USB on PA11/PA12:
M997over USB CDC drops the board from0483:5740to Katapult's1d50:6177in ~0.3s on every board, no button presses.pio run -t uploadwith the board already in Katapult flashes and SHA-verifies in ~6-11s.pio run -t uploadwith Marlin running does theM997handshake and completes in ~7-9s. Katapult reportsApplication Start: 0x8008000on F4 and0x8020000on H7, matching each env'sboard_build.offset.M115with the timestamp of the build just flashed.Tip
The crystal differs per board (12MHz on F446, 8MHz on F429, 25MHz on H723), so Katapult has to be configured to match.
For anyone testing over SWD: Marlin uses PA13/PA14 (SWDIO/SWCLK) for
LED_PINandE3_DIR_PINon the Octopus family, so an ST-Link has to connect under reset once firmware is running.Requirements
An STM32 board with Katapult installed at an offset matching the env's
board_build.offset.Benefits
Reflash a Katapult board over USB without opening the case to press BOOT / RESET.
Configurations
Stock configs with two changes, built against
env:STM32F446ZE_btt_katapult(swap the board for the other two envs):Bootloader Backups
These exist elsewhere, but I dumped BTT's stock SD card bootloaders just in case:
Related Issues