foxBMS  1.3.0
The foxBMS Battery Management System API Documentation
Macros | Enumerations | Variables
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   (1u)
 Number of parallel strings in the battery pack. More...
 
#define BS_NR_OF_MODULES_PER_STRING   (1u)
 number of modules in a string More...
 
#define BS_NR_OF_CELL_BLOCKS_PER_MODULE   (18u)
 number of cells per module 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_CELL_BLOCKS_PER_STRING   (BS_NR_OF_MODULES_PER_STRING * BS_NR_OF_CELL_BLOCKS_PER_MODULE)
 
#define BS_NR_OF_TEMP_SENSORS_PER_STRING   (BS_NR_OF_MODULES_PER_STRING * 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_SADC0   (3u)
 
#define BS_NR_OF_TEMP_SENSORS_ON_SADC1   (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 BS_IGNORE_INTERLOCK_FEEDBACK   (false)
 Define if interlock feedback should be discarded or not. 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_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...
 
#define BS_STANDBY_PERIODIC_OPEN_WIRE_CHECK   (false)
 
#define BS_STANDBY_OPEN_WIRE_PERIOD_ms   (600000)
 
#define BS_NORMAL_PERIODIC_OPEN_WIRE_CHECK   (false)
 
#define BS_NORMAL_OPEN_WIRE_PERIOD_ms   (600000)
 
#define BS_CHARGE_PERIODIC_OPEN_WIRE_CHECK   (false)
 
#define BS_CHARGE_OPEN_WIRE_PERIOD_ms   (600000)
 
#define BS_ERROR_OPEN_WIRE_PERIOD_ms   (30000)
 

Enumerations

enum  BS_STRING_PRECHARGE_PRESENT_e { BS_STRING_WITH_PRECHARGE , BS_STRING_WITHOUT_PRECHARGE }
 
enum  BS_STRING_ID_e { 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)

Copyright
© 2010 - 2022, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. All rights reserved.

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
2022-05-30 (date of last update)
Version
v1.3.0
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 253 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 270 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 278 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 157 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 356 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 343 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 210 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 317 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 207 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 213 of file battery_system_cfg.h.

◆ BS_IGNORE_INTERLOCK_FEEDBACK

#define BS_IGNORE_INTERLOCK_FEEDBACK   (false)

Define if interlock feedback should be discarded or not.

True: interlock feedback will be discarded False: interlock feedback will evaluated

Definition at line 239 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 330 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 231 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 223 of file battery_system_cfg.h.

◆ BS_NR_OF_CELL_BLOCKS_PER_MODULE

#define BS_NR_OF_CELL_BLOCKS_PER_MODULE   (18u)

number of cells per module

number of cells per module, where parallel cells are counted as one cell block. For details see Naming Conventions.

Type
uint

Definition at line 125 of file battery_system_cfg.h.

◆ BS_NR_OF_CELL_BLOCKS_PER_STRING

#define BS_NR_OF_CELL_BLOCKS_PER_STRING   (BS_NR_OF_MODULES_PER_STRING * BS_NR_OF_CELL_BLOCKS_PER_MODULE)

number of battery cells in the system

Definition at line 179 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 299 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 296 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 168 of file battery_system_cfg.h.

◆ BS_NR_OF_MODULES_PER_STRING

#define BS_NR_OF_MODULES_PER_STRING   (1u)

number of modules in a string

For details see Naming Conventions.

Type
uint

Definition at line 114 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

For details see Naming Conventions.

Type
uint

Definition at line 135 of file battery_system_cfg.h.

◆ BS_NR_OF_STRINGS

#define BS_NR_OF_STRINGS   (1u)

Number of parallel strings in the battery pack.

For details see Naming Conventions. Implementation detail: The number of parallel strings cannot exceed REPEAT_MAXIMUM_REPETITIONS unless the implementation of the repetition macro is adapted.

Type
uint

Definition at line 100 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 183 of file battery_system_cfg.h.

◆ BS_NR_OF_TEMP_SENSORS_ON_SADC0

#define BS_NR_OF_TEMP_SENSORS_ON_SADC0   (3u)

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

Definition at line 186 of file battery_system_cfg.h.

◆ BS_NR_OF_TEMP_SENSORS_ON_SADC1

#define BS_NR_OF_TEMP_SENSORS_ON_SADC1   (3u)

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

Definition at line 188 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 176 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_PER_STRING * BS_NR_OF_TEMP_SENSORS_PER_MODULE)

number of temperature sensors in a string

Definition at line 181 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 286 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 293 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 311 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 305 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 246 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 203 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 197 of file battery_system_cfg.h.

◆ POSITIVE_DISCHARGE_CURRENT

#define POSITIVE_DISCHARGE_CURRENT   (true)

Define if discharge current is seen as positive or negative

Definition at line 87 of file battery_system_cfg.h.

Enumeration Type Documentation

◆ BS_STRING_ID_e

enum BS_STRING_ID_e

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

Enumerator
BS_STRING0 
BS_STRING1 
BS_STRING2 
BS_STRING_MAX 

Definition at line 79 of file battery_system_cfg.h.

◆ BS_STRING_PRECHARGE_PRESENT_e

enum BS_STRING_PRECHARGE_PRESENT_e

Symbolic identifiers for strings with precharge

Enumerator
BS_STRING_WITH_PRECHARGE 
BS_STRING_WITHOUT_PRECHARGE 

Definition at line 69 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 65 of file battery_system_cfg.c.