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:

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_POWERLINES (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)

Copyright: © 2010 - 2021, 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:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
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.
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_POWERLINES

#define BS_SEPARATE_POWERLINES (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

typedef enum BS_STRING_ID BS_STRING_ID_e

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

◆ BS_STRING_PRECHARGE_PRESENT_e

typedef enum BS_STRING_PRECHARGE_PRESENT BS_STRING_PRECHARGE_PRESENT_e

Symbolic identifiers for strings with precharge

Enumeration Type Documentation

◆ BS_STRING_ID

enum BS_STRING_ID