# eagletrt/hv-bms-mainboard-sw architecture

> Architecture diagram of the GitHub repository eagletrt/hv-bms-mainboard-sw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eagletrt/hv-bms-mainboard-sw
- Repository: https://github.com/eagletrt/hv-bms-mainboard-sw

## Overview

1. This is an embedded firmware repository for an STM32F446-based high-voltage BMS mainboard. The main board sits above multiple cellboards in a master-slave battery architecture and is responsible for supervision, coordination, and safety actions.

2. The code is split into three practical layers:
   - STM32CubeMX-generated hardware bring-up and peripheral glue in `Core/Src` and `Core/Inc` outside `bms/`
   - platform-neutral BMS logic in `Core/Src/bms` and `Core/Inc/bms`
   - bundled dependencies in `Core/Lib` plus the STM32 CMSIS/HAL vendor trees under `Drivers/`

3. The hardware-abstraction boundary is the CubeMX/HAL layer. Files like `main.c`, `gpio.c`, `adc.c`, `can.c`, `spi.c`, `tim.c`, `usart.c`, `dma.c`, `dac.c`, and the interrupt/MSP files initialize and service the MCU peripherals. This layer is where platform-specific pinout, clocks, DMA, interrupts, and startup/linker behavior live.

4. The `bms/` folder is the functional core of the product. The README explicitly calls this the machine-independent part of the system, intended to be portable as long as equivalent peripheral hooks are provided for CAN, SPI, ADC, and similar interfaces.

5. Sensor acquisition and normalization are separated into dedicated modules:
   - `current`, `volt`, `temp`, `internal-voltage`, and `cooling/cooling-temp`
   - these likely translate raw ADC/peripheral readings into engineering values used by the rest of the system
   - `adc` and `dac` are the MCU-facing entry points into analog measurement/control

6. Safety and monitoring are first-class subsystems. Modules such as `imd`, `post`, `feedback`, `errors/error`, `identity`, and `programmer` suggest handling insulation monitoring, power-on/self-test, status feedback, fault reporting, device identification, and service/programming functions.

7. System behavior is driven by a finite-state machine in `bms/fsm`. The repository includes `assets/fsm/fsm.dot` and a generator script, which implies the FSM definition is treated as a maintained design artifact and compiled into code rather than hand-authored only in C.

8. Time-based orchestration is handled by `bms/timebase` with `tasks` and `watchdog`. This is the scheduling/control backbone: periodic jobs are run from a centralized tick/timebase mechanism, and watchdog handling provides liveness/safety supervision.

9. Communication outward from the BMS is centered on CAN. `bms/can-comm` plus `Core/Src/can.c` and the `Core/Lib/can` dependency form the main bus interface to cellboards and other vehicle systems. `pcu` and `display` are additional application-level endpoints that likely consume the same internal state and fault data.

10. Cell balancing is isolated in `bms/bal`, indicating a dedicated subsystem for pack-level balancing control rather than mixing balancing logic into measurement or communication code.

11. Hardware-specific safety components have their own drivers under `bms/drivers`:
   - `ir1553204`, `max22530`, and `tdsr0760`
   - these are treated as peripheral/device drivers, sitting below the main BMS logic and above the raw HAL layer

12. Error handling is generated and data-driven. `assets/errors/errors.json` and `scripts/generate-error-handler.sh` suggest a structured error catalog that is transformed into code or headers, so error IDs/messages remain consistent across the firmware.

13. Build and deployment are classic embedded tooling: GNU Make, Arm GCC toolchain, OpenOCD, and ST-Link flashing. `hv-bms-mainboard-sw.ioc` is the CubeMX source of truth for peripheral configuration, while `STM32F446ZETx_FLASH.ld` and `startup_stm32f446xx.s` define the MCU boot/link behavior.

14. Net result: the architecture is a safety-oriented embedded controller with a thin MCU-specific shell, a portable BMS domain layer, and explicit boundaries for sensing, safety checks, state control, balancing, and CAN-based coordination with the rest of the battery system.

Main entry points: [`Core/Src/gpio.c`](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/gpio.c) (Peripherals), [`Core/Src/bms/timebase/tasks.c`](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/timebase/tasks.c) (Tasks), [`Core/Src/bms/fsm.c`](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/fsm.c) (FSM), [`Core/Src/bms/can-comm.c`](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/can-comm.c) (CAN comms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_hw["MCU Shell"]
  node_node_main["Main<br/>entry point<br/>[main.c]"]
  node_node_mcu_io["Peripherals<br/>HAL glue<br/>[gpio.c]"]
  node_node_clock["System init<br/>startup/system<br/>[system_stm32f4xx.c]"]
end

subgraph group_group_bms["BMS Core"]
  node_node_bms_fsm{{"FSM<br/>state machine<br/>[fsm.c]"}}
  node_node_timebase["Timebase<br/>scheduler<br/>[timebase.c]"]
  node_node_tasks["Tasks<br/>periodic jobs<br/>[tasks.c]"]
  node_node_watchdog["Watchdog<br/>liveness<br/>[watchdog.c]"]
  node_node_sense_v["Voltage sense<br/>measurement<br/>[volt.c]"]
  node_node_sense_i["Current sense<br/>measurement<br/>[current.c]"]
  node_node_sense_t["Temperature sense<br/>measurement<br/>[temp.c]"]
  node_node_bal["Balancing<br/>pack control<br/>[bal.c]"]
  node_node_can["CAN comms<br/>bus interface<br/>[can-comm.c]"]
  node_node_endpoints["Endpoints<br/>app interfaces<br/>[display.c]"]
  node_node_safety["Safety<br/>supervision<br/>[imd.c]"]
  node_node_driver_dev["Device drivers<br/>hardware drivers<br/>[max22530.c]"]
end

subgraph group_group_deps["Dependencies"]
  node_node_can_lib["CAN lib<br/>vendor lib"]
  node_node_micro_libs["Micro libs<br/>utility lib"]
  node_node_hal["STM32 HAL<br/>vendor HAL"]
  node_node_cmsis["CMSIS"]
end

subgraph group_group_assets["Generated Artifacts"]
  node_node_errors["Errors<br/>catalog<br/>[error.c]"]
  node_node_fsm_asset["FSM spec<br/>design artifact<br/>[fsm.dot]"]
  node_node_error_asset["Error catalog<br/>design artifact<br/>[errors.json]"]
end

node_node_main -->|"starts"| node_node_clock
node_node_main -->|"configures"| node_node_mcu_io
node_node_main -->|"enters"| node_node_bms_fsm
node_node_mcu_io -->|"built on"| node_node_hal
node_node_clock -->|"uses"| node_node_cmsis
node_node_bms_fsm -->|"driven by"| node_node_timebase
node_node_timebase -->|"runs"| node_node_tasks
node_node_timebase -->|"supervises"| node_node_watchdog
node_node_tasks -->|"polls"| node_node_sense_v
node_node_tasks -->|"polls"| node_node_sense_i
node_node_tasks -->|"polls"| node_node_sense_t
node_node_tasks -->|"updates"| node_node_bal
node_node_tasks -->|"checks"| node_node_safety
node_node_sense_v -->|"reads via"| node_node_mcu_io
node_node_sense_i -->|"reads via"| node_node_mcu_io
node_node_sense_t -->|"reads via"| node_node_mcu_io
node_node_safety -->|"reports"| node_node_errors
node_node_errors -->|"generated from"| node_node_error_asset
node_node_bms_fsm -->|"derived from"| node_node_fsm_asset
node_node_can -->|"uses"| node_node_can_lib
node_node_can -->|"binds to"| node_node_mcu_io
node_node_endpoints -->|"shares state"| node_node_can
node_node_driver_dev -->|"sits above"| node_node_hal
node_node_driver_dev -->|"enabled by"| node_node_mcu_io
node_node_safety -->|"depends on"| node_node_driver_dev
node_node_bms_fsm -->|"coordinates"| node_node_can

click node_node_main "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/main.c"
click node_node_mcu_io "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/gpio.c"
click node_node_clock "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/system_stm32f4xx.c"
click node_node_bms_fsm "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/fsm.c"
click node_node_timebase "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/timebase/timebase.c"
click node_node_tasks "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/timebase/tasks.c"
click node_node_watchdog "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/timebase/watchdog.c"
click node_node_sense_v "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/volt.c"
click node_node_sense_i "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/current.c"
click node_node_sense_t "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/temp.c"
click node_node_bal "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/bal.c"
click node_node_can "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/can-comm.c"
click node_node_endpoints "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/display.c"
click node_node_safety "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/imd.c"
click node_node_driver_dev "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/drivers/max22530.c"
click node_node_errors "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/errors/error.c"
click node_node_fsm_asset "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/assets/fsm/fsm.dot"
click node_node_error_asset "https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/assets/errors/errors.json"
click node_node_can_lib "https://github.com/eagletrt/hv-bms-mainboard-sw/tree/master/Core/Lib/can"
click node_node_micro_libs "https://github.com/eagletrt/hv-bms-mainboard-sw/tree/master/Core/Lib/micro-libs"
click node_node_hal "https://github.com/eagletrt/hv-bms-mainboard-sw/tree/master/Drivers/STM32F4xx_HAL_Driver"
click node_node_cmsis "https://github.com/eagletrt/hv-bms-mainboard-sw/tree/master/Drivers/CMSIS"

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_node_main,node_node_mcu_io,node_node_clock toneBlue
class node_node_bms_fsm,node_node_timebase,node_node_tasks,node_node_watchdog,node_node_sense_v,node_node_sense_i,node_node_sense_t,node_node_bal,node_node_can,node_node_endpoints,node_node_safety,node_node_driver_dev toneAmber
class node_node_can_lib,node_node_micro_libs,node_node_hal,node_node_cmsis toneMint
class node_node_errors,node_node_fsm_asset,node_node_error_asset toneRose
```

## Components

### MCU Shell

CubeMX/HAL bring-up and device-specific firmware layer for the STM32F446 board.

- [Main](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/main.c): entry point · Boots the firmware and starts the MCU-side application flow. · `Core/Src/main.c`
- [Peripherals](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/gpio.c): HAL glue · GPIO, ADC, CAN, SPI, DAC, timers, USART, DMA, interrupts, and MSP setup. · `Core/Src/gpio.c`
- [System init](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/system_stm32f4xx.c): startup/system · MCU startup, system clock, syscall/sysmem, and low-level runtime setup. · `Core/Src/system_stm32f4xx.c`

### BMS Core

Portable domain logic for sensing, safety, state control, balancing, and coordination.

- [FSM](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/fsm.c): state machine · Central product state machine that drives BMS behavior. · `Core/Src/bms/fsm.c`
- [Timebase](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/timebase/timebase.c): scheduler · Periodic orchestration backbone for timed control and background work. · `Core/Src/bms/timebase/timebase.c`
- [Tasks](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/timebase/tasks.c): periodic jobs · Scheduled jobs executed from the central timebase. · `Core/Src/bms/timebase/tasks.c`
- [Watchdog](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/timebase/watchdog.c): liveness · Supervision and timeout handling for safe operation. · `Core/Src/bms/timebase/watchdog.c`
- [Voltage sense](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/volt.c): measurement · Pack and internal voltage acquisition and normalization. · `Core/Src/bms/volt.c`
- [Current sense](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/current.c): measurement · Current acquisition and engineering-value conversion. · `Core/Src/bms/current.c`
- [Temperature sense](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/temp.c): measurement · Temperature acquisition including cooling temperature inputs. · `Core/Src/bms/temp.c`
- [Balancing](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/bal.c): pack control · Cell balancing control isolated from sensing and communications. · `Core/Src/bms/bal.c`
- [CAN comms](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/can-comm.c): bus interface · Main external bus coordination layer for cellboards and vehicle systems. · `Core/Src/bms/can-comm.c`
- [Endpoints](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/display.c): app interfaces · Higher-level consumers and presenters of internal BMS state. · `Core/Src/bms/display.c`
- [Safety](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/imd.c): supervision · IMD, POST, feedback, identity, programmer, and fault handling. · `Core/Src/bms/imd.c`
- [Device drivers](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/drivers/max22530.c): hardware drivers · Board-specific device drivers beneath the portable BMS core. · `Core/Src/bms/drivers/max22530.c`

### Dependencies

Bundled vendor and reusable libraries pulled into the firmware build.

- [CAN lib](https://github.com/eagletrt/hv-bms-mainboard-sw/tree/master/Core/Lib/can): vendor lib · Reusable CAN support library bundled into the firmware tree. · `Core/Lib/can`
- [Micro libs](https://github.com/eagletrt/hv-bms-mainboard-sw/tree/master/Core/Lib/micro-libs): utility lib · Additional bundled helper libraries used by the firmware. · `Core/Lib/micro-libs`
- [STM32 HAL](https://github.com/eagletrt/hv-bms-mainboard-sw/tree/master/Drivers/STM32F4xx_HAL_Driver): vendor HAL · ST HAL and low-level device support for the STM32F4 family. · `Drivers/STM32F4xx_HAL_Driver`
- [CMSIS](https://github.com/eagletrt/hv-bms-mainboard-sw/tree/master/Drivers/CMSIS): vendor CMSIS · ARM/ST CMSIS core, device, RTOS, DSP, and NN support trees. · `Drivers/CMSIS`

### Generated Artifacts

Maintained design artifacts and code generators for errors and FSM behavior.

- [Errors](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/Core/Src/bms/errors/error.c): catalog · Generated error catalog and handler logic for consistent fault reporting. · `Core/Src/bms/errors/error.c`
- [FSM spec](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/assets/fsm/fsm.dot): design artifact · Maintained DOT definition used to generate or synchronize FSM code. · `assets/fsm/fsm.dot`
- [Error catalog](https://github.com/eagletrt/hv-bms-mainboard-sw/blob/master/assets/errors/errors.json): design artifact · Structured error definitions used to generate handler code and IDs. · `assets/errors/errors.json`

## Connections

- Main → System init: starts · Boot sequence depends on system initialization.
- Main → Peripherals: configures · Main uses peripheral setup and service glue.
- Main → FSM: enters · Application logic begins in the BMS state machine.
- Peripherals → STM32 HAL: built on · CubeMX-generated glue is backed by the STM32 HAL.
- System init → CMSIS: uses · Startup and system code rely on CMSIS runtime support.
- FSM → Timebase: driven by · FSM progression is orchestrated by the central timebase.
- Timebase → Tasks: runs · The timebase dispatches periodic tasks.
- Timebase → Watchdog: supervises · Liveness and timeout handling are tied into the scheduler.
- Tasks → Voltage sense: polls · Periodic jobs collect voltage data.
- Tasks → Current sense: polls · Periodic jobs collect current data.
- Tasks → Temperature sense: polls · Periodic jobs collect temperature data.
- Tasks → Balancing: updates · Balancing decisions are refreshed from scheduled logic.
- Tasks → Safety: checks · Scheduled logic evaluates safety and fault conditions.
- Voltage sense → Peripherals: reads via · Voltage sensing is fed by ADC/peripheral glue.
- Current sense → Peripherals: reads via · Current sensing is fed by ADC/peripheral glue.
- Temperature sense → Peripherals: reads via · Temperature sensing is fed by ADC/peripheral glue.
- Safety → Errors: reports · Safety subsystems emit structured faults through the error layer.
- Errors → Error catalog: generated from · The error handler is derived from the structured catalog.
- FSM → FSM spec: derived from · FSM behavior is maintained as a design artifact.
- CAN comms → CAN lib: uses · BMS CAN communication builds on the bundled CAN library.
- CAN comms → Peripherals: binds to · CAN communication depends on MCU peripheral service.
- Endpoints → CAN comms: shares state · Display/PCU endpoints consume the same internal BMS state.
- Device drivers → STM32 HAL: sits above · Hardware-specific device drivers sit on top of the HAL layer.
- Device drivers → Peripherals: enabled by · Drivers are wired through the board's peripheral glue.
- Safety → Device drivers: depends on · Safety functions use dedicated hardware-device drivers.
- FSM → CAN comms: coordinates · State transitions influence bus communication behavior.
