foxBMS - Unit Tests  1.5.0
The foxBMS Unit Tests API Documentation
bal_strategy_history.c
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2023, 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 bal_strategy_history.c
44  * @author foxBMS Team
45  * @date 2020-05-29 (date of creation)
46  * @updated 2023-02-03 (date of last update)
47  * @version v1.5.0
48  * @ingroup APPLICATION
49  * @prefix BAL
50  *
51  * @brief Driver for the Balancing module
52  *
53  */
54 
55 /*========== Includes =======================================================*/
56 #include "bal_strategy_history.h"
57 
58 #include "battery_cell_cfg.h"
59 
60 #include "bms.h"
61 #include "database.h"
62 #include "os.h"
63 #include "state_estimation.h"
64 
65 #include <math.h>
66 #include <stdbool.h>
67 #include <stdint.h>
68 
69 /*========== Macros and Definitions =========================================*/
70 
71 /*========== Static Constant and Variable Definitions =======================*/
72 /** local storage of the #DATA_BLOCK_BALANCING_CONTROL_s table */
74 /** local storage of the #DATA_BLOCK_CELL_VOLTAGE_s table */
76 
77 /** contains the state of the contactor state machine */
79  .timer = 0,
80  .stateRequest = BAL_STATE_NO_REQUEST,
82  .substate = BAL_ENTRY,
83  .lastState = BAL_STATEMACH_UNINITIALIZED,
84  .lastSubstate = 0,
85  .triggerEntry = 0,
86  .errorRequestCounter = 0,
87  .initializationFinished = STD_NOT_OK,
88  .active = false,
89  .balancingThreshold = BAL_DEFAULT_THRESHOLD_mV + BAL_HYSTERESIS_mV,
90  .balancingAllowed = true,
91  .balancingGlobalAllowed = false,
92 };
93 
94 /*========== Extern Constant and Variable Definitions =======================*/
95 
96 /*========== Static Function Prototypes =====================================*/
97 /** Activates history based balancing */
98 static void BAL_ActivateBalancing(void);
99 
100 /**
101  * @brief Deactivates history based balancing
102  * @details The balancing state of all cells in all strings set to inactivate
103  * (that is 0) and the delta charge is set to 0 As. The balancing
104  * enable bit is deactivate (that is 0).
105  */
106 static void BAL_Deactivate(void);
107 
108 /**
109  * @brief State machine subfunction to check if balancing is allowed
110  * @details Checks if balancing is allowed. If it is it transfers in the actual
111  * balancing state.
112  */
113 static void BAL_ProcessStateCheckBalancing(void);
114 
115 /** State machine subfunction to balance the battery cell */
116 static void BAL_ProcessStateBalancing(void);
117 
118 /** State machine subfunction to check for voltage imbalances */
119 static bool BAL_CheckImbalances(void);
120 
121 /** State machine subfunction to compute the imbalance of all cells */
122 static void BAL_ComputeImbalances(void);
123 
124 /*========== Static Function Implementations ================================*/
125 
126 static void BAL_ActivateBalancing(void) {
127  float_t cellBalancingCurrent = 0.0f;
128  uint32_t difference = 0;
129 
131 
132  for (uint8_t s = 0u; s < BS_NR_OF_STRINGS; s++) {
133  uint16_t nrBalancedCells = 0u;
134  for (uint8_t c = 0u; c < BS_NR_OF_CELL_BLOCKS_PER_STRING; c++) {
135  if (bal_state.balancingAllowed == false) {
136  bal_balancing.balancingState[s][c] = 0;
137  } else {
138  if (bal_balancing.deltaCharge_mAs[s][c] > 0) {
139  bal_balancing.balancingState[s][c] = 1;
140  nrBalancedCells++;
141  cellBalancingCurrent = ((float_t)(bal_cellVoltage.cellVoltage_mV[s][c])) /
143  difference = (BAL_STATEMACH_BALANCINGTIME_100ms / 10) * (uint32_t)(cellBalancingCurrent);
144  bal_state.active = true;
146  /* we are working with unsigned integers */
147  if (difference > bal_balancing.deltaCharge_mAs[s][c]) {
148  bal_balancing.deltaCharge_mAs[s][c] = 0;
149  } else {
150  bal_balancing.deltaCharge_mAs[s][c] -= difference;
151  }
152  } else {
153  bal_balancing.balancingState[s][c] = 0;
154  }
155  }
156  }
157  bal_balancing.nrBalancedCells[s] = nrBalancedCells;
158  }
159 
161 }
162 
163 static void BAL_Deactivate(void) {
164  for (uint8_t s = 0u; s < BS_NR_OF_STRINGS; s++) {
165  for (uint16_t c = 0u; c < BS_NR_OF_CELL_BLOCKS_PER_STRING; c++) {
166  bal_balancing.balancingState[s][c] = 0;
167  bal_balancing.deltaCharge_mAs[s][c] = 0;
168  }
170  }
172  bal_state.active = false;
173 
175 }
176 
178  if (bal_state.substate == BAL_ENTRY) {
179  if (bal_state.balancingGlobalAllowed == false) {
180  if (bal_state.active == true) {
181  BAL_Deactivate();
182  }
183  bal_state.active = false;
185  } else {
187  }
188 
190  return;
191  } else if (bal_state.substate == BAL_CHECK_IMBALANCES) {
192  if (bal_state.active == true) {
193  BAL_Deactivate();
194  }
195  if (BAL_CheckImbalances() == true) {
198  } else {
200  }
202  return;
203  } else if (bal_state.substate == BAL_COMPUTE_IMBALANCES) {
208  } else {
210  }
212  return;
213  }
214 }
215 
216 static void BAL_ProcessStateBalancing(void) {
217  bool activateBalancing = true;
218 
219  if (bal_state.substate == BAL_ENTRY) {
220  if (bal_state.balancingGlobalAllowed == false) {
221  if (bal_state.active == true) {
222  BAL_Deactivate();
223  }
224  bal_state.active = false;
226  } else {
228  }
230  return;
231  } else if (bal_state.substate == BAL_ACTIVATE_BALANCING) {
233  DATA_READ_DATA(&bal_minmax);
235  /* do not balance under a certain voltage level */
236  for (uint8_t s = 0u; s < BS_NR_OF_STRINGS; s++) {
237  if ((bal_minmax.minimumCellVoltage_mV[s] <= BAL_LOWER_VOLTAGE_LIMIT_mV) ||
239  (BAL_CheckImbalances() == false) || (bal_state.balancingGlobalAllowed == false)) {
240  activateBalancing = false;
241  if (bal_state.active == true) {
242  BAL_Deactivate();
243  }
246  return;
247  }
248  }
249 
250  if (activateBalancing == true) {
252  }
253  return;
254  }
255 }
256 static bool BAL_CheckImbalances(void) {
257  bool retVal = false;
258 
259  for (uint8_t s = 0u; s < BS_NR_OF_STRINGS; s++) {
260  for (uint16_t c = 0u; c < BS_NR_OF_CELL_BLOCKS_PER_STRING; c++) {
261  if (bal_balancing.deltaCharge_mAs[s][c] > 0) {
262  retVal = true;
263  }
264  }
265  }
266 
267  return retVal;
268 }
269 
270 static void BAL_ComputeImbalances(void) {
271  uint16_t voltageMin = 0;
272  uint16_t minVoltageIndex = 0;
273  float_t SOC = 0.0f;
274  uint32_t DOD = 0;
275  uint32_t maxDOD = 0;
276 
278 
279  for (uint8_t s = 0u; s < BS_NR_OF_STRINGS; s++) {
280  voltageMin = bal_cellVoltage.cellVoltage_mV[s][0];
281  minVoltageIndex = 0;
282 
283  for (uint16_t c = 0u; c < BS_NR_OF_CELL_BLOCKS_PER_STRING; c++) {
284  if (bal_cellVoltage.cellVoltage_mV[s][c] <= voltageMin) {
285  voltageMin = bal_cellVoltage.cellVoltage_mV[s][c];
286  minVoltageIndex = c;
287  }
288  }
289 
290  SOC = SE_GetStateOfChargeFromVoltage(((float_t)(bal_cellVoltage.cellVoltage_mV[s][minVoltageIndex])) / 1000.0f);
291  maxDOD = BC_CAPACITY_mAh * (uint32_t)((1.0f - SOC) * 3600.0f);
292  bal_balancing.deltaCharge_mAs[s][minVoltageIndex] = 0;
293 
294  /* update balancing threshold */
296 
297  for (uint16_t c = 0u; c < BS_NR_OF_CELL_BLOCKS_PER_STRING; c++) {
298  if (c != minVoltageIndex) {
299  if (bal_cellVoltage.cellVoltage_mV[s][c] >= (voltageMin + bal_state.balancingThreshold)) {
300  SOC = SE_GetStateOfChargeFromVoltage(((float_t)(bal_cellVoltage.cellVoltage_mV[s][c])) / 1000.0f);
301  DOD = BC_CAPACITY_mAh * (uint32_t)((1.0f - SOC) * 3600.0f);
302  bal_balancing.deltaCharge_mAs[s][c] = (maxDOD - DOD);
303  }
304  }
305  }
306  }
307 
309 }
310 
311 /*========== Extern Function Implementations ================================*/
314 }
315 
317  BAL_RETURN_TYPE_e retVal = BAL_OK;
318 
320  retVal = BAL_CheckStateRequest(&bal_state, stateRequest);
321 
322  if (retVal == BAL_OK) {
323  bal_state.stateRequest = stateRequest;
324  }
326 
327  return retVal;
328 }
329 
330 extern void BAL_Trigger(void) {
332 
333  /* Check re-entrance of function */
334  if (BAL_CheckReEntrance(&bal_state) > 0u) {
335  return;
336  }
337 
338  if (bal_state.timer > 0u) {
339  if ((--bal_state.timer) > 0) {
341  return; /* handle state machine only if timer has elapsed */
342  }
343  }
344 
345  switch (bal_state.state) {
348  stateRequest = BAL_TransferStateRequest(&bal_state);
349  BAL_ProcessStateUninitalized(&bal_state, stateRequest);
350  break;
355  break;
359  break;
363  break;
367  break;
368  default:
369  /* invalid state */
371  break;
372  }
374 }
375 
376 /*================== Getter for static Variables (Unit Test) ==============*/
377 #ifdef UNITY_UNIT_TEST
379  return &bal_balancing;
380 }
381 
383  return &bal_state;
384 }
385 #endif
386 
387 /*========== Externalized Static Function Implementations (Unit Test) =======*/
388 #ifdef UNITY_UNIT_TEST
390  return bal_state.state;
391 }
392 #endif
STD_RETURN_TYPE_e BAL_Init(DATA_BLOCK_BALANCING_CONTROL_s *pControl)
Generic initialization function for the balancing module.
Definition: bal.c:151
void BAL_SaveLastStates(BAL_STATE_s *pBalancingState)
Saves the last state and the last substate.
Definition: bal.c:73
void BAL_ProcessStateInitialization(BAL_STATE_s *currentState)
State machine subfunction to initialize the balancing state machine.
Definition: bal.c:174
void BAL_ProcessStateUninitalized(BAL_STATE_s *pCurrentState, BAL_STATE_REQUEST_e stateRequest)
Substate handling function for BAL_Trigger()
Definition: bal.c:160
BAL_STATE_REQUEST_e BAL_TransferStateRequest(BAL_STATE_s *currentState)
transfers the current state request to the state machine.
Definition: bal.c:103
void BAL_ProcessStateInitialized(BAL_STATE_s *currentState)
State machine subfunction to transfer from an initalized state to "running" states of th state machin...
Definition: bal.c:182
uint8_t BAL_CheckReEntrance(BAL_STATE_s *currentState)
re-entrance check of BAL state machine trigger function
Definition: bal.c:87
BAL_RETURN_TYPE_e BAL_CheckStateRequest(BAL_STATE_s *pCurrentState, BAL_STATE_REQUEST_e stateRequest)
checks the state requests that are made.
Definition: bal.c:116
BAL_RETURN_TYPE_e
Definition: bal.h:115
@ BAL_OK
Definition: bal.h:116
BAL_STATE_REQUEST_e
Definition: bal.h:102
@ BAL_STATE_NO_REQUEST
Definition: bal.h:109
BAL_STATEMACH_e
Definition: bal.h:71
@ BAL_STATEMACH_BALANCE
Definition: bal.h:77
@ BAL_STATEMACH_UNINITIALIZED
Definition: bal.h:73
@ BAL_STATEMACH_INITIALIZATION
Definition: bal.h:74
@ BAL_STATEMACH_INITIALIZED
Definition: bal.h:75
@ BAL_STATEMACH_CHECK_BALANCING
Definition: bal.h:76
BAL_STATEMACH_SUB_e
Definition: bal.h:90
@ BAL_ACTIVATE_BALANCING
Definition: bal.h:94
@ BAL_CHECK_IMBALANCES
Definition: bal.h:92
@ BAL_ENTRY
Definition: bal.h:91
@ BAL_COMPUTE_IMBALANCES
Definition: bal.h:93
int32_t BAL_GetBalancingThreshold_mV(void)
get balancing threshold
Definition: bal_cfg.c:88
#define BAL_LOWER_VOLTAGE_LIMIT_mV
Definition: bal_cfg.h:87
#define BAL_STATEMACH_SHORTTIME_100ms
Definition: bal_cfg.h:65
#define BAL_DEFAULT_THRESHOLD_mV
Definition: bal_cfg.h:75
#define BAL_UPPER_TEMPERATURE_LIMIT_ddegC
Definition: bal_cfg.h:90
#define BAL_STATEMACH_BALANCINGTIME_100ms
Definition: bal_cfg.h:72
#define BAL_HYSTERESIS_mV
Definition: bal_cfg.h:84
DATA_BLOCK_BALANCING_CONTROL_s * TEST_BAL_GetBalancingControl(void)
STD_RETURN_TYPE_e BAL_GetInitializationState(void)
gets the initialization state.
static void BAL_ActivateBalancing(void)
static BAL_STATE_s bal_state
BAL_STATEMACH_e BAL_GetState(void)
static void BAL_ProcessStateBalancing(void)
BAL_RETURN_TYPE_e BAL_SetStateRequest(BAL_STATE_REQUEST_e stateRequest)
sets the current state request of the state variable bal_state.
static bool BAL_CheckImbalances(void)
static DATA_BLOCK_BALANCING_CONTROL_s bal_balancing
static void BAL_Deactivate(void)
Deactivates history based balancing.
void BAL_Trigger(void)
trigger function for the BAL driver state machine.
static DATA_BLOCK_CELL_VOLTAGE_s bal_cellVoltage
static void BAL_ComputeImbalances(void)
BAL_STATE_s * TEST_BAL_GetBalancingState(void)
static void BAL_ProcessStateCheckBalancing(void)
State machine subfunction to check if balancing is allowed.
Header for the history-based balancing strategy module.
Configuration of the battery cell (e.g., minimum and maximum cell voltage)
#define BC_CAPACITY_mAh
Cell capacity used for SOC calculation.
#define BS_BALANCING_RESISTANCE_ohm
#define BS_NR_OF_STRINGS
Number of parallel strings in the battery pack.
#define BS_NR_OF_CELL_BLOCKS_PER_STRING
BMS_CURRENT_FLOW_STATE_e BMS_GetBatterySystemState(void)
Returns current battery system state (charging/discharging, resting or in relaxation phase)
Definition: bms.c:1586
bms driver header
@ BMS_AT_REST
Definition: bms.h:76
Database module header.
#define DATA_READ_DATA(...)
Definition: database.h:86
#define DATA_WRITE_DATA(...)
Definition: database.h:96
@ DATA_BLOCK_ID_BALANCING_CONTROL
Definition: database_cfg.h:83
@ DATA_BLOCK_ID_MIN_MAX
Definition: database_cfg.h:81
@ DATA_BLOCK_ID_CELL_VOLTAGE
Definition: database_cfg.h:79
#define FAS_ASSERT(x)
Assertion macro that asserts that x is true.
Definition: fassert.h:250
#define FAS_TRAP
Define that evaluates to essential boolean false thus tripping an assert.
Definition: fassert.h:129
STD_RETURN_TYPE_e
Definition: fstd_types.h:82
@ STD_NOT_OK
Definition: fstd_types.h:84
float_t SE_GetStateOfChargeFromVoltage(int16_t voltage_mV)
look-up table for SOC initialization
Definition: soc_counting.c:365
Declaration of the OS wrapper interface.
void OS_ExitTaskCritical(void)
Exit Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os_freertos.c:138
void OS_EnterTaskCritical(void)
Enter Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os_freertos.c:134
Header for state-estimation module responsible for the estimation of state-of-charge (SOC),...
int32_t balancingThreshold
Definition: bal.h:142
BAL_STATE_REQUEST_e stateRequest
Definition: bal.h:133
STD_RETURN_TYPE_e initializationFinished
Definition: bal.h:140
uint8_t triggerEntry
Definition: bal.h:138
bool active
Definition: bal.h:141
bool balancingGlobalAllowed
Definition: bal.h:144
BAL_STATEMACH_SUB_e substate
Definition: bal.h:135
bool balancingAllowed
Definition: bal.h:143
uint16_t timer
Definition: bal.h:132
BAL_STATEMACH_e state
Definition: bal.h:134
uint32_t deltaCharge_mAs[BS_NR_OF_STRINGS][BS_NR_OF_CELL_BLOCKS_PER_STRING]
Definition: database_cfg.h:257
DATA_BLOCK_HEADER_s header
Definition: database_cfg.h:250
uint8_t balancingState[BS_NR_OF_STRINGS][BS_NR_OF_CELL_BLOCKS_PER_STRING]
Definition: database_cfg.h:255
uint16_t nrBalancedCells[BS_NR_OF_STRINGS]
Definition: database_cfg.h:258
DATA_BLOCK_HEADER_s header
Definition: database_cfg.h:132
int16_t cellVoltage_mV[BS_NR_OF_STRINGS][BS_NR_OF_CELL_BLOCKS_PER_STRING]
Definition: database_cfg.h:135
DATA_BLOCK_ID_e uniqueId
Definition: database_cfg.h:122
int16_t maximumTemperature_ddegC[BS_NR_OF_STRINGS]
Definition: database_cfg.h:178
DATA_BLOCK_HEADER_s header
Definition: database_cfg.h:162
int16_t minimumCellVoltage_mV[BS_NR_OF_STRINGS]
Definition: database_cfg.h:165