foxBMS - Unit Tests  1.2.0
The foxBMS Unit Tests API Documentation
interlock.c
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 interlock.c
44  * @author foxBMS Team
45  * @date 2020-02-24 (date of creation)
46  * @updated 2021-10-18 (date of last update)
47  * @ingroup DRIVERS
48  * @prefix ILCK
49  *
50  * @brief Driver for the interlock.
51  * @details The interlock driver measures the relevant hardware signals from
52  * the interlock circuit. For details on available hardware signals
53  * please refer to the section on this module in the foxBMS
54  * documentation.
55  *
56  * In reference to the names in the foxBMS schematic, this module uses
57  * the following names:
58  *
59  * shorthand | meaning
60  * --------- | ---------
61  * IL | interlock
62  * HS | high-side
63  * LS | low-side
64  * VS | voltage sense
65  * CS | current sense
66  *
67  */
68 
69 /*========== Includes =======================================================*/
70 #include "interlock.h"
71 
72 #include "database.h"
73 #include "diag.h"
74 #include "io.h"
75 #include "os.h"
76 
77 /*========== Macros and Definitions =========================================*/
78 /**
79  * Saves the last state and the last substate
80  */
81 #define ILCK_SAVELASTSTATES() \
82  ilck_state.laststate = ilck_state.state; \
83  ilck_state.lastsubstate = ilck_state.substate
84 
85 /*========== Static Constant and Variable Definitions =======================*/
86 /**
87  * contains the state of the contactor state machine
88  */
90  .timer = 0,
91  .statereq = ILCK_STATE_NO_REQUEST,
93  .substate = ILCK_ENTRY,
95  .lastsubstate = ILCK_ENTRY,
96  .triggerentry = 0,
97  .ErrRequestCounter = 0,
98  .counter = 0,
99 };
100 
101 /** Local variable containing interlock feedback */
103 
104 /*========== Extern Constant and Variable Definitions =======================*/
105 
106 /*========== Static Function Prototypes =====================================*/
107 /**
108  * @brief checks the state requests that are made.
109  * @details This function checks the validity of the state requests. The
110  * results of the checked is returned immediately.
111  * @param statereq state request to be checked
112  * @return result of the state request that was made, taken from
113  * #ILCK_RETURN_TYPE_e
114  */
116 
117 /**
118  * @brief transfers the current state request to the state machine.
119  * @details This function takes the current state request from ilck_state and
120  * transfers it to the state machine. It resets the value from
121  * ilck_state to ILCK_STATE_NO_REQUEST
122  * @return current state request, taken from ILCK_STATE_REQUEST_e
123  */
125 
126 /**
127  * @brief re-entrance check of ILCK state machine trigger function
128  * @details This function is not re-entrant and should only be called time- or
129  * event-triggered. It increments the triggerentry counter from the
130  * state variable ilck_state. It should never be called by two
131  * different processes, so if it is the case, triggerentry should
132  * never be higher than 0 when this function is called.
133  * @return 0 if no further instance of the function is active, 0xFF else
134  */
135 static uint8_t ILCK_CheckReEntrance(void);
136 
137 /**
138  * @brief Initializes required pins for interlock evaluation
139  */
140 static void ILCK_InitializePins(void);
141 
142 /**
143  * @brief Reads the feedback pin of the interlock and returns its current value
144  * (ILCK_SWITCH_OFF/ILCK_SWITCH_ON)
145  * @return measuredInterlockState (type: ILCK_ELECTRICAL_STATE_TYPE_e)
146  */
148 
149 /*========== Static Function Implementations ================================*/
151  ILCK_RETURN_TYPE_e stateRequestCheck = ILCK_ILLEGAL_REQUEST;
152  if (!((statereq == ILCK_STATE_INITIALIZATION_REQUEST) || (statereq == ILCK_STATE_NO_REQUEST))) {
153  stateRequestCheck = ILCK_ILLEGAL_REQUEST;
154  } else if (ilck_state.statereq == ILCK_STATE_NO_REQUEST) {
155  /* init only allowed from the uninitialized state */
156  if (statereq == ILCK_STATE_INITIALIZATION_REQUEST) {
158  stateRequestCheck = ILCK_OK;
159  } else {
160  stateRequestCheck = ILCK_ALREADY_INITIALIZED;
161  }
162  }
163  } else {
164  stateRequestCheck = ILCK_REQUEST_PENDING;
165  }
166  return stateRequestCheck;
167 }
168 
171 
173  retval = ilck_state.statereq;
176 
177  return retval;
178 }
179 
180 static uint8_t ILCK_CheckReEntrance(void) {
181  uint8_t retval = 0;
182 
184  if (!ilck_state.triggerentry) {
186  } else {
187  retval = 0xFF; /* multiple calls of function */
188  }
190 
191  return retval;
192 }
193 
194 static void ILCK_InitializePins(void) {
195  /* Configure diagnostic supply enable pin as output */
197  /* Disable diagnostic power supply as component is currently NOT available */
199  /* Configure interlock feedback pin as input */
201 }
202 
204  ILCK_ELECTRICAL_STATE_TYPE_e measuredInterlockState = ILCK_SWITCH_UNDEF;
205  uint8_t pinState = 0U;
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 == 1u) {
217  measuredInterlockState = ILCK_SWITCH_OFF;
218  } else if (pinState == 0u) {
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:76
#define DATA_WRITE_DATA(...)
Definition: database.h:86
@ DATA_BLOCK_ID_INTERLOCK_FEEDBACK
Definition: database_cfg.h:85
@ DATA_BLOCK_ID_ADC_VOLTAGE
Definition: database_cfg.h:104
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:226
Diagnosis driver header.
@ DIAG_SYSTEM
Definition: diag_cfg.h:248
@ DIAG_EVENT_NOT_OK
Definition: diag_cfg.h:236
@ DIAG_EVENT_OK
Definition: diag_cfg.h:235
@ DIAG_ID_INTERLOCK_FEEDBACK
Definition: diag_cfg.h:211
#define FAS_ASSERT(x)
Assertion macro that asserts that x is true.
Definition: fassert.h:233
#define FAS_TRAP
Define that evaluates to essential boolean false thus tripping an assert.
Definition: fassert.h:108
static void ILCK_InitializePins(void)
Initializes required pins for interlock evaluation.
Definition: interlock.c:194
void TEST_ILCK_SetStateStruct(ILCK_STATE_s state)
Definition: interlock.c:322
#define ILCK_SAVELASTSTATES()
Definition: interlock.c:81
static ILCK_STATE_s ilck_state
Definition: interlock.c:89
static uint8_t ILCK_CheckReEntrance(void)
re-entrance check of ILCK state machine trigger function
Definition: interlock.c:180
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:169
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:203
static DATA_BLOCK_INTERLOCK_FEEDBACK_s ilck_tableFeedback
Definition: interlock.c:102
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:150
Headers for the driver for the interlock.
ILCK_STATEMACH_e
Definition: interlock.h:65
@ ILCK_STATEMACHINE_UNINITIALIZED
Definition: interlock.h:67
@ ILCK_STATEMACHINE_INITIALIZED
Definition: interlock.h:68
ILCK_RETURN_TYPE_e
Definition: interlock.h:90
@ ILCK_ALREADY_INITIALIZED
Definition: interlock.h:93
@ ILCK_ILLEGAL_REQUEST
Definition: interlock.h:94
@ ILCK_OK
Definition: interlock.h:91
@ ILCK_REQUEST_PENDING
Definition: interlock.h:92
@ ILCK_ENTRY
Definition: interlock.h:76
ILCK_STATE_REQUEST_e
Definition: interlock.h:82
@ ILCK_STATE_NO_REQUEST
Definition: interlock.h:84
@ ILCK_STATE_INITIALIZATION_REQUEST
Definition: interlock.h:83
#define ILCK_ADC_INPUT_HIGH_SIDE_VOLTAGE_SENSE
Definition: interlock_cfg.h:77
#define ILCK_VOLTAGE_DIVIDER_FACTOR
Definition: interlock_cfg.h:87
#define ILCK_ADC_INPUT_LOW_SIDE_VOLTAGE_SENSE
Definition: interlock_cfg.h:79
@ ILCK_SWITCH_ON
@ ILCK_SWITCH_UNDEF
@ ILCK_SWITCH_OFF
#define ILCK_IO_REG_PORT
Definition: interlock_cfg.h:67
enum ILCK_ELECTRICAL_STATE_TYPE ILCK_ELECTRICAL_STATE_TYPE_e
#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:70
#define ILCK_INTERLOCK_FEEDBACK_PIN_IL_STATE
Definition: interlock_cfg.h:73
#define ILCK_FACTOR_IL_LS_CS_1_ohm
Definition: interlock_cfg.h:99
#define ILCK_ADC_INPUT_LOW_SIDE_CURRENT_SENSE
Definition: interlock_cfg.h:83
#define ILCK_ADC_INPUT_HIGH_SIDE_CURRENT_SENSE
Definition: interlock_cfg.h:81
#define ILCK_IO_REG_DIR
Definition: interlock_cfg.h:65
#define ILCK_FACTOR_IL_HS_CS_1_ohm
Definition: interlock_cfg.h:95
uint8_t IO_PinGet(const volatile uint32_t *pRegisterAddress, uint32_t pin)
Get pin state.
Definition: io.c:98
void IO_SetPinDirectionToOutput(volatile uint32_t *pRegisterAddress, uint32_t pin)
Set pin to output by writing in pin direction register.
Definition: io.c:70
void IO_SetPinDirectionToInput(volatile uint32_t *pRegisterAddress, uint32_t pin)
Set pin to input by writing in pin direction register.
Definition: io.c:77
void IO_PinReset(volatile uint32_t *pRegisterAddress, uint32_t pin)
Reset pin by writing in pin output register.
Definition: io.c:91
Header for the driver for the IO module.
void OS_ExitTaskCritical(void)
Exit Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os.c:178
void OS_EnterTaskCritical(void)
Enter Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os.c:174
Implementation of the tasks used by the system, headers.
DATA_BLOCK_ID_e uniqueId
Definition: database_cfg.h:111
float adc1ConvertedVoltages_mV[ADC_ADC1_MAX_NR_CHANNELS]
Definition: database_cfg.h:567
DATA_BLOCK_HEADER_s header
Definition: database_cfg.h:566
DATA_BLOCK_HEADER_s header
Definition: database_cfg.h:371
uint32_t ErrRequestCounter
Definition: interlock.h:113
uint8_t triggerentry
Definition: interlock.h:114
ILCK_STATE_REQUEST_e statereq
Definition: interlock.h:104
ILCK_STATEMACH_e state
Definition: interlock.h:106
uint16_t timer
Definition: interlock.h:102
ILCK_STATEMACH_SUB_e substate
Definition: interlock.h:108