foxBMS - Unit Tests  1.4.0
The foxBMS Unit Tests API Documentation
imd.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 imd.h
44  * @author foxBMS Team
45  * @date 2020-11-20 (date of creation)
46  * @updated 2022-07-28 (date of last update)
47  * @version v1.4.0
48  * @ingroup DRIVERS
49  * @prefix IMD
50  *
51  * @brief API header for the insulation monitoring device
52  *
53  */
54 
55 #ifndef FOXBMS__IMD_H_
56 #define FOXBMS__IMD_H_
57 
58 /*========== Includes =======================================================*/
59 #include "general.h"
60 
61 #include "can_cfg.h"
62 #include "ftask_cfg.h"
63 
64 #include "database.h"
65 
66 /*========== Macros and Definitions =========================================*/
67 #define IMD_PERIODIC_CALL_TIME_ms (FTSK_TASK_CYCLIC_100MS_CYCLE_TIME)
68 
69 /** Minimum required insulation resistance - Error threshold */
70 #define IMD_ERROR_THRESHOLD_INSULATION_RESISTANCE_kOhm (500u)
71 
72 /** Minimum required insulation resistance - Warning threshold */
73 #define IMD_WARNING_THRESHOLD_INSULATION_RESISTANCE_kOhm (750u)
74 
75 /** Possible return values when state requests are made to the IMD statemachine */
76 typedef enum {
77  IMD_REQUEST_OK, /*!< request was successful */
78  IMD_REQUEST_PENDING, /*!< requested to be executed */
79  IMD_ILLEGAL_REQUEST, /*!< Request can not be executed */
80  IMD_ALREADY_INITIALIZED, /*!< IMD statemachine already initialized */
82 
83 /** State requests for the IMD statemachine */
84 typedef enum {
85  IMD_STATE_INITIALIZE_REQUEST, /*!< request for initialization */
86  IMD_STATE_SWITCH_ON_REQUEST, /*!< request to switch on IMD device */
87  IMD_STATE_SHUTDOWN_REQUEST, /*!< request for shut down */
88  IMD_STATE_NO_REQUEST, /*!< dummy request for no request */
90 
91 /** States of the state machine */
92 typedef enum {
93  IMD_FSM_STATE_DUMMY, /*!< dummy state - always the first state */
94  IMD_FSM_STATE_HAS_NEVER_RUN, /*!< never run state - always the second state */
95  IMD_FSM_STATE_UNINITIALIZED, /*!< uninitialized state */
96  IMD_FSM_STATE_INITIALIZATION, /*!< initializing the state machine */
97  IMD_FSM_STATE_IMD_ENABLE, /*!< switch on IMD */
98  IMD_FSM_STATE_SHUTDOWN, /*!< shut down state of IMD state machine */
99  IMD_FSM_STATE_RUNNING, /*!< operational mode of the state machine */
100  IMD_FSM_STATE_ERROR, /*!< state for error processing */
102 
103 /*========== Extern Constant and Variable Declarations ======================*/
104 
105 /*========== Extern Function Prototypes =====================================*/
106 /**
107  * @brief Request initialization of IMD statemachine
108  * @return Always #IMD_REQUEST_OK
109  */
111 
112 /**
113  * @brief Request to activate the actual IMD measurement
114  * @return Always #IMD_REQUEST_OK
115  */
117 
118 /**
119  * @brief Request to deactivate the actual IMD measurement
120  * @return Always #IMD_REQUEST_OK
121  */
123 
124 /**
125  * @brief Gets the initialization state.
126  * @details This function is used for getting the IMD initialization state.
127  * @return true if statemachine initialized, otherwise false
128  */
129 extern bool IMD_GetInitializationState(void);
130 
131 /**
132  * @brief trigger function for the IMD driver state machine.
133  * @details This function contains the sequence of events in the IMD state
134  * machine. It must be called time-triggered, every 100ms.
135  * @returns returns #STD_OK if trigger called successfully
136  */
137 extern STD_RETURN_TYPE_e IMD_Trigger(void);
138 
139 /**************************************************** FOLLOWING FUNCTIONS NEED TO BE IMPLEMENTED BY THE IMD DRIVER */
140 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE imd-documentation */
141 /**
142  * @brief Processes the initialization state
143  * @details This function needs to be implemented in the dedicated driver. This
144  * function initializes the required SW modules and peripherals but
145  * does not start the actual IMD measurement.
146  * @return #IMD_FSM_STATE_INITIALIZATION if initialization not fininished and
147  * another call is required. #IMD_FSM_STATE_IMD_ENABLE if
148  * initialization is finished and #IMD_FSM_STATE_ERROR if an error is
149  * detected that prohibits a working IMD driver.
150  */
152 
153 /**
154  * @brief Processes the IMD enable state
155  * @details This function needs to be implemented in the dedicated driver. This
156  * function enables the actual IMD device to start the insulation
157  * measurement. Functionality need to be fullfilled after one call.
158  * @return #IMD_FSM_STATE_RUNNING if startup has been completed. Returns #IMD_FSM_STATE_ERROR if an error is
159  * detected that prohibits a working IMD driver.
160  */
162 
163 /**
164  * @brief Processes the running state
165  * @details This function needs to be implemented in the dedicated driver
166  * @param pTableInsulationMonitoring pointer to insulation monitoring
167  * database entry
168  * @return #IMD_FSM_STATE_RUNNING if measurement works as expected, otherwise
169  * #IMD_FSM_STATE_ERROR if an error is detected that prohibits a
170  * further execution of the IMD driver.
171  */
173 
174 /**
175  * @brief Processes the shutdown state
176  * @details This function needs to be implemented in the dedicated driver. This
177  * function disables the actual IMD device to stop the insulation
178  * measurement.
179  * @return #IMD_FSM_STATE_SHUTDOWN if shutdown state is not fininished and
180  * another call is required. #IMD_FSM_STATE_IMD_ENABLE if shut down
181  * has been completed and #IMD_FSM_STATE_ERROR if an error is detected
182  * that prohibits a working IMD driver.
183  */
185 
186 /* INCLUDE MARKER FOR THE DOCUMENTATION; DO NOT MOVE imd-documentation */
187 /*******************************************************************************************************************/
188 
189 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
190 
191 #endif /* FOXBMS__IMD_H_ */
Headers for the configuration for the CAN module.
Database module header.
STD_RETURN_TYPE_e
Definition: fstd_types.h:81
Task configuration header.
General macros and definitions for the whole platform.
IMD_RETURN_TYPE_e IMD_RequestInsulationMeasurement(void)
Request to activate the actual IMD measurement.
Definition: imd.c:513
IMD_FSM_STATES_e IMD_ProcessInitializationState(void)
Processes the initialization state.
Definition: bender_ir155.c:207
bool IMD_GetInitializationState(void)
Gets the initialization state.
Definition: imd.c:521
STD_RETURN_TYPE_e IMD_Trigger(void)
trigger function for the IMD driver state machine.
Definition: imd.c:525
IMD_FSM_STATES_e IMD_ProcessShutdownState(void)
Processes the shutdown state.
Definition: bender_ir155.c:222
IMD_FSM_STATES_e IMD_ProcessEnableState(void)
Processes the IMD enable state.
Definition: bender_ir155.c:211
IMD_RETURN_TYPE_e IMD_RequestMeasurementStop(void)
Request to deactivate the actual IMD measurement.
Definition: imd.c:517
IMD_FSM_STATES_e
Definition: imd.h:92
@ IMD_FSM_STATE_RUNNING
Definition: imd.h:99
@ IMD_FSM_STATE_SHUTDOWN
Definition: imd.h:98
@ IMD_FSM_STATE_INITIALIZATION
Definition: imd.h:96
@ IMD_FSM_STATE_HAS_NEVER_RUN
Definition: imd.h:94
@ IMD_FSM_STATE_IMD_ENABLE
Definition: imd.h:97
@ IMD_FSM_STATE_DUMMY
Definition: imd.h:93
@ IMD_FSM_STATE_UNINITIALIZED
Definition: imd.h:95
@ IMD_FSM_STATE_ERROR
Definition: imd.h:100
IMD_STATE_REQUEST_e
Definition: imd.h:84
@ IMD_STATE_SWITCH_ON_REQUEST
Definition: imd.h:86
@ IMD_STATE_SHUTDOWN_REQUEST
Definition: imd.h:87
@ IMD_STATE_INITIALIZE_REQUEST
Definition: imd.h:85
@ IMD_STATE_NO_REQUEST
Definition: imd.h:88
IMD_RETURN_TYPE_e
Definition: imd.h:76
@ IMD_ALREADY_INITIALIZED
Definition: imd.h:80
@ IMD_ILLEGAL_REQUEST
Definition: imd.h:79
@ IMD_REQUEST_PENDING
Definition: imd.h:78
@ IMD_REQUEST_OK
Definition: imd.h:77
IMD_RETURN_TYPE_e IMD_RequestInitialization(void)
Request initialization of IMD statemachine.
Definition: imd.c:509
IMD_FSM_STATES_e IMD_ProcessRunningState(DATA_BLOCK_INSULATION_MONITORING_s *pTableInsulationMonitoring)
Processes the running state.
Definition: bender_ir155.c:217