How eagletrt/hv-bms-mainboard-sw works
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: gpio.c Peripherals · tasks.c Tasks · fsm.c FSM · can-comm.c CAN comms
Components 22
MCU Shell
CubeMX/HAL bring-up and device-specific firmware layer for the STM32F446 board.
- Main · Boots the firmware and starts the MCU-side application flow.
Core/Src/main.c - Peripherals · GPIO, ADC, CAN, SPI, DAC, timers, USART, DMA, interrupts, and MSP setup.
Core/Src/gpio.c - System init · 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 · Central product state machine that drives BMS behavior.
Core/Src/bms/fsm.c - Timebase · Periodic orchestration backbone for timed control and background work.
Core/Src/bms/timebase/timebase.c - Tasks · Scheduled jobs executed from the central timebase.
Core/Src/bms/timebase/tasks.c - Watchdog · Supervision and timeout handling for safe operation.
Core/Src/bms/timebase/watchdog.c - Voltage sense · Pack and internal voltage acquisition and normalization.
Core/Src/bms/volt.c - Current sense · Current acquisition and engineering-value conversion.
Core/Src/bms/current.c - Temperature sense · Temperature acquisition including cooling temperature inputs.
Core/Src/bms/temp.c - Balancing · Cell balancing control isolated from sensing and communications.
Core/Src/bms/bal.c - CAN comms · Main external bus coordination layer for cellboards and vehicle systems.
Core/Src/bms/can-comm.c - Endpoints · Higher-level consumers and presenters of internal BMS state.
Core/Src/bms/display.c - Safety · IMD, POST, feedback, identity, programmer, and fault handling.
Core/Src/bms/imd.c - Device 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 · Reusable CAN support library bundled into the firmware tree.
Core/Lib/can - Micro libs · Additional bundled helper libraries used by the firmware.
Core/Lib/micro-libs - STM32 HAL · ST HAL and low-level device support for the STM32F4 family.
Drivers/STM32F4xx_HAL_Driver - 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 · Generated error catalog and handler logic for consistent fault reporting.
Core/Src/bms/errors/error.c - FSM spec · Maintained DOT definition used to generate or synchronize FSM code.
assets/fsm/fsm.dot - Error catalog · Structured error definitions used to generate handler code and IDs.
assets/errors/errors.json
Connections 26
- 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.