foxBMS - Unit Tests  1.2.1
The foxBMS Unit Tests API Documentation
contactor.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 contactor.h
44  * @author foxBMS Team
45  * @date 2020-02-11 (date of creation)
46  * @updated 2021-03-24 (date of last update)
47  * @ingroup DRIVERS
48  * @prefix CONT
49  *
50  * @brief Headers for the driver for the contactors.
51  *
52  */
53 
54 #ifndef FOXBMS__CONTACTOR_H_
55 #define FOXBMS__CONTACTOR_H_
56 
57 /*========== Includes =======================================================*/
58 #include "contactor_cfg.h"
59 
60 /*========== Macros and Definitions =========================================*/
61 
62 /*========== Extern Constant and Variable Declarations ======================*/
63 
64 /*========== Extern Function Prototypes =====================================*/
65 
66 /**
67  * @brief Gets the latest value the contactors were set to.
68  * @param[in] name name of the contactor
69  * @return returns CONT_SWITCH_OFF or CONT_SWITCH_ON
70  */
72 
73 /**
74  * @brief Reads the feedback pin of every contactor and returns its current
75  * value (#CONT_SWITCH_OFF/#CONT_SWITCH_ON).
76  * @details If the contactor has a feedback pin the measured feedback is
77  * returned. If the contactor has no feedback pin, it is assumed that
78  * after a certain time the contactor has reached the requested state.
79  */
80 void CONT_GetContactorFeedback(void);
81 
82 /**
83  * @brief Sets the contactor state to its requested state, if the contactor
84  * is at that time not in the requested state.
85  * @details If the new state was already requested, but not reached (meaning
86  * the measured feedback does not return the requested state), there
87  * are two states: it can be still ok (#STD_OK), because the contactor
88  * has some time left to get physically in the requested state (passed
89  * time since the request is lower than the limit) or it can be not ok
90  * (#STD_NOT_OK), because there is timing violation, i.e. the
91  * contactor has surpassed the maximum time for getting in the
92  * requested state. It returns #STD_OK if the requested state was
93  * successfully set or if the contactor was at the requested state
94  * before.
95  * @param name
96  * @param requestedContactorState
97  * @return retVal (type: STD_RETURN_TYPE_e)
98  */
100  const CONT_NAMES_e name,
101  CONT_ELECTRICAL_STATE_TYPE_e requestedContactorState);
102 
103 /** @brief Substates of the CONT state machine */
104 typedef enum {
111 
112 /** @brief Names for connected power paths */
113 typedef enum CONT_POWER_LINE_e {
114  CONT_POWER_PATH_NONE, /*!< no power line is connected, contactors are open */
115  CONT_POWER_PATH_0, /*!< power line 0, e.g. used for the power train */
116 #if BS_SEPARATE_POWER_PATHS == 1
117  CONT_POWER_PATH_1, /*!< power line 1, e.g. used for charging */
118 #endif
120 
121 /**
122  * @brief Gets the current state.
123  * @details This function is used in the functioning of the CONT state machine.
124  * @param contactorNumber contactor to be addressed
125  * @return current state, taken from #CONT_ELECTRICAL_STATE_TYPE_e
126  */
127 extern CONT_ELECTRICAL_STATE_TYPE_e CONT_GetState(uint8_t contactorNumber);
128 
129 /**
130  * @brief Closes the contactor of a string.
131  * @details This function makes a close state request to the contactor of a
132  * specific string.
133  * @param stringNumber String addressed
134  */
135 extern STD_RETURN_TYPE_e CONT_CloseString(uint8_t stringNumber);
136 
137 /**
138  * @brief Opens the contactor of a string.
139  * @details This function makes an open state request to the contactor of a
140  * specific string.
141  * @param stringNumber String addressed
142  */
143 extern STD_RETURN_TYPE_e CONT_OpenString(uint8_t stringNumber);
144 
145 /**
146  * @brief Closes precharge.
147  * @details This function makes a close state request to the precharge
148  * contactor.
149  * @param stringNumber String addressed
150  */
151 extern STD_RETURN_TYPE_e CONT_ClosePrecharge(uint8_t stringNumber);
152 
153 /**
154  * @brief Opens precharge.
155  * @details This function makes an open state request to the precharge
156  * contactor.
157  * @param stringNumber String addressed
158  */
159 extern STD_RETURN_TYPE_e CONT_OpenPrecharge(uint8_t stringNumber);
160 
161 /**
162  * @brief checks the feedback of the contactors
163  * @details makes a DIAG entry for each contactor when the feedback does not
164  * match the set value
165  */
166 extern void CONT_CheckFeedback(void);
167 
168 /**
169  * @brief initializes the contactor module
170  */
171 extern void CONT_Initialize(void);
172 
173 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
174 #ifdef UNITY_UNIT_TEST
177 #endif /* UNITY_UNIT_TEST */
178 
179 #endif /* FOXBMS__CONTACTOR_H_ */
CONT_ELECTRICAL_STATE_TYPE_e CONT_GetState(uint8_t contactorNumber)
Gets the current state.
Definition: contactor.c:292
CONT_CONTACTOR_INDEX TEST_CONT_ResolveContactorName(const CONT_NAMES_e name)
Definition: contactor.c:306
void CONT_CheckFeedback(void)
checks the feedback of the contactors
Definition: contactor.c:217
STD_RETURN_TYPE_e CONT_OpenPrecharge(uint8_t stringNumber)
Opens precharge.
Definition: contactor.c:266
CONT_POWER_LINE_e
Names for connected power paths.
Definition: contactor.h:113
@ CONT_POWER_PATH_NONE
Definition: contactor.h:114
@ CONT_POWER_PATH_0
Definition: contactor.h:115
CONT_ELECTRICAL_STATE_TYPE_e CONT_GetContactorSetValue(const CONT_NAMES_e name)
Gets the latest value the contactors were set to.
Definition: contactor.c:162
STD_RETURN_TYPE_e CONT_SetContactorState(const CONT_NAMES_e name, CONT_ELECTRICAL_STATE_TYPE_e requestedContactorState)
Sets the contactor state to its requested state, if the contactor is at that time not in the requeste...
Definition: contactor.c:188
void TEST_CONT_InitializationCheckOfContactorRegistry(void)
Definition: contactor.c:303
STD_RETURN_TYPE_e CONT_CloseString(uint8_t stringNumber)
Closes the contactor of a string.
Definition: contactor.c:222
void CONT_GetContactorFeedback(void)
Reads the feedback pin of every contactor and returns its current value (CONT_SWITCH_OFF/CONT_SWITCH_...
Definition: contactor.c:168
STD_RETURN_TYPE_e CONT_ClosePrecharge(uint8_t stringNumber)
Closes precharge.
Definition: contactor.c:239
void CONT_Initialize(void)
initializes the contactor module
Definition: contactor.c:297
CONT_STATEMACH_SUB_e
Substates of the CONT state machine.
Definition: contactor.h:104
@ CONT_ENTRY
Definition: contactor.h:105
@ CONT_SET_EDGE_LOW_INIT
Definition: contactor.h:106
@ CONT_SET_EDGE_HIGH
Definition: contactor.h:107
@ CONT_CHECK_REQUESTS
Definition: contactor.h:109
@ CONT_SET_EDGE_LOW
Definition: contactor.h:108
STD_RETURN_TYPE_e CONT_OpenString(uint8_t stringNumber)
Opens the contactor of a string.
Definition: contactor.c:230
Header for the configuration for the driver for the contactors.
uint8_t CONT_CONTACTOR_INDEX
enum CONT_ELECTRICAL_STATE_TYPE CONT_ELECTRICAL_STATE_TYPE_e
enum CONT_NAMES CONT_NAMES_e
enum STD_RETURN_TYPE STD_RETURN_TYPE_e