foxBMS  1.1.0
The foxBMS Battery Management System API Documentation
sys.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 sys.h
44  * @author foxBMS Team
45  * @date 2020-02-24 (date of creation)
46  * @updated 2021-05-19 (date of last update)
47  * @ingroup ENGINE
48  * @prefix SYS
49  *
50  * @brief Sys driver header
51  *
52  *
53  */
54 
55 #ifndef FOXBMS__SYS_H_
56 #define FOXBMS__SYS_H_
57 
58 /*========== Includes =======================================================*/
59 #include "sys_cfg.h"
60 
61 /*========== Macros and Definitions =========================================*/
62 
63 /** Symbolic names for busyness of the system */
64 typedef enum SYS_CHECK {
65  SYS_CHECK_OK, /*!< system ok */
66  SYS_CHECK_BUSY, /*!< system busy */
67  SYS_CHECK_NOT_OK, /*!< system not ok */
69 
70 /** States of the state machine */
71 typedef enum SYS_FSM_STATES {
72  SYS_FSM_STATE_DUMMY, /*!< dummy state - always the first state */
73  SYS_FSM_STATE_HAS_NEVER_RUN, /*!< never run state - always the second state */
74  SYS_FSM_STATE_UNINITIALIZED, /*!< uninitialized state */
75  SYS_FSM_STATE_INITIALIZATION, /*!< initializing the state machine */
76  SYS_FSM_STATE_RUNNING, /*!< operational mode of the state machine */
77  SYS_FSM_STATE_ERROR, /*!< state for error processing */
79 
80 /** Substates of the state machine */
81 typedef enum SYS_FSM_SUBSTATES {
82  SYS_FSM_SUBSTATE_DUMMY, /*!< dummy state - always the first substate */
83  SYS_FSM_SUBSTATE_ENTRY, /*!< entry state - always the second substate */
94  SYS_FSM_SUBSTATE_RUNNING, /*!< fist running substate */
96 
97 /*================== Constant and Variable Definitions ======================*/
98 
99 /** States of the SYS state machine */
100 typedef enum SYS_STATEMACH {
101  /* Init-Sequence */
104  SYS_STATEMACH_SYSTEM_BIST, /*!< run a built-in self-test */
116  SYS_STATEMACH_ERROR, /*!< Error-State */
118 
119 /** Substates of the SYS state machine */
120 typedef enum SYS_STATEMACH_SUB {
121  SYS_ENTRY, /*!< Substate entry state */
122  SYS_CHECK_ERROR_FLAGS, /*!< Substate check if any error flag set */
123  SYS_CHECK_STATE_REQUESTS, /*!< Substate check if there is a state request */
124  SYS_WAIT_INITIALIZATION_SBC, /*!< Substate to wait for initialization of the sbc state machine */
125  SYS_WAIT_INITIALIZATION_INTERLOCK, /*!< Substate to wait for initialization of the interlock state machine */
126  SYS_WAIT_INITIALIZATION_CONT, /*!< Substate to wait for initialization of the contactor state machine */
127  SYS_WAIT_INITIALIZATION_BAL, /*!< Substate to wait for initialization of the balancing state machine */
128  SYS_WAIT_INITIALIZATION_BAL_GLOBAL_ENABLE, /*!< Substate to enable/disable balancing globally */
129  SYS_WAIT_INITIALIZATION_BMS, /*!< Substate to wait for initialization of the bms state machine */
130  SYS_WAIT_FIRST_MEASUREMENT_CYCLE, /*!< Substate to wait for first measurement cycle to complete */
131  SYS_WAIT_CURRENT_SENSOR_PRESENCE, /*!< Substate to wait for first measurement cycle to complete */
132  SYS_SBC_INIT_ERROR, /*!< Substate error of SBC initialization */
133  SYS_CONT_INIT_ERROR, /*!< Substate error of contactor state machine initialization */
134  SYS_BAL_INIT_ERROR, /*!< Substate error of balancing state machine initialization */
135  SYS_ILCK_INIT_ERROR, /*!< Substate error of contactor state machine initialization */
136  SYS_BMS_INIT_ERROR, /*!< Substate error of bms state machine initialization */
137  SYS_MEAS_INIT_ERROR, /*!< Substate error if first measurement cycle does not complete */
138  SYS_CURRENT_SENSOR_PRESENCE_ERROR, /*!< Substate error if first measurement cycle does not complete */
140 
141 /** State requests for the SYS statemachine */
142 typedef enum SYS_STATE_REQUEST {
143  SYS_STATE_INIT_REQUEST, /*!< initialization request */
144  SYS_STATE_ERROR_REQUEST, /*!< error state requested */
145  SYS_STATE_NO_REQUEST, /*!< no request */
147 
148 /** Possible return values when state requests are made to the SYS statemachine */
149 typedef enum SYS_RETURN_TYPE {
150  SYS_OK, /*!< sys --> ok */
151  SYS_BUSY_OK, /*!< sys busy --> ok */
152  SYS_REQUEST_PENDING, /*!< requested to be executed */
153  SYS_ILLEGAL_REQUEST, /*!< Request can not be executed */
154  SYS_ALREADY_INITIALIZED, /*!< Initialization of LTC already finished */
155  SYS_ILLEGAL_TASK_TYPE, /*!< Illegal */
157 
158 /**
159  * This structure contains all the variables relevant for the CONT state machine.
160  * The user can get the current state of the CONT state machine with this variable
161  */
162 typedef struct SYS_STATE {
163  uint16_t timer; /*!< time in ms before the state machine processes the next state, e.g. in counts of 1ms */
164  SYS_STATE_REQUEST_e stateRequest; /*!< current state request made to the state machine */
165  SYS_STATEMACH_e state; /*!< state of Driver State Machine */
166  SYS_STATEMACH_SUB_e substate; /*!< current substate of the state machine */
167  SYS_STATEMACH_e lastState; /*!< previous state of the state machine */
168  SYS_STATEMACH_SUB_e lastSubstate; /*!< previous substate of the state machine */
169  uint32_t illegalRequestsCounter; /*!< counts the number of illegal requests to the SYS state machine */
170  uint16_t initializationTimeout; /*!< Timeout to wait for initialization of state machine state machine */
171  uint8_t triggerEntry; /*!< counter for re-entrance protection (function running flag) */
173 
174 /*========== Extern Constant and Variable Declarations ======================*/
175 
176 extern SYS_STATE_s sys_state;
177 
178 /*========== Extern Function Prototypes =====================================*/
179 /**
180  * @brief sets the current state request of the state variable sys_state.
181  * @details This function is used to make a state request to the state machine,
182  * e.g., start voltage measurement, read result of voltage
183  * measurement, re-initialization. It calls #SYS_CheckStateRequest()
184  * to check if the request is valid. The state request is rejected if
185  * is not valid. The result of the check is returned immediately, so
186  * that the requester can act in case it made a non-valid state
187  * request.
188  * @param stateRequest state requested to set
189  * @return If the request was successfully set, it returns the SYS_OK, else
190  * the current state of requests (type #SYS_STATE_REQUEST_e)
191  */
193 
194 /**
195  * @brief tick function, call this to advance the state machine
196  * @details This function contains the sequence of events in the SYS state
197  * machine. It must be called time-triggered, every 10ms.
198  */
199 extern STD_RETURN_TYPE_e SYS_Trigger(SYS_STATE_s *pSystemState);
200 
201 /** built-in self-test for the macros in general.h */
202 extern void SYS_GeneralMacroBist(void);
203 
204 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
205 
206 #endif /* FOXBMS__SYS_H_ */
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
Definition: sys.h:162
uint32_t illegalRequestsCounter
Definition: sys.h:169
SYS_STATE_REQUEST_e stateRequest
Definition: sys.h:164
uint8_t triggerEntry
Definition: sys.h:171
uint16_t timer
Definition: sys.h:163
SYS_STATEMACH_SUB_e lastSubstate
Definition: sys.h:168
SYS_STATEMACH_e lastState
Definition: sys.h:167
uint16_t initializationTimeout
Definition: sys.h:170
SYS_STATEMACH_SUB_e substate
Definition: sys.h:166
SYS_STATEMACH_e state
Definition: sys.h:165
enum SYS_CHECK SYS_CHECK_e
SYS_CHECK
Definition: sys.h:64
@ SYS_CHECK_NOT_OK
Definition: sys.h:67
@ SYS_CHECK_OK
Definition: sys.h:65
@ SYS_CHECK_BUSY
Definition: sys.h:66
enum SYS_FSM_STATES SYS_FSM_STATES_e
SYS_STATEMACH
Definition: sys.h:100
@ SYS_STATEMACH_SYSTEM_BIST
Definition: sys.h:104
@ SYS_STATEMACH_INITIALIZE_SBC
Definition: sys.h:106
@ SYS_STATEMACH_UNINITIALIZED
Definition: sys.h:102
@ SYS_STATEMACH_INITIALIZE_ISOGUARD
Definition: sys.h:115
@ SYS_STATEMACH_INITIALIZE_BALANCING
Definition: sys.h:109
@ SYS_STATEMACH_INITIALIZATION
Definition: sys.h:103
@ SYS_STATEMACH_INITIALIZE_MISC
Definition: sys.h:113
@ SYS_STATEMACH_INITIALIZED
Definition: sys.h:105
@ SYS_STATEMACH_INITIALIZE_CONTACTORS
Definition: sys.h:108
@ SYS_STATEMACH_RUNNING
Definition: sys.h:111
@ SYS_STATEMACH_ERROR
Definition: sys.h:116
@ SYS_STATEMACH_FIRST_MEASUREMENT_CYCLE
Definition: sys.h:112
@ SYS_STATEMACH_INITIALIZE_BMS
Definition: sys.h:110
@ SYS_STATEMACH_CHECK_CURRENT_SENSOR_PRESENCE
Definition: sys.h:114
@ SYS_STATEMACH_INITIALIZE_INTERLOCK
Definition: sys.h:107
SYS_RETURN_TYPE
Definition: sys.h:149
@ SYS_ILLEGAL_TASK_TYPE
Definition: sys.h:155
@ SYS_OK
Definition: sys.h:150
@ SYS_REQUEST_PENDING
Definition: sys.h:152
@ SYS_ALREADY_INITIALIZED
Definition: sys.h:154
@ SYS_BUSY_OK
Definition: sys.h:151
@ SYS_ILLEGAL_REQUEST
Definition: sys.h:153
enum SYS_FSM_SUBSTATES SYS_FSM_SUBSTATES_e
SYS_FSM_STATES
Definition: sys.h:71
@ SYS_FSM_STATE_RUNNING
Definition: sys.h:76
@ SYS_FSM_STATE_UNINITIALIZED
Definition: sys.h:74
@ SYS_FSM_STATE_INITIALIZATION
Definition: sys.h:75
@ SYS_FSM_STATE_HAS_NEVER_RUN
Definition: sys.h:73
@ SYS_FSM_STATE_ERROR
Definition: sys.h:77
@ SYS_FSM_STATE_DUMMY
Definition: sys.h:72
struct SYS_STATE SYS_STATE_s
enum SYS_RETURN_TYPE SYS_RETURN_TYPE_e
enum SYS_STATEMACH SYS_STATEMACH_e
SYS_RETURN_TYPE_e SYS_SetStateRequest(SYS_STATE_REQUEST_e stateRequest)
sets the current state request of the state variable sys_state.
Definition: sys.c:565
SYS_FSM_SUBSTATES
Definition: sys.h:81
@ SYS_FSM_SUBSTATE_INITIALIZATION_INTERLOCK
Definition: sys.h:86
@ SYS_FSM_SUBSTATE_INITIALIZATION_MISC
Definition: sys.h:92
@ SYS_FSM_SUBSTATE_INITIALIZATION_FIRST_MEASUREMENT_CYCLE
Definition: sys.h:90
@ SYS_FSM_SUBSTATE_DUMMY
Definition: sys.h:82
@ SYS_FSM_SUBSTATE_INITIALIZATION_BOOT_MESSAGE
Definition: sys.h:85
@ SYS_FSM_SUBSTATE_INITIALIZATION_INSULATION_GUARD
Definition: sys.h:89
@ SYS_FSM_SUBSTATE_INITIALIZATION_CONTACTORS
Definition: sys.h:87
@ SYS_FSM_SUBSTATE_INITIALIZATION_BALANCING
Definition: sys.h:88
@ SYS_FSM_SUBSTATE_ENTRY
Definition: sys.h:83
@ SYS_FSM_SUBSTATE_INITIALIZATION_CHECK_CURRENT_SENSOR
Definition: sys.h:91
@ SYS_FSM_SUBSTATE_RUNNING
Definition: sys.h:94
@ SYS_FSM_SUBSTATE_INITIALIZATION_SBC
Definition: sys.h:84
@ SYS_FSM_SUBSTATE_INITIALIZATION_BMS
Definition: sys.h:93
enum SYS_STATEMACH_SUB SYS_STATEMACH_SUB_e
SYS_STATE_REQUEST
Definition: sys.h:142
@ SYS_STATE_NO_REQUEST
Definition: sys.h:145
@ SYS_STATE_INIT_REQUEST
Definition: sys.h:143
@ SYS_STATE_ERROR_REQUEST
Definition: sys.h:144
SYS_STATEMACH_SUB
Definition: sys.h:120
@ SYS_CONT_INIT_ERROR
Definition: sys.h:133
@ SYS_CHECK_ERROR_FLAGS
Definition: sys.h:122
@ SYS_WAIT_FIRST_MEASUREMENT_CYCLE
Definition: sys.h:130
@ SYS_WAIT_INITIALIZATION_BAL_GLOBAL_ENABLE
Definition: sys.h:128
@ SYS_BAL_INIT_ERROR
Definition: sys.h:134
@ SYS_ILCK_INIT_ERROR
Definition: sys.h:135
@ SYS_WAIT_INITIALIZATION_BMS
Definition: sys.h:129
@ SYS_SBC_INIT_ERROR
Definition: sys.h:132
@ SYS_WAIT_INITIALIZATION_SBC
Definition: sys.h:124
@ SYS_WAIT_INITIALIZATION_BAL
Definition: sys.h:127
@ SYS_WAIT_INITIALIZATION_INTERLOCK
Definition: sys.h:125
@ SYS_CURRENT_SENSOR_PRESENCE_ERROR
Definition: sys.h:138
@ SYS_MEAS_INIT_ERROR
Definition: sys.h:137
@ SYS_WAIT_CURRENT_SENSOR_PRESENCE
Definition: sys.h:131
@ SYS_BMS_INIT_ERROR
Definition: sys.h:136
@ SYS_ENTRY
Definition: sys.h:121
@ SYS_CHECK_STATE_REQUESTS
Definition: sys.h:123
@ SYS_WAIT_INITIALIZATION_CONT
Definition: sys.h:126
SYS_STATE_s sys_state
Definition: sys.c:92
enum SYS_STATE_REQUEST SYS_STATE_REQUEST_e
STD_RETURN_TYPE_e SYS_Trigger(SYS_STATE_s *pSystemState)
tick function, call this to advance the state machine
Definition: sys.c:622
void SYS_GeneralMacroBist(void)
Definition: sys.c:614
Sys driver configuration header.