DOCSEARCHbyAlgolia
Submit Docs

Libre Solar Charge Controller Firmware

repository·main·Indexed 41 days ago

https://github.com/libresolar/charge-controller-firmware

Firmware implementations for Libre Solar charge controllers built on the Zephyr RTOS. It includes modules for DC/DC buck/boost converter management via the Dcdc class, voltage control and droop compensation using the DcBus and PowerPort classes, and device health monitoring through the DeviceStatus and ErrorFlag systems.

Tokens
8.8K
Snippets
27
Records
42
Agent score
49%

What's inside Libre Solar Charge Controller Firmware

  1. Explore Libre Solar Charge Controller Firmware concepts and modules

    main

    The firmware documentation is organized into several key areas to help you understand the charge controller logic and the software architecture:

    • Charge Controller Concepts: Learn about the fundamental principles of solar charge controller operation.
    • Firmware Module Overview: Understand how the different software modules within the firmware are structured and interact.
    • API Documentation: Access the full technical reference for the codebase via the auto-generated Doxygen site.
    • Zephyr Project Integration: Since this firmware is built on the Zephyr RTOS, you may need to refer to Zephyr-specific documentation and cheatsheets for build and development tasks.

  2. Supported hardware and battery types

    main
    The firmware is designed for STM32F0, STM32L0, and STM32G4 series microcontrollers running on the Zephyr RTOS. It supports various battery chemistries including lead-acid, Li-ion, and LiFePO4. Key features include a Perturb and Observe (P&O) based Maximum Power Point Tracking (MPPT) algorithm, PWM solar input support (hardware dependent), and a load output with deep-discharge protection.

  4. Understand the Bus and Port structure

    main

    The firmware abstracts power flow using two primary components: DC buses and Power ports. This abstraction allows the firmware to support various charge controller hardware configurations.

    • DC bus: Represents a connection of electrical circuits with equal electric potential. A bus acts as a voltage reference point. Note that voltage control targets for a bus can only be set by a single connected port.
    • Power port: Connects a DC bus to an internal or external device/sub-circuit.
      • Ports typically include a current measurement mechanism.
      • The voltage of a port is determined by the DC bus it is connected to.
      • Ports may contain a switching element.

    In a typical solar charge controller setup, there are two main buses: a High-voltage side (e.g., solar panels or wind turbines) and a Low-voltage side (e.g., the battery bank). Most power ports connect to the low-voltage side.

  5. Understand the Libre Solar firmware development and release model

    main

    The firmware follows a specific branching and versioning strategy:

    • Ongoing Development: The main branch is the primary location for active development.
    • Releases: Official releases are cut from main after passing tests on multiple hardware boards. Version numbers follow the format v[Year].[Count] (e.g., v21.0).
    • Maintenance/Bug-fixes: For back-porting fixes to older versions, dedicated branches are created using the suffix -branch (e.g., v21.0-branch).

  8. Understand the Charger state machine

    main

    The charger module operates through a specific sequence of states to manage battery charging. The progression through these states depends on the battery type and current charging requirements:

    1. Standby: The initial state. If solar voltage is sufficient and the battery is not full, the controller transitions to the Bulk stage using Constant Current (CC) mode.
    2. Bulk stage: The first major charging stage (adding ~70% energy). The charger provides a Constant Current (CC), typically at the maximum available capacity. In solar controllers, this is when Maximum Power Point Tracking (MPPT) occurs. The terminal voltage rises during this stage until the peak charge voltage limit is reached.
    3. Topping stage (also called Boost or Absorption): The second stage (adding the remaining ~30% energy). The charger switches to Constant Voltage (CV) mode, gradually decreasing the charge current until the battery is fully charged.
    4. Equalization stage: (Specific to flooded lead-acid batteries). A periodic controlled overcharge used to balance cells and remove sulphation. It uses a voltage higher than the peak charge voltage limit but maintains a very low controlled current.
    5. Float stage: The final phase (trickle charging). Once absorption or equalization is complete, the charger maintains the battery at full charge by holding a constant, reduced voltage. The current drops to a very low value.

  9. Configure application firmware features via Kconfig

    main

    Application-specific features are configured using the Zephyr Kconfig system. You can modify settings in two ways:

    1. Interactive: Run west build -t menuconfig to open a configuration menu.
    2. Manual: Edit the prj.conf file or create a board-specific configuration file.

    To avoid merge conflicts during git pull, you can create a board-specific configuration file by creating a folder app/boards and placing a file named board_name.conf inside it. This file will be automatically merged with prj.conf during the build.

    west build -t menuconfig

  11. Run conformance testing locally

    main

    To ensure your changes pass the Continuous Integration (CI) checks before pushing to the repository, run the conformance testing script located in the scripts folder. Use check.sh on Linux/macOS or check.bat on Windows.

    It is highly recommended to run these tests locally before submitting pull requests.

    ./scripts/check.sh       # use check.bat on Windows