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