Holtek HT32 User manual

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 1 / 12 December 2, 2022
HT32 MCU Touch Key Library User’s Guide
D/N: AN0608EN
Introduction
The HT32 touch key library developed by Best Solution is a library that integrates 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 Holtek HT32 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 1 indicates the
location of the HT32 firmware library compressed files and the red box 2 indicates the location of
the touch key library download guide.
Figure 1

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 2 / 12 December 2, 2022
Keil Project Configuration
1. The user’s PC needs to have the Keil development tool installed.
2. Unzip and open the HT32 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.
Figure 2. HT32 Firmware Library File List
Figure 3. HT32 Pack Installation Finished
3. Unzip the HT32 touch key library which includes two folders, example and library.
Figure 4. HT32 Touch Key Library
4. Copy the example and library folders to the HT32_STD_xxxxx_FWLib_Vm.n.r_XXXX folder.
5. Execute ..\example\TouchKey\TouchKey_LIB\_CreateProject.bat (Figure 6).
Figure 5
Figure 6

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 3 / 12 December 2, 2022
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, as shown in Figure 8. Input “N” to go to next step.
Figure 7 Figure 8
7. As shown in Figure 9, input “*” to create projects for all IC types or input the IC name to create
a project for the selected IC.
Figure 9 Figure 10
8. 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.
Figure 11
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.
Figure 12

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 4 / 12 December 2, 2022
Step 2: Select DebugSettings.
Figure 13
Step 3: Select “under Reset” in the Connect field.
Figure 14
IAR EWARM Project Configuration
1. The user’s PC needs to have the IAR EWARM development tool installed.
2. After the IAR EWARM has been installed, it needs to install the HT32 support package for IAR.
This support package includes the microcontroller data libraries, Flash programming algorithms,
and all other files required for HT32 series microcontroller program development.
The following are the installation steps of installing the support package to IAR EWARM.
Step 1: Download the latest version of the HT32 IAR Support Package from the Holtek
website. The file name is "HT32_ IAR_Package_vnnn.exe", where "nnn" stands for version
number. The latest version of the HT32 IAR Support Package can be quickly found by
searching HT32_ IAR_Package in the search bar.
Step 2: Double-click the "HT32_IAR_Package_vnnn.exe" to execute the support package
wizard. When the following interface appears, press the "Finish" button.
Figure 15. HT32 IAR Pack Finished Installing

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 5 / 12 December 2, 2022
3. Unzip and open the Holtek HT32 Firmware Library, the files are listed as shown in Figure 16.
Figure 16. HT32 Firmware Library File List
4. Unzip the touch key library which includes two folders, example and library, as shown below.
Figure 17. Touch Key Library
5. Copy the example and library folders mentioned in the step 4 to the
HT32_STD_5xxxx_FWLib_Vm.n.r_XXXX folder.
6. Execute..\example\TouchKey\TouchKey_LIB\_CreateProject.bat (Figure 19).
Figure 18 Figure 19
7. An interface, as shown in Figure 20, will appear. Input the number corresponding to the user’s
IDE, after which a “*” sign will appear, as shown in Figure 21. Input “N” to go to next step.
Figure 20 Figure 21

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 6 / 12 December 2, 2022
8. As shown in Figure 22, input “*” to create projects for all IC types or input the IC name to create
a project for the selected IC.
Figure 22 Figure 23
9. After finishing steps 1~8, as shown in Figure 24, select the desired IC project such as
Project_54253.eww from the ..\example\TouchKey\TouchKey_LIB\EWARM\ path.
Figure 24
10. After opening the Project_54253.eww, connect to the e-Link32 Pro and click the compile and
emulate buttons (Figure 25) to implement emulation.
Figure 25
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
Note: 1. The RTC is used to wake up MCU from the sleep state and used as time base for sleep
state processing.
2. When the program is loaded into the IC, the Keil will determine whether the ROM or
RAM size has been exceeded.
3. For the specific use of resources, refer to the actual library version.

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 7 / 12 December 2, 2022
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 (Figure 26).
IAR files are in..\example\TouchKey\TouchKey_LIB\E WA R M \Project_54253.eww (Figure 27).
Figure 26 Figure 27
After the HT32 touch key library project is opened by using the Keil tool, the main screen is shown
as Figure 28.
After the HT32 touch key library project is opened by using the IAR tool, the main screen is shown
as Figure 29.
Figure 28 Figure 29
The relevant files are described as follows, among which are the ht32_TouchKey_conf.h and
system_ht32f5xxxx_09.c files, including a Configuration Wizard interface, as shown in Figure 30.
It should be noted that there is no Configuration Wizard interface within the IAR EWARM software.
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

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 8 / 12 December 2, 2022
Figure 30
Configuration Wizard Parameters
It should be noted that there is no Configuration Wizard interface in the IAR tool, and the
Configuration Wizard interface is unique to the KEIL MDK.
1. 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.
2. 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

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 9 / 12 December 2, 2022
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

HT32 MCU Touch Key Library User’s Guide
AN0608EN V1.10 10 / 12 December 2, 2022
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).
Figure 31