foxBMS  1.4.1
The foxBMS Battery Management System API Documentation
bal.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 bal.h
44  * @author foxBMS Team
45  * @date 2020-02-24 (date of creation)
46  * @updated 2022-10-27 (date of last update)
47  * @version v1.4.1
48  * @ingroup APPLICATION
49  * @prefix BAL
50  *
51  * @brief Header for the driver for balancing
52  *
53  */
54 
55 #ifndef FOXBMS__BAL_H_
56 #define FOXBMS__BAL_H_
57 
58 /*========== Includes =======================================================*/
59 #include "bal_cfg.h"
60 
61 #include "database.h"
62 
63 /*========== Macros and Definitions =========================================*/
64 
65 /*========== Extern Constant and Variable Declarations ======================*/
66 /**
67  * States of the BAL state machine
68  */
69 typedef enum {
70  /* Init-Sequence */
80  BAL_STATEMACH_UNDEFINED, /*!< undefined state */
81  BAL_STATEMACH_RESERVED1, /*!< reserved state */
82  BAL_STATEMACH_ERROR, /*!< Error-State: */
84 
85 /**
86  * Substates of the BAL state machine
87  */
88 typedef enum {
89  BAL_ENTRY, /*!< Substate entry state */
90  BAL_CHECK_IMBALANCES, /*!< Check if balancing has been initialized */
91  BAL_COMPUTE_IMBALANCES, /*!< Compute imbalances */
92  BAL_ACTIVATE_BALANCING, /*!< Activated balancing resistors */
93  BAL_CHECK_LOWEST_VOLTAGE, /*!< Check if lowest voltage is still above limit */
94  BAL_CHECK_CURRENT, /*!< Check if current is still under limit */
96 
97 /**
98  * State requests for the BAL statemachine
99  */
100 typedef enum {
107  BAL_STATE_NO_REQUEST, /*!< default state: no request to the statemachine */
109 
110 /**
111  * Possible return values when state requests are made to the BAL statemachine
112  */
113 typedef enum {
114  BAL_OK, /*!< BAL --> ok */
115  BAL_BUSY_OK, /*!< BAL busy */
116  BAL_REQUEST_PENDING, /*!< requested to be executed */
117  BAL_ILLEGAL_REQUEST, /*!< Request can not be executed */
118  BAL_INIT_ERROR, /*!< Error state: Source: Initialization */
119  BAL_OK_FROM_ERROR, /*!< Return from error --> ok */
120  BAL_ERROR, /*!< General error state */
121  BAL_ALREADY_INITIALIZED, /*!< Initialization of BAL already finished */
122  BAL_ILLEGAL_TASK_TYPE, /*!< Illegal */
124 
125 /**
126  * This structure contains all the variables relevant for the BAL state machine.
127  * The user can get the current state of the BAL state machine with this variable
128  */
129 typedef struct {
130  uint16_t timer; /*!< time in ms before the state machine processes the next state, e.g. in counts of 1ms */
131  BAL_STATE_REQUEST_e stateRequest; /*!< current state request made to the state machine */
132  BAL_STATEMACH_e state; /*!< state of Driver State Machine */
133  BAL_STATEMACH_SUB_e substate; /*!< current substate of the state machine */
134  BAL_STATEMACH_e lastState; /*!< previous state of the state machine */
135  uint8_t lastSubstate; /*!< previous substate of the state machine */
136  uint8_t triggerEntry; /*!< counter for re-entrance protection (function running flag) */
137  uint32_t errorRequestCounter; /*!< counts the number of illegal requests to the BAL state machine */
138  STD_RETURN_TYPE_e initializationFinished; /*!< #STD_OK if statemachine initialized, otherwise #STD_NOT_OK */
139  bool active; /*!< indicate if balancing active or not */
140  int32_t balancingThreshold; /*!< effective balancing threshold */
141  bool balancingAllowed; /*!< flag to disable balancing */
142  bool balancingGlobalAllowed; /*!< flag to globally disable balancing */
143 } BAL_STATE_s;
144 
145 /*========== Extern Function Prototypes =====================================*/
146 
147 /** @brief Saves the last state and the last substate */
148 extern void BAL_SaveLastStates(BAL_STATE_s *pBalancingState);
149 
150 /**
151  * @brief re-entrance check of BAL state machine trigger function
152  * @details This function is not re-entrant and should only be called time- or
153  * event-triggered. It increments the triggerentry counter from the
154  * state variable. It should never be called by two different
155  * processes, so if it is the case, triggerentry should never be
156  * higher than 0 when this function is called.
157  * @return 0 if no further instance of the function is active, 0xff otherwise
158  */
159 extern uint8_t BAL_CheckReEntrance(BAL_STATE_s *currentState);
160 
161 /**
162  * @brief transfers the current state request to the state machine.
163  * @details This function takes the current state request from current state
164  * and transfers it to the state machine. It resets the value from
165  * to #BAL_STATE_NO_REQUEST
166  * @return current state request
167  */
169 
170 /**
171  * @brief checks the state requests that are made.
172  * @details This function checks the validity of the state requests. The
173  * results of the checked is returned immediately.
174  * @param pCurrentState pointer to the current state
175  * @param stateRequest state request to be checked
176  * @return result of the state request that was made
177  */
178 extern BAL_RETURN_TYPE_e BAL_CheckStateRequest(BAL_STATE_s *pCurrentState, BAL_STATE_REQUEST_e stateRequest);
179 
180 /**
181  * @brief Substate handling function for #BAL_Trigger()
182  * @param pCurrentState pointer to the current state
183  * @param stateRequest state request to set
184  */
185 extern void BAL_ProcessStateUninitalized(BAL_STATE_s *pCurrentState, BAL_STATE_REQUEST_e stateRequest);
186 
187 /**
188  * @brief State machine subfunction to initialize the balancing state machine
189  * @details TODO
190  */
191 extern void BAL_ProcessStateInitialization(BAL_STATE_s *currentState);
192 
193 /**
194  * @brief State machine subfunction to transfer from an initalized state to
195  * "running" states of th state machine
196  * @details TODO
197  */
198 extern void BAL_ProcessStateInitialized(BAL_STATE_s *currentState);
199 
200 /** @brief Generic initialization function for the balancing module */
202 
203 /**
204  * @brief sets the current state request of the state variable bal_state.
205  * @details This function is used to make a state request to the state machine,
206  * e.g, start voltage measurement, read result of voltage measurement,
207  * re-initialization. It calls #BAL_CheckStateRequest() to check if
208  * the request is valid. The state request is rejected if is not
209  * valid. The result of the check is returned immediately, so that the
210  * requester can act in case it made a non-valid state request.
211  * @param stateRequest state request to set
212  * @return current state request
213  */
215 
216 /**
217  * @brief gets the initialization state.
218  * @details This function is used for getting the balancing initialization
219  * state
220  * @return #STD_OK if initialized, otherwise #STD_NOT_OK
221  */
223 
224 /**
225  * @brief trigger function for the BAL driver state machine.
226  * @details This function contains the sequence of events in the BAL state
227  * machine. It must be called time-triggered, every 100 milliseconds.
228  */
229 extern void BAL_Trigger(void);
230 
231 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
232 #ifdef UNITY_UNIT_TEST
233 extern BAL_STATEMACH_e BAL_GetState(void);
234 #endif
235 /*========== Getter for static Variables (Unit Test) ========================*/
236 #ifdef UNITY_UNIT_TEST
237 extern DATA_BLOCK_BALANCING_CONTROL_s *TEST_BAL_GetBalancingControl(void);
238 extern BAL_STATE_s *TEST_BAL_GetBalancingState(void);
239 #endif
240 
241 #endif /* FOXBMS__BAL_H_ */
STD_RETURN_TYPE_e BAL_GetInitializationState(void)
gets the initialization state.
BAL_RETURN_TYPE_e
Definition: bal.h:113
@ BAL_ILLEGAL_TASK_TYPE
Definition: bal.h:122
@ BAL_ALREADY_INITIALIZED
Definition: bal.h:121
@ BAL_BUSY_OK
Definition: bal.h:115
@ BAL_INIT_ERROR
Definition: bal.h:118
@ BAL_OK_FROM_ERROR
Definition: bal.h:119
@ BAL_ERROR
Definition: bal.h:120
@ BAL_OK
Definition: bal.h:114
@ BAL_ILLEGAL_REQUEST
Definition: bal.h:117
@ BAL_REQUEST_PENDING
Definition: bal.h:116
STD_RETURN_TYPE_e BAL_Init(DATA_BLOCK_BALANCING_CONTROL_s *pControl)
Generic initialization function for the balancing module.
Definition: bal.c:148
void BAL_SaveLastStates(BAL_STATE_s *pBalancingState)
Saves the last state and the last substate.
Definition: bal.c:70
BAL_STATE_REQUEST_e
Definition: bal.h:100
@ BAL_STATE_GLOBAL_ENABLE_REQUEST
Definition: bal.h:106
@ BAL_STATE_ERROR_REQUEST
Definition: bal.h:102
@ BAL_STATE_NO_REQUEST
Definition: bal.h:107
@ BAL_STATE_ALLOWBALANCING_REQUEST
Definition: bal.h:104
@ BAL_STATE_NO_BALANCING_REQUEST
Definition: bal.h:103
@ BAL_STATE_INIT_REQUEST
Definition: bal.h:101
@ BAL_STATE_GLOBAL_DISABLE_REQUEST
Definition: bal.h:105
BAL_STATEMACH_e
Definition: bal.h:69
@ BAL_STATEMACH_ERROR
Definition: bal.h:82
@ BAL_STATEMACH_BALANCE
Definition: bal.h:75
@ BAL_STATEMACH_ALLOWBALANCING
Definition: bal.h:77
@ BAL_STATEMACH_UNINITIALIZED
Definition: bal.h:71
@ BAL_STATEMACH_INITIALIZATION
Definition: bal.h:72
@ BAL_STATEMACH_GLOBALENABLE
Definition: bal.h:79
@ BAL_STATEMACH_NO_BALANCING
Definition: bal.h:76
@ BAL_STATEMACH_RESERVED1
Definition: bal.h:81
@ BAL_STATEMACH_GLOBALDISABLE
Definition: bal.h:78
@ BAL_STATEMACH_INITIALIZED
Definition: bal.h:73
@ BAL_STATEMACH_CHECK_BALANCING
Definition: bal.h:74
@ BAL_STATEMACH_UNDEFINED
Definition: bal.h:80
void BAL_ProcessStateInitialization(BAL_STATE_s *currentState)
State machine subfunction to initialize the balancing state machine.
Definition: bal.c:171
void BAL_ProcessStateUninitalized(BAL_STATE_s *pCurrentState, BAL_STATE_REQUEST_e stateRequest)
Substate handling function for BAL_Trigger()
Definition: bal.c:157
BAL_RETURN_TYPE_e BAL_SetStateRequest(BAL_STATE_REQUEST_e stateRequest)
sets the current state request of the state variable bal_state.
BAL_STATE_REQUEST_e BAL_TransferStateRequest(BAL_STATE_s *currentState)
transfers the current state request to the state machine.
Definition: bal.c:100
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:179
uint8_t BAL_CheckReEntrance(BAL_STATE_s *currentState)
re-entrance check of BAL state machine trigger function
Definition: bal.c:84
void BAL_Trigger(void)
trigger function for the BAL driver state machine.
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:113
BAL_STATEMACH_SUB_e
Definition: bal.h:88
@ BAL_ACTIVATE_BALANCING
Definition: bal.h:92
@ BAL_CHECK_IMBALANCES
Definition: bal.h:90
@ BAL_ENTRY
Definition: bal.h:89
@ BAL_CHECK_LOWEST_VOLTAGE
Definition: bal.h:93
@ BAL_COMPUTE_IMBALANCES
Definition: bal.h:91
@ BAL_CHECK_CURRENT
Definition: bal.h:94
Header for the configuration for the driver for balancing.
Database module header.
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
uint32_t errorRequestCounter
Definition: bal.h:137
int32_t balancingThreshold
Definition: bal.h:140
BAL_STATE_REQUEST_e stateRequest
Definition: bal.h:131
STD_RETURN_TYPE_e initializationFinished
Definition: bal.h:138
uint8_t lastSubstate
Definition: bal.h:135
uint8_t triggerEntry
Definition: bal.h:136
BAL_STATEMACH_e lastState
Definition: bal.h:134
bool active
Definition: bal.h:139
bool balancingGlobalAllowed
Definition: bal.h:142
BAL_STATEMACH_SUB_e substate
Definition: bal.h:133
bool balancingAllowed
Definition: bal.h:141
uint16_t timer
Definition: bal.h:130
BAL_STATEMACH_e state
Definition: bal.h:132