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

#include "general.h"
#include "fassert.h"
#include <stdbool.h>
#include <stdint.h>

Include dependency graph for battery_system_cfg.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	BS_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_CELL_BLOCK (1u)
	number of parallel connected battery cells in a cell block More...

#define	BS_BALANCING_RESISTANCE_ohm (100.0)

#define	BS_NR_OF_GPIOS_PER_MODULE (10u)
	Defines the number of GPIOs. More...

#define	BS_NR_OF_GPAS_PER_MODULE (2u)
	Defines the number of GPA inputs. 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_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_MAIN_CONTACTORS_MAXIMUM_BREAK_CURRENT_mA (500000)
	Maximum break current of main contactors. More...

#define	BS_MAIN_FUSE_MAXIMUM_TRIGGER_DURATION_ms (30000u)
	Maximum fuse trigger duration. More...

#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	BS_CHECK_CAN_TIMING (true)
	Defines whether CAN timing shall be evaluated or not. More...

#define	BS_BALANCING_DEFAULT_INACTIVE (true)
	Defines whether balancing shall be available or not. 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_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 determining 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 }

Functions
	FAS_STATIC_ASSERT ((BS_NR_OF_STRINGS<=(uint8_t) UINT8_MAX), "This code assumes BS_NR_OF_STRINGS fits into uint8_t")

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 - 2023, 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: 2023-10-12 (date of last update)

Version: v1.6.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

◆ BS_BALANCING_DEFAULT_INACTIVE

#define BS_BALANCING_DEFAULT_INACTIVE (true)

Defines whether balancing shall be available or not.

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 250 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 133 of file battery_system_cfg.h.

◆ BS_CHECK_CAN_TIMING

#define BS_CHECK_CAN_TIMING (true)

Defines whether CAN timing shall be evaluated or not.

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 242 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 322 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 309 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 184 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 283 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 181 of file battery_system_cfg.h.

◆ BS_CURRENT_SENSOR_PRESENT

#define BS_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 171 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 187 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 234 of file battery_system_cfg.h.

◆ BS_MAIN_CONTACTORS_MAXIMUM_BREAK_CURRENT_mA

#define BS_MAIN_CONTACTORS_MAXIMUM_BREAK_CURRENT_mA (500000)

Maximum break current of main contactors.

The contacts of the main contactors can be welded, when attempting to interrupt the current flow while a current higher than the maximum break current of the contactor is flowing.

Thus, the contactors will not be opened if the floating current is above this value. The fuse should trigger to interrupt current flows above this value.

Definition at line 201 of file battery_system_cfg.h.

◆ BS_MAIN_FUSE_MAXIMUM_TRIGGER_DURATION_ms

#define BS_MAIN_FUSE_MAXIMUM_TRIGGER_DURATION_ms (30000u)

Maximum fuse trigger duration.

If the current is above BS_MAIN_CONTACTORS_MAXIMUM_BREAK_CURRENT_mA, the BMS state machine will wait this time until the fuse triggers so that the current will be interrupted by the fuse and not the contactors. After this time, the BMS will nevertheless try to open the contactors.

Definition at line 211 of file battery_system_cfg.h.

◆ 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 296 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 227 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 219 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 122 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 158 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)

Total number of contactors in system:

Two contactors per string (string+ and string-)
One optional precharge contactor for each string

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

◆ BS_NR_OF_GPAS_PER_MODULE

#define BS_NR_OF_GPAS_PER_MODULE (2u)

Defines the number of GPA inputs.

Definition at line 145 of file battery_system_cfg.h.

◆ BS_NR_OF_GPIOS_PER_MODULE

#define BS_NR_OF_GPIOS_PER_MODULE (10u)

Defines the number of GPIOs.

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

◆ BS_NR_OF_PARALLEL_CELLS_PER_CELL_BLOCK

#define BS_NR_OF_PARALLEL_CELLS_PER_CELL_BLOCK (1u)

number of parallel connected battery cells in a cell block

For details see Naming Conventions.

Type: uint

Definition at line 130 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 GEN_REPEAT_MAXIMUM_REPETITIONS unless the implementation of the repetition macro is adapted.

Type: uint

Definition at line 99 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 162 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 151 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 160 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 257 of file battery_system_cfg.h.

◆ BS_POSITIVE_DISCHARGE_CURRENT

#define BS_POSITIVE_DISCHARGE_CURRENT (true)

Define if discharge current is seen as positive or negative

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

◆ BS_REST_CURRENT_mA

#define BS_REST_CURRENT_mA (200)

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

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

Enumeration Type Documentation

◆ BS_STRING_ID_e

enum BS_STRING_ID_e

Symbolic identifiers for strings.

Enumerator
BS_STRING0
BS_STRING1
BS_STRING2
BS_STRING_MAX

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

Function Documentation

◆ FAS_STATIC_ASSERT()

FAS_STATIC_ASSERT	(	(BS_NR_OF_STRINGS<=(uint8_t) UINT8_MAX)	,
		"This code assumes BS_NR_OF_STRINGS fits into uint8_t"
	)

Variable Documentation

◆ bs_stringsWithPrecharge

BS_STRING_PRECHARGE_PRESENT_e bs_stringsWithPrecharge[BS_NR_OF_STRINGS]

extern

Defines whether a string can be used to precharge or not

Definition at line 65 of file battery_system_cfg.c.

Macros

Enumerations

Functions

Variables