foxBMS - Unit Tests  1.1.0
The foxBMS Unit Tests 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_ADC0 (3u)
169 /** number of temperature sensors on each ADC1 channel of the slave-board */
170 #define BS_NR_OF_TEMP_SENSORS_ON_ADC1 (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  * @details - If set to false, foxBMS does not check CAN timing.
217  * - If set to true, foxBMS checks CAN timing. A valid request must
218  * come every 100ms, within the 95-150ms window.
219  */
220 #define CHECK_CAN_TIMING (true)
221 
222 /**
223  * @details - If set to true, balancing is deactivated completely.
224  * - If set to false, foxBMS checks when balancing must be done and
225  * activates it accordingly.
226  */
227 #define BALANCING_DEFAULT_INACTIVE (true)
228 
229 /**
230  * @ingroup CONFIG_BATTERYSYSTEM
231  * @brief Checking if current is in SOF limits of cells.
232  * @details If set to true the current is checked against the SOF limits.
233  * If set to false the current is checked against the constant values
234  * for charging and discharging:
235  * - #BC_CURRENT_MAX_DISCHARGE_MSL_mA
236  * - #BC_CURRENT_MAX_DISCHARGE_RSL_mA
237  * - #BC_CURRENT_MAX_DISCHARGE_MOL_mA
238  *
239  * - #BC_CURRENT_MAX_CHARGE_MSL_mA
240  * - #BC_CURRENT_MAX_CHARGE_RSL_mA
241  * - #BC_CURRENT_MAX_CHARGE_MOL_mA
242  * @ptype bool
243  */
244 #define BMS_CHECK_SOF_CURRENT_LIMITS (true)
245 
246 /**
247  * @ingroup CONFIG_BATTERYSYSTEM
248  * @brief Defines behaviour if an insulation error is detected
249  * @details - If set to true: contactors will be opened
250  * - If set to false: contactors will NOT be opened
251  */
252 #define BMS_OPEN_CONTACTORS_ON_INSULATION_ERROR (false)
253 
254 /**
255  * @ingroup CONFIG_BATTERYSYSTEM
256  * @brief number of high voltage inputs measured by current sensors (like
257  * IVT-MOD)
258  * @ptype int
259  */
260 #define BS_NR_OF_VOLTAGES_FROM_CURRENT_SENSOR (3u)
261 
262 /**
263  * @ingroup CONFIG_BATTERYSYSTEM
264  * @brief number of voltages measured by MCU internal ADC
265  * @ptype int
266  */
267 #define BS_NR_OF_VOLTAGES_FROM_MCU_ADC (2)
268 
269 /** Number of contactors in addition to string contactors (e.g., PRECHARGE).*/
270 #define BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS (1U)
271 
272 /** Number of contactors. One per string + main and precharge */
273 #define BS_NR_OF_CONTACTORS ((2U * BS_NR_OF_STRINGS) + BS_NR_OF_CONTACTORS_OUTSIDE_STRINGS)
274 
275 /**
276  * @ingroup CONFIG_BATTERYSYSTEM
277  * @brief separation of charge and discharge power line
278  * @ptype select(2)
279  */
280 #define BS_SEPARATE_POWERLINES (1)
281 
282 #if (BS_NR_OF_CONTACTORS > 3) && (BS_SEPARATE_POWERLINES == 0)
283 #error "Configuration mismatch: Can't use only one powerline with more than 3 contactors"
284 #endif /* */
285 
286 #if (BS_NR_OF_CONTACTORS < 4) && (BS_SEPARATE_POWERLINES == 1)
287 #error "Configuration mismatch: Can't use separate powerlines with less than 4 contactors"
288 #endif /* */
289 
290 /**
291  * @brief current threshold for determing rest state of battery. If absolute
292  * current is below this limit value the battery is resting.
293  */
294 #define BS_REST_CURRENT_mA (200)
295 
296 /**
297  * @brief Wait time in 10ms before battery system is at rest. Balancing for
298  * example only starts if battery system is at rest.
299  */
300 #define BS_RELAXATION_PERIOD_10ms (60000u)
301 
302 /**
303  * @brief current sensor threshold for 0 current in mA as the sensor has a
304  * jitter.
305  */
306 #define BS_CS_THRESHOLD_NO_CURRENT_mA (200u)
307 
308 /**
309  * @brief Maximum voltage drop over fuse.
310  * @details If the measured voltage difference between battery voltage
311  * voltage after fuse is larger than this value. It can be concluded,
312  * that the fuse has tripped. The voltage difference can be estimated
313  * by the maximum current and the resistance.
314  * For a Cooper Bussmann 1000A fuse the voltage drop can be estimated
315  * to: I_max = 1000A and P_loss = 206W
316  * -> voltage drop at 1000A roughly 206mV
317  * -> select 500mV because of measurement inaccuracies
318  */
319 #define BS_MAX_VOLTAGE_DROP_OVER_FUSE_mV (500)
320 
321 /**
322  * @brief TODO
323  * @details Set to true if fuse in NORMAL path should be checked. This can only
324  * be done if one dedicated HV measurement is used to monitor the
325  * voltage directly after the fuse. Then a voltage difference between
326  * V_bat and V_fuse indicates a tripped fuse.
327  *
328  * V_bat +------+ V_fuse Precharge/Main+ contactor
329  * -----+---| FUSE |-----+------------/ -----------------
330  * +------+
331  */
332 #define BS_CHECK_FUSE_PLACED_IN_NORMAL_PATH (true)
333 
334 /**
335  * @brief TODO
336  * @details Set to true if fuse in CHARGE path should be checked. This can only
337  * be done if one dedicated HV measurement is used to monitor
338  * voltage directly after the fuse. Then a voltage difference between
339  * V_bat and V_fuse indicates a tripped fuse.
340  *
341  * V_bat +------+ V_fuse Precharge/Charge+ contactor
342  * -----+---| FUSE |-----+------------/ -----------------
343  * +------+
344  */
345 #define BS_CHECK_FUSE_PLACED_IN_CHARGE_PATH (false)
346 
347 /*========== Extern Constant and Variable Declarations ======================*/
348 /** Precharge presence of not for each string */
350 
351 /*========== Extern Function Prototypes =====================================*/
352 
353 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
354 
355 #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.