# maxkgo/maxkgo-bms-firmware architecture

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

- Interactive diagram: https://gitdiagram.com/maxkgo/maxkgo-bms-firmware
- Repository: https://github.com/maxkgo/maxkgo-bms-firmware

## Overview

##### Project type and purpose
- Firmware for an STM32-based Battery Management System (ENNOID-BMS).
- Generates production binaries for various hardware variants (MKBMS-LV-MINI, SS-24S, etc.).
- Integrates with three companion repositories: hardware schematics, bootloader, and a PC configuration tool.

##### File structure
- Top level:
– Config: XML settings + a parser library
– CubeMX: auto-generated CMSIS/HAL code + project files
– Drivers:
· CMSIS DSP library
· CMSIS device templates
· HAL driver layer (STM32F3xx_HAL_Driver)
· HWDrivers: GPIO, ADC, I²C, SPI, UART, EEPROM emulation
· SWDrivers: high-level peripheral drivers (external ADCs, power monitors, sensors, display)
– Libraries: generic C libs (buffers, CRC, graphics, mempools, packet/ring buffers)
– Modules: application layer modules (CAN, UART, Display, Flash, PowerState, StateOfCharge, Commands, Safety checks, etc.)
– Main: entry point (main.c), data types, helper functions
– build_all, GCC, MDK-ARM etc.: build scripts, linker scripts, board binary outputs
– dbc: CAN database files
– makefile: build orchestration for GCC, flashing via STLink/JLink

##### README insights
- Outlines memory map (flash page layout for EEPROM emulation, application, bootloader).
- Describes chosen toolchain (arm-none-eabi-gcc, Makefile rules).
- Indicates how `generalDefines.h` toggles target variants.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Code Generation Tools
    subgraph "Code Generation & Config" 
        direction TB
        CubeMX["STM32CubeMX"]:::tool
        ConfigParser["Configuration Parser"]:::config
    end

    %% On-Chip Core & HAL
    subgraph "Core & HAL Layer"
        direction TB
        CMSISCore["CMSIS Core"]:::hal
        DSPLib["CMSIS DSP Library"]:::hal
        HAL["STM32F3xx HAL Driver"]:::hal
    end

    %% Drivers
    subgraph "Driver Layer"
        direction TB
        HWDrivers["HWDrivers"]:::driver
        SWDrivers["SWDrivers"]:::driver
    end

    %% Utilities and Modules
    subgraph "Libraries & Application Modules"
        direction TB
        Utils["Utility Libraries"]:::util
        Modules["Application Modules"]:::module
    end

    %% Main and Startup
    subgraph "Startup & Entry"
        direction TB
        Main["Main Entry Point"]:::main
    end

    %% External Systems
    subgraph "External Systems" 
        direction TB
        Sensors["Battery Pack Sensors & Electronics"]:::external
        CANBus["CAN Bus Network"]:::external
        PCTool["PC Configuration Tool (UART)"]:::external
        Bootloader["Bootloader Repo"]:::external
    end

    %% Memory Map Legend
    MemoryMap["Memory Map:\n- Bootloader Region\n- EEPROM Emulation Pages\n- Application Region"]:::legend

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        Makefile["makefile"]:::build
        GCCTool["GCC Toolchain & Scripts"]:::build
        MDK["MDK-ARM Project & Binaries"]:::build
        BuildAll["Multi-variant Builds"]:::build
        DBC["CAN Database Files"]:::build
        Logos["Display/Logos Resources"]:::build
    end

    %% Relationships
    CubeMX -->|"generates code"| CMSISCore
    CubeMX --> HAL
    ConfigParser --> Modules
    CMSISCore --> HAL
    DSPLib --> HAL
    HAL --> HWDrivers
    HAL --> SWDrivers
    HWDrivers --> Modules
    SWDrivers --> Modules
    Utils --> Modules
    Main --> CMSISCore
    Main --> HAL
    Main --> ConfigParser
    Main --> Modules
    CMSISCore -.->|"Interrupt vectors"| Modules
    CubeMX -->|"starts SysTick & NVIC"| Modules
    Modules -->|controls peripherals| Sensors
    Modules -->|sends frames| CANBus
    Modules -->|UART comms| PCTool
    Modules -->|flash wear-leveling| Main
    Main --> MemoryMap
    Makefile --> GCCTool
    Makefile --> BuildAll
    Makefile --> MDK
    GCCTool -->|links| Modules
    GCCTool -->|links| Main
    BuildAll -->|produces| MDK
    DBC --> Modules
    Logos --> Modules

    %% Click Events
    click ConfigParser "https://github.com/maxkgo/maxkgo-bms-firmware/blob/master/Config/confparser.c"
    click CubeMX "https://github.com/maxkgo/maxkgo-bms-firmware/blob/master/CubeMX/.ioc"
    click CMSISCore "https://github.com/maxkgo/maxkgo-bms-firmware/tree/master/Drivers/CMSIS/Include"
    click DSPLib "https://github.com/maxkgo/maxkgo-bms-firmware/tree/master/Drivers/CMSIS/DSP_Lib/Source"
    click HAL "https://github.com/maxkgo/maxkgo-bms-firmware/tree/master/Drivers/STM32F3xx_HAL_Driver/Src"
    click HWDrivers "https://github.com/maxkgo/maxkgo-bms-firmware/tree/master/Drivers/HWDrivers/Src"
    click SWDrivers "https://github.com/maxkgo/maxkgo-bms-firmware/tree/master/Drivers/SWDrivers/Src"
    click Utils "https://github.com/maxkgo/maxkgo-bms-firmware/tree/master/Libraries/Src"
    click Modules "https://github.com/maxkgo/maxkgo-bms-firmware/tree/master/Modules/Src"
    click Main "https://github.com/maxkgo/maxkgo-bms-firmware/blob/master/Main/main.c"
    click GCCTool "https://github.com/maxkgo/maxkgo-bms-firmware/blob/master/GCC/EBMS-linker.ld"
    click MDK "https://github.com/maxkgo/maxkgo-bms-firmware/blob/master/MDK-ARM/ENNOID-BMS.uvprojx"
    click BuildAll "https://github.com/maxkgo/maxkgo-bms-firmware/tree/master/build_all/rebuild_all"
    click DBC "https://github.com/maxkgo/maxkgo-bms-firmware/blob/master/dbc/sre.dbc"
    click Logos "https://github.com/maxkgo/maxkgo-bms-firmware/blob/master/Logos/*.bmp"

    %% Styles
    classDef tool fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef config fill:#e8f4fc,stroke:#1f77b4,stroke-width:1px
    classDef hal fill:#d6e9f8,stroke:#3b72a4,stroke-width:1px
    classDef driver fill:#dff0d8,stroke:#3c763d,stroke-width:1px
    classDef util fill:#fcf8e3,stroke:#8a6d3b,stroke-width:1px
    classDef module fill:#fce5cd,stroke:#d2691e,stroke-width:1px
    classDef main fill:#f9f0ff,stroke:#7a378b,stroke-width:1px
    classDef external fill:#f2dede,stroke:#a94442,stroke-width:1px
    classDef legend fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef build fill:#ebf5fb,stroke:#2c3e50,stroke-width:1px
```
