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