Holtek HT32 MCU Touch Key Library User Guide
- June 2, 2024
- HOLTEK
Table of Contents
Holtek HT32 MCU Touch Key Library
Introduction
The HT32 touch key library developed by Best Solution is a library that integrates into the MCU all of the touch key underlying driver library files. The library has pre-configured the touch-related MCU hardware, and provides intuitive and flexible touch key sensitivity settings, while integrating common functions such as key detection and power-saving sleep modes. Using the HT32 touch key library simplifies the use of the MCU touch functions, allowing users to get started quickly and reducing the development period. This document will describe in detail the environmental configuration and library usage.
Environmental Configuration
Obtain HT32 Touch Key Library
Contact Best Solution’s FAE or refer to its website:
http://www.bestsolution.com.tw/EN/
Or download the library from the Holtek website: https://www.holtek.com
Obtain HT32 Firmware Library
Refer to the following link to quickly obtain the firmware library:
https://www.holtek.com/productdetail/-/vg/HT32F54231_41_43_53
Open the link, select the Documents option as shown in Figure 1, where the red
box indicates the location of the HT32 compressed files. Note that only the
firmware library of version v022 or above supports the HT32 touch key library
.
Keil Project Configuration
- The user’s PC needs to have the Keil development tool installed.
- Unzip the firmware library. The files are listed as shown in Figure 2. Click on Holtek.HT32_DFP.latest to install it, after which the installation completion screen, as shown in Figure 3, will appear.
- Unzip the HT32 touch key library which includes two folders, example and library.
- Copy the example and library folders to the HT32_STD_xxxxx_FWLib_v022_XXXX folder.
- Execute ..\example\TouchKey\TouchKey_LIB\_CreateProject.bat (Figure 6).
- An interface, as shown in Figure 7, will appear. Input the number corresponding to the user’s IDE, after which a “*” sign will appear before the selected IDE, as shown in Figure 8. Input “N” to go to next step.
- As shown below, input “*” to create projects for all IC types or input the IC name to create a project for the selected IC.
- After finishing steps 1~7, as shown in Figure 11, select the desired IC project such as Project_54xxx.uvprojx from the ..\example\TouchKey\TouchKey_LIB\MDK_ARMv5\ path.
Note that only the MCU with the largest resources in each series is used to create the project. For example, to use the HT32F54231 users must select the HT32F54241 project.
Considerations
As the touch key program may enter the sleep state, it is required to set the
project to power on reset, otherwise it will not be available for programming.
The setting steps are as follows.
- Step 1: Click the button in the Keil5 tool menu, as shown below.
- Step 2: Select Debug–> Settings.
- Step 3: Select “under Reset” in the Connect field.
Library Files Description
Library Used Resources
Keil Project| Usable IC| ROM/RAM Resources| Used IP|
Max. Number of Keys
---|---|---|---|---
HT32F54241| HT32F54241 HT32F54231| 7148B / 2256B| Touch key
BFTM0 RTC
| 24
HT32F54253| HT32F54243 HT32F54253| **** 7140B / 2528B| Touch key BFTM0
RTC
| **** 28
- The RTC is used to wake up MCU from the sleep state and used as time base for sleep state processing.
- When the program is loaded into the IC, the Keil will determine whether the ROM or RAM size has been exceeded.
- For the specific use of resources, refer to the actual library version.
Environment and File Description
The HT32 touch key library is located in the following path.
..\example\TouchKey\TouchKey_LIB\MDK_ARMv5\Project_542xx.uvprojx project
(Figure15). After the HT32 touch key library project is opened, the main
screen is shown as Figure 16.
The relevant files are described as follows, among which are the ht32_TouchKey_conf.h and system_ht32f5xxxx_09.c files, included in the Configuration Wizard. See Figure 17.
| File Name | Description |
|---|---|
| main.c | Project main program file |
| ht32f5xxxx_01_it.c | Interrupt main program file |
| ht32_TouchKey_Lib_Mx_Keil.lib | Touch control library file |
| *ht32_TouchKey_conf.h | Touch control parameter file |
| ht32_TouchKey.h | External declaration definition file |
| ht32_TouchKey_BSconf.h | Underlying main parameter file (not recommended to |
modify)
ht32_board_config.h| Hardware definition file (not recommended to modify)
*system_ht32f5xxxx_09.c| Clock source and system clock parameter file
Configuration Wizard Parameters
- ht32_TouchKey_conf.h Configuration Wizard parameters:
Name| Function
---|---
PowerSave| Activate the default sleep procedure defined in main.c
TKL_HighSensitive| Touch sensitivity setting: high or low sensitivity; default to high sensitivity after being enabled
TKL_keyDebounce| Key debounce time setting
TKL_RefCalTime| Calibration time. The shorter the time, the more effective it will be in resisting environmental interference, however it will result in lower key sensitivities.
TKL_MaxOnHoldTime| The maximum time that the key is pressed. The key is automatically released after being pressed for n seconds.
KEYn_EN| Enable or disable KEYn
KeynThreshold| KEYn threshold value. The smaller the value, the more sensitive the key will be. - system_ht32f5xxxx_09.c Configuration Wizard parameters:
Name| Function
---|---
Enable High Speed External Crystal Oscillator – HSE| Enable or disable HSE (external high speed oscillator)
Enable Low Speed External Crystal Oscillator – LSE| Enable or disable LSE (external low speed oscillator)
Enable PLL| Enable or disable PLL
PLL Clock Source| Select clock source for PLL
SystemCoreClockConfiguration (CK_AHB)| Select clock source for system CK_AHB
Description of Touch Key Lib Interface Functions
Description of Get Functions
| Item | Description |
|---|---|
| Function Name | TKL_Get_Standby |
| Input Parameter | — |
| Return Value | Counting value (500~60000) |
| Description | Used to obtain the count-down counter value |
| Item | Description |
|---|---|
| Function Name | TKL_Get_KeyRCCValue |
| Input Parameter | Key value (0 ~ max. key value), frequency (0, 1) |
| Return Value | Capacitance value (0~1023) |
| Description | Used to obtain the capacitance value of the specified key |
| Item | Description |
|---|---|
| Function Name | TKL_GetKeyRef |
| Input Parameter | Key value (0 ~ max. key value) |
| Return Value | Reference value (0~65535) |
| Description | Used to obtain the reference value of the specified key |
| Item | Description |
|---|---|
| Function Name | TKL_GetKeyThreshold |
| Input Parameter | Key value (0 ~ max. key value) |
| Return Value | Threshold value (0~255) |
| Description | Used to obtain the threshold value of the specified key |
| Item | Description |
|---|---|
| Function Name | TKL_Get_AllKeyState |
| Input Parameter | — |
| **** Return Value | Key state (32-bit) |
BITn stands for KEYn state
Bit0 = 1 means that KEY0 is pressed, Bit0 = 0 means that KEY0 is not pressed
Description| Used to obtain all key states
Description of Set Functions
| Item | Description |
|---|---|
| Function Name | TKL_Set_KeyThreshold |
| Input Parameter | Key value (0 ~ max. key value), threshold value (10~127) |
| Return Value | — |
| Description | Used to set the threshold value of the specified key |
| Item | Description |
|---|---|
| Function Name | TKL_Set_Standby |
| Input Parameter | Sleep time (500~60000) |
| Return Value | — |
| Description | Used to set the count-down counter (not recommended to use this |
function)
Description of State and Command Functions
| Item | Description |
|---|---|
| Function Name | TKL_Is_Time |
| Input Parameter | Preset constant (kT2mS, kT4mS…kT2048mS) |
| Return Value | — |
| **** Description | Time flag for user reference. |
In the following example, the program enters the function every 2ms.
| Item | Description |
|---|---|
| Function Name | TKL_Is_AnyKeyPress |
| Input Parameter | — |
| Return Value | 1 = one or more key has been triggered; 0 = no key has been |
triggered
Description| Used to obtain the key press flag
| Item | Description |
|---|---|
| Function Name | TKL_Is_KeyPress |
| Input Parameter | Key value (0 ~ max. key value) |
| Return Value | 1 = key has been triggered; 0 = key has not been triggered |
| Description | Used to obtain the state flag of the specified key |
| Item | Description |
|---|---|
| Function Name | TKL_Is_Active |
| Input Parameter | — |
| Return Value | 1 = LIB initialisation has finished; 0 = LIB initialisation has |
not finished
Description| Used to obtain the LIB initialisation state flag
| Item | Description |
|---|---|
| Function Name | TKL_Is_Standby |
| Input Parameter | — |
| Return Value | 1 = allowed to enter sleep state; 0 = not allowed to enter sleep |
state
**** Description| Used to obtain the sleep state flag.
*When a value of 0 is returned, then entering the sleep state may result in an unexpected state.
| Item | Description |
|---|---|
| Function Name | TKL_Is_KeyScanCycle |
| Input Parameter | — |
| Return Value | 1 = scan has finished; 0 = presently scanning |
| Description | Used to obtain the scan flag |
| Item | Description |
|---|---|
| Function Name | TKL_Reset |
| Input Parameter | — |
| Return Value | — |
| **** Description | Used to compel LIB to execute a reset action. |
*Flags used by LIB and RAM will be initialised.
*Parameters and AFIO are excluded.
Description of Touch Key Lib Initialisation Functions
These functions are located in main.c. It is not recommended to modify their contents.
| Name | Function |
|---|---|
| GPIO_Configuration() | I/O port configurations |
| RTC_Configuration() | Touch keys are woken up by the RTC |
| BFTM_Configuration() | Touch key library time bases are implemented by BFTM |
| TKL_Configuration() | Touch key configurations |
Key State Query
As shown below, the main program includes a touch key example which will not
be activated by default. To activate this function, modify (0) after #if to
(1).
Sleep Mode Description
- In ht32_TouchKey_conf.h, select PowerSave to enable the sleep modes.
- After the sleep modes have been enabled, the touch keys will enter the sleep state if the keys have not experienced any touch conditions for a certain period of time.
- A standby time count function is used for down-counting, the current time is obtained using TKL_Get_Standby and the time parameter is set using TKL_Set_Standby.
- There are three sleep mode options.
Mode| Description
---|---
USE_SLEEP_MODE| Enter Sleep Mode
USE_DEEP_SLEEP1_MODE| Enter Deep Sleep1 Mode
USE_DEEP_SLEEP2_MODE| Enter Deep Sleep2 Mode - As shown below, set the required sleep mode using “#define” in the main file.
Conclusion
This document has provided instructions for setting up the entire HT32
touch key development environment, assisting users to get started quickly. In
addition, the resources used by the library, as well as various functions and
parameters, have been explained in detail, allowing for an easier development
process.
Reference Material
For more details, refer to the Holtek website: www.holtek.com or consult the Best Solution website: http://www.bestsolution.com.tw/EN/
Versions and Modification Information:
| Date | Author | Release | Description |
|---|---|---|---|
| 2022.03.16 | 谢东霖、梁德浩 | V1.00 | First version |
Disclaimer
All information, trademarks, logos, graphics, videos, audio clips, links and
other items appearing on this website (‘Information’) are for reference only
and is subject to change at any time without prior notice and at the
discretion of Holtek Semiconductor Inc. and its related companies (hereinafter
‘Holtek’, ‘the company’, ‘us’, ‘we’ or ‘our’). Whilst Holtek endeavors to
ensure the accuracy of the Information on this website, no express or implied
warranty is given by Holtek to the accuracy of the Information. Holtek will
bear no responsibility for any incorrectness or leakage.
Holtek will not be liable for any damages (including but not limited to
computer virus, system problems or data loss) whatsoever arising in using or
in connection with the use of this website by any party. There may be links in
this area, which allow you to visit the websites of other companies. These
websites are not controlled by Holtek. Holtek will bear no responsibility and
no guarantee to whatsoever Information displayed at such sites. Hyperlinks to
other websites are at your own risk.
Limitation of Liability
In no event shall Holtek Limited be liable to any other party for any loss or
damage whatsoever or howsoever caused directly or indirectly in connection
with your access to or use of this website, the content thereon or any goods,
materials or services.
Governing Law
The Disclaimer contained in the website shall be governed by and interpreted
in accordance with the laws of the Republic of China. Users will submit to the
non-exclusive jurisdiction of the Republic of China courts.
Update of Disclaimer
Holtek reserves the right to update the Disclaimer at any time with or without
prior notice, all changes are effective immediately upon posting to the
website.