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