1. Configuration

foxBMS 2 is an embedded system and some parts of the code are near to the hardware level. The code relies on a Hardware Abstraction Layer (HAL), which is a set of functions and definitions acting as an interface between the application and the underlying hardware. The HAL must be configured to fit the application and the hardware the software is running on (e.g., configure IO pins for communication with the outside world). This configuration is done with software called TI HALCoGen. This is described in TI HALCoGen.

Another point is that foxBMS 2 is a development platform. As such, many parts of the code must be configured to fit the target application (e.g., which monitoring IC is used to monitor the battery cells). This is explained in BMS Application.

1.1. TI HALCoGen

TI HALCoGen is a graphical user interface used to configure the HAL sources. It generates sources in the form of .h, .c and .asm files. These HAL sources are generated based on the TI HALCoGen configuration files (*.hcg and *.dil). The respective configuration files are found

• for the application at:

  • conf/hcg/app.hcg

  • conf/hcg/app.dil

• for the bootloader at:

  • conf/hcg/bootloader.hcg

  • conf/hcg/bootloader.dil

foxBMS 2 uses the Waf tool waf_tools.hcg to automatically run TI HALCoGen and create the required sources. Additional information on the tool can be found in TI HALCoGen Tool.

Note

In some cases it might be beneficial to not generate the HAL during the build step and instead use a generated version of the HAL. For this use case see How to Use Generated Sources from HALCoGen.

TI HALCoGen ships with its own version of FreeRTOS and generates the corresponding sources when running the code generator. As foxBMS 2 uses its own copy of FreeRTOS, the generated FreeRTOS files from TI HALCoGen are removed after the code generator has run.

Furthermore, generated sources listed in conf/hcg/app-remove.yml (application) and conf/hcg/bootloader-remove.yml (bootloader) are removed by the build integration.

The startup source check uses target-specific hash files:

• src/app/hal/app-startup.hash for the application build

• src/bootloader/hal/bootloader-startup.hash for the bootloader build

1.1.1. Enabling Cache

The TI TMS570LC4357 can use cache to improve performance.

• From foxBMS 2 v1.3.0 to v1.11.0, cache is enabled by setting the define OS_ENABLE_CACHE in src/app/task/os/os.h to true. In newer versions than v1.11.0, cache is enabled by setting mcu:↳use-cache: to true in conf/bms/bms.json. Therefore, the configuration setting in HALCoGen is ignored. However, as the startup code generated in HL_sys_startup.c by TI HALCoGen does still change (the line to activate cache is added), consequently the hash in src/app/hal/app-startup.hash still needs to be updated, but no further changes need to be applied. The process to enable cache is then as follows:

  • Enable cache by applying the cache setting dependent on the foxBMS 2 version.

  • Update the file hash in src/app/hal/app-startup.hash

• Before foxBMS 2 v1.3.0, enabling cache relied on the TI HALCoGen configuration and that this setting altered the startup code in HL_sys_startup.c. The cache enable setting is found at setting TMS570LC4357ZWT_FREERTOS, sub-setting R5-MPU-PMU and then the configuration Cortex-R5, sub-configuration General Configuration : Enable Cache. The process to enable cache is then as follows:

  • Enable cache in TI HALCoGen

  • Update the startup code in fstartup.c with the changes from HL_sys_startup.c.

  • Update the file hash in src/app/hal/app-startup.hash

1.2. BMS Application

The project provides two very basic configuration options:

1. general options in conf/bms/bms.json. This file is case-sensitive and all settings need to be in lower-case.

Furthermore, the used battery cells and the general configuration of the battery system that is built up need to be defined:

• for the used battery cell:

  • conf/bms/battery_cell_cfg.json

• for the top level view on the battery system:

  • conf/bms/battery_system_cfg.json

However, the actual behavior of the battery system in the target application is highly dependent on the target application and can therefore not simply be configured through some switches. This needs to be implemented in e.g., the BMS_Trigger() function. It is up to the developer to familiarize with the hardware, code and documentation and adapt the source code to the application-specific requirements.

1.2.1. General Options

Some BMS configurations require compiling different sources. That applies to the operating system and the Analog Front-End.

Note

Only very basic configurations can be changed via these options described here. Again, everything not mentioned here must still be configured by programming the application behavior in the source code.

The main keys

• application,

• bms-slave,

• debug (optional), and

• rtos.

are described in the following subsections.

1.2.1.1. application

1.2.1.1.1. application:↳algorithm

The algorithms key requires one key: state-estimation.

Supported settings:

• application:↳algorithm:↳state-estimation:↳soc: "counting", "debug", or null to disable the SOC algorithm

• application:↳algorithm:↳state-estimation:↳soe: "counting", "debug", or null to disable the SOE algorithm

• application:↳algorithm:↳state-estimation:↳sof: "trapezoid"

• application:↳algorithm:↳state-estimation:↳soh: "debug", or null to disable the SOH algorithm

1.2.1.1.2. application:↳balancing-strategy

Supported settings:

• "voltage": Voltage-based balancing: Cell balancing based on voltage differences. Details are found in Voltage-based Balancing

• "history": History-based balancing: Cell balancing based on voltage history. Details are found in History-based Balancing

• null: No balancing of any cell. Details are found in No Balancing

1.2.1.1.3. application:↳current-sensor

Currently only CAN-based current sensors are supported.

The manufacturer, model and the type of connection of the Insulation Monitoring Device must be provided:

• application:↳current-sensor:↳type: must be "can"

• application:↳current-sensor:↳manufacturer

• application:↳current-sensor:↳model

Supported devices:

• isabellenhuette: ivt-s

• lem: cab500

1.2.1.1.4. application:↳insulation-monitoring-device

In case no Insulation Monitoring Device is used, the entire key application:↳insulation-monitoring-device needs to be removed.

The manufacturer, model and the type of connection of the Insulation Monitoring Device must be provided:

• application:↳insulation-monitoring-device:↳type (either can or pwm)

• application:↳insulation-monitoring-device:↳manufacturer

• application:↳insulation-monitoring-device:↳model

Supported devices:

• bender: ir155, iso165c

Developer notes:

• The joint path from the values of manufacturer and model must be the name of the source directory in src/app/driver/imd/<manufacturer>/<model> that includes the driver implementation.

• Every Insulation Monitoring Device needs to provide its include directories via a Waf target named {ip}imd-<manufacturer>_<model> using export_includes in the corresponding wscript file at src/app/driver/imd/<manufacturer>/<model>/wscript.

1.2.1.2. bms-slave

bms-slave requires defining analog-front-end and temperature-sensor.

• analog-front-end: The manufacturer and the IC must be provided. Valid settings are:

  • adi

    • ades1830

  • debug

    • can

    • default

  • ltc

    • 6804-1

    • 6806

    • 6811-1

    • 6812-1

    • 6813-1

  • maxim:

    • max17852

  • nxp

    • mc33775a

  • st

  • ti

    • dummy

• temperature-sensor: The manufacturer, model and the evaluation method of the temperature sensor must be provided.

The list of supported ICs is also found in Section 4.19.3.1.

Developer notes:

• The joint path from the values of manufacturer and ic must be the name of the source directory in src/app/driver/afe/<manufacturer>/<ic> that includes the driver implementation.

• Every AFE needs to provide its include directories via a Waf target named {ip}afe-<manufacturer>_<ic> using export_includes in the corresponding wscript file at src/app/driver/afe/<manufacturer>/<ic>/wscript.

• The build process behind this configuration is documented at Building the Analog Front-End Library.

1.2.1.3. debug

Some features are only useful when debugging, and should not be enabled in the final application build. UART can be added as a debug interface as follows (debug:↳interfaces:↳["uart"]).

1.2.1.4. rtos

The RTOS name must be defined in rtos:↳name:"<name>", where <name> is the name of desired operating system. Currently only FreeRTOS is supported (rtos:↳name:"freertos").

FreeRTOS supports TCP/IP when the following TCP/IP addon is enabled by adding freertos-plus-tcp to the addon list (rtos:↳addons:↳["freertos-plus-tcp"]).

Developer notes:

• The name must correspond to the directory in source tree where the RTOS sources are (e.g., for freertos it needs to be at src/os/freertos)

• The value for os must be the name of the source directory in src/os/ that includes the operating system sources.

• Every RTOS needs to provide its include directories via a Waf target named {ip}rtos-<kernel|tcp> using export_includes in the corresponding wscript file at src/os/freertos/<name>/wscript.

1.2.2. Compiler and Linker Options and Remarks

The details of the project compiler configuration are described in Compiler Configuration.

1.2.3. Basic Battery Cell And System Configuration

1.2.3.1. Battery Cell Configuration

The basic parameters of the used battery cell of the battery system are defined in:

• conf/bms/battery_cell_cfg.json

The following parameters need to be defined (the links lead to the doxygen documentation for the explanation of the specific parameter) in conf/bms/battery_cell_cfg.json:

Setting	Details (define name)
Maximum discharge temperature MSL	BC_TEMPERATURE_MAX_DISCHARGE_MSL_ddegC
Maximum discharge temperature RSL	BC_TEMPERATURE_MAX_DISCHARGE_RSL_ddegC
Maximum discharge temperature MOL	BC_TEMPERATURE_MAX_DISCHARGE_MOL_ddegC
Minimum discharge temperature MSL	BC_TEMPERATURE_MIN_DISCHARGE_MSL_ddegC
Minimum discharge temperature RSL	BC_TEMPERATURE_MIN_DISCHARGE_RSL_ddegC
Minimum discharge temperature MOL	BC_TEMPERATURE_MIN_DISCHARGE_MOL_ddegC
Maximum temperature limit during charge MSL	BC_TEMPERATURE_MAX_CHARGE_MSL_ddegC
Maximum temperature limit during charge RSL	BC_TEMPERATURE_MAX_CHARGE_RSL_ddegC
Maximum temperature limit during charge MOL	BC_TEMPERATURE_MAX_CHARGE_MOL_ddegC
Minimum temperature limit during discharge MSL	BC_TEMPERATURE_MIN_CHARGE_MSL_ddegC
Minimum temperature limit during discharge RSL	BC_TEMPERATURE_MIN_CHARGE_RSL_ddegC
Minimum temperature limit during discharge MOL	BC_TEMPERATURE_MIN_CHARGE_MOL_ddegC
Maximum cell voltage limit MSL	BC_VOLTAGE_MAX_MSL_mV
Maximum cell voltage limit RSL	BC_VOLTAGE_MAX_RSL_mV
Maximum cell voltage limit MOL	BC_VOLTAGE_MAX_MOL_mV
Nominal cell voltage	BC_VOLTAGE_NOMINAL_mV
Minimum cell voltage limit MSL	BC_VOLTAGE_MIN_MSL_mV
Minimum cell voltage limit RSL	BC_VOLTAGE_MIN_RSL_mV
Minimum cell voltage limit MOL	BC_VOLTAGE_MIN_MOL_mV
Maximum discharge current limit MSL	BC_CURRENT_MAX_DISCHARGE_MSL_mA
Maximum discharge current limit RSL	BC_CURRENT_MAX_DISCHARGE_RSL_mA
Maximum discharge current limit MOL	BC_CURRENT_MAX_DISCHARGE_MOL_mA
Maximum charge current limit MSL	BC_CURRENT_MAX_CHARGE_MSL_mA
Maximum charge current limit RSL	BC_CURRENT_MAX_CHARGE_RSL_mA
Maximum charge current limit MOL	BC_CURRENT_MAX_CHARGE_MOL_mA
Cell capacity used for SOC calculation	BC_CAPACITY_mAh
Cell energy	BC_ENERGY_Wh

The state of charge lookup table bc_stateOfChargeLookupTable is defined in conf/bms/battery_cell_soc_lookup-table.csv and the state of energy lookup table bc_stateOfEnergyLookupTable is defined in conf/bms/battery_cell_soe_lookup-table.csv.

1.2.3.2. Battery System Configuration

The basic, top level view on the battery system configuration is defined at:

• conf/bms/battery_system_cfg.json

• src/app/application/config/bms-slave_cfg.h

Setting	Details (define name)
Defines whether discharge current is seen as positive or negative	BS_POSITIVE_DISCHARGE_CURRENT
Number of parallel strings in the battery pack	BS_NR_OF_STRINGS
Number of modules in a string	BS_NR_OF_MODULES_PER_STRING
Number of cells per module	BS_NR_OF_CELL_BLOCKS_PER_MODULE
Number of battery cells in a parallel cell connection per battery module	BS_NR_OF_PARALLEL_CELLS_PER_CELL_BLOCK
Number of temperature sensors per battery module	BS_NR_OF_TEMP_SENSORS_PER_MODULE
Delay in ms after which it is considered the current measurement is not responding anymore	BS_CURRENT_MEASUREMENT_RESPONSE_TIMEOUT_ms
Delay in ms after which it is considered the coulomb counting is not responding anymore	BS_COULOMB_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_ms
Delay in ms after which it is considered the energy counting is not responding anymore	BS_ENERGY_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_ms
Maximum break current of main contactors	BS_MAIN_CONTACTORS_MAXIMUM_BREAK_CURRENT_mA
Maximum fuse trigger duration	BS_MAIN_FUSE_MAXIMUM_TRIGGER_DURATION_ms
Maximum string current limit in mA that is used in the SOA module	BS_MAXIMUM_STRING_CURRENT_mA
Define if interlock feedback should be discarded or not	BS_IGNORE_INTERLOCK_FEEDBACK
Defines whether CAN timing shall be evaluated or not	BS_CHECK_CAN_TIMING
Defines whether balancing shall be available or not	BS_BALANCING_DEFAULT_INACTIVE
Number of contactors in addition to string contactors (e.g., precharge)	BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS
Current threshold for determining rest state of battery	BS_REST_CURRENT_mA
Wait time in 10ms before battery system is at rest	BS_RELAXATION_PERIOD_10ms
Current sensor threshold for 0 current in mA as the sensor has a jitter	BS_CS_THRESHOLD_NO_CURRENT_mA
Maximum voltage drop over fuse	BS_MAX_VOLTAGE_DROP_OVER_FUSE_mV
Defines whether fuse shall be checked in NORMAL path or not	BS_CHECK_FUSE_PLACED_IN_NORMAL_PATH
Defines whether fuse shall be checked in CHARGE path or not	BS_CHECK_FUSE_PLACED_IN_CHARGE_PATH

The symbolic names of the individual strings need to be adapted in BS_STRING_ID_e to the actual number of strings in the battery system.

The configuration array bs_stringsWithPrecharge needs to define whether a string can be used for precharging or not. This configuration array uses the entries in BS_STRING_ID_e for the assignment.