# arksine/katapult architecture

> Architecture diagram of the GitHub repository arksine/katapult, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arksine/katapult
- Repository: https://github.com/arksine/katapult

## Overview

Katapult is an ARM Cortex-M bootloader for installing firmware on LPC176x, STM32, and RP2040 devices over CAN, USB, or UART. The main workflow is a host operator selecting a target and firmware image, optionally requesting bootloader entry, then transferring an image for programming into flash. The device boot path initializes its platform and scheduler, exposes the bootloader protocol, and handles flash operations. The README documents host-tool capabilities; internal protocol wiring is represented at subsystem level where sampled source does not establish individual calls.

Main entry points: [`scripts/flashtool.py`](https://github.com/arksine/katapult/blob/master/scripts/flashtool.py) (Flash tool), [`src/flashcmd.c`](https://github.com/arksine/katapult/blob/master/src/flashcmd.c) (Flash commands), [`src/generic/canserial.c`](https://github.com/arksine/katapult/blob/master/src/generic/canserial.c) (CAN transport), [`src/sched.c`](https://github.com/arksine/katapult/blob/master/src/sched.c) (Scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host flashing"]
  node_flashtool["Flash tool<br/>[flashtool.py]"]
  node_flashcan["CAN flash helper<br/>[flash_can.py]"]
end

subgraph group_protocol["Bootloader protocol"]
  node_deployer["Deployer<br/>[deployer.c]"]
  node_command["Command handler<br/>[command.c]"]
  node_flashcmd["Flash commands<br/>[flashcmd.c]"]
end

subgraph group_runtime["Device runtime"]
  node_bootentry["Boot entry<br/>[bootentry.c]"]
  node_scheduler["Scheduler<br/>[sched.c]"]
  node_canserial["CAN transport<br/>[canserial.c]"]
  node_usbcdc["USB transport<br/>[usb_cdc.c]"]
  node_serialirq["UART transport<br/>[serial_irq.c]"]
end

subgraph group_platform["Platform hardware"]
  node_canbus["CAN bus<br/>[canbus.c]"]
  node_lpcmain["LPC startup<br/>[main.c]"]
  node_stm32main["STM32 startup<br/>[stm32f0.c]"]
  node_rpmain["RP2040 startup<br/>[main.c]"]
  node_lpcflash["LPC flash<br/>[flash.c]"]
  node_stmflash["STM32 flash<br/>[flash.c]"]
  node_rpflash["RP flash<br/>[flash.c]"]
  node_rpboot["RP boot ROM<br/>[bootrom.c]"]
end

node_operator(("Operator"))
node_firmware["Firmware image"]

node_operator -->|"selects target"| node_flashtool
node_operator -->|"provides image"| node_firmware
node_flashtool -->|"reads"| node_firmware
node_flashtool -->|"requests entry or upload"| node_command
node_flashtool -->|"communicates over CAN"| node_canserial
node_flashtool -->|"communicates over USB"| node_usbcdc
node_flashtool -->|"communicates over UART"| node_serialirq
node_flashcan -.->|"flashes CAN devices"| node_canserial
node_bootentry -->|"starts runtime"| node_scheduler
node_lpcmain -->|"starts"| node_scheduler
node_rpmain -->|"starts"| node_scheduler
node_command -->|"dispatches commands"| node_flashcmd
node_flashcmd -.->|"programs flash"| node_lpcflash
node_flashcmd -.->|"programs flash"| node_stmflash
node_flashcmd -.->|"programs flash"| node_rpflash
node_deployer -.->|"uses flash commands"| node_flashcmd
node_canserial -->|"uses bus"| node_canbus
node_rpflash -->|"uses boot ROM"| node_rpboot

click node_flashtool "https://github.com/arksine/katapult/blob/master/scripts/flashtool.py"
click node_flashcan "https://github.com/arksine/katapult/blob/master/scripts/flash_can.py"
click node_deployer "https://github.com/arksine/katapult/blob/master/src/deployer.c"
click node_command "https://github.com/arksine/katapult/blob/master/src/command.c"
click node_flashcmd "https://github.com/arksine/katapult/blob/master/src/flashcmd.c"
click node_bootentry "https://github.com/arksine/katapult/blob/master/src/bootentry.c"
click node_scheduler "https://github.com/arksine/katapult/blob/master/src/sched.c"
click node_canserial "https://github.com/arksine/katapult/blob/master/src/generic/canserial.c"
click node_usbcdc "https://github.com/arksine/katapult/blob/master/src/generic/usb_cdc.c"
click node_serialirq "https://github.com/arksine/katapult/blob/master/src/generic/serial_irq.c"
click node_canbus "https://github.com/arksine/katapult/blob/master/src/generic/canbus.c"
click node_lpcmain "https://github.com/arksine/katapult/blob/master/src/lpc176x/main.c"
click node_stm32main "https://github.com/arksine/katapult/blob/master/src/stm32/stm32f0.c"
click node_rpmain "https://github.com/arksine/katapult/blob/master/src/rp2040/main.c"
click node_lpcflash "https://github.com/arksine/katapult/blob/master/src/lpc176x/flash.c"
click node_stmflash "https://github.com/arksine/katapult/blob/master/src/stm32/flash.c"
click node_rpflash "https://github.com/arksine/katapult/blob/master/src/rp2040/flash.c"
click node_rpboot "https://github.com/arksine/katapult/blob/master/src/rp2040/bootrom.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flashtool,node_flashcan toneBlue
class node_deployer,node_command,node_flashcmd toneAmber
class node_bootentry,node_scheduler,node_canserial,node_usbcdc,node_serialirq toneMint
class node_canbus,node_lpcmain,node_stm32main,node_rpmain,node_lpcflash,node_stmflash,node_rpflash,node_rpboot toneRose
class node_operator,node_firmware toneIndigo
```

## Components

### Host flashing

- [Flash tool](https://github.com/arksine/katapult/blob/master/scripts/flashtool.py): `scripts/flashtool.py`
- [CAN flash helper](https://github.com/arksine/katapult/blob/master/scripts/flash_can.py): `scripts/flash_can.py`

### Bootloader protocol

- [Deployer](https://github.com/arksine/katapult/blob/master/src/deployer.c): `src/deployer.c`
- [Command handler](https://github.com/arksine/katapult/blob/master/src/command.c): `src/command.c`
- [Flash commands](https://github.com/arksine/katapult/blob/master/src/flashcmd.c): `src/flashcmd.c`

### Device runtime

- [Boot entry](https://github.com/arksine/katapult/blob/master/src/bootentry.c): `src/bootentry.c`
- [Scheduler](https://github.com/arksine/katapult/blob/master/src/sched.c): `src/sched.c`
- [CAN transport](https://github.com/arksine/katapult/blob/master/src/generic/canserial.c): `src/generic/canserial.c`
- [USB transport](https://github.com/arksine/katapult/blob/master/src/generic/usb_cdc.c): `src/generic/usb_cdc.c`
- [UART transport](https://github.com/arksine/katapult/blob/master/src/generic/serial_irq.c): `src/generic/serial_irq.c`

### Platform hardware

- [CAN bus](https://github.com/arksine/katapult/blob/master/src/generic/canbus.c): `src/generic/canbus.c`
- [LPC startup](https://github.com/arksine/katapult/blob/master/src/lpc176x/main.c): `src/lpc176x/main.c`
- [STM32 startup](https://github.com/arksine/katapult/blob/master/src/stm32/stm32f0.c): `src/stm32/stm32f0.c`
- [RP2040 startup](https://github.com/arksine/katapult/blob/master/src/rp2040/main.c): `src/rp2040/main.c`
- [LPC flash](https://github.com/arksine/katapult/blob/master/src/lpc176x/flash.c): `src/lpc176x/flash.c`
- [STM32 flash](https://github.com/arksine/katapult/blob/master/src/stm32/flash.c): `src/stm32/flash.c`
- [RP flash](https://github.com/arksine/katapult/blob/master/src/rp2040/flash.c): `src/rp2040/flash.c`
- [RP boot ROM](https://github.com/arksine/katapult/blob/master/src/rp2040/bootrom.c): `src/rp2040/bootrom.c`

### Other components

- **Operator**
- **Firmware image**

## Connections

- Operator → Flash tool: selects target
- Operator → Firmware image: provides image
- Flash tool → Firmware image: reads
- Flash tool → Command handler: requests entry or upload
- Flash tool → CAN transport: communicates over CAN
- Flash tool → USB transport: communicates over USB
- Flash tool → UART transport: communicates over UART
- CAN flash helper → CAN transport: flashes CAN devices
- Boot entry → Scheduler: starts runtime
- LPC startup → Scheduler: starts
- RP2040 startup → Scheduler: starts
- Command handler → Flash commands: dispatches commands
- Flash commands → LPC flash: programs flash
- Flash commands → STM32 flash: programs flash
- Flash commands → RP flash: programs flash
- Deployer → Flash commands: uses flash commands
- CAN transport → CAN bus: uses bus
- RP flash → RP boot ROM: uses boot ROM