foxBMS  1.4.0
The foxBMS Battery Management System API Documentation
battery_system_cfg.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2022, 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 2022-07-28 (date of last update)
47  * @version v1.4.0
48  * @ingroup BATTERY_SYSTEM_CONFIGURATION
49  * @prefix BS
50  *
51  * @brief Configuration of the battery system (e.g., number of battery
52  * modules, battery cells, temperature sensors)
53  *
54  * @details This files contains basic macros of the battery system in order to
55  * derive needed inputs in other parts of the software. These macros
56  * are all depended on the hardware.
57  *
58  */
59 
60 #ifndef FOXBMS__BATTERY_SYSTEM_CFG_H_
61 #define FOXBMS__BATTERY_SYSTEM_CFG_H_
62 
63 /*========== Includes =======================================================*/
64 #include "general.h"
65 
66 /*========== Macros and Definitions =========================================*/
67 
68 /** Symbolic identifiers for strings with precharge */
69 typedef enum {
73 
74 /**
75  * Symbolic identifiers for strings.
76  * Currently unused.
77  * Added for future compatibility.
78  */
79 typedef enum {
80  BS_STRING0 = 0u,
81  BS_STRING1 = 1u,
82  BS_STRING2 = 2u,
85 
86 /** Define if discharge current is seen as positive or negative */
87 #define POSITIVE_DISCHARGE_CURRENT (true)
88 
89 /** */
90 /**
91  * @ingroup CONFIG_BATTERYSYSTEM
92  * @brief Number of parallel strings in the battery pack
93  * @details For details see
94  * <a href="../../../../introduction/naming-conventions.html" target="_blank">Naming Conventions</a>.
95  * Implementation detail: The number of parallel strings cannot exceed
96  * #GEN_REPEAT_MAXIMUM_REPETITIONS unless the implementation of the
97  * repetition macro is adapted.
98  * @ptype uint
99  */
100 #define BS_NR_OF_STRINGS (1u)
101 
102 /* safety check: due to implementation BS_NR_OF_STRINGS may not be larger than GEN_REPEAT_MAXIMUM_REPETITIONS */
103 #if (BS_NR_OF_STRINGS > GEN_REPEAT_MAXIMUM_REPETITIONS)
104 #error "Too large number of strings, please check implementation of GEN_REPEAT_U()."
105 #endif
106 
107 /**
108  * @ingroup CONFIG_BATTERYSYSTEM
109  * @brief number of modules in a string
110  * @details For details see
111  * <a href="../../../../introduction/naming-conventions.html" target="_blank">Naming Conventions</a>.
112  * @ptype uint
113  */
114 #define BS_NR_OF_MODULES_PER_STRING (1u)
115 
116 /**
117  * @ingroup CONFIG_BATTERYSYSTEM
118  * @brief number of cells per module
119  * @details number of cells per module, where parallel cells are
120  * counted as one cell block.
121  * For details see
122  * <a href="../../../../introduction/naming-conventions.html" target="_blank">Naming Conventions</a>.
123  * @ptype uint
124  */
125 #define BS_NR_OF_CELL_BLOCKS_PER_MODULE (14u)
126 
127 /**
128  * @ingroup CONFIG_BATTERYSYSTEM
129  * @brief number of battery cells in a parallel cell connection per battery
130  * module
131  * @details For details see
132  * <a href="../../../../introduction/naming-conventions.html" target="_blank">Naming Conventions</a>.
133  * @ptype uint
134  */
135 #define BS_NR_OF_PARALLEL_CELLS_PER_MODULE (1u)
136 
137 #if BS_NR_OF_CELL_BLOCKS_PER_MODULE <= 12u
138 #define BS_MAX_SUPPORTED_CELLS (12u)
139 #elif BS_NR_OF_CELL_BLOCKS_PER_MODULE <= 14u
140 #define BS_MAX_SUPPORTED_CELLS (14u)
141 #elif BS_NR_OF_CELL_BLOCKS_PER_MODULE <= 15u
142 #define BS_MAX_SUPPORTED_CELLS (15u)
143 #elif BS_NR_OF_CELL_BLOCKS_PER_MODULE <= 16u
144 #define BS_MAX_SUPPORTED_CELLS (16u)
145 #elif BS_NR_OF_CELL_BLOCKS_PER_MODULE <= 18u
146 #define BS_MAX_SUPPORTED_CELLS (18u)
147 #elif BS_NR_OF_CELL_BLOCKS_PER_MODULE == 36u
148 #define BS_MAX_SUPPORTED_CELLS (36u)
149 #else
150 #error "Unsupported number of cells per module, higher than 18 and not 36"
151 #endif
152 
153 /**
154  * @def BS_MAX_SUPPORTED_CELLS
155  * @brief Defines the maximal number of supported cells per module
156  */
157 
158 /** Value of the balancing resistors on the slave-board */
159 #define BS_BALANCING_RESISTANCE_ohm (100.0)
160 
161 /**
162  * @def BS_NR_OF_GPIOS_PER_MODULE
163  * @brief Number of GPIOs on the LTC IC
164  * @details - 5 for 12 cell version
165  * - 9 for 18 cell version
166  */
167 #if BS_MAX_SUPPORTED_CELLS == 12u
168 #define BS_NR_OF_GPIOS_PER_MODULE (5u)
169 #elif BS_MAX_SUPPORTED_CELLS == 14u
170 #define BS_NR_OF_GPIOS_PER_MODULE (8u)
171 #else
172 #define BS_NR_OF_GPIOS_PER_MODULE (9u)
173 #endif
174 
175 /**
176  * @ingroup CONFIG_BATTERYSYSTEM
177  * @brief number of temperature sensors per battery module
178  * @ptype int
179  */
180 #define BS_NR_OF_TEMP_SENSORS_PER_MODULE (8u)
181 
182 /** number of battery cells in the system */
183 #define BS_NR_OF_CELL_BLOCKS_PER_STRING (BS_NR_OF_MODULES_PER_STRING * BS_NR_OF_CELL_BLOCKS_PER_MODULE)
184 /** number of temperature sensors in a string */
185 #define BS_NR_OF_TEMP_SENSORS_PER_STRING (BS_NR_OF_MODULES_PER_STRING * BS_NR_OF_TEMP_SENSORS_PER_MODULE)
186 /** number of temperature sensors in the battery system */
187 #define BS_NR_OF_TEMP_SENSORS (BS_NR_OF_TEMP_SENSORS_PER_STRING * BS_NR_OF_STRINGS)
188 
189 /** number of temperature sensors on each ADC0 channel of the slave-board */
190 #define BS_NR_OF_TEMP_SENSORS_ON_SADC0 (3u)
191 /** number of temperature sensors on each ADC1 channel of the slave-board */
192 #define BS_NR_OF_TEMP_SENSORS_ON_SADC1 (3u)
193 
194 /**
195  * @details - If set to false, foxBMS does not check for the presence of a
196  * current sensor.
197  * - If set to true, foxBMS checks for the presence of a current
198  * sensor. If sensor stops responding during runtime, an error is
199  * raised.
200  */
201 #define CURRENT_SENSOR_PRESENT (false)
202 
203 #if CURRENT_SENSOR_PRESENT == true
204 /**
205  * defines if the Isabellenhuette current sensor is used in cyclic or triggered mode
206  */
207 #define CURRENT_SENSOR_ISABELLENHUETTE_CYCLIC
208 /* #define CURRENT_SENSOR_ISABELLENHUETTE_TRIGGERED */
209 
210 /** Delay in ms after which it is considered the current measurement is not responding anymore. */
211 #define BS_CURRENT_MEASUREMENT_RESPONSE_TIMEOUT_MS (200u)
212 
213 /** Delay in ms after which it is considered the coulomb counting is not responding anymore. */
214 #define BS_COULOMB_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS (2000u)
215 
216 /** Delay in ms after which it is considered the energy counting is not responding anymore. */
217 #define BS_ENERGY_COUNTING_MEASUREMENT_RESPONSE_TIMEOUT_MS (2000u)
218 
219 #endif /* CURRENT_SENSOR_PRESENT == true */
220 
221 /**
222  * @brief Maximum string current limit in mA that is used in the SOA module
223  * to check for string overcurrent
224 * @details When maximum safety limit (MSL) is violated, error state is
225  * requested and contactors will open.
226  */
227 #define BS_MAXIMUM_STRING_CURRENT_mA (10000u)
228 
229 /**
230  * @brief Maximum pack current limit in mA that is used in the SOA module
231  * to check for pack overcurrent
232  * @details When maximum safety limit (MSL) is violated, error state is
233  * requested and contactors will open.
234  */
235 #define BS_MAXIMUM_PACK_CURRENT_mA (10000u * BS_NR_OF_STRINGS)
236 
237 /**
238  * @ingroup CONFIG_BATTERYSYSTEM
239  * @brief Define if interlock feedback should be discarded or not
240  * @details True: interlock feedback will be discarded
241  * False: interlock feedback will evaluated
242  */
243 #define BS_IGNORE_INTERLOCK_FEEDBACK (false)
244 
245 /**
246  * @details - If set to false, foxBMS does not check CAN timing.
247  * - If set to true, foxBMS checks CAN timing. A valid request must
248  * come every 100ms, within the 95-150ms window.
249  */
250 #define CHECK_CAN_TIMING (true)
251 
252 /**
253  * @details - If set to true, balancing is deactivated completely.
254  * - If set to false, foxBMS checks when balancing must be done and
255  * activates it accordingly.
256  */
257 #define BALANCING_DEFAULT_INACTIVE (true)
258 
259 /**
260  * @ingroup CONFIG_BATTERYSYSTEM
261  * @brief Checking if current is in SOF limits of cells.
262  * @details If set to true the current is checked against the SOF limits.
263  * If set to false the current is checked against the constant values
264  * for charging and discharging:
265  * - #BC_CURRENT_MAX_DISCHARGE_MSL_mA
266  * - #BC_CURRENT_MAX_DISCHARGE_RSL_mA
267  * - #BC_CURRENT_MAX_DISCHARGE_MOL_mA
268  *
269  * - #BC_CURRENT_MAX_CHARGE_MSL_mA
270  * - #BC_CURRENT_MAX_CHARGE_RSL_mA
271  * - #BC_CURRENT_MAX_CHARGE_MOL_mA
272  * @ptype bool
273  */
274 #define BMS_CHECK_SOF_CURRENT_LIMITS (true)
275 
276 /**
277  * @ingroup CONFIG_BATTERYSYSTEM
278  * @brief Defines behaviour if an insulation error is detected
279  * @details - If set to true: contactors will be opened
280  * - If set to false: contactors will NOT be opened
281  */
282 #define BMS_OPEN_CONTACTORS_ON_INSULATION_ERROR (false)
283 
284 /**
285  * @ingroup CONFIG_BATTERYSYSTEM
286  * @brief number of high voltage inputs measured by current sensors (like
287  * IVT-MOD)
288  * @ptype int
289  */
290 #define BS_NR_OF_VOLTAGES_FROM_CURRENT_SENSOR (3u)
291 
292 /**
293  * @ingroup CONFIG_BATTERYSYSTEM
294  * @brief number of voltages measured by MCU internal ADC
295  * @ptype int
296  */
297 #define BS_NR_OF_VOLTAGES_FROM_MCU_ADC (2)
298 
299 /** Number of contactors in addition to string contactors (e.g., PRECHARGE).*/
300 #define BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS (1u)
301 
302 /** Number of contactors. One per string + main and precharge */
303 #define BS_NR_OF_CONTACTORS ((2u * BS_NR_OF_STRINGS) + BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS)
304 
305 /**
306  * @brief current threshold for determing rest state of battery. If absolute
307  * current is below this limit value the battery is resting.
308  */
309 #define BS_REST_CURRENT_mA (200)
310 
311 /**
312  * @brief Wait time in 10ms before battery system is at rest. Balancing for
313  * example only starts if battery system is at rest.
314  */
315 #define BS_RELAXATION_PERIOD_10ms (60000u)
316 
317 /**
318  * @brief current sensor threshold for 0 current in mA as the sensor has a
319  * jitter.
320  */
321 #define BS_CS_THRESHOLD_NO_CURRENT_mA (200u)
322 
323 /**
324  * @brief Maximum voltage drop over fuse.
325  * @details If the measured voltage difference between battery voltage
326  * voltage after fuse is larger than this value. It can be concluded,
327  * that the fuse has tripped. The voltage difference can be estimated
328  * by the maximum current and the resistance.
329  * For a Cooper Bussmann 1000A fuse the voltage drop can be estimated
330  * to: I_max = 1000A and P_loss = 206W
331  * -> voltage drop at 1000A roughly 206mV
332  * -> select 500mV because of measurement inaccuracies
333  */
334 #define BS_MAX_VOLTAGE_DROP_OVER_FUSE_mV (500)
335 
336 /**
337  * @brief TODO
338  * @details Set to true if fuse in NORMAL path should be checked. This can only
339  * be done if one dedicated HV measurement is used to monitor the
340  * voltage directly after the fuse. Then a voltage difference between
341  * V_bat and V_fuse indicates a tripped fuse.
342  *
343  * V_bat +------+ V_fuse Precharge/Main+ contactor
344  * -----+---| FUSE |-----+------------/ -----------------
345  * +------+
346  */
347 #define BS_CHECK_FUSE_PLACED_IN_NORMAL_PATH (true)
348 
349 /**
350  * @brief TODO
351  * @details Set to true if fuse in CHARGE path should be checked. This can only
352  * be done if one dedicated HV measurement is used to monitor
353  * voltage directly after the fuse. Then a voltage difference between
354  * V_bat and V_fuse indicates a tripped fuse.
355  *
356  * V_bat +------+ V_fuse Precharge/Charge+ contactor
357  * -----+---| FUSE |-----+------------/ -----------------
358  * +------+
359  */
360 #define BS_CHECK_FUSE_PLACED_IN_CHARGE_PATH (false)
361 
362 /**
363  * \defgroup open wire check configuration
364  * @details If open-wire check is performed, depending on the AFE
365  * implementation, cell voltages and temperatures are not updated
366  * and thus old values can be transmitted on the CAN bus. Check
367  * time is dependent on module configuration and external
368  * capacitance. Activate open-wire check with care! See the AFE
369  * implementation for details.
370  * @{
371  */
372 /** enable open-wire checks during standby */
373 #define BS_STANDBY_PERIODIC_OPEN_WIRE_CHECK (false)
374 
375 /** Periodic open-wire check time in STANDBY state in ms */
376 #define BS_STANDBY_OPEN_WIRE_PERIOD_ms (600000)
377 
378 /** open-wire check in normal mode (set to true or false) */
379 #define BS_NORMAL_PERIODIC_OPEN_WIRE_CHECK (false)
380 
381 /** Periodic open-wire check time in NORMAL state in ms */
382 #define BS_NORMAL_OPEN_WIRE_PERIOD_ms (600000)
383 
384 /** open-wire check in charge mode (set to true or false) */
385 #define BS_CHARGE_PERIODIC_OPEN_WIRE_CHECK (false)
386 
387 /** Periodic open-wire check time in CHARGE state in ms */
388 #define BS_CHARGE_OPEN_WIRE_PERIOD_ms (600000)
389 
390 /** Periodic open-wire check time in ERROR state in ms */
391 #define BS_ERROR_OPEN_WIRE_PERIOD_ms (30000)
392 /**@}*/
393 
394 /*========== Extern Constant and Variable Declarations ======================*/
395 /** Precharge presence of not for each string */
397 
398 /*========== Extern Function Prototypes =====================================*/
399 
400 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
401 
402 #endif /* FOXBMS__BATTERY_SYSTEM_CFG_H_ */
BS_STRING_PRECHARGE_PRESENT_e bs_stringsWithPrecharge[BS_NR_OF_STRINGS]
#define BS_NR_OF_STRINGS
Number of parallel strings in the battery pack.
BS_STRING_PRECHARGE_PRESENT_e
@ BS_STRING_WITHOUT_PRECHARGE
@ BS_STRING_WITH_PRECHARGE
BS_STRING_ID_e
@ BS_STRING2
@ BS_STRING1
@ BS_STRING0
@ BS_STRING_MAX
General macros and definitions for the whole platform.