foxBMS - Unit Tests  1.3.0
The foxBMS Unit Tests API Documentation
interlock.c
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 interlock.c
44  * @author foxBMS Team
45  * @date 2020-02-24 (date of creation)
46  * @updated 2022-05-30 (date of last update)
47  * @version v1.3.0
48  * @ingroup DRIVERS
49  * @prefix ILCK
50  *
51  * @brief Driver for the interlock.
52  * @details The interlock driver measures the relevant hardware signals from
53  * the interlock circuit. For details on available hardware signals
54  * please refer to the section on this module in the foxBMS
55  * documentation.
56  *
57  * In reference to the names in the foxBMS schematic, this module uses
58  * the following names:
59  *
60  * shorthand | meaning
61  * --------- | ---------
62  * IL | interlock
63  * HS | high-side
64  * LS | low-side
65  * VS | voltage sense
66  * CS | current sense
67  *
68  */
69 
70 /*========== Includes =======================================================*/
71 #include "interlock.h"
72 
73 #include "database.h"
74 #include "diag.h"
75 #include "io.h"
76 #include "os.h"
77 
78 /*========== Macros and Definitions =========================================*/
79 /**
80  * Saves the last state and the last substate
81  */
82 #define ILCK_SAVELASTSTATES() \
83  ilck_state.laststate = ilck_state.state; \
84  ilck_state.lastsubstate = ilck_state.substate
85 
86 /*========== Static Constant and Variable Definitions =======================*/
87 /**
88  * contains the state of the contactor state machine
89  */
91  .timer = 0,
92  .statereq = ILCK_STATE_NO_REQUEST,
94  .substate = ILCK_ENTRY,
96  .lastsubstate = ILCK_ENTRY,
97  .triggerentry = 0,
98  .ErrRequestCounter = 0,
99  .counter = 0,
100 };
101 
102 /** Local variable containing interlock feedback */
104 
105 /*========== Extern Constant and Variable Definitions =======================*/
106 
107 /*========== Static Function Prototypes =====================================*/
108 /**
109  * @brief checks the state requests that are made.
110  * @details This function checks the validity of the state requests. The
111  * results of the checked is returned immediately.
112  * @param statereq state request to be checked
113  * @return result of the state request that was made, taken from
114  * #ILCK_RETURN_TYPE_e
115  */
117 
118 /**
119  * @brief transfers the current state request to the state machine.
120  * @details This function takes the current state request from ilck_state and
121  * transfers it to the state machine. It resets the value from
122  * ilck_state to ILCK_STATE_NO_REQUEST
123  * @return current state request, taken from ILCK_STATE_REQUEST_e
124  */
126 
127 /**
128  * @brief re-entrance check of ILCK state machine trigger function
129  * @details This function is not re-entrant and should only be called time- or
130  * event-triggered. It increments the triggerentry counter from the
131  * state variable ilck_state. It should never be called by two
132  * different processes, so if it is the case, triggerentry should
133  * never be higher than 0 when this function is called.
134  * @return 0 if no further instance of the function is active, 0xFF else
135  */
136 static uint8_t ILCK_CheckReEntrance(void);
137 
138 /**
139  * @brief Initializes required pins for interlock evaluation
140  */
141 static void ILCK_InitializePins(void);
142 
143 /**
144  * @brief Reads the feedback pin of the interlock and returns its current value
145  * (ILCK_SWITCH_OFF/ILCK_SWITCH_ON)
146  * @return measuredInterlockState (type: ILCK_ELECTRICAL_STATE_TYPE_e)
147  */
149 
150 /*========== Static Function Implementations ================================*/
152  ILCK_RETURN_TYPE_e stateRequestCheck = ILCK_ILLEGAL_REQUEST;
153  if (!((statereq == ILCK_STATE_INITIALIZATION_REQUEST) || (statereq == ILCK_STATE_NO_REQUEST))) {
154  stateRequestCheck = ILCK_ILLEGAL_REQUEST;
155  } else if (ilck_state.statereq == ILCK_STATE_NO_REQUEST) {
156  /* init only allowed from the uninitialized state */
157  if (statereq == ILCK_STATE_INITIALIZATION_REQUEST) {
159  stateRequestCheck = ILCK_OK;
160  } else {
161  stateRequestCheck = ILCK_ALREADY_INITIALIZED;
162  }
163  }
164  } else {
165  stateRequestCheck = ILCK_REQUEST_PENDING;
166  }
167  return stateRequestCheck;
168 }
169 
172 
174  retval = ilck_state.statereq;
177 
178  return retval;
179 }
180 
181 static uint8_t ILCK_CheckReEntrance(void) {
182  uint8_t retval = 0;
183 
185  if (!ilck_state.triggerentry) {
187  } else {
188  retval = 0xFF; /* multiple calls of function */
189  }
191 
192  return retval;
193 }
194 
195 static void ILCK_InitializePins(void) {
196  /* Configure diagnostic supply enable pin as output */
198  /* Disable diagnostic power supply as component is currently NOT available */
200  /* Configure interlock feedback pin as input */
202 }
203 
205  ILCK_ELECTRICAL_STATE_TYPE_e measuredInterlockState = ILCK_SWITCH_UNDEF;
206 
210 
211  /** Local variable containing voltages measured on TMS570 ADC1 inputs */
213  DATA_READ_DATA(&ilck_tableAdcVoltages);
214 
215  /** Pin low: interlock closed, pin high: interlock open */
216  if (pinState == STD_PIN_HIGH) {
217  measuredInterlockState = ILCK_SWITCH_OFF;
218  } else if (pinState == STD_PIN_LOW) {
219  measuredInterlockState = ILCK_SWITCH_ON;
220  }
221 
234 
235  ilck_tableFeedback.interlockFeedback_IL_STATE = measuredInterlockState;
236 
238 
239 #if (BS_IGNORE_INTERLOCK_FEEDBACK == true)
240  measuredInterlockState = ILCK_SWITCH_ON;
241 #endif
242 
243  return measuredInterlockState;
244 }
245 
246 /*========== Extern Function Implementations ================================*/
248  return ilck_state.state;
249 }
250 
253 
255  retVal = ILCK_CheckStateRequest(statereq);
256 
257  if (retVal != ILCK_ILLEGAL_REQUEST) {
258  ilck_state.statereq = statereq;
259  }
261 
262  return retVal;
263 }
264 
265 void ILCK_Trigger(void) {
268 
269  /* Check re-entrance of function */
270  if (ILCK_CheckReEntrance() > 0u) {
271  return;
272  }
273 
274  if (ilck_state.timer > 0u) {
275  if ((--ilck_state.timer) > 0u) {
277  return; /* handle state machine only if timer has elapsed */
278  }
279  }
280 
281  switch (ilck_state.state) {
282  /****************************UNINITIALIZED***********************************/
284  /* waiting for Initialization Request */
285  statereq = ILCK_TransferStateRequest();
286  if (statereq == ILCK_STATE_INITIALIZATION_REQUEST) {
292  } else if (statereq == ILCK_STATE_NO_REQUEST) {
293  /* no actual request pending */
294  } else {
295  ilck_state.ErrRequestCounter++; /* illegal request pending */
296  }
297  break;
298 
299  /****************************INITIALIZED*************************************/
303  interlockState = ILCK_GetInterlockFeedback();
304  if (interlockState == ILCK_SWITCH_ON) {
306  } else {
308  }
309  break;
310 
311  default:
312  /* this is an undefined state that should never be reached */
314  break;
315  } /* end switch (ilck_state.state) */
316 
318 }
319 
320 /*================== Setter for static Variables (Unit Test) ==============*/
321 #ifdef UNITY_UNIT_TEST
323  ilck_state = state;
324 }
326  return ILCK_GetInterlockFeedback();
327 }
328 #endif
329 
330 /*========== Externalized Static Function Implementations (Unit Test) =======*/
Database module header.
#define DATA_READ_DATA(...)
Definition: database.h:83
#define DATA_WRITE_DATA(...)
Definition: database.h:93
@ DATA_BLOCK_ID_INTERLOCK_FEEDBACK
Definition: database_cfg.h:88
@ DATA_BLOCK_ID_ADC_VOLTAGE
Definition: database_cfg.h:107
DIAG_RETURNTYPE_e DIAG_Handler(DIAG_ID_e diag_id, DIAG_EVENT_e event, DIAG_IMPACT_LEVEL_e impact, uint32_t data)
DIAG_Handler provides generic error handling, based on diagnosis group.
Definition: diag.c:229
Diagnosis driver header.
@ DIAG_EVENT_NOT_OK
Definition: diag_cfg.h:239
@ DIAG_EVENT_OK
Definition: diag_cfg.h:238
@ DIAG_SYSTEM
Definition: diag_cfg.h:251
@ DIAG_ID_INTERLOCK_FEEDBACK
Definition: diag_cfg.h:212
#define FAS_ASSERT(x)
Assertion macro that asserts that x is true.
Definition: fassert.h:237
#define FAS_TRAP
Define that evaluates to essential boolean false thus tripping an assert.
Definition: fassert.h:115
STD_PIN_STATE_e
Definition: fstd_types.h:87
@ STD_PIN_LOW
Definition: fstd_types.h:88
@ STD_PIN_HIGH
Definition: fstd_types.h:89
static void ILCK_InitializePins(void)
Initializes required pins for interlock evaluation.
Definition: interlock.c:195
void TEST_ILCK_SetStateStruct(ILCK_STATE_s state)
Definition: interlock.c:322
#define ILCK_SAVELASTSTATES()
Definition: interlock.c:82
static ILCK_STATE_s ilck_state
Definition: interlock.c:90
static uint8_t ILCK_CheckReEntrance(void)
re-entrance check of ILCK state machine trigger function
Definition: interlock.c:181
ILCK_RETURN_TYPE_e ILCK_SetStateRequest(ILCK_STATE_REQUEST_e statereq)
sets the current state request of the state variable ilck_state.
Definition: interlock.c:251
void ILCK_Trigger(void)
trigger function for the ILCK driver state machine.
Definition: interlock.c:265
static ILCK_STATE_REQUEST_e ILCK_TransferStateRequest(void)
transfers the current state request to the state machine.
Definition: interlock.c:170
static ILCK_ELECTRICAL_STATE_TYPE_e ILCK_GetInterlockFeedback(void)
Reads the feedback pin of the interlock and returns its current value (ILCK_SWITCH_OFF/ILCK_SWITCH_ON...
Definition: interlock.c:204
static DATA_BLOCK_INTERLOCK_FEEDBACK_s ilck_tableFeedback
Definition: interlock.c:103
ILCK_ELECTRICAL_STATE_TYPE_e TEST_ILCK_GetInterlockFeedback(void)
Definition: interlock.c:325
ILCK_STATEMACH_e ILCK_GetState(void)
gets the current state.
Definition: interlock.c:247
static ILCK_RETURN_TYPE_e ILCK_CheckStateRequest(ILCK_STATE_REQUEST_e statereq)
checks the state requests that are made.
Definition: interlock.c:151
Headers for the driver for the interlock.
ILCK_STATEMACH_e
Definition: interlock.h:66
@ ILCK_STATEMACHINE_UNINITIALIZED
Definition: interlock.h:68
@ ILCK_STATEMACHINE_INITIALIZED
Definition: interlock.h:69
ILCK_RETURN_TYPE_e
Definition: interlock.h:91
@ ILCK_ALREADY_INITIALIZED
Definition: interlock.h:94
@ ILCK_ILLEGAL_REQUEST
Definition: interlock.h:95
@ ILCK_OK
Definition: interlock.h:92
@ ILCK_REQUEST_PENDING
Definition: interlock.h:93
@ ILCK_ENTRY
Definition: interlock.h:77
ILCK_STATE_REQUEST_e
Definition: interlock.h:83
@ ILCK_STATE_NO_REQUEST
Definition: interlock.h:85
@ ILCK_STATE_INITIALIZATION_REQUEST
Definition: interlock.h:84
#define ILCK_ADC_INPUT_HIGH_SIDE_VOLTAGE_SENSE
Definition: interlock_cfg.h:78
#define ILCK_VOLTAGE_DIVIDER_FACTOR
Definition: interlock_cfg.h:88
ILCK_ELECTRICAL_STATE_TYPE_e
@ ILCK_SWITCH_ON
@ ILCK_SWITCH_UNDEF
@ ILCK_SWITCH_OFF
#define ILCK_ADC_INPUT_LOW_SIDE_VOLTAGE_SENSE
Definition: interlock_cfg.h:80
#define ILCK_IO_REG_PORT
Definition: interlock_cfg.h:68
#define ILCK_STATEMACH_SHORTTIME
ILCK statemachine short time definition in ILCK_Trigger() calls until next state/substate is processe...
#define ILCK_INTERLOCK_CONTROL_PIN_IL_HS_ENABLE
Definition: interlock_cfg.h:71
#define ILCK_INTERLOCK_FEEDBACK_PIN_IL_STATE
Definition: interlock_cfg.h:74
#define ILCK_FACTOR_IL_LS_CS_1_ohm
#define ILCK_ADC_INPUT_LOW_SIDE_CURRENT_SENSE
Definition: interlock_cfg.h:84
#define ILCK_ADC_INPUT_HIGH_SIDE_CURRENT_SENSE
Definition: interlock_cfg.h:82
#define ILCK_IO_REG_DIR
Definition: interlock_cfg.h:66
#define ILCK_FACTOR_IL_HS_CS_1_ohm
Definition: interlock_cfg.h:96
void IO_SetPinDirectionToOutput(volatile uint32_t *pRegisterAddress, uint32_t pin)
Set pin to output by writing in pin direction register.
Definition: io.c:73
void IO_SetPinDirectionToInput(volatile uint32_t *pRegisterAddress, uint32_t pin)
Set pin to input by writing in pin direction register.
Definition: io.c:80
void IO_PinReset(volatile uint32_t *pRegisterAddress, uint32_t pin)
Reset pin by writing in pin output register.
Definition: io.c:94
STD_PIN_STATE_e IO_PinGet(const volatile uint32_t *pRegisterAddress, uint32_t pin)
Get pin state.
Definition: io.c:101
Header for the driver for the IO module.
Declaration of the OS wrapper interface.
void OS_ExitTaskCritical(void)
Exit Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os_freertos.c:135
void OS_EnterTaskCritical(void)
Enter Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os_freertos.c:131
DATA_BLOCK_HEADER_s header
Definition: database_cfg.h:595
float adc1ConvertedVoltages_mV[ADC_ADC1_MAX_NR_CHANNELS]
Definition: database_cfg.h:596
DATA_BLOCK_ID_e uniqueId
Definition: database_cfg.h:119
DATA_BLOCK_HEADER_s header
Definition: database_cfg.h:398
uint32_t ErrRequestCounter
Definition: interlock.h:114
uint8_t triggerentry
Definition: interlock.h:115
ILCK_STATE_REQUEST_e statereq
Definition: interlock.h:105
ILCK_STATEMACH_e state
Definition: interlock.h:107
uint16_t timer
Definition: interlock.h:103
ILCK_STATEMACH_SUB_e substate
Definition: interlock.h:109