deploy: d71e544

.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,44 @@
+======================================
+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/simulator
+    src/dev/unit_tests
+
+.. toctree::
+    :caption: API Reference
+    :hidden:
+
+    src/api/bms
+    src/api/bms_ic
+    src/api/data_objects
+    src/api/misc

_sources/src/api/bms.rst.txt

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

_sources/src/api/bms_ic.rst.txt

@@ -0,0 +1,5 @@
+BMS front-end IC driver
+=======================
+
+.. doxygenfile:: include/drivers/bms_ic.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,89 @@
+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
+
+Boards with ESP32 MCU
+"""""""""""""""""""""
+
++-----------------------------+----------------------+----------------+
+| Board with ESP32 MCU        | board-name           | revision(s)    |
++=============================+======================+================+
+| Libre Solar BMS C1          | bms_c1               | 0.4, 0.3       |
++-----------------------------+----------------------+----------------+
+
+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 using the board name and revision from the table
+above:
+
+.. code-block:: bash
+
+    west build -b <board-name>@<revision>
+    west flash
+
+We recommend ``picocom`` as a serial console under Linux. Add ``--lower-dtr`` in order
+to reset the board before connecting, so that the entire log output during boot can be seen.
+
+.. code-block:: bash
+
+    picocom /dev/ttyACM0 --lower-dtr
+
+Press Ctrl+a followed by q to exit.
+
+Boards with STM32 MCU
+"""""""""""""""""""""
+
++-----------------------------+----------------------+----------------+
+| Board with STM32 MCU        | board-name           | revision(s)    |
++=============================+======================+================+
+| Libre Solar BMS 5S50 SC     | bms_5s50_sc          | 0.1            |
++-----------------------------+----------------------+----------------+
+| Libre Solar BMS 15S80 SC    | bms_15s80_sc         | 0.1            |
++-----------------------------+----------------------+----------------+
+| Libre Solar BMS 16S100 SC   | bms_16s100_sc        | 0.2            |
++-----------------------------+----------------------+----------------+
+| Libre Solar BMS 8S50 IC     | bms_8s50_ic          | 0.2, 0.1       |
++-----------------------------+----------------------+----------------+
+| Libre Solar BMS-8S50-IC *   | bms_8s50_ic_f072     | 0.1            |
++-----------------------------+----------------------+----------------+
+
+(*) Only for BMS-8S50-IC with STM32F072 MCU.
+
+Supported hardware is further described in :doc:`../supported_hardware`.
+
+Build and flash the firmware using the board name and revision from the table above:
+
+.. code-block:: bash
+
+    west build -b <board-name>@<revision>
+    west flash
+
+The revision 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.
+
+For flashing with a specific debug probe (runner), e.g. J-Link, use the following command:
+
+.. code-block:: bash
+
+    west flash -r jlink
+
+We recommend ``picocom`` as a serial console under Linux:
+
+.. code-block:: bash
+
+    picocom -b 115200 /dev/ttyACM0
+
+Press Ctrl+a followed by q 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/simulator.rst.txt

@@ -0,0 +1,13 @@
+Simulator
+=========
+
+Zephyr allows to run an application on a Linux or Mac hosts using the ``native_sim`` board.
+
+The BMS firmware currently does not mock an entire BMS IC. However, the simulated application
+allows to test the ThingSet communication and other basic features.
+
+Execute the following command to run the simulated application:
+
+.. code-block:: bash
+
+    west build -b native_sim -t run

_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