foxBMS  1.2.0
The foxBMS Battery Management System API Documentation
battery_system_cfg.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright notice, this
12  * list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright notice,
15  * this list of conditions and the following disclaimer in the documentation
16  * and/or other materials provided with the distribution.
17  *
18  * 3. Neither the name of the copyright holder nor the names of its
19  * contributors may be used to endorse or promote products derived from
20  * this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32  *
33  * We kindly request you to use one or more of the following phrases to refer to
34  * foxBMS in your hardware, software, documentation or advertising materials:
35  *
36  * - ″This product uses parts of foxBMS®″
37  * - ″This product includes parts of foxBMS®″
38  * - ″This product is derived from foxBMS®″
39  *
40  */
41 
42 /**
43  * @file battery_system_cfg.h
44  * @author foxBMS Team
45  * @date 2019-12-10 (date of creation)
46  * @updated 2021-06-09 (date of last update)
47  * @ingroup BATTERY_SYSTEM_CONFIGURATION
48  * @prefix BS
49  *
50  * @brief Configuration of the battery system (e.g., number of battery
51  * modules, battery cells, temperature sensors)
52  *
53  * @details This files contains basic macros of the battery system in order to
54  * derive needed inputs in other parts of the software. These macros
55  * are all depended on the hardware.
56  *
57  */
58 
59 #ifndef FOXBMS__BATTERY_SYSTEM_CFG_H_
60 #define FOXBMS__BATTERY_SYSTEM_CFG_H_
61 
62 /*========== Includes =======================================================*/
63 #include "general.h"
64 
65 /*========== Macros and Definitions =========================================*/
66 
67 /** Symbolic identifiers for strings with precharge */
72 
73 /**
74  * Symbolic identifiers for strings.
75  * Currently unused.
76  * Added for future compatibility.
77  */
78 typedef enum BS_STRING_ID {
79  BS_STRING0 = 0u,
80  BS_STRING1 = 1u,
81  BS_STRING2 = 2u,
84 
85 /** Define if discharge current are positive negative, default is positive */
86 #define POSITIVE_DISCHARGE_CURRENT (true)
87 
88 /** Number of strings in system */
89 #define BS_NR_OF_STRINGS (3u)
90 
91 /* safety check: due to implementation BS_NR_OF_STRINGS may not be larger than REPEAT_MAXIMUM_REPETITIONS */
92 #if (BS_NR_OF_STRINGS > REPEAT_MAXIMUM_REPETITIONS)
93 #error "Too large number of strings, please check implementation of REPEAT_U()."
94 #endif
95 
96 /**
97  * @ingroup CONFIG_BATTERYSYSTEM
98  * @brief number of modules in battery pack
99  * @ptype uint
100  */
101 #define BS_NR_OF_MODULES (1u)
102 
103 /**
104  * @ingroup CONFIG_BATTERYSYSTEM
105  * @brief number of battery cells per battery module (parallel cells are
106  * counted as one)
107  * @ptype uint
108  */
109 #define BS_NR_OF_CELLS_PER_MODULE (18u)
110 
111 /**
112  * @ingroup CONFIG_BATTERYSYSTEM
113  * @brief number of battery cells in a parallel cell connection per battery
114  * module
115  * @ptype uint
116  */
117 #define BS_NR_OF_PARALLEL_CELLS_PER_MODULE (1u)
118 
119 #if BS_NR_OF_CELLS_PER_MODULE <= 12u
120 #define BS_MAX_SUPPORTED_CELLS (12u)
121 #elif BS_NR_OF_CELLS_PER_MODULE <= 15u
122 #define BS_MAX_SUPPORTED_CELLS (15u)
123 #elif BS_NR_OF_CELLS_PER_MODULE <= 16u
124 #define BS_MAX_SUPPORTED_CELLS (16u)
125 #elif BS_NR_OF_CELLS_PER_MODULE <= 18u
126 #define BS_MAX_SUPPORTED_CELLS (18u)
127 #elif BS_NR_OF_CELLS_PER_MODULE == 36u
128 #define BS_MAX_SUPPORTED_CELLS (36u)
129 #else
130 #error "Unsupported number of cells per module, higher than 18 and not 36"
131 #endif
132 
133 /**
134  * @def BS_MAX_SUPPORTED_CELLS
135  * @brief Defines the maximal number of supported cells per module
136  */
137 
138 /** Value of the balancing resistors on the slave-board */
139 #define BS_BALANCING_RESISTANCE_ohm (100.0)
140 
141 /**
142  * @def BS_NR_OF_GPIOS_PER_MODULE
143  * @brief Number of GPIOs on the LTC IC
144  * @details - 5 for 12 cell version
145  * - 9 for 18 cell version
146  */
147 #if BS_MAX_SUPPORTED_CELLS == 12u
148 #define BS_NR_OF_GPIOS_PER_MODULE (5u)
149 #else
150 #define BS_NR_OF_GPIOS_PER_MODULE (9u)
151 #endif
152 
153 /**
154  * @ingroup CONFIG_BATTERYSYSTEM
155  * @brief number of temperature sensors per battery module
156  * @ptype int
157  */
158 #define BS_NR_OF_TEMP_SENSORS_PER_MODULE (8u)
159 
160 /** number of (not parallel) battery cells in the system */
161 #define BS_NR_OF_BAT_CELLS (BS_NR_OF_MODULES * BS_NR_OF_CELLS_PER_MODULE)
162 /** number of temperature sensors in a string */
163 #define BS_NR_OF_TEMP_SENSORS_PER_STRING (BS_NR_OF_MODULES * BS_NR_OF_TEMP_SENSORS_PER_MODULE)
164 /** number of temperature sensors in the battery system */
165 #define BS_NR_OF_TEMP_SENSORS (BS_NR_OF_TEMP_SENSORS_PER_STRING * BS_NR_OF_STRINGS)
166 
167 /** number of temperature sensors on each ADC0 channel of the slave-board */
168 #define BS_NR_OF_TEMP_SENSORS_ON_SADC0 (3u)
169 /** number of temperature sensors on each ADC1 channel of the slave-board */
170 #define BS_NR_OF_TEMP_SENSORS_ON_SADC1 (3u)
171 
172 /**
173  * @details - If set to false, foxBMS does not check for the presence of a
174  * current sensor.
175  * - If set to true, foxBMS checks for the presence of a current
176  * sensor. If sensor stops responding during runtime, an error is
177  * raised.
178  */
179 #define CURRENT_SENSOR_PRESENT (false)
180 
181 #if CURRENT_SENSOR_PRESENT == true
182 /**
183  * defines if the Isabellenhuette current sensor is used in cyclic or triggered mode
184  */
185 #define CURRENT_SENSOR_ISABELLENHUETTE_CYCLIC
186 /* #define CURRENT_SENSOR_ISABELLENHUETTE_TRIGGERED */
187 
188 /** Delay in ms after which it is considered the current measurement is not responding anymore. */
189 #define BS_CURRENT_MEASUREMENT_RESPONSE_TIMEOUT_MS (200u)
190 
191 /** Delay in ms after which it is considered the coulomb counting is not responding anymore. */
192 #define BS_COULOMB_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS (2000u)
193 
194 /** Delay in ms after which it is considered the energy counting is not responding anymore. */
195 #define BS_ENERGY_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS (2000u)
196 
197 #endif /* CURRENT_SENSOR_PRESENT == true */
198 
199 /**
200  * @brief Maximum string current limit in mA that is used in the SOA module
201  * to check for string overcurrent
202 * @details When maximum safety limit (MSL) is violated, error state is
203  * requested and contactors will open.
204  */
205 #define BS_MAXIMUM_STRING_CURRENT_mA (10000u)
206 
207 /**
208  * @brief Maximum pack current limit in mA that is used in the SOA module
209  * to check for pack overcurrent
210  * @details When maximum safety limit (MSL) is violated, error state is
211  * requested and contactors will open.
212  */
213 #define BS_MAXIMUM_PACK_CURRENT_mA (10000u * BS_NR_OF_STRINGS)
214 
215 /**
216  * @ingroup CONFIG_BATTERYSYSTEM
217  * @brief Define if interlock feedback should be discarded or not
218  * @details True: interlock feedback will be discarded
219  * False: interlock feedback will evaluated
220  */
221 #define BS_IGNORE_INTERLOCK_FEEDBACK (false)
222 
223 /**
224  * @details - If set to false, foxBMS does not check CAN timing.
225  * - If set to true, foxBMS checks CAN timing. A valid request must
226  * come every 100ms, within the 95-150ms window.
227  */
228 #define CHECK_CAN_TIMING (true)
229 
230 /**
231  * @details - If set to true, balancing is deactivated completely.
232  * - If set to false, foxBMS checks when balancing must be done and
233  * activates it accordingly.
234  */
235 #define BALANCING_DEFAULT_INACTIVE (true)
236 
237 /**
238  * @ingroup CONFIG_BATTERYSYSTEM
239  * @brief Checking if current is in SOF limits of cells.
240  * @details If set to true the current is checked against the SOF limits.
241  * If set to false the current is checked against the constant values
242  * for charging and discharging:
243  * - #BC_CURRENT_MAX_DISCHARGE_MSL_mA
244  * - #BC_CURRENT_MAX_DISCHARGE_RSL_mA
245  * - #BC_CURRENT_MAX_DISCHARGE_MOL_mA
246  *
247  * - #BC_CURRENT_MAX_CHARGE_MSL_mA
248  * - #BC_CURRENT_MAX_CHARGE_RSL_mA
249  * - #BC_CURRENT_MAX_CHARGE_MOL_mA
250  * @ptype bool
251  */
252 #define BMS_CHECK_SOF_CURRENT_LIMITS (true)
253 
254 /**
255  * @ingroup CONFIG_BATTERYSYSTEM
256  * @brief Defines behaviour if an insulation error is detected
257  * @details - If set to true: contactors will be opened
258  * - If set to false: contactors will NOT be opened
259  */
260 #define BMS_OPEN_CONTACTORS_ON_INSULATION_ERROR (false)
261 
262 /**
263  * @ingroup CONFIG_BATTERYSYSTEM
264  * @brief number of high voltage inputs measured by current sensors (like
265  * IVT-MOD)
266  * @ptype int
267  */
268 #define BS_NR_OF_VOLTAGES_FROM_CURRENT_SENSOR (3u)
269 
270 /**
271  * @ingroup CONFIG_BATTERYSYSTEM
272  * @brief number of voltages measured by MCU internal ADC
273  * @ptype int
274  */
275 #define BS_NR_OF_VOLTAGES_FROM_MCU_ADC (2)
276 
277 /** Number of contactors in addition to string contactors (e.g., PRECHARGE).*/
278 #define BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS (1U)
279 
280 /** Number of contactors. One per string + main and precharge */
281 #define BS_NR_OF_CONTACTORS ((2U * BS_NR_OF_STRINGS) + BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS)
282 
283 /**
284  * @ingroup CONFIG_BATTERYSYSTEM
285  * @brief separation of charge and discharge power line
286  * @ptype select(2)
287  */
288 #define BS_SEPARATE_POWER_PATHS (1)
289 
290 #if (BS_NR_OF_CONTACTORS > 3) && (BS_SEPARATE_POWER_PATHS == 0)
291 #error "Configuration mismatch: Can't use only one power path with more than 3 contactors"
292 #endif /* */
293 
294 #if (BS_NR_OF_CONTACTORS < 4) && (BS_SEPARATE_POWER_PATHS == 1)
295 #error "Configuration mismatch: Can't use separate power path with less than 4 contactors"
296 #endif /* */
297 
298 /**
299  * @brief current threshold for determing rest state of battery. If absolute
300  * current is below this limit value the battery is resting.
301  */
302 #define BS_REST_CURRENT_mA (200)
303 
304 /**
305  * @brief Wait time in 10ms before battery system is at rest. Balancing for
306  * example only starts if battery system is at rest.
307  */
308 #define BS_RELAXATION_PERIOD_10ms (60000u)
309 
310 /**
311  * @brief current sensor threshold for 0 current in mA as the sensor has a
312  * jitter.
313  */
314 #define BS_CS_THRESHOLD_NO_CURRENT_mA (200u)
315 
316 /**
317  * @brief Maximum voltage drop over fuse.
318  * @details If the measured voltage difference between battery voltage
319  * voltage after fuse is larger than this value. It can be concluded,
320  * that the fuse has tripped. The voltage difference can be estimated
321  * by the maximum current and the resistance.
322  * For a Cooper Bussmann 1000A fuse the voltage drop can be estimated
323  * to: I_max = 1000A and P_loss = 206W
324  * -> voltage drop at 1000A roughly 206mV
325  * -> select 500mV because of measurement inaccuracies
326  */
327 #define BS_MAX_VOLTAGE_DROP_OVER_FUSE_mV (500)
328 
329 /**
330  * @brief TODO
331  * @details Set to true if fuse in NORMAL path should be checked. This can only
332  * be done if one dedicated HV measurement is used to monitor the
333  * voltage directly after the fuse. Then a voltage difference between
334  * V_bat and V_fuse indicates a tripped fuse.
335  *
336  * V_bat +------+ V_fuse Precharge/Main+ contactor
337  * -----+---| FUSE |-----+------------/ -----------------
338  * +------+
339  */
340 #define BS_CHECK_FUSE_PLACED_IN_NORMAL_PATH (true)
341 
342 /**
343  * @brief TODO
344  * @details Set to true if fuse in CHARGE path should be checked. This can only
345  * be done if one dedicated HV measurement is used to monitor
346  * voltage directly after the fuse. Then a voltage difference between
347  * V_bat and V_fuse indicates a tripped fuse.
348  *
349  * V_bat +------+ V_fuse Precharge/Charge+ contactor
350  * -----+---| FUSE |-----+------------/ -----------------
351  * +------+
352  */
353 #define BS_CHECK_FUSE_PLACED_IN_CHARGE_PATH (false)
354 
355 /*========== Extern Constant and Variable Declarations ======================*/
356 /** Precharge presence of not for each string */
358 
359 /*========== Extern Function Prototypes =====================================*/
360 
361 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
362 
363 #endif /* FOXBMS__BATTERY_SYSTEM_CFG_H_ */
BS_STRING_PRECHARGE_PRESENT_e bs_stringsWithPrecharge[BS_NR_OF_STRINGS]
#define BS_NR_OF_STRINGS
BS_STRING_ID
@ BS_STRING2
@ BS_STRING1
@ BS_STRING0
@ BS_STRING_MAX
enum BS_STRING_PRECHARGE_PRESENT BS_STRING_PRECHARGE_PRESENT_e
enum BS_STRING_ID BS_STRING_ID_e
BS_STRING_PRECHARGE_PRESENT
@ BS_STRING_WITHOUT_PRECHARGE
@ BS_STRING_WITH_PRECHARGE
General macros and definitions for the whole platform.