1 /**
2 ******************************************************************************
3 * @file stm32u0xx_hal_tsc.c
4 * @author MCD Application Team
5 * @brief This file provides firmware functions to manage the following
6 * functionalities of the Touch Sensing Controller (TSC) peripheral:
7 * + Initialization and De-initialization
8 * + Channel IOs, Shield IOs and Sampling IOs configuration
9 * + Start and Stop an acquisition
10 * + Read acquisition result
11 * + Interrupts and flags management
12 *
13 ******************************************************************************
14 * @attention
15 *
16 * Copyright (c) 2023 STMicroelectronics.
17 * All rights reserved.
18 *
19 * This software is licensed under terms that can be found in the LICENSE file
20 * in the root directory of this software component.
21 * If no LICENSE file comes with this software, it is provided AS-IS.
22 *
23 ******************************************************************************
24 @verbatim
25 ================================================================================
26 ##### TSC specific features #####
27 ================================================================================
28 [..]
29 (#) Proven and robust surface charge transfer acquisition principle
30
31 (#) Supports up to 3 capacitive sensing channels per group
32
33 (#) Capacitive sensing channels can be acquired in parallel offering a very good
34 response time
35
36 (#) Spread spectrum feature to improve system robustness in noisy environments
37
38 (#) Full hardware management of the charge transfer acquisition sequence
39
40 (#) Programmable charge transfer frequency
41
42 (#) Programmable sampling capacitor I/O pin
43
44 (#) Programmable channel I/O pin
45
46 (#) Programmable max count value to avoid long acquisition when a channel is faulty
47
48 (#) Dedicated end of acquisition and max count error flags with interrupt capability
49
50 (#) One sampling capacitor for up to 3 capacitive sensing channels to reduce the system
51 components
52
53 (#) Compatible with proximity, touchkey, linear and rotary touch sensor implementation
54
55 ##### How to use this driver #####
56 ================================================================================
57 [..]
58 (#) Enable the TSC interface clock using __HAL_RCC_TSC_CLK_ENABLE() macro.
59
60 (#) GPIO pins configuration
61 (++) Enable the clock for the TSC GPIOs using __HAL_RCC_GPIOx_CLK_ENABLE() macro.
62 (++) Configure the TSC pins used as sampling IOs in alternate function output Open-Drain mode,
63 and TSC pins used as channel/shield IOs in alternate function output Push-Pull mode
64 using HAL_GPIO_Init() function.
65
66 (#) Interrupts configuration
67 (++) Configure the NVIC (if the interrupt model is used) using HAL_NVIC_SetPriority()
68 and HAL_NVIC_EnableIRQ() and function.
69
70 (#) TSC configuration
71 (++) Configure all TSC parameters and used TSC IOs using HAL_TSC_Init() function.
72
73 [..] TSC peripheral alternate functions are mapped on AF9.
74
75 *** Acquisition sequence ***
76 ===================================
77 [..]
78 (+) Discharge all IOs using HAL_TSC_IODischarge() function.
79 (+) Wait a certain time allowing a good discharge of all capacitors. This delay depends
80 of the sampling capacitor and electrodes design.
81 (+) Select the channel IOs to be acquired using HAL_TSC_IOConfig() function.
82 (+) Launch the acquisition using either HAL_TSC_Start() or HAL_TSC_Start_IT() function.
83 If the synchronized mode is selected, the acquisition will start as soon as the signal
84 is received on the synchro pin.
85 (+) Wait the end of acquisition using either HAL_TSC_PollForAcquisition() or
86 HAL_TSC_GetState() function or using WFI instruction for example.
87 (+) Check the group acquisition status using HAL_TSC_GroupGetStatus() function.
88 (+) Read the acquisition value using HAL_TSC_GroupGetValue() function.
89
90 *** Callback registration ***
91 =============================================
92
93 [..]
94 The compilation flag USE_HAL_TSC_REGISTER_CALLBACKS when set to 1
95 allows the user to configure dynamically the driver callbacks.
96 Use Functions HAL_TSC_RegisterCallback() to register an interrupt callback.
97
98 [..]
99 Function HAL_TSC_RegisterCallback() allows to register following callbacks:
100 (+) ConvCpltCallback : callback for conversion complete process.
101 (+) ErrorCallback : callback for error detection.
102 (+) MspInitCallback : callback for Msp Init.
103 (+) MspDeInitCallback : callback for Msp DeInit.
104 [..]
105 This function takes as parameters the HAL peripheral handle, the Callback ID
106 and a pointer to the user callback function.
107
108 [..]
109 Use function HAL_TSC_UnRegisterCallback to reset a callback to the default
110 weak function.
111 HAL_TSC_UnRegisterCallback takes as parameters the HAL peripheral handle,
112 and the Callback ID.
113 [..]
114 This function allows to reset following callbacks:
115 (+) ConvCpltCallback : callback for conversion complete process.
116 (+) ErrorCallback : callback for error detection.
117 (+) MspInitCallback : callback for Msp Init.
118 (+) MspDeInitCallback : callback for Msp DeInit.
119
120 [..]
121 By default, after the HAL_TSC_Init() and when the state is HAL_TSC_STATE_RESET
122 all callbacks are set to the corresponding weak functions:
123 examples HAL_TSC_ConvCpltCallback(), HAL_TSC_ErrorCallback().
124 Exception done for MspInit and MspDeInit functions that are
125 reset to the legacy weak functions in the HAL_TSC_Init()/ HAL_TSC_DeInit() only when
126 these callbacks are null (not registered beforehand).
127 If MspInit or MspDeInit are not null, the HAL_TSC_Init()/ HAL_TSC_DeInit()
128 keep and use the user MspInit/MspDeInit callbacks (registered beforehand) whatever the state.
129
130 [..]
131 Callbacks can be registered/unregistered in HAL_TSC_STATE_READY state only.
132 Exception done MspInit/MspDeInit functions that can be registered/unregistered
133 in HAL_TSC_STATE_READY or HAL_TSC_STATE_RESET state,
134 thus registered (user) MspInit/DeInit callbacks can be used during the Init/DeInit.
135 Then, the user first registers the MspInit/MspDeInit user callbacks
136 using HAL_TSC_RegisterCallback() before calling HAL_TSC_DeInit()
137 or HAL_TSC_Init() function.
138
139 [..]
140 When the compilation flag USE_HAL_TSC_REGISTER_CALLBACKS is set to 0 or
141 not defined, the callback registration feature is not available and all callbacks
142 are set to the corresponding weak functions.
143
144 @endverbatim
145 ******************************************************************************
146
147 Table 1. IOs for the STM32U0xx devices
148 +--------------------------------+
149 | IOs | TSC functions |
150 |--------------|-----------------|
151 | PB12 (AF) | TSC_G1_IO1 |
152 | PB13 (AF) | TSC_G1_IO2 |
153 | PB14 (AF) | TSC_G1_IO3 |
154 | PB15 (AF) | TSC_G1_IO4 |
155 |--------------|-----------------|
156 | PB4 (AF) | TSC_G2_IO1 |
157 | PB5 (AF) | TSC_G2_IO2 |
158 | PB6 (AF) | TSC_G2_IO3 |
159 | PB7 (AF) | TSC_G2_IO4 |
160 |--------------|-----------------|
161 | PA15 (AF) | TSC_G3_IO1 |
162 | PC10 (AF) | TSC_G3_IO2 |
163 | PC11 (AF) | TSC_G3_IO3 |
164 | PA14 (AF) | TSC_G3_IO4 |
165 |--------------|-----------------|
166 | PC6 (AF) | TSC_G4_IO1 |
167 | PC7 (AF) | TSC_G4_IO2 |
168 | PC8 (AF) | TSC_G4_IO3 |
169 | PC9 (AF) | TSC_G4_IO4 |
170 |--------------|-----------------|
171 | PA6 (AF) | TSC_G5_IO1 |
172 | PB0 (AF) | TSC_G5_IO2 |
173 | PB10 (AF) | TSC_G5_IO3 |
174 | PB11 (AF) | TSC_G5_IO4 |
175 |--------------|-----------------|
176 | PD10 (AF) | TSC_G6_IO1 |
177 | PD11 (AF) | TSC_G6_IO2 |
178 | PD12 (AF) | TSC_G6_IO3 |
179 | PD13 (AF) | TSC_G6_IO4 |
180 |--------------|-----------------|
181 | PA8 (AF) | TSC_G7_IO1 |
182 | PA9 (AF) | TSC_G7_IO2 |
183 | PA10 (AF) | TSC_G7_IO3 |
184 | PA13 (AF) | TSC_G7_IO4 |
185 |--------------|-----------------|
186 | PB1 (AF) | TSC_SYNC |
187 | PD2 (AF) | |
188 +--------------------------------+
189
190
191 */
192
193 /* Includes ------------------------------------------------------------------*/
194 #include "stm32u0xx_hal.h"
195
196 /** @addtogroup STM32U0xx_HAL_Driver
197 * @{
198 */
199
200 /** @defgroup TSC TSC
201 * @brief HAL TSC module driver
202 * @{
203 */
204
205 #ifdef HAL_TSC_MODULE_ENABLED
206
207 /* Private typedef -----------------------------------------------------------*/
208 /* Private define ------------------------------------------------------------*/
209 /* Private macro -------------------------------------------------------------*/
210 /* Private variables ---------------------------------------------------------*/
211 /* Private function prototypes -----------------------------------------------*/
212 static uint32_t TSC_extract_groups(uint32_t iomask);
213
214 /* Exported functions --------------------------------------------------------*/
215
216 /** @defgroup TSC_Exported_Functions TSC Exported Functions
217 * @{
218 */
219
220 /** @defgroup TSC_Exported_Functions_Group1 Initialization and de-initialization functions
221 * @brief Initialization and Configuration functions
222 *
223 @verbatim
224 ===============================================================================
225 ##### Initialization and de-initialization functions #####
226 ===============================================================================
227 [..] This section provides functions allowing to:
228 (+) Initialize and configure the TSC.
229 (+) De-initialize the TSC.
230 @endverbatim
231 * @{
232 */
233
234 /**
235 * @brief Initialize the TSC peripheral according to the specified parameters
236 * in the TSC_InitTypeDef structure and initialize the associated handle.
237 * @param htsc TSC handle
238 * @retval HAL status
239 */
HAL_TSC_Init(TSC_HandleTypeDef * htsc)240 HAL_StatusTypeDef HAL_TSC_Init(TSC_HandleTypeDef *htsc)
241 {
242 /* Check TSC handle allocation */
243 if (htsc == NULL)
244 {
245 return HAL_ERROR;
246 }
247
248 /* Check the parameters */
249 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
250 assert_param(IS_TSC_CTPH(htsc->Init.CTPulseHighLength));
251 assert_param(IS_TSC_CTPL(htsc->Init.CTPulseLowLength));
252 assert_param(IS_TSC_SS(htsc->Init.SpreadSpectrum));
253 assert_param(IS_TSC_SSD(htsc->Init.SpreadSpectrumDeviation));
254 assert_param(IS_TSC_SS_PRESC(htsc->Init.SpreadSpectrumPrescaler));
255 assert_param(IS_TSC_PG_PRESC(htsc->Init.PulseGeneratorPrescaler));
256 assert_param(IS_TSC_PG_PRESC_VS_CTPL(htsc->Init.PulseGeneratorPrescaler, htsc->Init.CTPulseLowLength));
257 assert_param(IS_TSC_MCV(htsc->Init.MaxCountValue));
258 assert_param(IS_TSC_IODEF(htsc->Init.IODefaultMode));
259 assert_param(IS_TSC_SYNC_POL(htsc->Init.SynchroPinPolarity));
260 assert_param(IS_TSC_ACQ_MODE(htsc->Init.AcquisitionMode));
261 assert_param(IS_TSC_MCE_IT(htsc->Init.MaxCountInterrupt));
262 assert_param(IS_TSC_GROUP(htsc->Init.ChannelIOs));
263 assert_param(IS_TSC_GROUP(htsc->Init.ShieldIOs));
264 assert_param(IS_TSC_GROUP(htsc->Init.SamplingIOs));
265
266 if (htsc->State == HAL_TSC_STATE_RESET)
267 {
268 /* Allocate lock resource and initialize it */
269 htsc->Lock = HAL_UNLOCKED;
270
271 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
272 /* Init the TSC Callback settings */
273 htsc->ConvCpltCallback = HAL_TSC_ConvCpltCallback; /* Legacy weak ConvCpltCallback */
274 htsc->ErrorCallback = HAL_TSC_ErrorCallback; /* Legacy weak ErrorCallback */
275
276 if (htsc->MspInitCallback == NULL)
277 {
278 htsc->MspInitCallback = HAL_TSC_MspInit; /* Legacy weak MspInit */
279 }
280
281 /* Init the low level hardware : GPIO, CLOCK, CORTEX...etc */
282 htsc->MspInitCallback(htsc);
283 #else
284 /* Init the low level hardware : GPIO, CLOCK, CORTEX */
285 HAL_TSC_MspInit(htsc);
286 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
287 }
288
289 /* Initialize the TSC state */
290 htsc->State = HAL_TSC_STATE_BUSY;
291
292 /*--------------------------------------------------------------------------*/
293 /* Set TSC parameters */
294
295 /* Enable TSC */
296 htsc->Instance->CR = TSC_CR_TSCE;
297
298 /* Set all functions */
299 htsc->Instance->CR |= (htsc->Init.CTPulseHighLength |
300 htsc->Init.CTPulseLowLength |
301 (htsc->Init.SpreadSpectrumDeviation << TSC_CR_SSD_Pos) |
302 htsc->Init.SpreadSpectrumPrescaler |
303 htsc->Init.PulseGeneratorPrescaler |
304 htsc->Init.MaxCountValue |
305 htsc->Init.SynchroPinPolarity |
306 htsc->Init.AcquisitionMode);
307
308 /* Spread spectrum */
309 if (htsc->Init.SpreadSpectrum == ENABLE)
310 {
311 htsc->Instance->CR |= TSC_CR_SSE;
312 }
313
314 /* Disable Schmitt trigger hysteresis on all used TSC IOs */
315 htsc->Instance->IOHCR = (~(htsc->Init.ChannelIOs | htsc->Init.ShieldIOs | htsc->Init.SamplingIOs));
316
317 /* Set channel and shield IOs */
318 htsc->Instance->IOCCR = (htsc->Init.ChannelIOs | htsc->Init.ShieldIOs);
319
320 /* Set sampling IOs */
321 htsc->Instance->IOSCR = htsc->Init.SamplingIOs;
322
323 /* Set the groups to be acquired */
324 htsc->Instance->IOGCSR = TSC_extract_groups(htsc->Init.ChannelIOs);
325
326 /* Disable interrupts */
327 htsc->Instance->IER &= (~(TSC_IT_EOA | TSC_IT_MCE));
328
329 /* Clear flags */
330 htsc->Instance->ICR = (TSC_FLAG_EOA | TSC_FLAG_MCE);
331
332 /*--------------------------------------------------------------------------*/
333
334 /* Initialize the TSC state */
335 htsc->State = HAL_TSC_STATE_READY;
336
337 /* Return function status */
338 return HAL_OK;
339 }
340
341 /**
342 * @brief Deinitialize the TSC peripheral registers to their default reset values.
343 * @param htsc TSC handle
344 * @retval HAL status
345 */
HAL_TSC_DeInit(TSC_HandleTypeDef * htsc)346 HAL_StatusTypeDef HAL_TSC_DeInit(TSC_HandleTypeDef *htsc)
347 {
348 /* Check TSC handle allocation */
349 if (htsc == NULL)
350 {
351 return HAL_ERROR;
352 }
353
354 /* Check the parameters */
355 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
356
357 /* Change TSC state */
358 htsc->State = HAL_TSC_STATE_BUSY;
359
360 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
361 if (htsc->MspDeInitCallback == NULL)
362 {
363 htsc->MspDeInitCallback = HAL_TSC_MspDeInit; /* Legacy weak MspDeInit */
364 }
365
366 /* DeInit the low level hardware: GPIO, CLOCK, NVIC */
367 htsc->MspDeInitCallback(htsc);
368 #else
369 /* DeInit the low level hardware */
370 HAL_TSC_MspDeInit(htsc);
371 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
372
373 /* Change TSC state */
374 htsc->State = HAL_TSC_STATE_RESET;
375
376 /* Process unlocked */
377 __HAL_UNLOCK(htsc);
378
379 /* Return function status */
380 return HAL_OK;
381 }
382
383 /**
384 * @brief Initialize the TSC MSP.
385 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
386 * the configuration information for the specified TSC.
387 * @retval None
388 */
HAL_TSC_MspInit(TSC_HandleTypeDef * htsc)389 __weak void HAL_TSC_MspInit(TSC_HandleTypeDef *htsc)
390 {
391 /* Prevent unused argument(s) compilation warning */
392 UNUSED(htsc);
393
394 /* NOTE : This function should not be modified, when the callback is needed,
395 the HAL_TSC_MspInit could be implemented in the user file.
396 */
397 }
398
399 /**
400 * @brief DeInitialize the TSC MSP.
401 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
402 * the configuration information for the specified TSC.
403 * @retval None
404 */
HAL_TSC_MspDeInit(TSC_HandleTypeDef * htsc)405 __weak void HAL_TSC_MspDeInit(TSC_HandleTypeDef *htsc)
406 {
407 /* Prevent unused argument(s) compilation warning */
408 UNUSED(htsc);
409
410 /* NOTE : This function should not be modified, when the callback is needed,
411 the HAL_TSC_MspDeInit could be implemented in the user file.
412 */
413 }
414
415 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
416 /**
417 * @brief Register a User TSC Callback
418 * To be used instead of the weak predefined callback
419 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
420 * the configuration information for the specified TSC.
421 * @param CallbackID ID of the callback to be registered
422 * This parameter can be one of the following values:
423 * @arg @ref HAL_TSC_CONV_COMPLETE_CB_ID Conversion completed callback ID
424 * @arg @ref HAL_TSC_ERROR_CB_ID Error callback ID
425 * @arg @ref HAL_TSC_MSPINIT_CB_ID MspInit callback ID
426 * @arg @ref HAL_TSC_MSPDEINIT_CB_ID MspDeInit callback ID
427 * @param pCallback pointer to the Callback function
428 * @retval HAL status
429 */
HAL_TSC_RegisterCallback(TSC_HandleTypeDef * htsc,HAL_TSC_CallbackIDTypeDef CallbackID,pTSC_CallbackTypeDef pCallback)430 HAL_StatusTypeDef HAL_TSC_RegisterCallback(TSC_HandleTypeDef *htsc, HAL_TSC_CallbackIDTypeDef CallbackID,
431 pTSC_CallbackTypeDef pCallback)
432 {
433 HAL_StatusTypeDef status = HAL_OK;
434
435 if (pCallback == NULL)
436 {
437 /* Update the error code */
438 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
439
440 return HAL_ERROR;
441 }
442 /* Process locked */
443 __HAL_LOCK(htsc);
444
445 if (HAL_TSC_STATE_READY == htsc->State)
446 {
447 switch (CallbackID)
448 {
449 case HAL_TSC_CONV_COMPLETE_CB_ID :
450 htsc->ConvCpltCallback = pCallback;
451 break;
452
453 case HAL_TSC_ERROR_CB_ID :
454 htsc->ErrorCallback = pCallback;
455 break;
456
457 case HAL_TSC_MSPINIT_CB_ID :
458 htsc->MspInitCallback = pCallback;
459 break;
460
461 case HAL_TSC_MSPDEINIT_CB_ID :
462 htsc->MspDeInitCallback = pCallback;
463 break;
464
465 default :
466 /* Update the error code */
467 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
468
469 /* Return error status */
470 status = HAL_ERROR;
471 break;
472 }
473 }
474 else if (HAL_TSC_STATE_RESET == htsc->State)
475 {
476 switch (CallbackID)
477 {
478 case HAL_TSC_MSPINIT_CB_ID :
479 htsc->MspInitCallback = pCallback;
480 break;
481
482 case HAL_TSC_MSPDEINIT_CB_ID :
483 htsc->MspDeInitCallback = pCallback;
484 break;
485
486 default :
487 /* Update the error code */
488 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
489
490 /* Return error status */
491 status = HAL_ERROR;
492 break;
493 }
494 }
495 else
496 {
497 /* Update the error code */
498 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
499
500 /* Return error status */
501 status = HAL_ERROR;
502 }
503
504 /* Release Lock */
505 __HAL_UNLOCK(htsc);
506 return status;
507 }
508
509 /**
510 * @brief Unregister an TSC Callback
511 * TSC callback is redirected to the weak predefined callback
512 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
513 * the configuration information for the specified TSC.
514 * @param CallbackID ID of the callback to be unregistered
515 * This parameter can be one of the following values:
516 * This parameter can be one of the following values:
517 * @arg @ref HAL_TSC_CONV_COMPLETE_CB_ID Conversion completed callback ID
518 * @arg @ref HAL_TSC_ERROR_CB_ID Error callback ID
519 * @arg @ref HAL_TSC_MSPINIT_CB_ID MspInit callback ID
520 * @arg @ref HAL_TSC_MSPDEINIT_CB_ID MspDeInit callback ID
521 * @retval HAL status
522 */
HAL_TSC_UnRegisterCallback(TSC_HandleTypeDef * htsc,HAL_TSC_CallbackIDTypeDef CallbackID)523 HAL_StatusTypeDef HAL_TSC_UnRegisterCallback(TSC_HandleTypeDef *htsc, HAL_TSC_CallbackIDTypeDef CallbackID)
524 {
525 HAL_StatusTypeDef status = HAL_OK;
526
527 /* Process locked */
528 __HAL_LOCK(htsc);
529
530 if (HAL_TSC_STATE_READY == htsc->State)
531 {
532 switch (CallbackID)
533 {
534 case HAL_TSC_CONV_COMPLETE_CB_ID :
535 htsc->ConvCpltCallback = HAL_TSC_ConvCpltCallback; /* Legacy weak ConvCpltCallback */
536 break;
537
538 case HAL_TSC_ERROR_CB_ID :
539 htsc->ErrorCallback = HAL_TSC_ErrorCallback; /* Legacy weak ErrorCallback */
540 break;
541
542 case HAL_TSC_MSPINIT_CB_ID :
543 htsc->MspInitCallback = HAL_TSC_MspInit; /* Legacy weak MspInit */
544 break;
545
546 case HAL_TSC_MSPDEINIT_CB_ID :
547 htsc->MspDeInitCallback = HAL_TSC_MspDeInit; /* Legacy weak MspDeInit */
548 break;
549
550 default :
551 /* Update the error code */
552 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
553
554 /* Return error status */
555 status = HAL_ERROR;
556 break;
557 }
558 }
559 else if (HAL_TSC_STATE_RESET == htsc->State)
560 {
561 switch (CallbackID)
562 {
563 case HAL_TSC_MSPINIT_CB_ID :
564 htsc->MspInitCallback = HAL_TSC_MspInit; /* Legacy weak MspInit */
565 break;
566
567 case HAL_TSC_MSPDEINIT_CB_ID :
568 htsc->MspDeInitCallback = HAL_TSC_MspDeInit; /* Legacy weak MspDeInit */
569 break;
570
571 default :
572 /* Update the error code */
573 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
574
575 /* Return error status */
576 status = HAL_ERROR;
577 break;
578 }
579 }
580 else
581 {
582 /* Update the error code */
583 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
584
585 /* Return error status */
586 status = HAL_ERROR;
587 }
588
589 /* Release Lock */
590 __HAL_UNLOCK(htsc);
591 return status;
592 }
593
594 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
595
596 /**
597 * @}
598 */
599
600 /** @defgroup TSC_Exported_Functions_Group2 Input and Output operation functions
601 * @brief Input and Output operation functions
602 *
603 @verbatim
604 ===============================================================================
605 ##### IO Operation functions #####
606 ===============================================================================
607 [..] This section provides functions allowing to:
608 (+) Start acquisition in polling mode.
609 (+) Start acquisition in interrupt mode.
610 (+) Stop conversion in polling mode.
611 (+) Stop conversion in interrupt mode.
612 (+) Poll for acquisition completed.
613 (+) Get group acquisition status.
614 (+) Get group acquisition value.
615 @endverbatim
616 * @{
617 */
618
619 /**
620 * @brief Start the acquisition.
621 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
622 * the configuration information for the specified TSC.
623 * @retval HAL status
624 */
HAL_TSC_Start(TSC_HandleTypeDef * htsc)625 HAL_StatusTypeDef HAL_TSC_Start(TSC_HandleTypeDef *htsc)
626 {
627 /* Check the parameters */
628 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
629
630 /* Process locked */
631 __HAL_LOCK(htsc);
632
633 /* Change TSC state */
634 htsc->State = HAL_TSC_STATE_BUSY;
635
636 /* Clear interrupts */
637 __HAL_TSC_DISABLE_IT(htsc, (TSC_IT_EOA | TSC_IT_MCE));
638
639 /* Clear flags */
640 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
641
642 /* Set touch sensing IOs not acquired to the specified IODefaultMode */
643 if (htsc->Init.IODefaultMode == TSC_IODEF_OUT_PP_LOW)
644 {
645 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
646 }
647 else
648 {
649 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
650 }
651
652 /* Launch the acquisition */
653 __HAL_TSC_START_ACQ(htsc);
654
655 /* Process unlocked */
656 __HAL_UNLOCK(htsc);
657
658 /* Return function status */
659 return HAL_OK;
660 }
661
662 /**
663 * @brief Start the acquisition in interrupt mode.
664 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
665 * the configuration information for the specified TSC.
666 * @retval HAL status.
667 */
HAL_TSC_Start_IT(TSC_HandleTypeDef * htsc)668 HAL_StatusTypeDef HAL_TSC_Start_IT(TSC_HandleTypeDef *htsc)
669 {
670 /* Check the parameters */
671 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
672 assert_param(IS_TSC_MCE_IT(htsc->Init.MaxCountInterrupt));
673
674 /* Process locked */
675 __HAL_LOCK(htsc);
676
677 /* Change TSC state */
678 htsc->State = HAL_TSC_STATE_BUSY;
679
680 /* Enable end of acquisition interrupt */
681 __HAL_TSC_ENABLE_IT(htsc, TSC_IT_EOA);
682
683 /* Enable max count error interrupt (optional) */
684 if (htsc->Init.MaxCountInterrupt == ENABLE)
685 {
686 __HAL_TSC_ENABLE_IT(htsc, TSC_IT_MCE);
687 }
688 else
689 {
690 __HAL_TSC_DISABLE_IT(htsc, TSC_IT_MCE);
691 }
692
693 /* Clear flags */
694 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
695
696 /* Set touch sensing IOs not acquired to the specified IODefaultMode */
697 if (htsc->Init.IODefaultMode == TSC_IODEF_OUT_PP_LOW)
698 {
699 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
700 }
701 else
702 {
703 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
704 }
705
706 /* Launch the acquisition */
707 __HAL_TSC_START_ACQ(htsc);
708
709 /* Process unlocked */
710 __HAL_UNLOCK(htsc);
711
712 /* Return function status */
713 return HAL_OK;
714 }
715
716 /**
717 * @brief Stop the acquisition previously launched in polling mode.
718 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
719 * the configuration information for the specified TSC.
720 * @retval HAL status
721 */
HAL_TSC_Stop(TSC_HandleTypeDef * htsc)722 HAL_StatusTypeDef HAL_TSC_Stop(TSC_HandleTypeDef *htsc)
723 {
724 /* Check the parameters */
725 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
726
727 /* Process locked */
728 __HAL_LOCK(htsc);
729
730 /* Stop the acquisition */
731 __HAL_TSC_STOP_ACQ(htsc);
732
733 /* Set touch sensing IOs in low power mode (output push-pull) */
734 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
735
736 /* Clear flags */
737 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
738
739 /* Change TSC state */
740 htsc->State = HAL_TSC_STATE_READY;
741
742 /* Process unlocked */
743 __HAL_UNLOCK(htsc);
744
745 /* Return function status */
746 return HAL_OK;
747 }
748
749 /**
750 * @brief Stop the acquisition previously launched in interrupt mode.
751 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
752 * the configuration information for the specified TSC.
753 * @retval HAL status
754 */
HAL_TSC_Stop_IT(TSC_HandleTypeDef * htsc)755 HAL_StatusTypeDef HAL_TSC_Stop_IT(TSC_HandleTypeDef *htsc)
756 {
757 /* Check the parameters */
758 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
759
760 /* Process locked */
761 __HAL_LOCK(htsc);
762
763 /* Stop the acquisition */
764 __HAL_TSC_STOP_ACQ(htsc);
765
766 /* Set touch sensing IOs in low power mode (output push-pull) */
767 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
768
769 /* Disable interrupts */
770 __HAL_TSC_DISABLE_IT(htsc, (TSC_IT_EOA | TSC_IT_MCE));
771
772 /* Clear flags */
773 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
774
775 /* Change TSC state */
776 htsc->State = HAL_TSC_STATE_READY;
777
778 /* Process unlocked */
779 __HAL_UNLOCK(htsc);
780
781 /* Return function status */
782 return HAL_OK;
783 }
784
785 /**
786 * @brief Start acquisition and wait until completion.
787 * @note There is no need of a timeout parameter as the max count error is already
788 * managed by the TSC peripheral.
789 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
790 * the configuration information for the specified TSC.
791 * @retval HAL state
792 */
HAL_TSC_PollForAcquisition(TSC_HandleTypeDef * htsc)793 HAL_StatusTypeDef HAL_TSC_PollForAcquisition(TSC_HandleTypeDef *htsc)
794 {
795 /* Check the parameters */
796 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
797
798 /* Process locked */
799 __HAL_LOCK(htsc);
800
801 /* Check end of acquisition */
802 while (HAL_TSC_GetState(htsc) == HAL_TSC_STATE_BUSY)
803 {
804 /* The timeout (max count error) is managed by the TSC peripheral itself. */
805 }
806
807 /* Process unlocked */
808 __HAL_UNLOCK(htsc);
809
810 return HAL_OK;
811 }
812
813 /**
814 * @brief Get the acquisition status for a group.
815 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
816 * the configuration information for the specified TSC.
817 * @param gx_index Index of the group
818 * @retval Group status
819 */
HAL_TSC_GroupGetStatus(const TSC_HandleTypeDef * htsc,uint32_t gx_index)820 TSC_GroupStatusTypeDef HAL_TSC_GroupGetStatus(const TSC_HandleTypeDef *htsc, uint32_t gx_index)
821 {
822 /* Check the parameters */
823 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
824 assert_param(IS_TSC_GROUP_INDEX(gx_index));
825
826 /* Return the group status */
827 return (__HAL_TSC_GET_GROUP_STATUS(htsc, gx_index));
828 }
829
830 /**
831 * @brief Get the acquisition measure for a group.
832 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
833 * the configuration information for the specified TSC.
834 * @param gx_index Index of the group
835 * @retval Acquisition measure
836 */
HAL_TSC_GroupGetValue(const TSC_HandleTypeDef * htsc,uint32_t gx_index)837 uint32_t HAL_TSC_GroupGetValue(const TSC_HandleTypeDef *htsc, uint32_t gx_index)
838 {
839 /* Check the parameters */
840 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
841 assert_param(IS_TSC_GROUP_INDEX(gx_index));
842
843 /* Return the group acquisition counter */
844 return htsc->Instance->IOGXCR[gx_index];
845 }
846
847 /**
848 * @}
849 */
850
851 /** @defgroup TSC_Exported_Functions_Group3 Peripheral Control functions
852 * @brief Peripheral Control functions
853 *
854 @verbatim
855 ===============================================================================
856 ##### Peripheral Control functions #####
857 ===============================================================================
858 [..] This section provides functions allowing to:
859 (+) Configure TSC IOs
860 (+) Discharge TSC IOs
861 @endverbatim
862 * @{
863 */
864
865 /**
866 * @brief Configure TSC IOs.
867 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
868 * the configuration information for the specified TSC.
869 * @param config Pointer to the configuration structure.
870 * @retval HAL status
871 */
HAL_TSC_IOConfig(TSC_HandleTypeDef * htsc,const TSC_IOConfigTypeDef * config)872 HAL_StatusTypeDef HAL_TSC_IOConfig(TSC_HandleTypeDef *htsc, const TSC_IOConfigTypeDef *config)
873 {
874 /* Check the parameters */
875 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
876 assert_param(IS_TSC_GROUP(config->ChannelIOs));
877 assert_param(IS_TSC_GROUP(config->ShieldIOs));
878 assert_param(IS_TSC_GROUP(config->SamplingIOs));
879
880 /* Process locked */
881 __HAL_LOCK(htsc);
882
883 /* Stop acquisition */
884 __HAL_TSC_STOP_ACQ(htsc);
885
886 /* Disable Schmitt trigger hysteresis on all used TSC IOs */
887 htsc->Instance->IOHCR = (~(config->ChannelIOs | config->ShieldIOs | config->SamplingIOs));
888
889 /* Set channel and shield IOs */
890 htsc->Instance->IOCCR = (config->ChannelIOs | config->ShieldIOs);
891
892 /* Set sampling IOs */
893 htsc->Instance->IOSCR = config->SamplingIOs;
894
895 /* Set groups to be acquired */
896 htsc->Instance->IOGCSR = TSC_extract_groups(config->ChannelIOs);
897
898 /* Process unlocked */
899 __HAL_UNLOCK(htsc);
900
901 /* Return function status */
902 return HAL_OK;
903 }
904
905 /**
906 * @brief Discharge TSC IOs.
907 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
908 * the configuration information for the specified TSC.
909 * @param choice This parameter can be set to ENABLE or DISABLE.
910 * @retval HAL status
911 */
HAL_TSC_IODischarge(TSC_HandleTypeDef * htsc,FunctionalState choice)912 HAL_StatusTypeDef HAL_TSC_IODischarge(TSC_HandleTypeDef *htsc, FunctionalState choice)
913 {
914 /* Check the parameters */
915 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
916
917 /* Process locked */
918 __HAL_LOCK(htsc);
919
920 if (choice == ENABLE)
921 {
922 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
923 }
924 else
925 {
926 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
927 }
928
929 /* Process unlocked */
930 __HAL_UNLOCK(htsc);
931
932 /* Return the group acquisition counter */
933 return HAL_OK;
934 }
935
936 /**
937 * @}
938 */
939
940 /** @defgroup TSC_Exported_Functions_Group4 Peripheral State and Errors functions
941 * @brief Peripheral State and Errors functions
942 *
943 @verbatim
944 ===============================================================================
945 ##### State and Errors functions #####
946 ===============================================================================
947 [..]
948 This subsection provides functions allowing to
949 (+) Get TSC state.
950
951 @endverbatim
952 * @{
953 */
954
955 /**
956 * @brief Return the TSC handle state.
957 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
958 * the configuration information for the specified TSC.
959 * @retval HAL state
960 */
HAL_TSC_GetState(TSC_HandleTypeDef * htsc)961 HAL_TSC_StateTypeDef HAL_TSC_GetState(TSC_HandleTypeDef *htsc)
962 {
963 /* Check the parameters */
964 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
965
966 if (htsc->State == HAL_TSC_STATE_BUSY)
967 {
968 /* Check end of acquisition flag */
969 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_EOA) != RESET)
970 {
971 /* Check max count error flag */
972 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_MCE) != RESET)
973 {
974 /* Change TSC state */
975 htsc->State = HAL_TSC_STATE_ERROR;
976 }
977 else
978 {
979 /* Change TSC state */
980 htsc->State = HAL_TSC_STATE_READY;
981 }
982 }
983 }
984
985 /* Return TSC state */
986 return htsc->State;
987 }
988
989 /**
990 * @}
991 */
992
993 /** @defgroup TSC_IRQ_Handler_and_Callbacks IRQ Handler and Callbacks
994 * @{
995 */
996
997 /**
998 * @brief Handle TSC interrupt request.
999 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
1000 * the configuration information for the specified TSC.
1001 * @retval None
1002 */
HAL_TSC_IRQHandler(TSC_HandleTypeDef * htsc)1003 void HAL_TSC_IRQHandler(TSC_HandleTypeDef *htsc)
1004 {
1005 /* Check the parameters */
1006 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
1007
1008 /* Check if the end of acquisition occurred */
1009 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_EOA) != RESET)
1010 {
1011 /* Clear EOA flag */
1012 __HAL_TSC_CLEAR_FLAG(htsc, TSC_FLAG_EOA);
1013 }
1014
1015 /* Check if max count error occurred */
1016 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_MCE) != RESET)
1017 {
1018 /* Clear MCE flag */
1019 __HAL_TSC_CLEAR_FLAG(htsc, TSC_FLAG_MCE);
1020 /* Change TSC state */
1021 htsc->State = HAL_TSC_STATE_ERROR;
1022 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
1023 htsc->ErrorCallback(htsc);
1024 #else
1025 /* Conversion completed callback */
1026 HAL_TSC_ErrorCallback(htsc);
1027 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
1028 }
1029 else
1030 {
1031 /* Change TSC state */
1032 htsc->State = HAL_TSC_STATE_READY;
1033 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
1034 htsc->ConvCpltCallback(htsc);
1035 #else
1036 /* Conversion completed callback */
1037 HAL_TSC_ConvCpltCallback(htsc);
1038 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
1039 }
1040 }
1041
1042 /**
1043 * @brief Acquisition completed callback in non-blocking mode.
1044 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
1045 * the configuration information for the specified TSC.
1046 * @retval None
1047 */
HAL_TSC_ConvCpltCallback(TSC_HandleTypeDef * htsc)1048 __weak void HAL_TSC_ConvCpltCallback(TSC_HandleTypeDef *htsc)
1049 {
1050 /* Prevent unused argument(s) compilation warning */
1051 UNUSED(htsc);
1052
1053 /* NOTE : This function should not be modified, when the callback is needed,
1054 the HAL_TSC_ConvCpltCallback could be implemented in the user file.
1055 */
1056 }
1057
1058 /**
1059 * @brief Error callback in non-blocking mode.
1060 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
1061 * the configuration information for the specified TSC.
1062 * @retval None
1063 */
HAL_TSC_ErrorCallback(TSC_HandleTypeDef * htsc)1064 __weak void HAL_TSC_ErrorCallback(TSC_HandleTypeDef *htsc)
1065 {
1066 /* Prevent unused argument(s) compilation warning */
1067 UNUSED(htsc);
1068
1069 /* NOTE : This function should not be modified, when the callback is needed,
1070 the HAL_TSC_ErrorCallback could be implemented in the user file.
1071 */
1072 }
1073
1074 /**
1075 * @}
1076 */
1077
1078 /**
1079 * @}
1080 */
1081
1082 /* Private functions ---------------------------------------------------------*/
1083 /** @defgroup TSC_Private_Functions TSC Private Functions
1084 * @{
1085 */
1086
1087 /**
1088 * @brief Utility function used to set the acquired groups mask.
1089 * @param iomask Channels IOs mask
1090 * @retval Acquired groups mask
1091 */
TSC_extract_groups(uint32_t iomask)1092 static uint32_t TSC_extract_groups(uint32_t iomask)
1093 {
1094 uint32_t groups = 0UL;
1095 uint32_t idx;
1096
1097 for (idx = 0UL; idx < (uint32_t)TSC_NB_OF_GROUPS; idx++)
1098 {
1099 if ((iomask & (0x0FUL << (idx * 4UL))) != 0UL)
1100 {
1101 groups |= (1UL << idx);
1102 }
1103 }
1104
1105 return groups;
1106 }
1107
1108 /**
1109 * @}
1110 */
1111
1112 #endif /* HAL_TSC_MODULE_ENABLED */
1113
1114 /**
1115 * @}
1116 */
1117
1118 /**
1119 * @}
1120 */
1121
1122
