1 /**
2 ******************************************************************************
3 * @file stm32wbaxx_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) 2022 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 STM32WBAxx devices
148 +--------------------------------+
149 | IOs | TSC functions |
150 |--------------|-----------------|
151 | PA8 (AF9) | TSC_G1_IO1 |
152 | PA7 (AF9) | TSC_G1_IO2 |
153 | PA6 (AF9) | TSC_G1_IO3 |
154 | PA5 (AF9) | TSC_G1_IO4 |
155 |--------------|-----------------|
156 | PA1 (AF9) | TSC_G2_IO1 |
157 | PA0 (AF9) | TSC_G2_IO2 |
158 | PB9 (AF9) | TSC_G2_IO3 |
159 | PB8 (AF9) | TSC_G2_IO4 |
160 |--------------|-----------------|
161 | PB4 (AF9) | TSC_G3_IO1 |
162 | PB3 (AF9) | TSC_G3_IO2 |
163 | PA15 (AF9) | TSC_G3_IO3 |
164 | PA12 (AF9) | TSC_G3_IO4 |
165 |--------------|-----------------|
166 | PA4 (AF9) | TSC_G4_IO1 |
167 | PA3 (AF9) | TSC_G4_IO2 |
168 | PB10 (AF9) | TSC_G4_IO3 |
169 | PA2 (AF9) | TSC_G4_IO4 |
170 |--------------|-----------------|
171 | PC13 (AF9) | TSC_G5_IO1 |
172 | PB7 (AF9) | TSC_G5_IO2 |
173 | PB6 (AF9) | TSC_G5_IO3 |
174 | PB5 (AF9) | TSC_G5_IO4 |
175 |--------------|-----------------|
176 | PB14 (AF9) | TSC_G6_IO1 |
177 | PB13 (AF9) | TSC_G6_IO2 |
178 |--------------|-----------------|
179 | PB12 (AF9) | TSC_SYNC |
180 +--------------------------------+
181
182 */
183
184 /* Includes ------------------------------------------------------------------*/
185 #include "stm32wbaxx_hal.h"
186
187 /** @addtogroup STM32WBAxx_HAL_Driver
188 * @{
189 */
190
191 /** @defgroup TSC TSC
192 * @brief HAL TSC module driver
193 * @{
194 */
195
196 #ifdef HAL_TSC_MODULE_ENABLED
197
198 /* Private typedef -----------------------------------------------------------*/
199 /* Private define ------------------------------------------------------------*/
200 /* Private macro -------------------------------------------------------------*/
201 /* Private variables ---------------------------------------------------------*/
202 /* Private function prototypes -----------------------------------------------*/
203 static uint32_t TSC_extract_groups(uint32_t iomask);
204
205 /* Exported functions --------------------------------------------------------*/
206
207 /** @defgroup TSC_Exported_Functions TSC Exported Functions
208 * @{
209 */
210
211 /** @defgroup TSC_Exported_Functions_Group1 Initialization and de-initialization functions
212 * @brief Initialization and Configuration functions
213 *
214 @verbatim
215 ===============================================================================
216 ##### Initialization and de-initialization functions #####
217 ===============================================================================
218 [..] This section provides functions allowing to:
219 (+) Initialize and configure the TSC.
220 (+) De-initialize the TSC.
221 @endverbatim
222 * @{
223 */
224
225 /**
226 * @brief Initialize the TSC peripheral according to the specified parameters
227 * in the TSC_InitTypeDef structure and initialize the associated handle.
228 * @param htsc TSC handle
229 * @retval HAL status
230 */
HAL_TSC_Init(TSC_HandleTypeDef * htsc)231 HAL_StatusTypeDef HAL_TSC_Init(TSC_HandleTypeDef *htsc)
232 {
233 /* Check TSC handle allocation */
234 if (htsc == NULL)
235 {
236 return HAL_ERROR;
237 }
238
239 /* Check the parameters */
240 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
241 assert_param(IS_TSC_CTPH(htsc->Init.CTPulseHighLength));
242 assert_param(IS_TSC_CTPL(htsc->Init.CTPulseLowLength));
243 assert_param(IS_TSC_SS(htsc->Init.SpreadSpectrum));
244 assert_param(IS_TSC_SSD(htsc->Init.SpreadSpectrumDeviation));
245 assert_param(IS_TSC_SS_PRESC(htsc->Init.SpreadSpectrumPrescaler));
246 assert_param(IS_TSC_PG_PRESC(htsc->Init.PulseGeneratorPrescaler));
247 assert_param(IS_TSC_PG_PRESC_VS_CTPL(htsc->Init.PulseGeneratorPrescaler, htsc->Init.CTPulseLowLength));
248 assert_param(IS_TSC_MCV(htsc->Init.MaxCountValue));
249 assert_param(IS_TSC_IODEF(htsc->Init.IODefaultMode));
250 assert_param(IS_TSC_SYNC_POL(htsc->Init.SynchroPinPolarity));
251 assert_param(IS_TSC_ACQ_MODE(htsc->Init.AcquisitionMode));
252 assert_param(IS_TSC_MCE_IT(htsc->Init.MaxCountInterrupt));
253 assert_param(IS_TSC_GROUP(htsc->Init.ChannelIOs));
254 assert_param(IS_TSC_GROUP(htsc->Init.ShieldIOs));
255 assert_param(IS_TSC_GROUP(htsc->Init.SamplingIOs));
256
257 if (htsc->State == HAL_TSC_STATE_RESET)
258 {
259 /* Allocate lock resource and initialize it */
260 htsc->Lock = HAL_UNLOCKED;
261
262 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
263 /* Init the TSC Callback settings */
264 htsc->ConvCpltCallback = HAL_TSC_ConvCpltCallback; /* Legacy weak ConvCpltCallback */
265 htsc->ErrorCallback = HAL_TSC_ErrorCallback; /* Legacy weak ErrorCallback */
266
267 if (htsc->MspInitCallback == NULL)
268 {
269 htsc->MspInitCallback = HAL_TSC_MspInit; /* Legacy weak MspInit */
270 }
271
272 /* Init the low level hardware : GPIO, CLOCK, CORTEX...etc */
273 htsc->MspInitCallback(htsc);
274 #else
275 /* Init the low level hardware : GPIO, CLOCK, CORTEX */
276 HAL_TSC_MspInit(htsc);
277 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
278 }
279
280 /* Initialize the TSC state */
281 htsc->State = HAL_TSC_STATE_BUSY;
282
283 /*--------------------------------------------------------------------------*/
284 /* Set TSC parameters */
285
286 /* Enable TSC */
287 htsc->Instance->CR = TSC_CR_TSCE;
288
289 /* Set all functions */
290 htsc->Instance->CR |= (htsc->Init.CTPulseHighLength |
291 htsc->Init.CTPulseLowLength |
292 (htsc->Init.SpreadSpectrumDeviation << TSC_CR_SSD_Pos) |
293 htsc->Init.SpreadSpectrumPrescaler |
294 htsc->Init.PulseGeneratorPrescaler |
295 htsc->Init.MaxCountValue |
296 htsc->Init.SynchroPinPolarity |
297 htsc->Init.AcquisitionMode);
298
299 /* Spread spectrum */
300 if (htsc->Init.SpreadSpectrum == ENABLE)
301 {
302 htsc->Instance->CR |= TSC_CR_SSE;
303 }
304
305 /* Disable Schmitt trigger hysteresis on all used TSC IOs */
306 htsc->Instance->IOHCR = (~(htsc->Init.ChannelIOs | htsc->Init.ShieldIOs | htsc->Init.SamplingIOs));
307
308 /* Set channel and shield IOs */
309 htsc->Instance->IOCCR = (htsc->Init.ChannelIOs | htsc->Init.ShieldIOs);
310
311 /* Set sampling IOs */
312 htsc->Instance->IOSCR = htsc->Init.SamplingIOs;
313
314 /* Set the groups to be acquired */
315 htsc->Instance->IOGCSR = TSC_extract_groups(htsc->Init.ChannelIOs);
316
317 /* Disable interrupts */
318 htsc->Instance->IER &= (~(TSC_IT_EOA | TSC_IT_MCE));
319
320 /* Clear flags */
321 htsc->Instance->ICR = (TSC_FLAG_EOA | TSC_FLAG_MCE);
322
323 /*--------------------------------------------------------------------------*/
324
325 /* Initialize the TSC state */
326 htsc->State = HAL_TSC_STATE_READY;
327
328 /* Return function status */
329 return HAL_OK;
330 }
331
332 /**
333 * @brief Deinitialize the TSC peripheral registers to their default reset values.
334 * @param htsc TSC handle
335 * @retval HAL status
336 */
HAL_TSC_DeInit(TSC_HandleTypeDef * htsc)337 HAL_StatusTypeDef HAL_TSC_DeInit(TSC_HandleTypeDef *htsc)
338 {
339 /* Check TSC handle allocation */
340 if (htsc == NULL)
341 {
342 return HAL_ERROR;
343 }
344
345 /* Check the parameters */
346 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
347
348 /* Change TSC state */
349 htsc->State = HAL_TSC_STATE_BUSY;
350
351 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
352 if (htsc->MspDeInitCallback == NULL)
353 {
354 htsc->MspDeInitCallback = HAL_TSC_MspDeInit; /* Legacy weak MspDeInit */
355 }
356
357 /* DeInit the low level hardware: GPIO, CLOCK, NVIC */
358 htsc->MspDeInitCallback(htsc);
359 #else
360 /* DeInit the low level hardware */
361 HAL_TSC_MspDeInit(htsc);
362 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
363
364 /* Change TSC state */
365 htsc->State = HAL_TSC_STATE_RESET;
366
367 /* Process unlocked */
368 __HAL_UNLOCK(htsc);
369
370 /* Return function status */
371 return HAL_OK;
372 }
373
374 /**
375 * @brief Initialize the TSC MSP.
376 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
377 * the configuration information for the specified TSC.
378 * @retval None
379 */
HAL_TSC_MspInit(TSC_HandleTypeDef * htsc)380 __weak void HAL_TSC_MspInit(TSC_HandleTypeDef *htsc)
381 {
382 /* Prevent unused argument(s) compilation warning */
383 UNUSED(htsc);
384
385 /* NOTE : This function should not be modified, when the callback is needed,
386 the HAL_TSC_MspInit could be implemented in the user file.
387 */
388 }
389
390 /**
391 * @brief DeInitialize the TSC MSP.
392 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
393 * the configuration information for the specified TSC.
394 * @retval None
395 */
HAL_TSC_MspDeInit(TSC_HandleTypeDef * htsc)396 __weak void HAL_TSC_MspDeInit(TSC_HandleTypeDef *htsc)
397 {
398 /* Prevent unused argument(s) compilation warning */
399 UNUSED(htsc);
400
401 /* NOTE : This function should not be modified, when the callback is needed,
402 the HAL_TSC_MspDeInit could be implemented in the user file.
403 */
404 }
405
406 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
407 /**
408 * @brief Register a User TSC Callback
409 * To be used instead of the weak predefined callback
410 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
411 * the configuration information for the specified TSC.
412 * @param CallbackID ID of the callback to be registered
413 * This parameter can be one of the following values:
414 * @arg @ref HAL_TSC_CONV_COMPLETE_CB_ID Conversion completed callback ID
415 * @arg @ref HAL_TSC_ERROR_CB_ID Error callback ID
416 * @arg @ref HAL_TSC_MSPINIT_CB_ID MspInit callback ID
417 * @arg @ref HAL_TSC_MSPDEINIT_CB_ID MspDeInit callback ID
418 * @param pCallback pointer to the Callback function
419 * @retval HAL status
420 */
HAL_TSC_RegisterCallback(TSC_HandleTypeDef * htsc,HAL_TSC_CallbackIDTypeDef CallbackID,pTSC_CallbackTypeDef pCallback)421 HAL_StatusTypeDef HAL_TSC_RegisterCallback(TSC_HandleTypeDef *htsc, HAL_TSC_CallbackIDTypeDef CallbackID,
422 pTSC_CallbackTypeDef pCallback)
423 {
424 HAL_StatusTypeDef status = HAL_OK;
425
426 if (pCallback == NULL)
427 {
428 /* Update the error code */
429 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
430
431 return HAL_ERROR;
432 }
433 /* Process locked */
434 __HAL_LOCK(htsc);
435
436 if (HAL_TSC_STATE_READY == htsc->State)
437 {
438 switch (CallbackID)
439 {
440 case HAL_TSC_CONV_COMPLETE_CB_ID :
441 htsc->ConvCpltCallback = pCallback;
442 break;
443
444 case HAL_TSC_ERROR_CB_ID :
445 htsc->ErrorCallback = pCallback;
446 break;
447
448 case HAL_TSC_MSPINIT_CB_ID :
449 htsc->MspInitCallback = pCallback;
450 break;
451
452 case HAL_TSC_MSPDEINIT_CB_ID :
453 htsc->MspDeInitCallback = pCallback;
454 break;
455
456 default :
457 /* Update the error code */
458 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
459
460 /* Return error status */
461 status = HAL_ERROR;
462 break;
463 }
464 }
465 else if (HAL_TSC_STATE_RESET == htsc->State)
466 {
467 switch (CallbackID)
468 {
469 case HAL_TSC_MSPINIT_CB_ID :
470 htsc->MspInitCallback = pCallback;
471 break;
472
473 case HAL_TSC_MSPDEINIT_CB_ID :
474 htsc->MspDeInitCallback = pCallback;
475 break;
476
477 default :
478 /* Update the error code */
479 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
480
481 /* Return error status */
482 status = HAL_ERROR;
483 break;
484 }
485 }
486 else
487 {
488 /* Update the error code */
489 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
490
491 /* Return error status */
492 status = HAL_ERROR;
493 }
494
495 /* Release Lock */
496 __HAL_UNLOCK(htsc);
497 return status;
498 }
499
500 /**
501 * @brief Unregister an TSC Callback
502 * TSC callback is redirected to the weak predefined callback
503 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
504 * the configuration information for the specified TSC.
505 * @param CallbackID ID of the callback to be unregistered
506 * This parameter can be one of the following values:
507 * This parameter can be one of the following values:
508 * @arg @ref HAL_TSC_CONV_COMPLETE_CB_ID Conversion completed callback ID
509 * @arg @ref HAL_TSC_ERROR_CB_ID Error callback ID
510 * @arg @ref HAL_TSC_MSPINIT_CB_ID MspInit callback ID
511 * @arg @ref HAL_TSC_MSPDEINIT_CB_ID MspDeInit callback ID
512 * @retval HAL status
513 */
HAL_TSC_UnRegisterCallback(TSC_HandleTypeDef * htsc,HAL_TSC_CallbackIDTypeDef CallbackID)514 HAL_StatusTypeDef HAL_TSC_UnRegisterCallback(TSC_HandleTypeDef *htsc, HAL_TSC_CallbackIDTypeDef CallbackID)
515 {
516 HAL_StatusTypeDef status = HAL_OK;
517
518 /* Process locked */
519 __HAL_LOCK(htsc);
520
521 if (HAL_TSC_STATE_READY == htsc->State)
522 {
523 switch (CallbackID)
524 {
525 case HAL_TSC_CONV_COMPLETE_CB_ID :
526 htsc->ConvCpltCallback = HAL_TSC_ConvCpltCallback; /* Legacy weak ConvCpltCallback */
527 break;
528
529 case HAL_TSC_ERROR_CB_ID :
530 htsc->ErrorCallback = HAL_TSC_ErrorCallback; /* Legacy weak ErrorCallback */
531 break;
532
533 case HAL_TSC_MSPINIT_CB_ID :
534 htsc->MspInitCallback = HAL_TSC_MspInit; /* Legacy weak MspInit */
535 break;
536
537 case HAL_TSC_MSPDEINIT_CB_ID :
538 htsc->MspDeInitCallback = HAL_TSC_MspDeInit; /* Legacy weak MspDeInit */
539 break;
540
541 default :
542 /* Update the error code */
543 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
544
545 /* Return error status */
546 status = HAL_ERROR;
547 break;
548 }
549 }
550 else if (HAL_TSC_STATE_RESET == htsc->State)
551 {
552 switch (CallbackID)
553 {
554 case HAL_TSC_MSPINIT_CB_ID :
555 htsc->MspInitCallback = HAL_TSC_MspInit; /* Legacy weak MspInit */
556 break;
557
558 case HAL_TSC_MSPDEINIT_CB_ID :
559 htsc->MspDeInitCallback = HAL_TSC_MspDeInit; /* Legacy weak MspDeInit */
560 break;
561
562 default :
563 /* Update the error code */
564 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
565
566 /* Return error status */
567 status = HAL_ERROR;
568 break;
569 }
570 }
571 else
572 {
573 /* Update the error code */
574 htsc->ErrorCode |= HAL_TSC_ERROR_INVALID_CALLBACK;
575
576 /* Return error status */
577 status = HAL_ERROR;
578 }
579
580 /* Release Lock */
581 __HAL_UNLOCK(htsc);
582 return status;
583 }
584
585 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
586
587 /**
588 * @}
589 */
590
591 /** @defgroup TSC_Exported_Functions_Group2 Input and Output operation functions
592 * @brief Input and Output operation functions
593 *
594 @verbatim
595 ===============================================================================
596 ##### IO Operation functions #####
597 ===============================================================================
598 [..] This section provides functions allowing to:
599 (+) Start acquisition in polling mode.
600 (+) Start acquisition in interrupt mode.
601 (+) Stop conversion in polling mode.
602 (+) Stop conversion in interrupt mode.
603 (+) Poll for acquisition completed.
604 (+) Get group acquisition status.
605 (+) Get group acquisition value.
606 @endverbatim
607 * @{
608 */
609
610 /**
611 * @brief Start the acquisition.
612 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
613 * the configuration information for the specified TSC.
614 * @retval HAL status
615 */
HAL_TSC_Start(TSC_HandleTypeDef * htsc)616 HAL_StatusTypeDef HAL_TSC_Start(TSC_HandleTypeDef *htsc)
617 {
618 /* Check the parameters */
619 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
620
621 /* Process locked */
622 __HAL_LOCK(htsc);
623
624 /* Change TSC state */
625 htsc->State = HAL_TSC_STATE_BUSY;
626
627 /* Clear interrupts */
628 __HAL_TSC_DISABLE_IT(htsc, (TSC_IT_EOA | TSC_IT_MCE));
629
630 /* Clear flags */
631 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
632
633 /* Set touch sensing IOs not acquired to the specified IODefaultMode */
634 if (htsc->Init.IODefaultMode == TSC_IODEF_OUT_PP_LOW)
635 {
636 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
637 }
638 else
639 {
640 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
641 }
642
643 /* Launch the acquisition */
644 __HAL_TSC_START_ACQ(htsc);
645
646 /* Process unlocked */
647 __HAL_UNLOCK(htsc);
648
649 /* Return function status */
650 return HAL_OK;
651 }
652
653 /**
654 * @brief Start the acquisition in interrupt mode.
655 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
656 * the configuration information for the specified TSC.
657 * @retval HAL status.
658 */
HAL_TSC_Start_IT(TSC_HandleTypeDef * htsc)659 HAL_StatusTypeDef HAL_TSC_Start_IT(TSC_HandleTypeDef *htsc)
660 {
661 /* Check the parameters */
662 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
663 assert_param(IS_TSC_MCE_IT(htsc->Init.MaxCountInterrupt));
664
665 /* Process locked */
666 __HAL_LOCK(htsc);
667
668 /* Change TSC state */
669 htsc->State = HAL_TSC_STATE_BUSY;
670
671 /* Enable end of acquisition interrupt */
672 __HAL_TSC_ENABLE_IT(htsc, TSC_IT_EOA);
673
674 /* Enable max count error interrupt (optional) */
675 if (htsc->Init.MaxCountInterrupt == ENABLE)
676 {
677 __HAL_TSC_ENABLE_IT(htsc, TSC_IT_MCE);
678 }
679 else
680 {
681 __HAL_TSC_DISABLE_IT(htsc, TSC_IT_MCE);
682 }
683
684 /* Clear flags */
685 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
686
687 /* Set touch sensing IOs not acquired to the specified IODefaultMode */
688 if (htsc->Init.IODefaultMode == TSC_IODEF_OUT_PP_LOW)
689 {
690 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
691 }
692 else
693 {
694 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
695 }
696
697 /* Launch the acquisition */
698 __HAL_TSC_START_ACQ(htsc);
699
700 /* Process unlocked */
701 __HAL_UNLOCK(htsc);
702
703 /* Return function status */
704 return HAL_OK;
705 }
706
707 /**
708 * @brief Stop the acquisition previously launched in polling mode.
709 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
710 * the configuration information for the specified TSC.
711 * @retval HAL status
712 */
HAL_TSC_Stop(TSC_HandleTypeDef * htsc)713 HAL_StatusTypeDef HAL_TSC_Stop(TSC_HandleTypeDef *htsc)
714 {
715 /* Check the parameters */
716 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
717
718 /* Process locked */
719 __HAL_LOCK(htsc);
720
721 /* Stop the acquisition */
722 __HAL_TSC_STOP_ACQ(htsc);
723
724 /* Set touch sensing IOs in low power mode (output push-pull) */
725 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
726
727 /* Clear flags */
728 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
729
730 /* Change TSC state */
731 htsc->State = HAL_TSC_STATE_READY;
732
733 /* Process unlocked */
734 __HAL_UNLOCK(htsc);
735
736 /* Return function status */
737 return HAL_OK;
738 }
739
740 /**
741 * @brief Stop the acquisition previously launched in interrupt mode.
742 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
743 * the configuration information for the specified TSC.
744 * @retval HAL status
745 */
HAL_TSC_Stop_IT(TSC_HandleTypeDef * htsc)746 HAL_StatusTypeDef HAL_TSC_Stop_IT(TSC_HandleTypeDef *htsc)
747 {
748 /* Check the parameters */
749 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
750
751 /* Process locked */
752 __HAL_LOCK(htsc);
753
754 /* Stop the acquisition */
755 __HAL_TSC_STOP_ACQ(htsc);
756
757 /* Set touch sensing IOs in low power mode (output push-pull) */
758 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
759
760 /* Disable interrupts */
761 __HAL_TSC_DISABLE_IT(htsc, (TSC_IT_EOA | TSC_IT_MCE));
762
763 /* Clear flags */
764 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
765
766 /* Change TSC state */
767 htsc->State = HAL_TSC_STATE_READY;
768
769 /* Process unlocked */
770 __HAL_UNLOCK(htsc);
771
772 /* Return function status */
773 return HAL_OK;
774 }
775
776 /**
777 * @brief Start acquisition and wait until completion.
778 * @note There is no need of a timeout parameter as the max count error is already
779 * managed by the TSC peripheral.
780 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
781 * the configuration information for the specified TSC.
782 * @retval HAL state
783 */
HAL_TSC_PollForAcquisition(TSC_HandleTypeDef * htsc)784 HAL_StatusTypeDef HAL_TSC_PollForAcquisition(TSC_HandleTypeDef *htsc)
785 {
786 /* Check the parameters */
787 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
788
789 /* Process locked */
790 __HAL_LOCK(htsc);
791
792 /* Check end of acquisition */
793 while (HAL_TSC_GetState(htsc) == HAL_TSC_STATE_BUSY)
794 {
795 /* The timeout (max count error) is managed by the TSC peripheral itself. */
796 }
797
798 /* Process unlocked */
799 __HAL_UNLOCK(htsc);
800
801 return HAL_OK;
802 }
803
804 /**
805 * @brief Get the acquisition status for a group.
806 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
807 * the configuration information for the specified TSC.
808 * @param gx_index Index of the group
809 * @retval Group status
810 */
HAL_TSC_GroupGetStatus(const TSC_HandleTypeDef * htsc,uint32_t gx_index)811 TSC_GroupStatusTypeDef HAL_TSC_GroupGetStatus(const TSC_HandleTypeDef *htsc, uint32_t gx_index)
812 {
813 /* Check the parameters */
814 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
815 assert_param(IS_TSC_GROUP_INDEX(gx_index));
816
817 /* Return the group status */
818 return (__HAL_TSC_GET_GROUP_STATUS(htsc, gx_index));
819 }
820
821 /**
822 * @brief Get the acquisition measure for a group.
823 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
824 * the configuration information for the specified TSC.
825 * @param gx_index Index of the group
826 * @retval Acquisition measure
827 */
HAL_TSC_GroupGetValue(const TSC_HandleTypeDef * htsc,uint32_t gx_index)828 uint32_t HAL_TSC_GroupGetValue(const TSC_HandleTypeDef *htsc, uint32_t gx_index)
829 {
830 /* Check the parameters */
831 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
832 assert_param(IS_TSC_GROUP_INDEX(gx_index));
833
834 /* Return the group acquisition counter */
835 return htsc->Instance->IOGXCR[gx_index];
836 }
837
838 /**
839 * @}
840 */
841
842 /** @defgroup TSC_Exported_Functions_Group3 Peripheral Control functions
843 * @brief Peripheral Control functions
844 *
845 @verbatim
846 ===============================================================================
847 ##### Peripheral Control functions #####
848 ===============================================================================
849 [..] This section provides functions allowing to:
850 (+) Configure TSC IOs
851 (+) Discharge TSC IOs
852 @endverbatim
853 * @{
854 */
855
856 /**
857 * @brief Configure TSC IOs.
858 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
859 * the configuration information for the specified TSC.
860 * @param config Pointer to the configuration structure.
861 * @retval HAL status
862 */
HAL_TSC_IOConfig(TSC_HandleTypeDef * htsc,const TSC_IOConfigTypeDef * config)863 HAL_StatusTypeDef HAL_TSC_IOConfig(TSC_HandleTypeDef *htsc, const TSC_IOConfigTypeDef *config)
864 {
865 /* Check the parameters */
866 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
867 assert_param(IS_TSC_GROUP(config->ChannelIOs));
868 assert_param(IS_TSC_GROUP(config->ShieldIOs));
869 assert_param(IS_TSC_GROUP(config->SamplingIOs));
870
871 /* Process locked */
872 __HAL_LOCK(htsc);
873
874 /* Stop acquisition */
875 __HAL_TSC_STOP_ACQ(htsc);
876
877 /* Disable Schmitt trigger hysteresis on all used TSC IOs */
878 htsc->Instance->IOHCR = (~(config->ChannelIOs | config->ShieldIOs | config->SamplingIOs));
879
880 /* Set channel and shield IOs */
881 htsc->Instance->IOCCR = (config->ChannelIOs | config->ShieldIOs);
882
883 /* Set sampling IOs */
884 htsc->Instance->IOSCR = config->SamplingIOs;
885
886 /* Set groups to be acquired */
887 htsc->Instance->IOGCSR = TSC_extract_groups(config->ChannelIOs);
888
889 /* Process unlocked */
890 __HAL_UNLOCK(htsc);
891
892 /* Return function status */
893 return HAL_OK;
894 }
895
896 /**
897 * @brief Discharge TSC IOs.
898 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
899 * the configuration information for the specified TSC.
900 * @param choice This parameter can be set to ENABLE or DISABLE.
901 * @retval HAL status
902 */
HAL_TSC_IODischarge(TSC_HandleTypeDef * htsc,FunctionalState choice)903 HAL_StatusTypeDef HAL_TSC_IODischarge(TSC_HandleTypeDef *htsc, FunctionalState choice)
904 {
905 /* Check the parameters */
906 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
907
908 /* Process locked */
909 __HAL_LOCK(htsc);
910
911 if (choice == ENABLE)
912 {
913 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
914 }
915 else
916 {
917 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
918 }
919
920 /* Process unlocked */
921 __HAL_UNLOCK(htsc);
922
923 /* Return the group acquisition counter */
924 return HAL_OK;
925 }
926
927 /**
928 * @}
929 */
930
931 /** @defgroup TSC_Exported_Functions_Group4 Peripheral State and Errors functions
932 * @brief Peripheral State and Errors functions
933 *
934 @verbatim
935 ===============================================================================
936 ##### State and Errors functions #####
937 ===============================================================================
938 [..]
939 This subsection provides functions allowing to
940 (+) Get TSC state.
941
942 @endverbatim
943 * @{
944 */
945
946 /**
947 * @brief Return the TSC handle state.
948 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
949 * the configuration information for the specified TSC.
950 * @retval HAL state
951 */
HAL_TSC_GetState(TSC_HandleTypeDef * htsc)952 HAL_TSC_StateTypeDef HAL_TSC_GetState(TSC_HandleTypeDef *htsc)
953 {
954 /* Check the parameters */
955 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
956
957 if (htsc->State == HAL_TSC_STATE_BUSY)
958 {
959 /* Check end of acquisition flag */
960 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_EOA) != RESET)
961 {
962 /* Check max count error flag */
963 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_MCE) != RESET)
964 {
965 /* Change TSC state */
966 htsc->State = HAL_TSC_STATE_ERROR;
967 }
968 else
969 {
970 /* Change TSC state */
971 htsc->State = HAL_TSC_STATE_READY;
972 }
973 }
974 }
975
976 /* Return TSC state */
977 return htsc->State;
978 }
979
980 /**
981 * @}
982 */
983
984 /** @defgroup TSC_IRQ_Handler_and_Callbacks IRQ Handler and Callbacks
985 * @{
986 */
987
988 /**
989 * @brief Handle TSC interrupt request.
990 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
991 * the configuration information for the specified TSC.
992 * @retval None
993 */
HAL_TSC_IRQHandler(TSC_HandleTypeDef * htsc)994 void HAL_TSC_IRQHandler(TSC_HandleTypeDef *htsc)
995 {
996 /* Check the parameters */
997 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
998
999 /* Check if the end of acquisition occurred */
1000 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_EOA) != RESET)
1001 {
1002 /* Clear EOA flag */
1003 __HAL_TSC_CLEAR_FLAG(htsc, TSC_FLAG_EOA);
1004 }
1005
1006 /* Check if max count error occurred */
1007 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_MCE) != RESET)
1008 {
1009 /* Clear MCE flag */
1010 __HAL_TSC_CLEAR_FLAG(htsc, TSC_FLAG_MCE);
1011 /* Change TSC state */
1012 htsc->State = HAL_TSC_STATE_ERROR;
1013 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
1014 htsc->ErrorCallback(htsc);
1015 #else
1016 /* Conversion completed callback */
1017 HAL_TSC_ErrorCallback(htsc);
1018 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
1019 }
1020 else
1021 {
1022 /* Change TSC state */
1023 htsc->State = HAL_TSC_STATE_READY;
1024 #if (USE_HAL_TSC_REGISTER_CALLBACKS == 1)
1025 htsc->ConvCpltCallback(htsc);
1026 #else
1027 /* Conversion completed callback */
1028 HAL_TSC_ConvCpltCallback(htsc);
1029 #endif /* USE_HAL_TSC_REGISTER_CALLBACKS */
1030 }
1031 }
1032
1033 /**
1034 * @brief Acquisition completed callback in non-blocking mode.
1035 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
1036 * the configuration information for the specified TSC.
1037 * @retval None
1038 */
HAL_TSC_ConvCpltCallback(TSC_HandleTypeDef * htsc)1039 __weak void HAL_TSC_ConvCpltCallback(TSC_HandleTypeDef *htsc)
1040 {
1041 /* Prevent unused argument(s) compilation warning */
1042 UNUSED(htsc);
1043
1044 /* NOTE : This function should not be modified, when the callback is needed,
1045 the HAL_TSC_ConvCpltCallback could be implemented in the user file.
1046 */
1047 }
1048
1049 /**
1050 * @brief Error callback in non-blocking mode.
1051 * @param htsc Pointer to a TSC_HandleTypeDef structure that contains
1052 * the configuration information for the specified TSC.
1053 * @retval None
1054 */
HAL_TSC_ErrorCallback(TSC_HandleTypeDef * htsc)1055 __weak void HAL_TSC_ErrorCallback(TSC_HandleTypeDef *htsc)
1056 {
1057 /* Prevent unused argument(s) compilation warning */
1058 UNUSED(htsc);
1059
1060 /* NOTE : This function should not be modified, when the callback is needed,
1061 the HAL_TSC_ErrorCallback could be implemented in the user file.
1062 */
1063 }
1064
1065 /**
1066 * @}
1067 */
1068
1069 /**
1070 * @}
1071 */
1072
1073 /* Private functions ---------------------------------------------------------*/
1074 /** @defgroup TSC_Private_Functions TSC Private Functions
1075 * @{
1076 */
1077
1078 /**
1079 * @brief Utility function used to set the acquired groups mask.
1080 * @param iomask Channels IOs mask
1081 * @retval Acquired groups mask
1082 */
TSC_extract_groups(uint32_t iomask)1083 static uint32_t TSC_extract_groups(uint32_t iomask)
1084 {
1085 uint32_t groups = 0UL;
1086 uint32_t idx;
1087
1088 for (idx = 0UL; idx < (uint32_t)TSC_NB_OF_GROUPS; idx++)
1089 {
1090 if ((iomask & (0x0FUL << (idx * 4UL))) != 0UL)
1091 {
1092 groups |= (1UL << idx);
1093 }
1094 }
1095
1096 return groups;
1097 }
1098
1099 /**
1100 * @}
1101 */
1102
1103 #endif /* HAL_TSC_MODULE_ENABLED */
1104
1105 /**
1106 * @}
1107 */
1108
1109 /**
1110 * @}
1111 */
1112
1113
