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