foxBMS  1.2.0
The foxBMS Battery Management System API Documentation
sof_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 sof_cfg.h
44  * @author foxBMS Team
45  * @date 2020-10-07 (date of creation)
46  * @updated 2020-10-07 (date of last update)
47  * @ingroup APPLICATION_CONFIGURATION
48  * @prefix SOF
49  *
50  * @brief Header for SOF configuration
51  *
52  */
53 
54 #ifndef FOXBMS__SOF_CFG_H_
55 #define FOXBMS__SOF_CFG_H_
56 
57 /*========== Includes =======================================================*/
58 #include "general.h"
59 
60 /*========== Macros and Definitions =========================================*/
61 
62 /**
63  * Maximum current in mA in charge direction that a string can sustain.
64  * Normally set once for the specific battery cell from datasheet
65  */
66 #define SOF_STRING_CURRENT_CONTINUOUS_CHARGE_mA (120000.00f)
67 
68 /**
69  * Different alarm levels for the maximum continuous charge current in mA.
70  * @{
71  */
72 #define SOF_MOL_STRING_CURRENT_CONTINUOUS_CHARGE_mA (10000.00f)
73 #define SOF_RSL_STRING_CURRENT_CONTINUOUS_CHARGE_mA (11500.00f)
74 #define SOF_MSL_STRING_CURRENT_CONTINUOUS_CHARGE_mA (12200.00f)
75 /**@}*/
76 
77 /**
78  * Maximum current in mA in discharge direction that a string can deliver.
79  * Normally set once for the specific battery cell from datasheet.
80  */
81 #define SOF_STRING_CURRENT_CONTINUOUS_DISCHARGE_mA (120000.00f)
82 
83 /**
84  * Different alarm levels for the maximum continuous string discharge current in mA.
85  * @{
86  */
87 #define SOF_MOL_STRING_CURRENT_CONTINUOUS_DISCHARGE_mA (10000.00f)
88 #define SOF_RSL_STRING_CURRENT_CONTINUOUS_DISCHARGE_mA (11500.00f)
89 #define SOF_MSL_STRING_CURRENT_CONTINUOUS_DISCHARGE_mA (12200.00f)
90 /**@}*/
91 
92 /**
93  * Current in mA that the string should be able to discharge when in
94  * limp home mode, i.e., something noncritical went wrong but it should be able
95  * to drive home. The value is chosen by the system engineer.
96  */
97 #define SOF_STRING_CURRENT_LIMP_HOME_mA (20000.00f)
98 
99 /**
100  * Different alarm levels for the limp home current in mA
101  * @{
102  */
103 #define SOF_MOL_STRING_CURRENT_LIMP_HOME_mA (20000.00f)
104 #define SOF_RSL_STRING_CURRENT_LIMP_HOME_mA (20000.00f)
105 #define SOF_MSL_STRING_CURRENT_LIMP_HOME_mA (20000.00f)
106 /**@}*/
107 
108 /**
109  * Cold temperature in deci °C where the derating of maximum discharge
110  * current starts, i.e., below this temperature battery pack should not deliver
111  * full discharge current.
112  */
113 #define SOF_TEMPERATURE_LOW_CUTOFF_DISCHARGE_ddegC (0)
114 
115 /**
116  * Different alarm levels for the cold temperature in deci °C where the
117  * derating of maximum discharge current starts, i.e., below this temperature
118  * battery pack should not deliver full discharge current.
119  * @{
120  */
121 #define SOF_MOL_TEMPERATURE_LOW_CUTOFF_DISCHARGE_ddegC (0)
122 #define SOF_RSL_TEMPERATURE_LOW_CUTOFF_DISCHARGE_ddegC (0)
123 #define SOF_MSL_TEMPERATURE_LOW_CUTOFF_DISCHARGE_ddegC (0)
124 /**@}*/
125 
126 /**
127  * Cold temperature in deci °C where the derating of maximum discharge
128  * current is fully applied, i.e., below this temperature battery pack should
129  * not deliver any current in discharge direction.
130  */
131 #define SOF_TEMPERATURE_LOW_LIMIT_DISCHARGE_ddegC (-100)
132 
133 /**
134  * Different alarm levels for the cold temperature in deci °C where the
135  * derating of maximum discharge current is fully applied. Below this
136  * temperature the battery pack should not deliver any current in discharge
137  * direction.
138  * @{
139  */
140 #define SOF_MOL_TEMPERATURE_LOW_LIMIT_DISCHARGE_ddegC (-100)
141 #define SOF_RSL_TEMPERATURE_LOW_LIMIT_DISCHARGE_ddegC (-100)
142 #define SOF_MSL_TEMPERATURE_LOW_LIMIT_DISCHARGE_ddegC (-100)
143 /**@}*/
144 
145 /**
146  * Cold temperature in deci °C where the derating of maximum charge current
147  * starts, i.e., below this temperature battery pack should not deliver full
148  * charge current.
149  */
150 #define SOF_TEMPERATURE_LOW_CUTOFF_CHARGE_ddegC (0)
151 
152 /**
153  * Different alarm levels for the cold temperature in deci °C where the
154  * derating of maximum charge current starts, i.e., below this temperature
155  * battery pack should not deliver full charge current
156  * @{
157  */
158 #define SOF_MOL_TEMPERATURE_LOW_CUTOFF_CHARGE_ddegC (0)
159 #define SOF_RSL_TEMPERATURE_LOW_CUTOFF_CHARGE_ddegC (0)
160 #define SOF_MSL_TEMPERATURE_LOW_CUTOFF_CHARGE_ddegC (0)
161 /**@}*/
162 
163 /**
164  * Cold temperature in deci °C where the derating of maximum charge current
165  * is fully applied, i.e., below this temperature battery pack should not
166  * deliver any current in charge direction.
167  */
168 #define SOF_TEMPERATURE_LOW_LIMIT_CHARGE_ddegC (-100)
169 
170 /**
171  * Different alarm levels for the cold temperature in deci °C where the
172  * derating of maximum charge current is fully applied. Below this temperature
173  * the battery pack should not deliver any current in charge direction.
174  * @{
175  */
176 #define SOF_MOL_TEMPERATURE_LOW_LIMIT_CHARGE_ddegC (-100)
177 #define SOF_RSL_TEMPERATURE_LOW_LIMIT_CHARGE_ddegC (-100)
178 #define SOF_MSL_TEMPERATURE_LOW_LIMIT_CHARGE_ddegC (-100)
179 /**@}*/
180 
181 /**
182  * Hot temperature in deci °C where the derating of maximum discharge
183  * current starts, i.e., above this temperature battery pack should not deliver
184  * full discharge current.
185  */
186 #define SOF_TEMPERATURE_HIGH_CUTOFF_DISCHARGE_ddegC (450)
187 
188 /**
189  * Different alarm levels for the high temperature in deci °C where the
190  * derating of maximum discharge current starts, i.e., above this temperature
191  * battery pack should not deliver full discharge current
192  * @{
193  */
194 #define SOF_MOL_TEMPERATURE_HIGH_CUTOFF_DISCHARGE_ddegC (450)
195 #define SOF_RSL_TEMPERATURE_HIGH_CUTOFF_DISCHARGE_ddegC (450)
196 #define SOF_MSL_TEMPERATURE_HIGH_CUTOFF_DISCHARGE_ddegC (450)
197 /**@}*/
198 
199 /**
200  * Hot temperature in deci °C where the derating of maximum discharge
201  * current is fully applied, i.e., above this temperature battery pack should
202  * not deliver any current in discharge direction.
203  */
204 #define SOF_TEMPERATURE_HIGH_LIMIT_DISCHARGE_ddegC (550)
205 
206 /**
207  * Different alarm levels for the high temperature in deci °C where the
208  * derating of maximum discharge current is fully applied. Above this
209  * temperature the battery pack should not deliver any current in discharge
210  * direction.
211  * @{
212  */
213 #define SOF_MOL_TEMPERATURE_HIGH_LIMIT_DISCHARGE_ddegC (550)
214 #define SOF_RSL_TEMPERATURE_HIGH_LIMIT_DISCHARGE_ddegC (550)
215 #define SOF_MSL_TEMPERATURE_HIGH_LIMIT_DISCHARGE_ddegC (550)
216 /**@}*/
217 
218 /**
219  * Hot temperature in deci °C where the derating of maximum charge current
220  * starts, i.e., above this temperature battery pack should not deliver full
221  * charge current.
222  */
223 #define SOF_TEMPERATURE_HIGH_CUTOFF_CHARGE_ddegC (450)
224 
225 /**
226  * Different alarm levels for the high temperature in deci °C where the
227  * derating of maximum charge current starts, i.e., above this temperature
228  * battery pack should not deliver full charge current
229  * @{
230  */
231 #define SOF_MOL_TEMPERATURE_HIGH_CUTOFF_CHARGE_ddegC (450)
232 #define SOF_RSL_TEMPERATURE_HIGH_CUTOFF_CHARGE_ddegC (450)
233 #define SOF_MSL_TEMPERATURE_HIGH_CUTOFF_CHARGE_ddegC (450)
234 /**@}*/
235 
236 /**
237  * Hot temperature in deci °C where the derating of maximum charge current
238  * is fully applied, i.e., above this temperature battery pack should not
239  * deliver any current in charge direction.
240  */
241 #define SOF_TEMPERATURE_HIGH_LIMIT_CHARGE_ddegC (550)
242 
243 /**
244  * Different alarm levels for the high temperature in deci °C where the
245  * derating of maximum charge current is fully applied. Above this temperature
246  * the battery pack should not deliver any current in charge direction.
247  * @{
248  */
249 #define SOF_MOL_TEMPERATURE_HIGH_LIMIT_CHARGE_ddegC (550)
250 #define SOF_RSL_TEMPERATURE_HIGH_LIMIT_CHARGE_ddegC (550)
251 #define SOF_MSL_TEMPERATURE_HIGH_LIMIT_CHARGE_ddegC (550)
252 /**@}*/
253 
254 /**
255  * Above this voltage value battery pack should not be exposed to full current in charge direction.
256  */
257 #define SOF_VOLTAGE_CUTOFF_CHARGE_mV (2400)
258 
259 /**
260  * Different alarm levels for the upper voltage limit where the derating of
261  * maximum charge current starts. Above this value the battery pack
262  * should not deliver full current in charge direction.
263  * @{
264  */
265 #define SOF_MOL_VOLTAGE_CUTOFF_CHARGE_mV (2400)
266 #define SOF_RSL_VOLTAGE_CUTOFF_CHARGE_mV (2400)
267 #define SOF_MSL_VOLTAGE_CUTOFF_CHARGE_mV (2400)
268 /**@}*/
269 
270 /**
271  * Above this voltage value battery pack should not be exposed to any current in charge direction.
272  */
273 #define SOF_VOLTAGE_LIMIT_CHARGE_mV (2550)
274 
275 /**
276  * Different alarm levels for the upper voltage limit where the derating of
277  * maximum charge current is fully applied. Above this value the battery pack
278  * should not deliver any current in charge direction.
279  * @{
280  */
281 #define SOF_MOL_VOLTAGE_LIMIT_CHARGE_mV (2550)
282 #define SOF_RSL_VOLTAGE_LIMIT_CHARGE_mV (2550)
283 #define SOF_MSL_VOLTAGE_LIMIT_CHARGE_mV (2550)
284 /**@}*/
285 
286 /**
287  * Below this voltage value battery pack should not deliver full current in discharge direction.
288  */
289 #define SOF_VOLTAGE_CUTOFF_DISCHARGE_mV (2000)
290 
291 /**
292  * Different alarm levels for the lower voltage limit where the derating of
293  * maximum discharge current starts. Below this value the battery pack
294  * should not deliver full current in discharge direction.
295  * @{
296  */
297 #define SOF_MOL_VOLTAGE_CUTOFF_DISCHARGE_mV (2000)
298 #define SOF_RSL_VOLTAGE_CUTOFF_DISCHARGE_mV (2000)
299 #define SOF_MSL_VOLTAGE_CUTOFF_DISCHARGE_mV (2000)
300 /**@}*/
301 
302 /**
303  * Below this voltage value battery pack should not deliver any current in discharge direction.
304  */
305 #define SOF_VOLTAGE_LIMIT_DISCHARGE_mV (1750)
306 
307 /**
308  * Different alarm levels for the lower voltage limit where the derating of
309  * maximum discharge is fully applied. Below this value the battery pack
310  * should not deliver any current in discharge direction.
311  * @{
312  */
313 #define SOF_MOL_VOLTAGE_LIMIT_DISCHARGE_mV (1750)
314 #define SOF_RSL_VOLTAGE_LIMIT_DISCHARGE_mV (1750)
315 #define SOF_MSL_VOLTAGE_LIMIT_DISCHARGE_mV (1750)
316 /**@}*/
317 
318 /**
319  * structure for configuration of SoF Calculation
320  */
321 typedef struct SOF_CONFIG {
322  /** Current derating limits @{ */
326  /**@}*/
327 
328  /** Low temperature derating limits @{ */
333  /**@}*/
334 
335  /** High temperature derating limits @{ */
340  /**@}*/
341 
342  /** Cell voltage derating limits @{ */
347  /**@}*/
349 
350 /*========== Extern Constant and Variable Declarations ======================*/
351 
352 /**
353  * Configuration values for the SOF window of the recommended battery current
354  */
356 
357 /**
358  * Configuration values for the SOF window of the different alarm levels (MOL,
359  * RSL and MSL)
360  * @{
361  */
365 /**@}*/
366 
367 /*========== Extern Function Prototypes =====================================*/
368 
369 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
370 
371 #endif /* FOXBMS__SOF_CFG_H_ */
General macros and definitions for the whole platform.
const SOF_CONFIG_s sof_recommendedCurrent
Definition: sof_cfg.c:63
const SOF_CONFIG_s sof_recommendedSafetyLimit
Definition: sof_cfg.c:97
const SOF_CONFIG_s sof_configMaximumSafetyLimit
Definition: sof_cfg.c:114
struct SOF_CONFIG SOF_CONFIG_s
const SOF_CONFIG_s sof_maximumOperatingLimit
Definition: sof_cfg.c:80
float limpHomeCurrent_mA
Definition: sof_cfg.h:325
int16_t limitUpperCellVoltage_mV
Definition: sof_cfg.h:344
int16_t cutoffUpperCellVoltage_mV
Definition: sof_cfg.h:343
int16_t limitHighTemperatureDischarge_ddegC
Definition: sof_cfg.h:337
float maximumDischargeCurrent_mA
Definition: sof_cfg.h:323
int16_t limitLowerCellVoltage_mV
Definition: sof_cfg.h:346
int16_t cutoffLowTemperatureCharge_ddegC
Definition: sof_cfg.h:331
int16_t limitLowTemperatureDischarge_ddegC
Definition: sof_cfg.h:330
int16_t limitLowTemperatureCharge_ddegC
Definition: sof_cfg.h:332
int16_t cutoffHighTemperatureDischarge_ddegC
Definition: sof_cfg.h:336
float maximumChargeCurrent_mA
Definition: sof_cfg.h:324
int16_t cutoffLowerCellVoltage_mV
Definition: sof_cfg.h:345
int16_t limitHighTemperatureCharge_ddegC
Definition: sof_cfg.h:339
int16_t cutoffLowTemperatureDischarge_ddegC
Definition: sof_cfg.h:329
int16_t cutoffHighTemperatureCharge_ddegC
Definition: sof_cfg.h:338