# stmicroelectronics/stm32-mw-openbl architecture

> Architecture diagram of the GitHub repository stmicroelectronics/stm32-mw-openbl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stmicroelectronics/stm32-mw-openbl
- Repository: https://github.com/stmicroelectronics/stm32-mw-openbl

## Overview

##### Project type and purpose
- This is a middleware MCU component providing an In-Application Bootloader for STM32 microcontrollers (“Open Bootloader”).
- It implements the same protocol and command set as the STM32 system bootloader, exposing interfaces (USART, I2C, SPI, USB-DFU, FDCAN…) to a host tool (e.g., STM32CubeProgrammer).
- It is not a full-stack app but firmware middleware, intended to be compiled into Flash on a Cortex-M device’s non-secure domain.

##### File structure
- Top-level:
- Core/ – bootloader core logic (dispatch, protocol engine)
- Interfaces/Patterns/ – reference implementations for each hardware interface
- Interfaces/Templates/ – stub templates for user customization
- Modules/ – command handlers for each protocol, mapping commands to memory operations
- _htmresc, docs, CI, licensing, and project metadata
- Config files in Interfaces/Patterns (interfaces_conf.h, openbootloader_conf.h) define which interfaces and commands are enabled.
- The Core calls into Modules to execute high-level commands and uses HAL/LL drivers for low-level peripheral initialization.

##### Key README insights
- The bootloader lives in non-secure Flash/SRAM, is driven by the Core, and relies on STM32Cube HAL/LL.
- It services a Host over multiple comms, performing memory operations (read, write, erase, jump…).
- Customization points: location in Flash, enabled interfaces, supported commands, Templates for board-specific code.

a. Components
1. Host Tool (STM32CubeProgrammer or custom PC utility)
2. Physical Interfaces (USART, I2C, SPI, USB-DFU, FDCAN)
3. Interface Layer
– Patterns (concrete drivers)
– Templates (user-supplied overrides)
– Configuration (interfaces_conf.h, platform.h)
4. Bootloader Core
– Protocol parser
– Command dispatcher
5. Modules
– openbl_xxx_cmd.c / .h for each interface
– Implements each bootloader command (GetVersion, ReadMemory, FlashErase, etc.)
6. HAL/LL Drivers
– Clock init, GPIO, DMA, SysTick, IWDG
7. Memory Resources
– Internal Flash, SRAM, OTP, Option Bytes, External memory if configured
b. Relationships & interactions
- Host Tool → (over chosen interface) → Interface Layer
- Interface Layer → Bootloader Core (incoming frames)
- Bootloader Core → Module (execute command logic)
- Module → HAL/LL → Memory (perform read/write/erase)
- Bootloader Core → Interface Layer → Host (send responses)
c. Architectural patterns & principles
- Layered design: Interface abstraction, Core logic, Modules, HAL drivers
- Plugin-style Interfaces/Templates: user can swap in board-specific code
- Command dispatch pattern: central dispatcher calls per-command handlers
d. Key technologies & libraries
- STM32Cube HAL/LL (injected at compile time)
- C language, Makefile/CMake integration in STM32Cube Packages
- Communication protocols: AN3155 (USART), AN4221 (I2C), AN3156 (USB-DFU), AN5405 (FDCAN), AN4286 (SPI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Host
    Host["Host Tool"]:::external

    %% Cortex-M Device
    subgraph "Cortex-M Device (Non-Secure Domain)"
        direction TB

        %% Interface Layer
        subgraph "Interface Layer"
            direction TB

            subgraph "Patterns"
                direction TB
                USART_P["USART Pattern"]:::pattern
                I2C_P["I2C Pattern"]:::pattern
                SPI_P["SPI Pattern"]:::pattern
                USB_P["USB-DFU Pattern"]:::pattern
                FDCAN_P["FDCAN Pattern"]:::pattern
                COMMON_P["Common Interface"]:::pattern
            end

            subgraph "Templates"
                direction TB
                USART_T["USART Template"]:::template
                I2C_T["I2C Template"]:::template
                SPI_T["SPI Template"]:::template
                USB_T["USB-DFU Template"]:::template
                FDCAN_T["FDCAN Template"]:::template
            end

            subgraph "Configuration"
                direction TB
                CONFIG1["interfaces_conf.h"]:::config
                CONFIG2["openbootloader_conf.h"]:::config
                CONFIG3["platform.h"]:::config
            end
        end

        %% Bootloader Core
        BootloaderCore["Bootloader Core"]:::core

        %% Modules
        subgraph "Modules"
            direction TB
            MemM["Memory Operations Module"]:::module
            USARTM["USART Command Module"]:::module
            I2CM["I2C Command Module"]:::module
            SPIM["SPI Command Module"]:::module
            USBM["USB-DFU Command Module"]:::module
            FDCANM["FDCAN Command Module"]:::module
            CANM["CAN (Legacy) Module"]:::module
        end

        %% HAL/LL Layer
        HAL["HAL/LL Drivers"]:::hal

        %% Memory Resources
        subgraph "Memory Resources"
            direction TB
            Flash["Internal Flash"]:::memory
            SRAM["Internal SRAM"]:::memory
            OTP["OTP Memory"]:::memory
            OptBytes["Option Bytes"]:::memory
            ExtMem["External Memory"]:::memory
        end
    end

    %% Relationships
    Host -->|"BL frame"| USART_P
    Host -->|"BL frame"| I2C_P
    Host -->|"BL frame"| SPI_P
    Host -->|"BL frame"| USB_P
    Host -->|"BL frame"| FDCAN_P

    %% Templates override Patterns
    USART_T -.->|override| USART_P
    I2C_T -.->|override| I2C_P
    SPI_T -.->|override| SPI_P
    USB_T -.->|override| USB_P
    FDCAN_T -.->|override| FDCAN_P

    %% Configuration enables Interfaces
    CONFIG1 -->|enable config| USART_P
    CONFIG1 -->|enable config| I2C_P
    CONFIG1 -->|enable config| SPI_P
    CONFIG1 -->|enable config| USB_P
    CONFIG1 -->|enable config| FDCAN_P
    CONFIG2 -->|settings| BootloaderCore
    CONFIG3 -->|board info| USART_P

    %% Data flow into Core
    USART_P -->|"parsed frame"| BootloaderCore
    I2C_P -->|"parsed frame"| BootloaderCore
    SPI_P -->|"parsed frame"| BootloaderCore
    USB_P -->|"parsed frame"| BootloaderCore
    FDCAN_P -->|"parsed frame"| BootloaderCore
    COMMON_P -->|"helpers"| BootloaderCore

    %% Core dispatch to Modules
    BootloaderCore -->|"dispatch command"| MemM
    BootloaderCore -->|"dispatch command"| USARTM
    BootloaderCore -->|"dispatch command"| I2CM
    BootloaderCore -->|"dispatch command"| SPIM
    BootloaderCore -->|"dispatch command"| USBM
    BootloaderCore -->|"dispatch command"| FDCANM
    BootloaderCore -->|"dispatch command"| CANM

    %% Modules to HAL/LL
    MemM -->|"memory op"| HAL
    USARTM -->|"comm op"| HAL
    I2CM -->|"comm op"| HAL
    SPIM -->|"comm op"| HAL
    USBM -->|"comm op"| HAL
    FDCANM -->|"comm op"| HAL
    CANM -->|"comm op"| HAL

    %% HAL to Memory
    HAL -->|"read/write/erase"| Flash
    HAL -->|"read/write"| SRAM
    HAL -->|"read"| OTP
    HAL -->|"config"| OptBytes
    HAL -->|"read/write"| ExtMem

    %% Response path
    BootloaderCore -->|"ACK/NAK"| USART_P
    BootloaderCore -->|"ACK/NAK"| I2C_P
    BootloaderCore -->|"ACK/NAK"| SPI_P
    BootloaderCore -->|"ACK/NAK"| USB_P
    BootloaderCore -->|"ACK/NAK"| FDCAN_P
    USART_P -->|"BL frame"| Host
    I2C_P -->|"BL frame"| Host
    SPI_P -->|"BL frame"| Host
    USB_P -->|"BL frame"| Host
    FDCAN_P -->|"BL frame"| Host

    %% Click Events
    click BootloaderCore "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Core/openbl_core.c"
    click USART_P "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/USART/usart_interface.c"
    click I2C_P "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/I2C/i2c_interface.c"
    click SPI_P "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/SPI/spi_interface.c"
    click USB_P "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/USB/usb_interface.c"
    click FDCAN_P "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/FDCAN/fdcan_interface.c"
    click COMMON_P "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/COMMON/common_interface.c"
    click USART_T "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Templates/USART/usart_interface.c"
    click I2C_T "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Templates/I2C/i2c_interface.c"
    click SPI_T "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Templates/SPI/spi_interface.c"
    click USB_T "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Templates/USB/usb_interface.c"
    click FDCAN_T "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Templates/FDCAN/fdcan_interface.c"
    click CONFIG1 "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/interfaces_conf.h"
    click CONFIG2 "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/openbootloader_conf.h"
    click CONFIG3 "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Interfaces/Patterns/platform.h"
    click MemM "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Modules/Mem/openbl_mem.c"
    click USARTM "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Modules/USART/openbl_usart_cmd.c"
    click I2CM "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Modules/I2C/openbl_i2c_cmd.c"
    click SPIM "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Modules/SPI/openbl_spi_cmd.c"
    click USBM "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Modules/USB/openbl_usb_cmd.c"
    click FDCANM "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Modules/FDCAN/openbl_fdcan_cmd.c"
    click CANM "https://github.com/stmicroelectronics/stm32-mw-openbl/blob/main/Modules/CAN/openbl_can_cmd.c"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef firmware fill:#bbf,stroke:#333,stroke-width:1px
    classDef pattern fill:#bfb,stroke:#333,stroke-width:1px
    classDef template fill:#dfd,stroke:#333,stroke-width:1px
    classDef config fill:#ffd,stroke:#333,stroke-width:1px
    classDef core fill:#fbb,stroke:#333,stroke-width:1px
    classDef module fill:#fbf,stroke:#333,stroke-width:1px
    classDef hal fill:#fdd,stroke:#333,stroke-width:1px
    classDef memory fill:#fdc,stroke:#333,stroke-width:1px
```
