# libresolar/bms-firmware architecture

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

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

## Overview

1. **Overall structure**
   This is a Zephyr RTOS firmware repository for Libre Solar battery management systems. The codebase is organized around Zephyr’s standard split: application code in `app`, reusable drivers in `drivers`, public headers in `include`, board definitions in `boards`, tests in `tests`, and documentation in `docs`.

2. **Application layer**
   The `app/src` directory contains the runtime firmware for the BMS device. `main.c` is the top-level entry point, while modules like `bms_common.c`, `bms_soc.c`, `data_objects.c`, `leds.c`, `button.c`, and `oled.c` implement the device behavior, user interface, state presentation, and battery-state logic. These modules are the main consumers of driver data and the main producers of user-visible output.

3. **Battery-management domain model**
   The `include/bms` and `app/src/data_objects.*` files suggest a shared data model for battery-management values and state. This is the boundary between low-level sensing/control and higher-level application logic: driver measurements are translated into internal objects, then used by state-machine logic, UI, and reporting.

4. **BMS IC driver subsystem**
   The `drivers/bms_ic` tree is the hardware abstraction layer for supported battery monitor ICs. It contains multiple vendor/family-specific implementations:
   - TI `bq769x0`
   - TI `bq769x2`
   - Renesas/Intersil `isl94202`
   
   Each driver family has its own source, private headers, and register definitions. This subsystem is the main interface to cell-voltage, current, temperature, protection, and balancing hardware.

5. **Driver interfaces and emulation**
   The `*_interface.c/.h` files under `bq769x2` and `isl94202` indicate a layered design where protocol/device access is separated from chip behavior. The presence of `*_emul.c` files shows emulated devices for simulation and testing, allowing driver logic to be validated without physical IC hardware.

6. **Hardware description and binding layer**
   The `dts/bindings` tree defines Devicetree bindings for the BMS domain and its ICs. This is the contract between board descriptions and firmware drivers. It makes the firmware hardware-configurable through Zephyr Devicetree rather than hard-coded board logic.

7. **Board support and product variants**
   The `boards/libresolar` directory contains multiple custom board definitions such as `bms_5s50_sc`, `bms_15s80_sc`, `bms_16s100_sc`, `bms_8s50_ic`, and `bms_c1`. Each board has its own DTS, defconfig, Kconfig fragments, and sometimes hardware overlays. This is where product-specific electrical topology, MCU setup, and supported peripherals are defined.

8. **Build-time configuration model**
   The repository uses Zephyr’s `CMakeLists.txt`, `Kconfig`, and per-board `.conf` files heavily. The app and drivers are configured through board-specific and feature-specific Kconfig/overlay files in `app/boards`, `app/sysbuild`, and the board directories. This means the same source tree can target multiple BMS hardware variants with different cell counts, monitors, and peripherals.

9. **Boot and multi-image support**
   The `app/sysbuild` and `app/sysbuild/mcuboot` directories show support for a sysbuild-based multi-image setup with MCUboot on at least some boards, especially `bms_c1`. This introduces a bootloader/application boundary and indicates the firmware can be deployed with secure or staged updates on supported hardware.

10. **User interaction and local I/O**
   The `app/src/button.c`, `leds.c`, and `oled.c` modules form the local interaction layer. Buttons and LEDs provide simple control/status feedback, while the OLED support is tied to the `boards/shields/uext_oled` shield definition. This is the visible edge of the firmware for installers or operators.

11. **Testing and simulation**
   The `tests` directory is split by scope:
   - `tests/bms` for BMS logic/state-machine behavior
   - `tests/bms_ic/*` for chip-driver tests
   - `tests/helper` for utility functions
   
   Tests use `native_sim` overlays and dedicated configs, showing that the firmware is designed to run on Zephyr’s native simulator as well as on hardware. This is a key boundary for validating logic without flashing boards.

12. **Shared utilities and public APIs**
   The `lib/helper.c` and `include/helper.h` pieces look like small shared utilities used across app and tests. Public headers under `include/bms`, `include/drivers`, and `include/dt-bindings` define the stable API surface for consumers inside the repository and for the Devicetree/Kconfig configuration layer.

13. **Tooling and documentation**
   The repo includes `docs` built with Sphinx/Doxygen/Breathe, plus GitHub Actions workflows for docs and Zephyr builds. `west.yml` and `zephyr/module.yml` confirm it is structured as a Zephyr module/repository, intended to be integrated into Zephyr’s workspace and build ecosystem.

14. **Architecture summary**
   The core data flow is: **board/Devicetree configuration → BMS IC driver → application data objects/state logic → UI outputs and control actions**. The main architectural boundaries are between hardware-specific board setup, chip-specific drivers, shared BMS domain logic, and user-facing application modules.

Main entry points: [`include/drivers/bms_ic.h`](https://github.com/libresolar/bms-firmware/blob/main/include/drivers/bms_ic.h) (Driver API), [`boards/libresolar/bms_5s50_sc/bms_5s50_sc.dts`](https://github.com/libresolar/bms-firmware/blob/main/boards/libresolar/bms_5s50_sc/bms_5s50_sc.dts) (Boards), [`app/src/bms_common.c`](https://github.com/libresolar/bms-firmware/blob/main/app/src/bms_common.c) (BMS logic), [`drivers/bms_ic/bq769x2/bq769x2.c`](https://github.com/libresolar/bms-firmware/blob/main/drivers/bms_ic/bq769x2/bq769x2.c) (bq769x2)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["Application"]
  node_n_app_entry["Main app<br/>firmware entry<br/>[main.c]"]
  node_n_app_logic["BMS logic<br/>runtime modules<br/>[bms_common.c]"]
  node_n_app_data["Data objects<br/>domain model<br/>[data_objects.c]"]
  node_n_app_ui["UI modules<br/>local I/O<br/>[button.c]"]
end

subgraph group_g_drv["BMS IC drivers"]
  node_n_drv_bq769x0["bq769x0<br/>TI driver<br/>[bq769x0.c]"]
  node_n_drv_bq769x2["bq769x2<br/>TI driver<br/>[bq769x2.c]"]
  node_n_drv_isl94202["isl94202<br/>Renesas driver<br/>[isl94202.c]"]
  node_n_drv_api["Driver API<br/>public interface<br/>[bms_ic.h]"]
end

subgraph group_g_hw["Hardware description"]
  node_n_bind_bms["BMS binding<br/>dt binding<br/>[bms.yaml]"]
  node_n_bind_ic["IC bindings<br/>dt bindings<br/>[bms-ic-common.yaml]"]
  node_n_boards["Boards<br/>board variants<br/>[bms_5s50_sc.dts]"]
  node_n_shield["OLED shield<br/>board shield<br/>[uext_oled.overlay]"]
end

subgraph group_g_test["Verification"]
  node_n_test_bms["BMS tests<br/>logic tests<br/>[state_machine.c]"]
  node_n_test_ic["IC tests<br/>driver tests<br/>[functions.c]"]
  node_n_test_helper["Helper tests<br/>utility tests<br/>[interpolation.c]"]
end

subgraph group_g_tool["Build and docs"]
  node_n_build["Build system<br/>zephyr module<br/>[module.yml]"]
  node_n_sysbuild["Sysbuild<br/>multi-image build<br/>[prj.conf]"]
  node_n_docs["Docs<br/>[index.rst]"]
end

node_n_build -->|"builds"| node_n_app_entry
node_n_build -->|"exposes"| node_n_drv_api
node_n_build -->|"targets"| node_n_boards
node_n_bind_bms -->|"describes"| node_n_boards
node_n_bind_ic -->|"configures"| node_n_drv_bq769x0
node_n_bind_ic -->|"configures"| node_n_drv_bq769x2
node_n_bind_ic -->|"configures"| node_n_drv_isl94202
node_n_boards -->|"selects"| node_n_drv_bq769x0
node_n_boards -->|"selects"| node_n_drv_bq769x2
node_n_boards -->|"selects"| node_n_drv_isl94202
node_n_drv_bq769x0 -->|"implements"| node_n_drv_api
node_n_drv_bq769x2 -->|"implements"| node_n_drv_api
node_n_drv_isl94202 -->|"implements"| node_n_drv_api
node_n_drv_api -->|"feeds"| node_n_app_data
node_n_app_entry -->|"starts"| node_n_app_logic
node_n_app_logic -->|"updates"| node_n_app_data
node_n_app_logic -->|"controls"| node_n_app_ui
node_n_app_ui -->|"uses"| node_n_shield
node_n_test_bms -.->|"verifies"| node_n_app_data
node_n_test_ic -.->|"verifies"| node_n_drv_bq769x2
node_n_test_ic -.->|"verifies"| node_n_drv_isl94202
node_n_test_helper -.->|"supports"| node_n_app_data
node_n_sysbuild -->|"packages"| node_n_app_entry
node_n_docs -.->|"documents"| node_n_app_logic
node_n_docs -.->|"documents"| node_n_drv_api

click node_n_app_entry "https://github.com/libresolar/bms-firmware/blob/main/app/src/main.c"
click node_n_app_logic "https://github.com/libresolar/bms-firmware/blob/main/app/src/bms_common.c"
click node_n_app_data "https://github.com/libresolar/bms-firmware/blob/main/app/src/data_objects.c"
click node_n_app_ui "https://github.com/libresolar/bms-firmware/blob/main/app/src/button.c"
click node_n_drv_bq769x0 "https://github.com/libresolar/bms-firmware/blob/main/drivers/bms_ic/bq769x0/bq769x0.c"
click node_n_drv_bq769x2 "https://github.com/libresolar/bms-firmware/blob/main/drivers/bms_ic/bq769x2/bq769x2.c"
click node_n_drv_isl94202 "https://github.com/libresolar/bms-firmware/blob/main/drivers/bms_ic/isl94202/isl94202.c"
click node_n_drv_api "https://github.com/libresolar/bms-firmware/blob/main/include/drivers/bms_ic.h"
click node_n_bind_bms "https://github.com/libresolar/bms-firmware/blob/main/dts/bindings/bms.yaml"
click node_n_bind_ic "https://github.com/libresolar/bms-firmware/blob/main/dts/bindings/bms_ic/bms-ic-common.yaml"
click node_n_boards "https://github.com/libresolar/bms-firmware/blob/main/boards/libresolar/bms_5s50_sc/bms_5s50_sc.dts"
click node_n_shield "https://github.com/libresolar/bms-firmware/blob/main/boards/shields/uext_oled/uext_oled.overlay"
click node_n_test_bms "https://github.com/libresolar/bms-firmware/blob/main/tests/bms/src/state_machine.c"
click node_n_test_ic "https://github.com/libresolar/bms-firmware/blob/main/tests/bms_ic/bq769x2/src/functions.c"
click node_n_test_helper "https://github.com/libresolar/bms-firmware/blob/main/tests/helper/src/interpolation.c"
click node_n_build "https://github.com/libresolar/bms-firmware/blob/main/zephyr/module.yml"
click node_n_sysbuild "https://github.com/libresolar/bms-firmware/blob/main/app/sysbuild/mcuboot/prj.conf"
click node_n_docs "https://github.com/libresolar/bms-firmware/blob/main/docs/index.rst"

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_n_app_entry,node_n_app_logic,node_n_app_data,node_n_app_ui toneBlue
class node_n_drv_bq769x0,node_n_drv_bq769x2,node_n_drv_isl94202,node_n_drv_api toneAmber
class node_n_bind_bms,node_n_bind_ic,node_n_boards,node_n_shield toneMint
class node_n_test_bms,node_n_test_ic,node_n_test_helper toneRose
class node_n_build,node_n_sysbuild,node_n_docs toneIndigo
```

## Components

### Application

Runtime firmware and device behavior

- [Main app](https://github.com/libresolar/bms-firmware/blob/main/app/src/main.c): firmware entry · Top-level Zephyr application entry point · `app/src/main.c`
- [BMS logic](https://github.com/libresolar/bms-firmware/blob/main/app/src/bms_common.c): runtime modules · Common behavior, SoC logic, and shared application state · `app/src/bms_common.c`
- [Data objects](https://github.com/libresolar/bms-firmware/blob/main/app/src/data_objects.c): domain model · Battery measurements and internal state model · `app/src/data_objects.c`
- [UI modules](https://github.com/libresolar/bms-firmware/blob/main/app/src/button.c): local I/O · Buttons, LEDs, and OLED presentation · `app/src/button.c`

### BMS IC drivers

Chip-specific hardware abstraction layer

- [bq769x0](https://github.com/libresolar/bms-firmware/blob/main/drivers/bms_ic/bq769x0/bq769x0.c): TI driver · Driver for TI bq769x0 battery monitor ICs · `drivers/bms_ic/bq769x0/bq769x0.c`
- [bq769x2](https://github.com/libresolar/bms-firmware/blob/main/drivers/bms_ic/bq769x2/bq769x2.c): TI driver · Driver, interface, and emulation for TI bq769x2 · `drivers/bms_ic/bq769x2/bq769x2.c`
- [isl94202](https://github.com/libresolar/bms-firmware/blob/main/drivers/bms_ic/isl94202/isl94202.c): Renesas driver · Driver, interface, and emulation for Renesas/Intersil ISL94202 · `drivers/bms_ic/isl94202/isl94202.c`
- [Driver API](https://github.com/libresolar/bms-firmware/blob/main/include/drivers/bms_ic.h): public interface · Shared BMS IC driver API exposed to the application · `include/drivers/bms_ic.h`

### Hardware description

Boards, shields, and Devicetree bindings

- [BMS binding](https://github.com/libresolar/bms-firmware/blob/main/dts/bindings/bms.yaml): dt binding · Devicetree contract for the BMS domain · `dts/bindings/bms.yaml`
- [IC bindings](https://github.com/libresolar/bms-firmware/blob/main/dts/bindings/bms_ic/bms-ic-common.yaml): dt bindings · Devicetree bindings for supported monitor ICs · `dts/bindings/bms_ic/bms-ic-common.yaml`
- [Boards](https://github.com/libresolar/bms-firmware/blob/main/boards/libresolar/bms_5s50_sc/bms_5s50_sc.dts): board variants · Product-specific board definitions and overlays · `boards/libresolar/bms_5s50_sc/bms_5s50_sc.dts`
- [OLED shield](https://github.com/libresolar/bms-firmware/blob/main/boards/shields/uext_oled/uext_oled.overlay): board shield · UEXT OLED shield overlay and config · `boards/shields/uext_oled/uext_oled.overlay`

### Verification

Unit and simulator-based tests

- [BMS tests](https://github.com/libresolar/bms-firmware/blob/main/tests/bms/src/state_machine.c): logic tests · Simulator-backed tests for BMS state machine behavior · `tests/bms/src/state_machine.c`
- [IC tests](https://github.com/libresolar/bms-firmware/blob/main/tests/bms_ic/bq769x2/src/functions.c): driver tests · Driver and interface tests for supported ICs · `tests/bms_ic/bq769x2/src/functions.c`
- [Helper tests](https://github.com/libresolar/bms-firmware/blob/main/tests/helper/src/interpolation.c): utility tests · Tests for shared helper utilities · `tests/helper/src/interpolation.c`

### Build and docs

Repository integration and documentation

- [Build system](https://github.com/libresolar/bms-firmware/blob/main/zephyr/module.yml): zephyr module · Root Zephyr module and build orchestration · `zephyr/module.yml`
- [Sysbuild](https://github.com/libresolar/bms-firmware/blob/main/app/sysbuild/mcuboot/prj.conf): multi-image build · MCUboot and application build setup for supported boards · `app/sysbuild/mcuboot/prj.conf`
- [Docs](https://github.com/libresolar/bms-firmware/blob/main/docs/index.rst): sphinx docs · Sphinx and Doxygen documentation site · `docs/index.rst`

## Connections

- Build system → Main app: builds · Zephyr module builds the application
- Build system → Driver API: exposes · Provides shared driver API headers
- Build system → Boards: targets · Builds for multiple board variants
- BMS binding → Boards: describes · Board DTS references BMS domain bindings
- IC bindings → bq769x0: configures · Devicetree bindings configure IC drivers
- IC bindings → bq769x2: configures · Devicetree bindings configure IC drivers
- IC bindings → isl94202: configures · Devicetree bindings configure IC drivers
- Boards → bq769x0: selects · Boards select a supported monitor IC
- Boards → bq769x2: selects · Boards select a supported monitor IC
- Boards → isl94202: selects · Boards select a supported monitor IC
- bq769x0 → Driver API: implements · Driver implements the common IC API
- bq769x2 → Driver API: implements · Driver implements the common IC API
- isl94202 → Driver API: implements · Driver implements the common IC API
- Driver API → Data objects: feeds · Driver measurements populate the shared data model
- Main app → BMS logic: starts · Main entry drives application modules
- BMS logic → Data objects: updates · Application logic translates measurements into state
- BMS logic → UI modules: controls · Logic updates status indicators and local UI
- UI modules → OLED shield: uses · OLED support relies on the shield definition
- BMS tests → Data objects: verifies · Tests validate BMS state-machine behavior
- IC tests → bq769x2: verifies · Tests validate driver functions and interfaces
- IC tests → isl94202: verifies · Tests validate driver functions and interfaces
- Helper tests → Data objects: supports · Utility tests cover shared helper logic used by app code
- Sysbuild → Main app: packages · Sysbuild packages MCUboot and application images
- Docs → BMS logic: documents · Docs describe firmware features and architecture
- Docs → Driver API: documents · Docs describe driver APIs and supported hardware