foxBMS  1.1.1
The foxBMS Battery Management System API Documentation
battery_system_cfg.h File Reference

Configuration of the battery system (e.g., number of battery modules, battery cells, temperature sensors) More...

#include "general.h"
Include dependency graph for battery_system_cfg.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define POSITIVE_DISCHARGE_CURRENT   (true)
 
#define BS_NR_OF_STRINGS   (3u)
 
#define BS_NR_OF_MODULES   (1u)
 number of modules in battery pack More...
 
#define BS_NR_OF_CELLS_PER_MODULE   (18u)
 number of battery cells per battery module (parallel cells are counted as one) More...
 
#define BS_NR_OF_PARALLEL_CELLS_PER_MODULE   (1u)
 number of battery cells in a parallel cell connection per battery module More...
 
#define BS_MAX_SUPPORTED_CELLS   (18u)
 Defines the maximal number of supported cells per module. More...
 
#define BS_BALANCING_RESISTANCE_ohm   (100.0)
 
#define BS_NR_OF_GPIOS_PER_MODULE   (9u)
 Number of GPIOs on the LTC IC. More...
 
#define BS_NR_OF_TEMP_SENSORS_PER_MODULE   (8u)
 number of temperature sensors per battery module More...
 
#define BS_NR_OF_BAT_CELLS   (BS_NR_OF_MODULES * BS_NR_OF_CELLS_PER_MODULE)
 
#define BS_NR_OF_TEMP_SENSORS_PER_STRING   (BS_NR_OF_MODULES * BS_NR_OF_TEMP_SENSORS_PER_MODULE)
 
#define BS_NR_OF_TEMP_SENSORS   (BS_NR_OF_TEMP_SENSORS_PER_STRING * BS_NR_OF_STRINGS)
 
#define BS_NR_OF_TEMP_SENSORS_ON_ADC0   (3u)
 
#define BS_NR_OF_TEMP_SENSORS_ON_ADC1   (3u)
 
#define CURRENT_SENSOR_PRESENT   (false)
 
#define CURRENT_SENSOR_ISABELLENHUETTE_CYCLIC
 
#define BS_CURRENT_MEASUREMENT_RESPONSE_TIMEOUT_MS   (200u)
 
#define BS_COULOMB_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS   (2000u)
 
#define BS_ENERGY_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS   (2000u)
 
#define BS_MAXIMUM_STRING_CURRENT_mA   (10000u)
 Maximum string current limit in mA that is used in the SOA module to check for string overcurrent. More...
 
#define BS_MAXIMUM_PACK_CURRENT_mA   (10000u * BS_NR_OF_STRINGS)
 Maximum pack current limit in mA that is used in the SOA module to check for pack overcurrent. More...
 
#define CHECK_CAN_TIMING   (true)
 
#define BALANCING_DEFAULT_INACTIVE   (true)
 
#define BMS_CHECK_SOF_CURRENT_LIMITS   (true)
 Checking if current is in SOF limits of cells. More...
 
#define BMS_OPEN_CONTACTORS_ON_INSULATION_ERROR   (false)
 Defines behaviour if an insulation error is detected. More...
 
#define BS_NR_OF_VOLTAGES_FROM_CURRENT_SENSOR   (3u)
 number of high voltage inputs measured by current sensors (like IVT-MOD) More...
 
#define BS_NR_OF_VOLTAGES_FROM_MCU_ADC   (2)
 number of voltages measured by MCU internal ADC More...
 
#define BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS   (1U)
 
#define BS_NR_OF_CONTACTORS   ((2U * BS_NR_OF_STRINGS) + BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS)
 
#define BS_SEPARATE_POWER_PATHS   (1)
 separation of charge and discharge power line More...
 
#define BS_REST_CURRENT_mA   (200)
 current threshold for determing rest state of battery. If absolute current is below this limit value the battery is resting. More...
 
#define BS_RELAXATION_PERIOD_10ms   (60000u)
 Wait time in 10ms before battery system is at rest. Balancing for example only starts if battery system is at rest. More...
 
#define BS_CS_THRESHOLD_NO_CURRENT_mA   (200u)
 current sensor threshold for 0 current in mA as the sensor has a jitter. More...
 
#define BS_MAX_VOLTAGE_DROP_OVER_FUSE_mV   (500)
 Maximum voltage drop over fuse. More...
 
#define BS_CHECK_FUSE_PLACED_IN_NORMAL_PATH   (true)
 TODO. More...
 
#define BS_CHECK_FUSE_PLACED_IN_CHARGE_PATH   (false)
 TODO. More...
 

Typedefs

typedef enum BS_STRING_PRECHARGE_PRESENT BS_STRING_PRECHARGE_PRESENT_e
 
typedef enum BS_STRING_ID BS_STRING_ID_e
 

Enumerations

enum  BS_STRING_PRECHARGE_PRESENT { BS_STRING_WITH_PRECHARGE , BS_STRING_WITHOUT_PRECHARGE }
 
enum  BS_STRING_ID { BS_STRING0 = 0u , BS_STRING1 = 1u , BS_STRING2 = 2u , BS_STRING_MAX = 3u }
 

Variables

BS_STRING_PRECHARGE_PRESENT_e bs_stringsWithPrecharge [BS_NR_OF_STRINGS]
 

Detailed Description

Configuration of the battery system (e.g., number of battery modules, battery cells, temperature sensors)

SPDX-License-Identifier: BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

We kindly request you to use one or more of the following phrases to refer to foxBMS in your hardware, software, documentation or advertising materials:

  • ″This product uses parts of foxBMS®″
  • ″This product includes parts of foxBMS®″
  • ″This product is derived from foxBMS®″
Author
foxBMS Team
Date
2019-12-10 (date of creation)
Updated
2021-06-09 (date of last update)
Prefix
BS

This files contains basic macros of the battery system in order to derive needed inputs in other parts of the software. These macros are all depended on the hardware.

Definition in file battery_system_cfg.h.

Macro Definition Documentation

◆ BALANCING_DEFAULT_INACTIVE

#define BALANCING_DEFAULT_INACTIVE   (true)
  • If set to true, balancing is deactivated completely.
    • If set to false, foxBMS checks when balancing must be done and activates it accordingly.

Definition at line 227 of file battery_system_cfg.h.

◆ BMS_CHECK_SOF_CURRENT_LIMITS

#define BMS_CHECK_SOF_CURRENT_LIMITS   (true)

Checking if current is in SOF limits of cells.

If set to true the current is checked against the SOF limits. If set to false the current is checked against the constant values for charging and discharging:

Definition at line 244 of file battery_system_cfg.h.

◆ BMS_OPEN_CONTACTORS_ON_INSULATION_ERROR

#define BMS_OPEN_CONTACTORS_ON_INSULATION_ERROR   (false)

Defines behaviour if an insulation error is detected.

  • If set to true: contactors will be opened
    • If set to false: contactors will NOT be opened

Definition at line 252 of file battery_system_cfg.h.

◆ BS_BALANCING_RESISTANCE_ohm

#define BS_BALANCING_RESISTANCE_ohm   (100.0)

Value of the balancing resistors on the slave-board

Definition at line 139 of file battery_system_cfg.h.

◆ BS_CHECK_FUSE_PLACED_IN_CHARGE_PATH

#define BS_CHECK_FUSE_PLACED_IN_CHARGE_PATH   (false)

TODO.

Set to true if fuse in CHARGE path should be checked. This can only be done if one dedicated HV measurement is used to monitor voltage directly after the fuse. Then a voltage difference between V_bat and V_fuse indicates a tripped fuse.

V_bat +---—+ V_fuse Precharge/Charge+ contactor --—+—| FUSE |--—+---------—/ --------------— +---—+

Definition at line 345 of file battery_system_cfg.h.

◆ BS_CHECK_FUSE_PLACED_IN_NORMAL_PATH

#define BS_CHECK_FUSE_PLACED_IN_NORMAL_PATH   (true)

TODO.

Set to true if fuse in NORMAL path should be checked. This can only be done if one dedicated HV measurement is used to monitor the voltage directly after the fuse. Then a voltage difference between V_bat and V_fuse indicates a tripped fuse.

V_bat +---—+ V_fuse Precharge/Main+ contactor --—+—| FUSE |--—+---------—/ --------------— +---—+

Definition at line 332 of file battery_system_cfg.h.

◆ BS_COULOMB_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS

#define BS_COULOMB_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS   (2000u)

Delay in ms after which it is considered the coulomb counting is not responding anymore.

Definition at line 192 of file battery_system_cfg.h.

◆ BS_CS_THRESHOLD_NO_CURRENT_mA

#define BS_CS_THRESHOLD_NO_CURRENT_mA   (200u)

current sensor threshold for 0 current in mA as the sensor has a jitter.

Definition at line 306 of file battery_system_cfg.h.

◆ BS_CURRENT_MEASUREMENT_RESPONSE_TIMEOUT_MS

#define BS_CURRENT_MEASUREMENT_RESPONSE_TIMEOUT_MS   (200u)

Delay in ms after which it is considered the current measurement is not responding anymore.

Definition at line 189 of file battery_system_cfg.h.

◆ BS_ENERGY_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS

#define BS_ENERGY_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS   (2000u)

Delay in ms after which it is considered the energy counting is not responding anymore.

Definition at line 195 of file battery_system_cfg.h.

◆ BS_MAX_SUPPORTED_CELLS

#define BS_MAX_SUPPORTED_CELLS   (18u)

Defines the maximal number of supported cells per module.

◆ BS_MAX_VOLTAGE_DROP_OVER_FUSE_mV

#define BS_MAX_VOLTAGE_DROP_OVER_FUSE_mV   (500)

Maximum voltage drop over fuse.

If the measured voltage difference between battery voltage voltage after fuse is larger than this value. It can be concluded, that the fuse has tripped. The voltage difference can be estimated by the maximum current and the resistance. For a Cooper Bussmann 1000A fuse the voltage drop can be estimated to: I_max = 1000A and P_loss = 206W -> voltage drop at 1000A roughly 206mV -> select 500mV because of measurement inaccuracies

Definition at line 319 of file battery_system_cfg.h.

◆ BS_MAXIMUM_PACK_CURRENT_mA

#define BS_MAXIMUM_PACK_CURRENT_mA   (10000u * BS_NR_OF_STRINGS)

Maximum pack current limit in mA that is used in the SOA module to check for pack overcurrent.

When maximum safety limit (MSL) is violated, error state is requested and contactors will open.

Definition at line 213 of file battery_system_cfg.h.

◆ BS_MAXIMUM_STRING_CURRENT_mA

#define BS_MAXIMUM_STRING_CURRENT_mA   (10000u)

Maximum string current limit in mA that is used in the SOA module to check for string overcurrent.

When maximum safety limit (MSL) is violated, error state is requested and contactors will open.

Definition at line 205 of file battery_system_cfg.h.

◆ BS_NR_OF_BAT_CELLS

#define BS_NR_OF_BAT_CELLS   (BS_NR_OF_MODULES * BS_NR_OF_CELLS_PER_MODULE)

number of (not parallel) battery cells in the system

Definition at line 161 of file battery_system_cfg.h.

◆ BS_NR_OF_CELLS_PER_MODULE

#define BS_NR_OF_CELLS_PER_MODULE   (18u)

number of battery cells per battery module (parallel cells are counted as one)

Type
uint

Definition at line 109 of file battery_system_cfg.h.

◆ BS_NR_OF_CONTACTORS

#define BS_NR_OF_CONTACTORS   ((2U * BS_NR_OF_STRINGS) + BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS)

Number of contactors. One per string + main and precharge

Definition at line 273 of file battery_system_cfg.h.

◆ BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS

#define BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS   (1U)

Number of contactors in addition to string contactors (e.g., PRECHARGE).

Definition at line 270 of file battery_system_cfg.h.

◆ BS_NR_OF_GPIOS_PER_MODULE

#define BS_NR_OF_GPIOS_PER_MODULE   (9u)

Number of GPIOs on the LTC IC.

  • 5 for 12 cell version
    • 9 for 18 cell version

Definition at line 150 of file battery_system_cfg.h.

◆ BS_NR_OF_MODULES

#define BS_NR_OF_MODULES   (1u)

number of modules in battery pack

Type
uint

Definition at line 101 of file battery_system_cfg.h.

◆ BS_NR_OF_PARALLEL_CELLS_PER_MODULE

#define BS_NR_OF_PARALLEL_CELLS_PER_MODULE   (1u)

number of battery cells in a parallel cell connection per battery module

Type
uint

Definition at line 117 of file battery_system_cfg.h.

◆ BS_NR_OF_STRINGS

#define BS_NR_OF_STRINGS   (3u)

Number of strings in system

Definition at line 89 of file battery_system_cfg.h.

◆ BS_NR_OF_TEMP_SENSORS

#define BS_NR_OF_TEMP_SENSORS   (BS_NR_OF_TEMP_SENSORS_PER_STRING * BS_NR_OF_STRINGS)

number of temperature sensors in the battery system

Definition at line 165 of file battery_system_cfg.h.

◆ BS_NR_OF_TEMP_SENSORS_ON_ADC0

#define BS_NR_OF_TEMP_SENSORS_ON_ADC0   (3u)

number of temperature sensors on each ADC0 channel of the slave-board

Definition at line 168 of file battery_system_cfg.h.

◆ BS_NR_OF_TEMP_SENSORS_ON_ADC1

#define BS_NR_OF_TEMP_SENSORS_ON_ADC1   (3u)

number of temperature sensors on each ADC1 channel of the slave-board

Definition at line 170 of file battery_system_cfg.h.

◆ BS_NR_OF_TEMP_SENSORS_PER_MODULE

#define BS_NR_OF_TEMP_SENSORS_PER_MODULE   (8u)

number of temperature sensors per battery module

Type
int

Definition at line 158 of file battery_system_cfg.h.

◆ BS_NR_OF_TEMP_SENSORS_PER_STRING

#define BS_NR_OF_TEMP_SENSORS_PER_STRING   (BS_NR_OF_MODULES * BS_NR_OF_TEMP_SENSORS_PER_MODULE)

number of temperature sensors in a string

Definition at line 163 of file battery_system_cfg.h.

◆ BS_NR_OF_VOLTAGES_FROM_CURRENT_SENSOR

#define BS_NR_OF_VOLTAGES_FROM_CURRENT_SENSOR   (3u)

number of high voltage inputs measured by current sensors (like IVT-MOD)

Type
int

Definition at line 260 of file battery_system_cfg.h.

◆ BS_NR_OF_VOLTAGES_FROM_MCU_ADC

#define BS_NR_OF_VOLTAGES_FROM_MCU_ADC   (2)

number of voltages measured by MCU internal ADC

Type
int

Definition at line 267 of file battery_system_cfg.h.

◆ BS_RELAXATION_PERIOD_10ms

#define BS_RELAXATION_PERIOD_10ms   (60000u)

Wait time in 10ms before battery system is at rest. Balancing for example only starts if battery system is at rest.

Definition at line 300 of file battery_system_cfg.h.

◆ BS_REST_CURRENT_mA

#define BS_REST_CURRENT_mA   (200)

current threshold for determing rest state of battery. If absolute current is below this limit value the battery is resting.

Definition at line 294 of file battery_system_cfg.h.

◆ BS_SEPARATE_POWER_PATHS

#define BS_SEPARATE_POWER_PATHS   (1)

separation of charge and discharge power line

Type
select(2)

Definition at line 280 of file battery_system_cfg.h.

◆ CHECK_CAN_TIMING

#define CHECK_CAN_TIMING   (true)
  • If set to false, foxBMS does not check CAN timing.
    • If set to true, foxBMS checks CAN timing. A valid request must come every 100ms, within the 95-150ms window.

Definition at line 220 of file battery_system_cfg.h.

◆ CURRENT_SENSOR_ISABELLENHUETTE_CYCLIC

#define CURRENT_SENSOR_ISABELLENHUETTE_CYCLIC

defines if the Isabellenhuette current sensor is used in cyclic or triggered mode

Definition at line 185 of file battery_system_cfg.h.

◆ CURRENT_SENSOR_PRESENT

#define CURRENT_SENSOR_PRESENT   (false)
  • If set to false, foxBMS does not check for the presence of a current sensor.
    • If set to true, foxBMS checks for the presence of a current sensor. If sensor stops responding during runtime, an error is raised.

Definition at line 179 of file battery_system_cfg.h.

◆ POSITIVE_DISCHARGE_CURRENT

#define POSITIVE_DISCHARGE_CURRENT   (true)

Define if discharge current are positive negative, default is positive

Definition at line 86 of file battery_system_cfg.h.

Typedef Documentation

◆ BS_STRING_ID_e

Symbolic identifiers for strings. Currently unused. Added for future compatibility.

◆ BS_STRING_PRECHARGE_PRESENT_e

Symbolic identifiers for strings with precharge

Enumeration Type Documentation

◆ BS_STRING_ID

Symbolic identifiers for strings. Currently unused. Added for future compatibility.

Enumerator
BS_STRING0 
BS_STRING1 
BS_STRING2 
BS_STRING_MAX 

Definition at line 78 of file battery_system_cfg.h.

◆ BS_STRING_PRECHARGE_PRESENT

Symbolic identifiers for strings with precharge

Enumerator
BS_STRING_WITH_PRECHARGE 
BS_STRING_WITHOUT_PRECHARGE 

Definition at line 68 of file battery_system_cfg.h.

Variable Documentation

◆ bs_stringsWithPrecharge

BS_STRING_PRECHARGE_PRESENT_e bs_stringsWithPrecharge[BS_NR_OF_STRINGS]
extern

Precharge presence of not for each string

Definition at line 64 of file battery_system_cfg.c.