foxBMS-UnitTests  1.0.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
4  * angewandten Forschung e.V. All rights reserved.
5  *
6  * BSD 3-Clause License
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions are met:
9  * 1. Redistributions of source code must retain the above copyright notice,
10  * this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  * 3. Neither the name of the copyright holder nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28  * POSSIBILITY OF SUCH DAMAGE.
29  *
30  * We kindly request you to use one or more of the following phrases to refer
31  * to foxBMS in your hardware, software, documentation or advertising
32  * materials:
33  *
34  * ″This product uses parts of foxBMS®″
35  *
36  * ″This product includes parts of foxBMS®″
37  *
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 #if BC_VOLTAGE_MIN_MSL_mV < BC_VOLTAGE_DEEP_DISCHARGE_mV
223 #error "Configuration error! - Maximum safety limit for under voltage can't be lower than deep-discharge limit"
224 #endif
225 
226 /** structure for lookup table */
227 typedef struct BC_LUT {
228  const uint16_t voltage_mV; /*!< cell voltage in mV */
229  const float value; /*!< corresponding value, can be SOC/SOE in % or capacity/energy */
231 
232 /*========== Extern Constant and Variable Declarations ======================*/
233 extern uint16_t bc_stateOfChargeLookupTableLength; /*!< length of the SOC lookup table */
234 extern const BC_LUT_s bc_stateOfChargeLookupTable[]; /*!< SOC lookup table */
235 
236 extern uint16_t bc_stateOfEnergyLookupTableLength; /*!< length of the SOE lookup table */
237 extern const BC_LUT_s bc_stateOfEnergyLookupTable[]; /*!< SOE lookup table */
238 
239 /*========== Extern Function Prototypes =====================================*/
240 
241 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
242 
243 #endif /* FOXBMS__BATTERY_CELL_CFG_H_ */
general.h
TODO.
BC_LUT::voltage_mV
const uint16_t voltage_mV
Definition: battery_cell_cfg.h:228
BC_LUT
Definition: battery_cell_cfg.h:227
BC_LUT_s
struct BC_LUT BC_LUT_s
bc_stateOfEnergyLookupTableLength
uint16_t bc_stateOfEnergyLookupTableLength
Definition: battery_cell_cfg.c:103
bc_stateOfEnergyLookupTable
const BC_LUT_s bc_stateOfEnergyLookupTable[]
Definition: battery_cell_cfg.c:84
bc_stateOfChargeLookupTable
const BC_LUT_s bc_stateOfChargeLookupTable[]
Definition: battery_cell_cfg.c:65
bc_stateOfChargeLookupTableLength
uint16_t bc_stateOfChargeLookupTableLength
Definition: battery_cell_cfg.c:102
BC_LUT::value
const float value
Definition: battery_cell_cfg.h:229