deploy: da1a449

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 277bcfa08c6011ee254f93606fdff359
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/index.rst.txt

@@ -0,0 +1,42 @@
+======================================
+Libre Solar BMS Firmware Documentation
+======================================
+
+This documentation describes the firmware based on `Zephyr RTOS`_ for different Libre Solar Battery
+Management Systems.
+
+The firmware is under ongoing development. Most recent version can be found on
+`GitHub <https://github.com/LibreSolar/bms-firmware>`_.
+
+This documentation is licensed under the Creative Commons Attribution-ShareAlike 4.0 International
+(CC BY-SA 4.0) License.
+
+.. image:: static/images/cc-by-sa-centered.png
+
+The full license text is available at `<https://creativecommons.org/licenses/by-sa/4.0/>`_.
+
+.. _Zephyr RTOS: https://zephyrproject.org
+
+.. toctree::
+    :caption: Overview
+    :hidden:
+
+    src/features
+    src/supported_hardware
+
+.. toctree::
+    :caption: Development
+    :hidden:
+
+    src/dev/workspace_setup
+    src/dev/building_flashing
+    src/dev/customization
+    src/dev/unit_tests
+
+.. toctree::
+    :caption: API Reference
+    :hidden:
+
+    src/api/bms
+    src/api/data_objects
+    src/api/misc

_sources/src/api/bms.rst.txt

@@ -0,0 +1,5 @@
+BMS
+===
+
+.. doxygenfile:: include/bms/bms.h
+   :project: app

_sources/src/api/data_objects.rst.txt

@@ -0,0 +1,5 @@
+Data Objects
+============
+
+.. doxygenfile:: data_objects.h
+   :project: app

_sources/src/api/misc.rst.txt

@@ -0,0 +1,14 @@
+Misc
+====
+
+Button
+------
+
+.. doxygenfile:: button.h
+   :project: app
+
+Helper
+------
+
+.. doxygenfile:: include/helper.h
+   :project: app

_sources/src/dev/building_flashing.rst.txt

@@ -0,0 +1,64 @@
+Building and Flashing
+=====================
+
+As the ``main`` branch may contain unstable code, make sure to select the desired release branch
+(see GitHub for a list of releases and branches):
+
+.. code-block:: bash
+
+    git switch <your-release>-branch
+    west update
+
+The ``app`` subfolder contains all application source files and the CMake entry point to build the
+firmware, so we go into that directory first.
+
+.. code-block:: bash
+
+    cd app
+
+
+Boards with STM32 MCU
+"""""""""""""""""""""
+
+Initial board selection (see ``boards`` subfolder for correct names):
+
+.. code-block:: bash
+
+    west build -b <board-name>@<revision>
+
+The appended ``@<revision>`` specifies the board version according to the table in
+:doc:`../supported_hardware`. It can be omitted if only a single board revision is available or if
+the default (most recent) version should be used. See also
+`here <https://docs.zephyrproject.org/latest/application/index.html#application-board-version>`_
+for more details regarding board revision handling in Zephyr.
+
+Flash with specific debug probe (runner), e.g. J-Link:
+
+.. code-block:: bash
+
+    west flash -r jlink
+
+
+Boards with ESP32 MCU
+"""""""""""""""""""""
+
+The ESP32 requires additional steps to get required binary blobs:
+
+.. code-block:: bash
+
+    west blobs fetch hal_espressif
+
+Afterwards you can build and flash the firmware the same way as for STM32:
+
+.. code-block:: bash
+
+    west build -b <board-name>@<revision>
+    west flash
+
+For monitoring the serial monitor built into the Espressif toolchain can be used with:
+
+.. code-block:: bash
+
+    west espressif monitor
+
+Press Ctrl+T followed by X to exit.

_sources/src/dev/customization.rst.txt

@@ -0,0 +1,94 @@
+Customization
+=============
+
+This firmware is developed to allow easy addition of new boards and customization of the firmware.
+
+Hardware-specific changes
+-------------------------
+
+In Zephyr, all hardware-specific configuration is described in the
+`Devicetree <https://docs.zephyrproject.org/latest/build/dts/index.html>`_.
+
+The file ``boards/arm/board_name/board_name.dts`` contains the default devicetree specification
+(DTS) for a board. It is based on the DTS of the used MCU, which is included from the main Zephyr
+repository.
+
+In order to overwrite the default devicetree specification, so-called overlays can be used. An
+overlay file can be specified via the west command line. If it is stored as ``board_name.overlay``
+in the ``app`` subfolder, it will be recognized automatically when building the firmware for that
+board.
+
+Application firmware configuration
+----------------------------------
+
+For configuration of the application-specific features, Zephyr uses the
+`Kconfig system <https://docs.zephyrproject.org/latest/build/kconfig/index.html>`_.
+
+The configuration can be changed using ``west build -t menuconfig`` command or manually by changing
+the prj.conf file (see ``Kconfig`` file for possible options).
+
+Similar to DTS overlays, Kconfig can also be customized per board. Create a folder ``app/boards``
+and  a file ``board_name.conf`` in that folder. The configuration from this file will be merged with
+the ``prj.conf`` automatically.
+
+Change battery capacity, cell type and number of cells in series
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+By default, the BMS is configured for LiFePO4 cells (``CONFIG_CELL_TYPE_LFP``).
+Possible other pre-defined options are ``CONFIG_BAT_TYPE_NMC``, ``CONFIG_BAT_TYPE_NMC_HV`` and
+``CONFIG_BAT_TYPE_LTO``.
+
+The number of cells only has to be specified via ``CONFIG_BMS_IC_ISL94202_NUM_CELLS`` for boards
+with the ISL94202 chip. For all other chips it is detected automatically.
+
+To compile the firmware with default settings e.g. for a 24V LiFePO4 battery with a nominal capacity
+of 100Ah, add the following to ``prj.conf`` or the board-specific ``.conf`` file:
+
+.. code-block:: bash
+
+    CONFIG_BAT_CAPACITY_AH=100
+    CONFIG_CELL_TYPE_LFP=y
+
+Configure serial interface
+""""""""""""""""""""""""""
+
+The BMS exposes its data using the `ThingSet protocol <https://libre.solar/thingset/>`_.
+
+By default, live data is published on a serial interface in a 1 second interval.
+
+The used serial interface can be configured via Devicetree, e.g. with the following snippet in
+``board_name.overlay``:
+
+.. code-block:: bash
+
+    / {
+        chosen {
+            thingset,serial = &usart2;
+	    };
+    };
+
+To disable regular data publication at startup, add the following to ``prj.conf`` or the
+board-specific ``.conf`` file:
+
+.. code-block:: bash
+
+    CONFIG_THINGSET_REPORTING_LIVE_ENABLE_PRESET=n
+
+The default period for data publication can be changed with the following Kconfig option:
+
+.. code-block:: bash
+
+    CONFIG_THINGSET_REPORTING_LIVE_PERIOD_PRESET=10
+
+Shields for UEXT connector
+--------------------------
+
+There are some shields like an OLED display which can be connected to the UEXT connector.
+
+See the full list of shields in the ``boards/shields`` folder.
+
+The below example compiles the firmware with the OLED shield enabled.
+
+.. code-block:: bash
+
+    west build -b bms_8s50_ic@0.2 app -- -DEXTRA_CONF_FILE=oled.conf -DSHIELD=uext_oled

_sources/src/dev/unit_tests.rst.txt

@@ -0,0 +1,12 @@
+Unit Tests
+==========
+
+Writing the tests is still work in progress. New functions should be implemented in test-driven
+development fashion. Tests for old functions will be added step by step.
+
+The tests use Zephyr's Ztest framework and the twister tool. Build and run the tests with the
+following command:
+
+.. code-block:: bash
+
+    ../zephyr/scripts/twister -T ./tests --integration --inline-logs -n

_sources/src/dev/workspace_setup.rst.txt

@@ -0,0 +1,52 @@
+
+Workspace Setup
+===============
+
+This guide assumes you have already installed the Zephyr SDK and the ``west`` tool according to the
+`Zephyr documentation <https://docs.zephyrproject.org/latest/getting_started/>`_.
+
+Below commands initialize a new workspace and pull all required source files:
+
+.. code-block:: bash
+
+    # create a new west workspace and pull the BMS firmware
+    west init -m https://github.com/LibreSolar/bms-firmware west-workspace
+    cd west-workspace/bms-firmware
+
+    # pull Zephyr upstream repository and modules (may take a while)
+    west update
+
+Afterwards, most important folders in your workspace will look like this:
+
+.. code-block:: bash
+
+    west-workspace/         # contains .west/config
+    │
+    ├── bms-firmware/       # application firmware repository
+    │   ├── app/            # application source files
+    │   ├── boards/         # board specifications
+    │   ├── tests/          # unit test source files
+    │   └── west.yml        # main manifest file
+    │
+    ├── modules/            # modules imported by Zephyr and BMS firmware
+    |
+    ├── tools/              # tools used by Zephyr
+    │
+    └── zephyr/             # upstream Zephyr repository
+
+If you already have a west workspace set up (e.g. for other Libre Solar firmware), you can also
+re-use it to avoid having many copies of upstream Zephyr and modules:
+
+.. code-block:: bash
+
+    # go to your workspace directory
+    cd your-zephyr-workspace
+
+    # pull the BMS firmware
+    git clone https://github.com/LibreSolar/bms-firmware
+    cd bms-firmware
+
+    # re-configure and update the workspace
+    # (to be done each time you switch between applications in same workspace)
+    west config manifest.path bms-firmware
+    west update

_sources/src/features.rst.txt

@@ -0,0 +1,64 @@
+Features
+========
+
+Amongst all features inherited from underlying Zephyr, the BMS has the following features:
+
+- Monitoring and configuration using the `ThingSet`_ protocol (mapping to MQTT, CoAP and HTTP
+  possible)
+
+  - Serial interface
+  - CAN bus
+  - Bluetooth (not available on all boards)
+
+- Extensions via `UEXT connector`_ possible (depending on hardware)
+
+  - I2C
+  - SPI
+  - UART
+
+- SOC estimation based on coulomb counting
+
+- Configuration options
+
+  - Pack layout
+
+    - Cell chemistry (LiFePO4, NMC, NCA)
+    - Nominal capacity
+    - Number of cells
+    - Thermistor type
+    - Shunt resistor
+    - Custom open circuit voltage (OCV) look-up table
+
+  - Protection
+
+    - Discharge short circuit limit (A)
+    - Discharge short circuit delay (us)
+    - Discharge over-current limit (A)
+    - Discharge over-current delay (ms)
+    - Charge over-current limit (A)
+    - Charge over-current delay (ms)
+    - Cell target charge voltage (V)
+    - Cell discharge voltage limit (V)
+    - Cell over-voltage limit (V)
+    - Cell over-voltage error reset threshold (V)
+    - Cell over-voltage delay (ms)
+    - Cell under-voltage limit (V)
+    - Cell under-voltage error reset threshold (V)
+    - Cell under-voltage delay (ms)
+    - Discharge over-temperature (DOT) limit (°C)
+    - Discharge under-temperature (DUT) limit (°C)
+    - Charge over-temperature (COT) limit (°C)
+    - Charge under-temperature (CUT) limit (°C)
+    - Temperature limit hysteresis (°C)
+
+  - Balancing
+
+    - Enable automatic balancing.
+    - Balancing cell voltage target difference (V)
+    - Minimum cell voltage to start balancing (V)
+    - Current threshold to be considered idle (A)
+    - Minimum idle duration before balancing (s)
+
+
+.. _ThingSet: https://thingset.io
+.. _UEXT connector: https://en.wikipedia.org/wiki/UEXT