Software -------- To understand and work with the provided BMS master software it is necessary to have a general knowledge about STM32 microcontroller software and the BMS master hardware. Therefore, read the capter :ref:`Electronic Management System Master` at first and have a look at the following chapter General knowledge - STM32. General knowledge - STM32 ~~~~~~~~~~~~~~~~~~~~~~~~~ Since there are already different documentations and youtube videos for the STM32 development available, here are only some hints which documentation could be helpful. - Getting started with STM32: `STM32 step by step `_ .. hint:: The understanding of step 1 and step 2 are neccessary for the Battery Management software! .. https://www.youtube.com/watch?v=szMGedsp9jc - Specific information for the BMS Software - Link to relevant information of STM32 - `F407 `_ - Download and install the following software tools `software tools `_ - STM32CubeIDE - STM32CubeMX - Tutorials of STM32 - Getting started - `Introduction to STM32CubeIDE and Blinky `_ - `How to use SPI `_ - `Timers and Timer Interrupts `_ - `Working with ADC and DMA `_ Battery Management System - Master ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In general the **Battery Managment System Master** is responsible for monitoring and controling the battery system depending on different input signals. The software itself is running on a STM32-F407 microcontroller by using the peripherie of the microcontroller (SPI, CAN, GPIO, JTAG). The following peripherie of the microcontroller is used: (For detailed information regarding the hardware see chapter :ref:`Electronic Management System Master`.) Communication interfaces (**isoSPI** and **CAN**): - BMS master to BMS slave via isoSPI (to read out the single cell voltages and temperatures) - BMS master to VCU via CAN Components/ Values which are control by the BMS master via **GPIO output**: - BMS error - Negative AIR - Positive AIR - Precharge Relay/ AIR Values which are evaluated by the BMS master via a **GPIO input**: - Shutdown cirucit (SC) - Auxilary contact of the negative AIR - Auxilary contact of the positive AIR - Auxilary contact of the precharge relay/ AIR - BMS latched signal - IMD latched signal - TSAL green - HVIL red - Activate Tractive System (button) - Reset IMD error (button) - Reset BMS error (button) Specific Links for the BMS Master ********************************* .. ToDo: Update the links The documentation of the BMS master software is separated in different smaller documentations to get a more clear and structured documentation. - Link to the git repository with the software implementation. In the source code a lot of comments are provided: `Battery Management System - Software `_ - Generated documentation of the STM32 pin layout by CubeMX: `STM32 pin layout `_ - Generated doxygen documentation out of the BMS software implementation: `Software Documentation `_ Design Software Architecture **************************** The BMS master software is split in two parts. 1. The **generated STM32 part** from the CubeMX project, which should only be adapted by using CubeMX or adapations only made in the specific regions in the generated C code. The generated STM32 part is documented in the STM32 `F407 `_ documentation. Further information are not provided in this documentation. 2. The **specific part** for the battery managment, which can be adapted to the needs of your battery system. In the UML diagram, the specific software files, which can be adapted is shown with .c and .h files. The files, which are marked in red in the UML diagram, **must** be manually adapted by the user depending on the system. .. hint:: If the battery is completely constructed regarding this documentation the preconfigured default files and values can be used. No manual adaption is necessary! .. uml:: :caption: File include structure @startuml skinparam linetype ortho package "C-Files" #APPLICATION { class C::analog_if class C::app_bms_if class C::app_tasks class C::bms_var_states class C::can_if class C::io_if class C::isascale class C::led_if class C::ltc6811_if class C::ltc6811 class C::main } package "H-Files" #CORNSILK { class H::analog_if class H::app_bms_cfg #LIGHTSALMON class H::app_bms_if class H::app_tasks class H::bms_enums class H::bms_var_states class H::can_if_cfg_isascale #LIGHTSALMON class H::can_if_cfg #LIGHTSALMON class H::can_if class H::general_cfg #LIGHTSALMON class H::io_if class H::isascale class H::led_if class H::ltc6811_if_cfg #LIGHTSALMON class H::ltc6811_if class H::ltc6811 class H::main } C::analog_if --> H::analog_if C::app_bms_if --> H::app_bms_if C::app_bms_if --> H::app_bms_cfg C::app_bms_if --> H::bms_var_states C::app_bms_if --> H::io_if C::app_bms_if --> H::main C::app_bms_if --> H::analog_if C::app_bms_if --> H::isascale C::app_tasks --> H::app_bms_if C::app_tasks --> H::can_if C::app_tasks --> H::ltc6811_if C::app_tasks --> H::led_if C::app_tasks --> H::general_cfg C::app_tasks --> H::bms_enums C::bms_var_states --> H::bms_var_states C::can_if --> H::can_if C::can_if --> H::can_if_cfg_isascale C::can_if --> H::bms_var_states C::can_if --> H::isascale C::io_if --> H::main C::io_if --> H::bms_var_states C::isascale --> H::isascale C::led_if --> H::led_if C::led_if --> H::main C::ltc6811_if --> H::ltc6811_if C::ltc6811_if --> H::ltc6811 H::app_bms_if --> H::bms_var_states H::app_bms_if --> H::bms_enums H::bms_var_states --> H::bms_enums H::can_if --> H::can_if_cfg H::io_if --> H::bms_enums H::led_if --> H::bms_enums H::ltc6811_if --> H::ltc6811_if_cfg @enduml The following files must manually be adapted regarding the specific use case if something is changed in the battery concept: - **general_cfg.h** Configure the general parameter which are used for the software as preprocessor switches. .. hint:: Becareful with configuration. Take care of the hints provided in the comments above. - **app_bms_cfg.h** Configure manually the cell parameters voltage and temperature for used cell. - **can_if_cfg_isascale.h** Configure manually the CAN IDs for the isascale. The following table shows the default CAN IDs which are used for default. - **can_if_cfg.h** Configure the CAN IDs for the cell voltages, cell temperatures and general values. The following tables show the default CAN IDs which are used for default. - **ltc6811_if_cfg.h**: ToDo Configure the parameter depending on the used BMS slave hardware and the used temperature sensor. CAN messages ************ For the communication between the BMS master and the VCU (vehicle control unit) CAN messages are used. The following tables give an overview over the preconfigured CAN messages in the *can_if_cfg.h*. .. csv-table:: Overview of the CAN message IDs :header: "CAN ID", "CAN messages content", "type" "0x200", "Average values, Sum of Voltage", "Transmit" "0x201", "Min, Max value of Voltage", "Transmit" "0x202", "Min, Max value of Temperature", "Transmit" "0x203", "Error States", "Transmit" "0x521", "Isascale: I", "Receive" "0x522", "Isascale: U1", "Receive" "0x523", "Isascale: U2", "Receive" "0x524", "Isascale: U3", "Receive" "0x600", "All Cell Voltages (multiplexed)", "Transmit" "0x601", "All Cell Temperatures (multiplexed)", "Transmit" .. csv-table:: Structure of CAN message 0x200 :header: "Position (Byte)", "Content" "0", "Average voltage value calculated over all cells (high byte)" "1", "Average voltage value calculated over all cells (low byte)" "2", "Average temperature value calculated over all cells (high byte)" "3", "Average temperature value calculated over all cells (low byte)" "4", "Sum of all cells (high byte)" "5", "Sum of all cells (low byte)" .. csv-table:: Structure of CAN message 0x201 :header: "Position (Byte)", "Content" "0", "ID of the cell with the minimum voltage" "1", "Value of the cell with the minimum voltage (high byte)" "2", "Value of the cell with the minimum voltage (low byte)" "3", "ID of the cell with the maximum voltage" "4", "Value of the cell with the maximum voltage (high byte)" "5", "Value of the cell with the maximum voltage (low byte)" .. csv-table:: Structure of CAN message 0x202 :header: "Position (Byte)", "Content" "0", "ID of the cell with the minimum temperature" "1", "Value of the cell with the minimum temperature (high byte)" "2", "Value of the cell with the minimum temperature (low byte)" "3", "ID of the cell with the maximum temperature" "4", "Value of the cell with the maximum temperature (high byte)" "5", "Value of the cell with the maximum temperature (low byte)" .. csv-table:: Structure of CAN message 0x203 :header: "Position (Byte)", "Position (Bit)", "Content", "Description" "0", "0", "State of IMD reset button", "0: Released 1: Pressed" "0", "1", "State of BMS reset button", "0: Released 1: Pressed" "0", "2", "State of TS button", "0: Released 1: Pressed" "1", "0", "Error state: Undervoltage", "0: No error 1: Error" "1", "1", "Error state: Overvoltage", "0: No error 1: Error" "1", "2", "Error state: Undertemperature", "0: No error 1: Error" "1", "3", "Error state: Overtemperature", "0: No error 1: Error" "1", "4", "Error state: Overcurrent discharge", "0: No error 1: Error" "1", "4", "Error state: Overcurrent charge", "0: No error 1: Error" And the specific CAN messages for the isascale configured in the file *can_if_cfg_isascale.h*. .. csv-table:: Structure of CAN message 0x521 :header: "Position (Byte)", "Content" "2", "Current value (Byte 1)" "3", "Current value (Byte 2)" "4", "Current value (Byte 3)" "5", "Current value (Byte 4)" .. csv-table:: Structure of CAN message 0x522 :header: "Position (Byte)", "Content" "2", "U1 value (Byte 1)" "3", "U1 value (Byte 2)" "4", "U1 value (Byte 3)" "5", "U1 value (Byte 4)" .. csv-table:: Structure of CAN message 0x523 :header: "Position (Byte)", "Content" "2", "U2 value (Byte 1)" "3", "U2 value (Byte 2)" "4", "U2 value (Byte 3)" "5", "U2 value (Byte 4)" .. csv-table:: Structure of CAN message 0x524 :header: "Position (Byte)", "Content" "2", "U3 value (Byte 1)" "3", "U3 value (Byte 2)" "4", "U3 value (Byte 3)" "5", "U3 value (Byte 4)" How to connect, flash and debug ******************************* Possible commissioning preprocessor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Monitoring Software ~~~~~~~~~~~~~~~~~~~ Still under construction.... .. ToDo: Update the repo link Link to the git repository: `Monitoring Software `_