2 ******************************************************************************
3 * @file stm32l0xx_hal_tsc.c
4 * @author MCD Application Team
6 * @date 06-February-2015
7 * @brief This file provides firmware functions to manage the following
8 * functionalities of the Touch Sensing Controller (TSC) peripheral:
9 * + Initialization and DeInitialization
10 * + Channel IOs, Shield IOs and Sampling IOs configuration
11 * + Start and Stop an acquisition
12 * + Read acquisition result
13 * + Interrupts and flags management
16 ================================================================================
17 ##### TSC specific features #####
18 ================================================================================
20 (#) Proven and robust surface charge transfer acquisition principle
22 (#) Supports up to 3 capacitive sensing channels per group
24 (#) Capacitive sensing channels can be acquired in parallel offering a very good
27 (#) Spread spectrum feature to improve system robustness in noisy environments
29 (#) Full hardware management of the charge transfer acquisition sequence
31 (#) Programmable charge transfer frequency
33 (#) Programmable sampling capacitor I/O pin
35 (#) Programmable channel I/O pin
37 (#) Programmable max count value to avoid long acquisition when a channel is faulty
39 (#) Dedicated end of acquisition and max count error flags with interrupt capability
41 (#) One sampling capacitor for up to 3 capacitive sensing channels to reduce the system
44 (#) Compatible with proximity, touchkey, linear and rotary touch sensor implementation
47 ##### How to use this driver #####
48 ================================================================================
50 (#) Enable the TSC interface clock using __HAL_RCC_TSC_CLK_ENABLE() macro.
52 (#) GPIO pins configuration
53 (++) Enable the clock for the TSC GPIOs using __HAL_RCC_GPIOx_CLK_ENABLE() macro.
54 (++) Configure the TSC pins used as sampling IOs in alternate function output Open-Drain mode,
55 and TSC pins used as channel/shield IOs in alternate function output Push-Pull mode
56 using HAL_GPIO_Init() function.
57 (++) Configure the alternate function on all the TSC pins using HAL_xxxx() function.
59 (#) Interrupts configuration
60 (++) Configure the NVIC (if the interrupt model is used) using HAL_xxx() function.
63 (++) Configure all TSC parameters and used TSC IOs using HAL_TSC_Init() function.
65 *** Acquisition sequence ***
66 ===================================
68 (+) Discharge all IOs using HAL_TSC_IODischarge() function.
69 (+) Wait a certain time allowing a good discharge of all capacitors. This delay depends
70 of the sampling capacitor and electrodes design.
71 (+) Select the channel IOs to be acquired using HAL_TSC_IOConfig() function.
72 (+) Launch the acquisition using either HAL_TSC_Start() or HAL_TSC_Start_IT() function.
73 If the synchronized mode is selected, the acquisition will start as soon as the signal
74 is received on the synchro pin.
75 (+) Wait the end of acquisition using either HAL_TSC_PollForAcquisition() or
76 HAL_TSC_GetState() function or using WFI instruction for example.
77 (+) Check the group acquisition status using HAL_TSC_GroupGetStatus() function.
78 (+) Read the acquisition value using HAL_TSC_GroupGetValue() function.
81 ******************************************************************************
84 * <h2><center>© COPYRIGHT(c) 2015 STMicroelectronics</center></h2>
86 * Redistribution and use in source and binary forms, with or without modification,
87 * are permitted provided that the following conditions are met:
88 * 1. Redistributions of source code must retain the above copyright notice,
89 * this list of conditions and the following disclaimer.
90 * 2. Redistributions in binary form must reproduce the above copyright notice,
91 * this list of conditions and the following disclaimer in the documentation
92 * and/or other materials provided with the distribution.
93 * 3. Neither the name of STMicroelectronics nor the names of its contributors
94 * may be used to endorse or promote products derived from this software
95 * without specific prior written permission.
97 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
98 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
99 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
100 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
101 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
102 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
103 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
104 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
105 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
106 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
108 ******************************************************************************
111 /* Includes ------------------------------------------------------------------*/
112 #if !defined (STM32L031xx) && !defined (STM32L041xx) && !defined (STM32L051xx) && !defined (STM32L061xx) && !defined (STM32L071xx) && !defined (STM32L081xx)
113 #include "stm32l0xx_hal.h"
115 #ifdef HAL_TSC_MODULE_ENABLED
116 /** @addtogroup STM32L0xx_HAL_Driver
121 * @brief HAL TSC module driver
126 /* Private typedef -----------------------------------------------------------*/
127 /* Private define ------------------------------------------------------------*/
128 /* Private macro -------------------------------------------------------------*/
129 /* Private variables ---------------------------------------------------------*/
130 /* Private function prototypes -----------------------------------------------*/
131 static uint32_t TSC_extract_groups(uint32_t iomask);
132 /* Private functions ---------------------------------------------------------*/
134 /** @defgroup TSC_Private_Functions
138 /** @defgroup TSC_Group1 Initialization/de-initialization functions
139 * @brief Initialization and Configuration functions
142 ===============================================================================
143 ##### Initialization and de-initialization functions #####
144 ===============================================================================
145 [..] This section provides functions allowing to:
146 (+) Initialize and configure the TSC.
147 (+) De-initialize the TSC.
153 * @brief Initializes the TSC peripheral according to the specified parameters
154 * in the TSC_InitTypeDef structure.
155 * @param htsc: TSC handle
158 HAL_StatusTypeDef HAL_TSC_Init(TSC_HandleTypeDef* htsc)
160 /* Check TSC handle allocation */
166 /* Check the parameters */
167 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
168 assert_param(IS_TSC_CTPH(htsc->Init.CTPulseHighLength));
169 assert_param(IS_TSC_CTPL(htsc->Init.CTPulseLowLength));
170 assert_param(IS_TSC_SS(htsc->Init.SpreadSpectrum));
171 assert_param(IS_TSC_SSD(htsc->Init.SpreadSpectrumDeviation));
172 assert_param(IS_TSC_SS_PRESC(htsc->Init.SpreadSpectrumPrescaler));
173 assert_param(IS_TSC_PG_PRESC(htsc->Init.PulseGeneratorPrescaler));
174 assert_param(IS_TSC_MCV(htsc->Init.MaxCountValue));
175 assert_param(IS_TSC_IODEF(htsc->Init.IODefaultMode));
176 assert_param(IS_TSC_SYNC_POL(htsc->Init.SynchroPinPolarity));
177 assert_param(IS_TSC_ACQ_MODE(htsc->Init.AcquisitionMode));
178 assert_param(IS_TSC_MCE_IT(htsc->Init.MaxCountInterrupt));
180 /* Initialize the TSC state */
181 htsc->State = HAL_TSC_STATE_BUSY;
183 /* Init the low level hardware : GPIO, CLOCK, CORTEX */
184 HAL_TSC_MspInit(htsc);
186 /*--------------------------------------------------------------------------*/
187 /* Set TSC parameters */
190 htsc->Instance->CR = TSC_CR_TSCE;
192 /* Set all functions */
193 htsc->Instance->CR |= (htsc->Init.CTPulseHighLength |
194 htsc->Init.CTPulseLowLength |
195 (uint32_t)(htsc->Init.SpreadSpectrumDeviation << 17) |
196 htsc->Init.SpreadSpectrumPrescaler |
197 htsc->Init.PulseGeneratorPrescaler |
198 htsc->Init.MaxCountValue |
199 htsc->Init.IODefaultMode |
200 htsc->Init.SynchroPinPolarity |
201 htsc->Init.AcquisitionMode);
203 /* Spread spectrum */
204 if (htsc->Init.SpreadSpectrum == ENABLE)
206 htsc->Instance->CR |= TSC_CR_SSE;
209 /* Disable Schmitt trigger hysteresis on all used TSC IOs */
210 htsc->Instance->IOHCR = (uint32_t)(~(htsc->Init.ChannelIOs | htsc->Init.ShieldIOs | htsc->Init.SamplingIOs));
212 /* Set channel and shield IOs */
213 htsc->Instance->IOCCR = (htsc->Init.ChannelIOs | htsc->Init.ShieldIOs);
215 /* Set sampling IOs */
216 htsc->Instance->IOSCR = htsc->Init.SamplingIOs;
218 /* Set the groups to be acquired */
219 htsc->Instance->IOGCSR = TSC_extract_groups(htsc->Init.ChannelIOs);
221 /* Clear interrupts */
222 htsc->Instance->IER &= (uint32_t)(~(TSC_IT_EOA | TSC_IT_MCE));
225 htsc->Instance->ICR |= (TSC_FLAG_EOA | TSC_FLAG_MCE);
227 /*--------------------------------------------------------------------------*/
229 /* Initialize the TSC state */
230 htsc->State = HAL_TSC_STATE_READY;
232 /* Return function status */
237 * @brief Deinitializes the TSC peripheral registers to their default reset values.
238 * @param htsc: TSC handle
241 HAL_StatusTypeDef HAL_TSC_DeInit(TSC_HandleTypeDef* htsc)
243 /* Check TSC handle allocation */
249 /* Check the parameters */
250 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
252 /* Change TSC state */
253 htsc->State = HAL_TSC_STATE_BUSY;
255 /* DeInit the low level hardware */
256 HAL_TSC_MspDeInit(htsc);
258 /* Change TSC state */
259 htsc->State = HAL_TSC_STATE_RESET;
261 /* Process unlocked */
264 /* Return function status */
269 * @brief Initializes the TSC MSP.
270 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
271 * the configuration information for the specified TSC.
274 __weak void HAL_TSC_MspInit(TSC_HandleTypeDef* htsc)
276 /* NOTE : This function should not be modified, when the callback is needed,
277 the HAL_TSC_MspInit could be implemented in the user file.
282 * @brief DeInitializes the TSC MSP.
283 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
284 * the configuration information for the specified TSC.
287 __weak void HAL_TSC_MspDeInit(TSC_HandleTypeDef* htsc)
289 /* NOTE : This function should not be modified, when the callback is needed,
290 the HAL_TSC_MspDeInit could be implemented in the user file.
298 /** @defgroup HAL_TSC_Group2 IO operation functions
299 * @brief IO operation functions
302 ===============================================================================
303 ##### I/O Operation functions #####
304 ===============================================================================
305 [..] This section provides functions allowing to:
306 (+) Start acquisition in polling mode.
307 (+) Start acquisition in interrupt mode.
308 (+) Stop conversion in polling mode.
309 (+) Stop conversion in interrupt mode.
310 (+) Get group acquisition status.
311 (+) Get group acquisition value.
317 * @brief Starts the acquisition.
318 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
319 * the configuration information for the specified TSC.
322 HAL_StatusTypeDef HAL_TSC_Start(TSC_HandleTypeDef* htsc)
324 /* Check the parameters */
325 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
330 /* Change TSC state */
331 htsc->State = HAL_TSC_STATE_BUSY;
333 /* Clear interrupts */
334 __HAL_TSC_DISABLE_IT(htsc, (TSC_IT_EOA | TSC_IT_MCE));
337 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
339 /* Stop discharging the IOs */
340 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
342 /* Launch the acquisition */
343 __HAL_TSC_START_ACQ(htsc);
345 /* Process unlocked */
348 /* Return function status */
353 * @brief Enables the interrupt and starts the acquisition
354 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
355 * the configuration information for the specified TSC.
356 * @retval HAL status.
358 HAL_StatusTypeDef HAL_TSC_Start_IT(TSC_HandleTypeDef* htsc)
360 /* Check the parameters */
361 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
362 assert_param(IS_TSC_MCE_IT(htsc->Init.MaxCountInterrupt));
367 /* Change TSC state */
368 htsc->State = HAL_TSC_STATE_BUSY;
370 /* Enable end of acquisition interrupt */
371 __HAL_TSC_ENABLE_IT(htsc, TSC_IT_EOA);
373 /* Enable max count error interrupt (optional) */
374 if (htsc->Init.MaxCountInterrupt == ENABLE)
376 __HAL_TSC_ENABLE_IT(htsc, TSC_IT_MCE);
380 __HAL_TSC_DISABLE_IT(htsc, TSC_IT_MCE);
384 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
386 /* Stop discharging the IOs */
387 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
389 /* Launch the acquisition */
390 __HAL_TSC_START_ACQ(htsc);
392 /* Process unlocked */
395 /* Return function status */
400 * @brief Stops the acquisition previously launched in polling mode
401 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
402 * the configuration information for the specified TSC.
405 HAL_StatusTypeDef HAL_TSC_Stop(TSC_HandleTypeDef* htsc)
407 /* Check the parameters */
408 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
413 /* Stop the acquisition */
414 __HAL_TSC_STOP_ACQ(htsc);
417 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
419 /* Change TSC state */
420 htsc->State = HAL_TSC_STATE_READY;
422 /* Process unlocked */
425 /* Return function status */
430 * @brief Stops the acquisition previously launched in interrupt mode
431 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
432 * the configuration information for the specified TSC.
435 HAL_StatusTypeDef HAL_TSC_Stop_IT(TSC_HandleTypeDef* htsc)
437 /* Check the parameters */
438 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
443 /* Stop the acquisition */
444 __HAL_TSC_STOP_ACQ(htsc);
446 /* Disable interrupts */
447 __HAL_TSC_DISABLE_IT(htsc, (TSC_IT_EOA | TSC_IT_MCE));
450 __HAL_TSC_CLEAR_FLAG(htsc, (TSC_FLAG_EOA | TSC_FLAG_MCE));
452 /* Change TSC state */
453 htsc->State = HAL_TSC_STATE_READY;
455 /* Process unlocked */
458 /* Return function status */
463 * @brief Gets the acquisition status for a group
464 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
465 * the configuration information for the specified TSC.
466 * @param gx_index: Index of the group
467 * @retval Group status
469 TSC_GroupStatusTypeDef HAL_TSC_GroupGetStatus(TSC_HandleTypeDef* htsc, uint32_t gx_index)
471 /* Check the parameters */
472 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
473 assert_param(IS_GROUP_INDEX(gx_index));
475 /* Return the group status */
476 return(__HAL_TSC_GET_GROUP_STATUS(htsc, gx_index));
480 * @brief Gets the acquisition measure for a group
481 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
482 * the configuration information for the specified TSC.
483 * @param gx_index: Index of the group
484 * @retval Acquisition measure
486 uint32_t HAL_TSC_GroupGetValue(TSC_HandleTypeDef* htsc, uint32_t gx_index)
488 /* Check the parameters */
489 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
490 assert_param(IS_GROUP_INDEX(gx_index));
492 /* Return the group acquisition counter */
493 return htsc->Instance->IOGXCR[gx_index];
500 /** @defgroup HAL_TSC_Group3 Peripheral Control functions
501 * @brief Peripheral Control functions
504 ===============================================================================
505 ##### Peripheral Control functions #####
506 ===============================================================================
507 [..] This section provides functions allowing to:
508 (+) Configure TSC IOs
509 (+) Discharge TSC IOs
515 * @brief Configures TSC IOs
516 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
517 * the configuration information for the specified TSC.
518 * @param config: pointer to the configuration structure.
521 HAL_StatusTypeDef HAL_TSC_IOConfig(TSC_HandleTypeDef* htsc, TSC_IOConfigTypeDef* config)
523 /* Check the parameters */
524 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
529 /* Stop acquisition */
530 __HAL_TSC_STOP_ACQ(htsc);
532 /* Disable Schmitt trigger hysteresis on all used TSC IOs */
533 htsc->Instance->IOHCR = (uint32_t)(~(config->ChannelIOs | config->ShieldIOs | config->SamplingIOs));
535 /* Set channel and shield IOs */
536 htsc->Instance->IOCCR = (config->ChannelIOs | config->ShieldIOs);
538 /* Set sampling IOs */
539 htsc->Instance->IOSCR = config->SamplingIOs;
541 /* Set groups to be acquired */
542 htsc->Instance->IOGCSR = TSC_extract_groups(config->ChannelIOs);
544 /* Process unlocked */
547 /* Return function status */
552 * @brief Discharge TSC IOs
553 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
554 * the configuration information for the specified TSC.
555 * @param choice: enable or disable
558 HAL_StatusTypeDef HAL_TSC_IODischarge(TSC_HandleTypeDef* htsc, uint32_t choice)
560 /* Check the parameters */
561 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
566 if (choice == ENABLE)
568 __HAL_TSC_SET_IODEF_OUTPPLOW(htsc);
572 __HAL_TSC_SET_IODEF_INFLOAT(htsc);
575 /* Process unlocked */
578 /* Return the group acquisition counter */
586 /** @defgroup HAL_TSC_Group4 State functions
587 * @brief State functions
590 ===============================================================================
591 ##### State functions #####
592 ===============================================================================
594 This subsection provides functions allowing to
596 (+) Poll for acquisition completed.
597 (+) Handles TSC interrupt request.
604 * @brief Return the TSC state
605 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
606 * the configuration information for the specified TSC.
609 HAL_TSC_StateTypeDef HAL_TSC_GetState(TSC_HandleTypeDef* htsc)
611 /* Check the parameters */
612 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
614 if (htsc->State == HAL_TSC_STATE_BUSY)
616 /* Check end of acquisition flag */
617 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_EOA) != RESET)
619 /* Check max count error flag */
620 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_MCE) != RESET)
622 /* Change TSC state */
623 htsc->State = HAL_TSC_STATE_ERROR;
627 /* Change TSC state */
628 htsc->State = HAL_TSC_STATE_READY;
633 /* Return TSC state */
638 * @brief Start acquisition and wait until completion
639 * @note There is no need of a timeout parameter as the max count error is already
640 * managed by the TSC peripheral.
641 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
642 * the configuration information for the specified TSC.
645 HAL_StatusTypeDef HAL_TSC_PollForAcquisition(TSC_HandleTypeDef* htsc)
647 /* Check the parameters */
648 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
653 /* Check end of acquisition */
654 while (HAL_TSC_GetState(htsc) == HAL_TSC_STATE_BUSY)
656 /* The timeout (max count error) is managed by the TSC peripheral itself. */
659 /* Process unlocked */
666 * @brief Handles TSC interrupt request
667 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
668 * the configuration information for the specified TSC.
671 void HAL_TSC_IRQHandler(TSC_HandleTypeDef* htsc)
673 /* Check the parameters */
674 assert_param(IS_TSC_ALL_INSTANCE(htsc->Instance));
676 /* Check if the end of acquisition occured */
677 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_EOA) != RESET)
680 __HAL_TSC_CLEAR_FLAG(htsc, TSC_FLAG_EOA);
683 /* Check if max count error occured */
684 if (__HAL_TSC_GET_FLAG(htsc, TSC_FLAG_MCE) != RESET)
687 __HAL_TSC_CLEAR_FLAG(htsc, TSC_FLAG_MCE);
688 /* Change TSC state */
689 htsc->State = HAL_TSC_STATE_ERROR;
690 /* Conversion completed callback */
691 HAL_TSC_ErrorCallback(htsc);
695 /* Change TSC state */
696 htsc->State = HAL_TSC_STATE_READY;
697 /* Conversion completed callback */
698 HAL_TSC_ConvCpltCallback(htsc);
707 * @brief Acquisition completed callback in non blocking mode
708 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
709 * the configuration information for the specified TSC.
712 __weak void HAL_TSC_ConvCpltCallback(TSC_HandleTypeDef* htsc)
714 /* NOTE : This function should not be modified, when the callback is needed,
715 the HAL_TSC_ConvCpltCallback could be implemented in the user file.
720 * @brief Error callback in non blocking mode
721 * @param htsc: pointer to a TSC_HandleTypeDef structure that contains
722 * the configuration information for the specified TSC.
725 __weak void HAL_TSC_ErrorCallback(TSC_HandleTypeDef* htsc)
727 /* NOTE : This function should not be modified, when the callback is needed,
728 the HAL_TSC_ErrorCallback could be implemented in the user file.
733 * @brief Utility function used to set the acquired groups mask
734 * @param iomask: Channels IOs mask
735 * @retval Acquired groups mask
737 static uint32_t TSC_extract_groups(uint32_t iomask)
742 for (idx = 0; idx < TSC_NB_OF_GROUPS; idx++)
744 if ((iomask & ((uint32_t)0x0F << (idx * 4))) != RESET)
746 groups |= ((uint32_t)1 << idx);
765 #endif /* HAL_TSC_MODULE_ENABLED */
766 #endif /* #if !defined (STM32L031xx) && !defined (STM32L041xx) && !defined (STM32L051xx) && !defined (STM32L061xx) && !defined (STM32L071xx) && !defined (STM32L081xx) */
768 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/