foxBMS  1.4.0
The foxBMS Battery Management System API Documentation
battery_cell_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_cell_cfg.h
44  * @author foxBMS Team
45  * @date 2017-03-14 (date of creation)
46  * @updated 2022-07-28 (date of last update)
47  * @version v1.4.0
48  * @ingroup BATTERY_CELL_CONFIGURATION
49  * @prefix BC
50  *
51  * @brief Configuration of the battery cell (e.g., minimum and maximum cell
52  * voltage)
53  *
54  * @details This files contains basic macros of the battery cell 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_CELL_CFG_H_
61 #define FOXBMS__BATTERY_CELL_CFG_H_
62 
63 /*========== Includes =======================================================*/
64 #include "general.h"
65 
66 /*========== Macros and Definitions =========================================*/
67 
68 /**
69  * @ingroup CONFIG_BATTERY_CELL
70  * @brief Maximum temperature limit during discharge.
71  * @details When maximum safety limit (MSL) is violated, error state is
72  * requested and contactors will open. When recommended safety limit
73  * (RSL) or maximum operating limit (MOL) is violated, the respective
74  * flag will be set.
75  * @ptype int
76  * @unit deci °C
77  */
78 /**@{*/
79 #define BC_TEMPERATURE_MAX_DISCHARGE_MSL_ddegC (550)
80 #define BC_TEMPERATURE_MAX_DISCHARGE_RSL_ddegC (500)
81 #define BC_TEMPERATURE_MAX_DISCHARGE_MOL_ddegC (450)
82 /**@}*/
83 
84 /**
85  * @ingroup CONFIG_BATTERY_CELL
86  * @brief Minimum temperature limit during discharge.
87  * @details When maximum safety limit (MSL) is violated, error state is
88  * requested and contactors will open. When recommended safety limit
89  * (RSL) or maximum operating limit (MOL) is violated, the respective
90  * flag will be set.
91  * @ptype int
92  * @unit deci °C
93  */
94 /**@{*/
95 #define BC_TEMPERATURE_MIN_DISCHARGE_MSL_ddegC (-200)
96 #define BC_TEMPERATURE_MIN_DISCHARGE_RSL_ddegC (-150)
97 #define BC_TEMPERATURE_MIN_DISCHARGE_MOL_ddegC (-100)
98 /**@}*/
99 
100 /**
101  * @ingroup CONFIG_BATTERY_CELL
102  * @brief Maximum temperature limit during charge.
103  * @details When maximum safety limit (MSL) is violated, error state is
104  * requested and contactors will open. When recommended safety limit
105  * (RSL) or maximum operating limit (MOL) is violated, the respective
106  * flag will be set.
107  * @ptype int
108  * @unit deci °C
109  */
110 /**@{*/
111 #define BC_TEMPERATURE_MAX_CHARGE_MSL_ddegC (450)
112 #define BC_TEMPERATURE_MAX_CHARGE_RSL_ddegC (400)
113 #define BC_TEMPERATURE_MAX_CHARGE_MOL_ddegC (350)
114 /**@}*/
115 
116 /**
117  * @ingroup CONFIG_BATTERY_CELL
118  * @brief Minimum temperature limit during discharge.
119  * @details When maximum safety limit (MSL) is violated, error state is
120  * requested and contactors will open. When recommended safety limit
121  * (RSL) or maximum operating limit (MOL) is violated, the respective
122  * flag will be set.
123  * @ptype int
124  * @unit deci °C
125  */
126 /**@{*/
127 #define BC_TEMPERATURE_MIN_CHARGE_MSL_ddegC (-200)
128 #define BC_TEMPERATURE_MIN_CHARGE_RSL_ddegC (-150)
129 #define BC_TEMPERATURE_MIN_CHARGE_MOL_ddegC (-100)
130 /**@}*/
131 
132 /**
133  * @ingroup CONFIG_BATTERY_CELL
134  * @brief Maximum cell voltage limit.
135  * @details When maximum safety limit (MSL) is violated, error state is
136  * requested and contactors will open. When recommended safety limit
137  * (RSL) or maximum operating limit (MOL) is violated, the respective
138  * flag will be set.
139  * @ptype int
140  * @unit mV
141  */
142 /**@{*/
143 #define BC_VOLTAGE_MAX_MSL_mV (2800)
144 #define BC_VOLTAGE_MAX_RSL_mV (2750)
145 #define BC_VOLTAGE_MAX_MOL_mV (2720)
146 /**@}*/
147 
148 /**
149  * @ingroup CONFIG_BATTERY_CELL
150  * @brief nominal cell voltage according to data sheet
151  * @ptype int
152  * @unit mV
153  */
154 #define BC_VOLTAGE_NOMINAL_mV (2500)
155 
156 /**
157  * @ingroup CONFIG_BATTERY_CELL
158  * @brief Minimum cell voltage limit.
159  * @details When maximum safety limit (MSL) is violated, error state is
160  * requested and contactors will open. When recommended safety limit
161  * (RSL) or maximum operating limit (MOL) is violated, the respective
162  * flag will be set.
163  * @ptype int
164  * @unit mV
165  */
166 /**@{*/
167 #define BC_VOLTAGE_MIN_MSL_mV (1700)
168 #define BC_VOLTAGE_MIN_RSL_mV (1750)
169 #define BC_VOLTAGE_MIN_MOL_mV (1780)
170 /**@}*/
171 
172 /**
173  * @ingroup CONFIG_BATTERY_CELL
174  * @brief Deep-discharge cell voltage limit.
175  * @details If this voltage limit is violated, the cell is faulty. The BMS will
176  * not allow a closing of the contactors until this cell is replaced.
177  * A replacement of the cell is confirmed by sending the respective
178  * CAN debug message
179  * @ptype int
180  * @unit mV
181  */
182 #define BC_VOLTAGE_DEEP_DISCHARGE_mV (BC_VOLTAGE_MIN_MSL_mV)
183 
184 /**
185  * @ingroup CONFIG_BATTERY_CELL
186  * @brief Maximum discharge current limit.
187  * @details When maximum safety limit (MSL) is violated, error state is
188  * requested and contactors will open. When recommended safety limit
189  * (RSL) or maximum operating limit (MOL) is violated, the respective
190  * flag will be set.
191  * @ptype int
192  * @unit mA
193  */
194 /**@{*/
195 #define BC_CURRENT_MAX_DISCHARGE_MSL_mA (180000u)
196 #define BC_CURRENT_MAX_DISCHARGE_RSL_mA (175000u)
197 #define BC_CURRENT_MAX_DISCHARGE_MOL_mA (170000u)
198 /**@}*/
199 
200 /**
201  * @ingroup CONFIG_BATTERY_CELL
202  * @brief Maximum charge current limit.
203  * @details When maximum safety limit (MSL) is violated, error state is
204  * requested and contactors will open. When recommended safety limit
205  * (RSL) or maximum operating limit (MOL) is violated, the respective
206  * flag will be set.
207  * @ptype int
208  * @unit mA
209  */
210 /**@{*/
211 #define BC_CURRENT_MAX_CHARGE_MSL_mA (180000u)
212 #define BC_CURRENT_MAX_CHARGE_RSL_mA (175000u)
213 #define BC_CURRENT_MAX_CHARGE_MOL_mA (170000u)
214 /**@}*/
215 
216 /**
217  * @brief Cell capacity used for SOC calculation
218  * @ptype int
219  * @unit mAh
220  */
221 #define BC_CAPACITY_mAh (3500u)
222 
223 #define BC_ENERGY_Wh (10.0f)
224 
225 #if BC_VOLTAGE_MIN_MSL_mV < BC_VOLTAGE_DEEP_DISCHARGE_mV
226 #error "Configuration error! - Maximum safety limit for under voltage can't be lower than deep-discharge limit"
227 #endif
228 
229 /** structure for lookup table */
230 typedef struct {
231  const int16_t voltage_mV; /*!< cell voltage in mV */
232  const float value; /*!< corresponding value, can be SOC/SOE in % or capacity/energy */
233 } BC_LUT_s;
234 
235 /*========== Extern Constant and Variable Declarations ======================*/
236 extern uint16_t bc_stateOfChargeLookupTableLength; /*!< length of the SOC lookup table */
237 extern const BC_LUT_s bc_stateOfChargeLookupTable[]; /*!< SOC lookup table */
238 
239 extern uint16_t bc_stateOfEnergyLookupTableLength; /*!< length of the SOE lookup table */
240 extern const BC_LUT_s bc_stateOfEnergyLookupTable[]; /*!< SOE lookup table */
241 
242 /*========== Extern Function Prototypes =====================================*/
243 
244 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
245 
246 #endif /* FOXBMS__BATTERY_CELL_CFG_H_ */
uint16_t bc_stateOfChargeLookupTableLength
uint16_t bc_stateOfEnergyLookupTableLength
const BC_LUT_s bc_stateOfEnergyLookupTable[]
const BC_LUT_s bc_stateOfChargeLookupTable[]
General macros and definitions for the whole platform.
const int16_t voltage_mV
const float value