BMS tesseracted

.github/workflows/cmake.yml

@@ -7,7 +7,7 @@ name: CMake
 # Define the workflow's triggers
 on:
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 # Set necessary environment variables
 env:
@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      # Checkout the repository, including all submodules
+      # Check out the repository, including all submodules
       - name: Checkout Repository
         uses: actions/checkout@v2
         with:
@@ -30,20 +30,25 @@ jobs:
       - name: Install Compiler and Linter
         run: |
           sudo apt-get install gcc-arm-none-eabi
-          sudo apt-get install clang-format-12
-          sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-12 10000
+          sudo apt-get install clang-format-15
+          sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-15 10000
 
       # Build the code for all supported chips
-      - name: F302 Build
-        run: |
-          cmake -DTARGET_DEV=STM32F302x8 -B ${{github.workspace}}/build
-          cmake --build ${{github.workspace}}/build
+#      - name: F302 Build
+#        run: |
+#          cmake -DTARGET_DEV=STM32F302x8 -B ${{github.workspace}}/build
+#          cmake --build ${{github.workspace}}/build
 
       - name: F334 Build
         run: |
           cmake -DTARGET_DEV=STM32F334x8 -B ${{github.workspace}}/build
           cmake --build ${{github.workspace}}/build
 
+#      - name: F446 Build
+#        run: |
+#          cmake -DTARGET_DEV=STM32F446xx -B ${{github.workspace}}/build
+#          cmake --build ${{github.workspace}}/build
+
       # Apply clang-format formatting to the branch and create a new commit if any files are changed
       - name: Apply Formatting
         run: |
@@ -57,4 +62,4 @@ jobs:
             git config --global user.name "GitHub Build"
             git commit -a -m "Applied Formatting Changes During GitHub Build"
             git push origin
-          fi
+          fi

CMakeLists.txt

@@ -4,9 +4,9 @@
 cmake_minimum_required(VERSION 3.15)
 
 # Convert CMake flags to compiler flags
-if(EVT_CORE_LOG_ENABLE)
+if (EVT_CORE_LOG_ENABLE)
     add_compile_definitions(EVT_CORE_LOG_ENABLE)
-endif()
+endif ()
 
 # Allow for up to 8 CANopen TPDOs
 add_compile_definitions(CO_TPDO_N=8)
@@ -23,11 +23,11 @@ add_compile_definitions(USE_HAL_DRIVER)
 
 # Handle Selection of the target device
 option(TARGET_DEV "Target device" "STM32F302x8")
-if(NOT TARGET_DEV)
+if (NOT TARGET_DEV)
     set(TARGET_DEV "STM32F334x8")
-endif()
+endif ()
 
-set(EVT_CORE_DIR      ${CMAKE_SOURCE_DIR}/libs/EVT-core)
+set(EVT_CORE_DIR ${CMAKE_SOURCE_DIR}/libs/EVT-core)
 
 # Link to the EVT-core library
 add_subdirectory(libs/EVT-core/)
@@ -39,11 +39,11 @@ include(${EVT_CORE_DIR}/cmake/evt-core_install.cmake)
 ###############################################################################
 # Project Setup
 ###############################################################################
-set(BOARD_LIB_NAME   BMS)
-if("${BOARD_LIB_NAME}" STREQUAL BOARD_NAME)
+set(BOARD_LIB_NAME BMS)
+if ("${BOARD_LIB_NAME}" STREQUAL BOARD_NAME)
     message(FATAL_ERROR
             "You must set the template project name in the top-level CMakeLists.txt")
-endif()
+endif ()
 
 file(STRINGS version.txt BOARD_VERSION)
 
@@ -56,22 +56,22 @@ add_library(${PROJECT_NAME} STATIC)
 
 # Add sources
 target_sources(${PROJECT_NAME} PRIVATE
-    src/BMS.cpp
-    src/BQSettingStorage.cpp
-    src/BQSetting.cpp
-    src/ResetHandler.cpp
-    src/SystemDetect.cpp
-    src/dev/BQ76952.cpp
-    src/dev/Interlock.cpp
-    src/dev/ThermistorMux.cpp
+        src/BMS.cpp
+        src/BQSettingStorage.cpp
+        src/BQSetting.cpp
+        src/ResetHandler.cpp
+        src/SystemDetect.cpp
+        src/dev/BQ76952.cpp
+        src/dev/Interlock.cpp
+        src/dev/ThermistorMux.cpp
 )
 
 ###############################################################################
 # Handle dependencies
 ###############################################################################
 target_link_libraries(${PROJECT_NAME}
         PUBLIC EVT
-        )
+)
 
 ###############################################################################
 # Install and expose library

docs/source/BQ/transfer_utility.rst

@@ -36,7 +36,7 @@ diagrams below.
 CANopen
 -------
 
-.. image:: ../_static/images/bq_settings_update_sequence.png
+.. image:: ../_static/images/bq_settings_update_sequence_canopen.png
    :width: 300
    :align: center
 
@@ -78,6 +78,44 @@ Users will interact directly with the scripts in order to execute the
 conversion logic as well as the transfer logic. The remainder of this
 document will go over the specifics of interacting with these scripts.
 
+.. _transfer_over_uart:
+Converting and Transferring over UART
+=====================================
+
+With revision 3 of the BMS, UART was exposed, so we were able to start using
+that interface for transferring settings instead of CAN. Because UART is a
+simpler method of communication, this is generally the preferred method of
+transferring settings to the BMS.
+
+To get started, all you'll need is a BMS, a BMS battery power source, an
+STLink-v3 Mini, and your laptop. Connect the STLink to your computer and the
+BMS, and carefully plug the BMS in. In STM32CubeProgrammer, confirm that you are
+able to connect to the microcontroller.
+
+Next, confirm that you have the Python scripts ready by get the help message for the ``convert_transfer`` command.
+Below is some example output. The python scripts are located in ``tools/bqsettings/``
+
+.. code-block:: bash
+    $ python run.py convert_transfer --help
+
+    usage: run.py convert_transfer [-h] input port
+
+    positional arguments:
+      input       The TI file containing the settings to transfer
+      port        Serial port connected to the BMS
+
+    optional arguments:
+      -h, --help  show this help message and exit
+
+Once this is working, you can begin the transfer process by following these steps:
+
+1. Open a command prompt and navigate to ``BMS/tools/bqsettings``.
+2. Compile and flash ``uart_settings_upload`` to the BMS.
+3. Within 10 seconds [#f1]_, run ``python3 run.py convert_transfer ../parse/settings_3_28_23.gg.csv PORT``, replacing PORT with the usb port, the ST-Link V3 is connected to.
+4. Wait for all settings to be sent to the BMS and written to the EEPROM.
+
+To confirm that settings have been sent successfully and that they don't cause issues with the BQ chip, follow :ref:`_flash_bms`.
+
 Training Module
 ===============
 
@@ -248,55 +286,14 @@ command below to convert the CSV into binary.
 
    python run.py convert output.csv output.bin
 
-Converting and Transferring over UART
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-With revision 3 of the BMS, UART was exposed, so we were able to start using
-that interface for transferring settings instead of CAN. Because UART is a
-simpler method of communication, this is generally the preferred method of
-transferring settings to the BMS.
-
-To get started, all you'll need is a BMS, a BMS battery power source, an
-STLink-v3 Mini, and your laptop. Connect the STLink to your computer and the
-BMS, and carefully plug the BMS in. In STM32CubeProgrammer, confirm that you are
-able to connect to the microcontroller. Next, confirm that you have the Python
-scripts ready by get the help message for the ``convert_transfer`` command.
-Below is some example output.
-
-.. code-block:: bash
-
-    $ python run.py convert_transfer --help
-
-    usage: run.py convert_transfer [-h] input port
-
-    positional arguments:
-      input       The TI file containing the settings to transfer
-      port        Serial port connected to the BMS
-
-    optional arguments:
-      -h, --help  show this help message and exit
-
-Once this is working, you can begin the transfer process by following these
-steps:
-
-1. Open a command prompt and navigate to ``BMS/tools/bqsettings``.
-2. Compile and flash ``uart_settings_upload`` to the BMS.
-3. Within 10 seconds, run ``
-   a. This 10-second time limit is caused by a limitation of EVT-core. It should
-   be fixed in future development.
-4. Wait for all settings to be sent to the BMS and written to the EEPROM.
-
-To confirm that settings have been sent successfully and that they don't cause
-issues with the BQ chip, perform the following steps:
-
-1. Compile and flash bq_interface to the BMS.
-2. Confirm that you have communication with BQ chip ('v').
-3. Transfer settings from the EEPROM to the BQ chip ('t').
-4. Check if you have communication with the BQ chip ('v').
 
 References
 ~~~~~~~~~~
 
 * `BQ76952 3-s to 16-s high-accuracy battery monitor and protector for Li-ion, Li-polymer and LiFePO4 <https://www.ti.com/product/BQ76952>`_
 * `CANopen - The standardized embedded network <https://www.can-cia.org/canopen/>`_
 * `EVT-core <https://evt-core.readthedocs.io/en/latest/>`_
+
+.. rubric:: Footnotes
+
+.. [#f1] This 10-second time limit is caused by a limitation of EVT-core. It should be fixed in future development.

docs/source/testing_setup.rst

@@ -0,0 +1,114 @@
+=========================
+Test setup for BMS v4.0
+=========================
+This document will cover how to set up a test environment for the BMS v4.0.
+
+Getting Started
+===============
+To get started, the settings for the BMS need to be transferred. Follow the steps outlined in :ref:`_transfer_over_uart`. This is a **very** important step and must be done **once** when a board is first brought up.
+
+Loading BMS settings
+--------------------
+Once the settings have been transferred to the BMS, you must transfer them from the STM to the BQ chip. Since we do not freeze the settings on the BQ, we are required to flash the settings **every** time the board is turned on. This is often a source of errors, and settings transfers should always be redone if other errors appear on the BMS.
+
+.. _flash_bms:
+Flashing the BMS
+================
+The testing setup for the BMS uses the ``bq_interface`` target. This should be built, and flashed to the BMS. Flashing should be done using an ST-Link and STM32CubeProgrammer. This is the same `same process <https://sites.google.com/g.rit.edu/evt-home-page/firmware-team/getting-started/running-code>`_ as the rest of our boards.
+
+UART Connection
+---------------
+UART on the BMS uses a baud rate of `115200`. When you first connect to the BMS after flashing ``bq_interface``, you may not have anything in your uart terminal. To fix this, just type h and hit enter to bring up the help menu.
+
+Settings Transfer
+-----------------
+Before you can begin testing BMS functions, you need to transfer the settings. This can be done by entering `t` and waiting for all settings to transfer.
+
+If there are any errors during settings transfer, unplug and replug the board, reflash ``bq_interface``, and try again. Errors in this section are caused by a flaw in BMS v4.0 that fails to hold the BQ reset line low. When the reset line is held high, it will shut down the BQ chip.
+
+Testing
+=======
+You are now ready to start testing BMS functions! For each section, check the values that the BMS reports, then check the real-world value. After checking the real-world value, recheck that the BMS has not changed (just a sanity check).
+
+Testing Voltages
+----------------
+Testing pack voltages is the first step in validating the BMS. First, plug the BMS into a test battery pack. You can then use ``v - Read voltages`` to list out the voltages for every cell.
+
+*Note that on BMS v4.0, the BMS skips cells 8, 10, 12, and 14. Practically, this just requires you to adjust cell numbering after 8 when checking voltages.*
+
+To double-check that the BMS is correctly reading voltages, grab a multimeter with two probes. The voltage of the first cell has a different measurement process than all other cells. This is because every cell is grounded to the previous cell. Since Cell #1 doesn't have a previous cell, you need to use the Batt - pad on the BMS as ground.
+
+The diagram below shows the placement for the positive and negative probes from your multimeter.
+
+.. image:: ./_static/images/cell_1_voltage_measurement.png
+   :align: center
+
+For every other cell (greater than 1), this diagram shows the positions of the positive and negative probes of the multimeter.
+
+.. image:: ./_static/images/cell_voltage_measurement.png
+   :align: center
+
+Test pack balancing
+-------------------
+Checking pack balancing requires you to use a thermal imaging camera to check for heat waste coming off of the cell ICs.
+
+To check cell balancing, use the ``B - Write balancing state`` command. Starting at cell 1, set the balancing state to 1. Point the thermal imaging camera at the cell you just enabled balancing for. If the cell begins to heat up, balancing is working! You should then write the balancing state to 0 and continue through the rest of the cells.
+
+*Note that the BMS v4.0 cells after 8 are not numbered in order. Check "Testing Voltages" for an instruction on how to number cells.*
+
+*Note 2, if you do not have a Thermal Imaging camera, you can place your finger on the IC and wait for it to get warm. BE CAREFUL as the IC gets VERY hot, so remove your finger right as it feels warm.*
+
+Testing Polarity / Current: Paragraph Style
+-------------------------------------------
+Testing pack polarity requires a fairly intricate hardware setup to safely test. It is **VERY** important that you closely look at the following diagram & photo of the setup. The diagram will be used to explain the testing process; it is recommended that you use the photo as a reference for your physical setup. It is recommended that you talk to an electrical team member to get the entire setup right.
+
+.. image:: ./_static/images/pack_polarity_photo.jpeg
+   :align: center
+
+The following diagram will be used to explain the testing process; take a look at it now.
+
+.. image:: ./_static/images/pack_polarity_diagram.png
+   :align: center
+
+The first step to set up the power supply so it can provide a safe current to the BMS for testing:
+1. Set the voltage on the power supply to ~10 mV.
+2. Set the current limit on the power supply all the way down.
+
+The second step is to connect the Battery Pack to the Power Supply. Be **very** careful here, as the battery packs run at a high voltage. To connect the two, connect the Positive line from the battery pack into the Negative line of the power supply.
+
+The next step in testing polarity is to send a positive current through the BMS Current Shunt. This is done by connecting the *Positive Power Supply line (Red)* to the *Positive Bike Battery line (Red)*. Next, connect the *Negative Power Supply line (Gray)* to the *Negative Bike Battery Line (Purple)*. This creates a positive current flow through the BMS's current shunt.
+
+It is now time to read the actual current that the BMS is reading. You should use the ``p - Read Current Shunt Polarity`` command to read the polarity across the shunt. This command should tell you that the polarity is **positive**. In a non-test setup, this would indicate that the battery pack is currently charging.
+
+To test if discharging is being properly detected, you swap how the power supply is connected to the BMS. In this setup, you should connect the *Positive Power Supply line (Red)* to the *Negative Bike Battery Line (Purple)* and the *Negative Power Supply line (Gray)* to the *Positive Bike Battery line (Red)*. This creates a negative current flow through the BMS's current shunt.
+
+Again, it is time to read the actual current that the BMS is reading. You should use the ``p - Read Current Shunt Polarity`` command to read the polarity across the shunt. This command should tell you that the polarity is **negative**. In a non-test setup, this would indicate that the battery pack is currently discharging.
+
+Congrats! You have now tested the BMS current shunt. At this point, unplug the BMS from the power supply, then the battery pack from the power supply. You can then turn off the power supply and clean up!
+
+Testing Polarity / Current: Bulleted Style
+------------------------------------------
+This diagram lays out the connection schema for the testing setup. Lines are colored to match the expected color of testing equipment that is available with the BMS v4.0.
+
+.. image:: ./_static/images/pack_polarity_diagram.png
+   :align: center
+
+Initial Circuit Setup:
+1. Plug two negative leads into the Power Supply.
+2. Plug one positive lead into the Power Supply.
+3. Set the voltage on the power supply to ~10mV.
+4. Set the current limit on the power supply all the way down.
+5. Connect the BMS to the Test Battery Pack.
+6. Connect one of the negative leads from the power supply to the positive line coming out of the test battery pack. You will need an unterminated male connector to do this (available with testing equipment).
+
+Shunt Polarity Testing (Charging):
+1. Connect the *Positive Power Supply line (Red)* to the *Positive Bike Battery line (Red)*.
+2. Connect the *Negative Power Supply line (Gray)* to the *Negative Bike Battery Line (Purple)*.
+3. Use the ``p - Read Current Shunt Polarity`` command.
+4. Ensure that the polarity is **positive**
+
+Shunt Polarity Testing (Discharging):
+1. Connect the *Positive Power Supply line (Red)* to the *Negative Bike Battery Line (Purple)*.
+2. Connect the *Negative Power Supply line (Gray)* to the *Positive Bike Battery line (Red)*.
+3. Use the ``p - Read Current Shunt Polarity`` command.
+4. Ensure that the polarity is **negative**