libresolar/bms-firmware

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.