Skip to Content

Key Module

Last modified by Microchip on 2026/02/24 14:41

Key Module Typedefs

The TouchKey module in Microchip’s Touch Modular Library provides robust detection and processing for individual capacitive touch buttons (keys). It manages touch state, debounce, thresholding, and Adjacent Key Suppression (AKS).

threshold_t

typedef uint8_t threshold_t;

Description: This is an unsigned 8-bit number setting a sensor detection threshold.

 

sensor_id_t

typedef uint16_t sensor_id_t;

Description: This represents the sensor number type.

 

touch_current_time_t

typedef uint16_t touch_current_time_t;

Description: This represents the current time type.

 

touch_delta_t

typedef int16_t touch_delta_t;

Description: This represents the touch sensor delta value type.

 

touch_acq_status_t

typedef uint16_t touch_acq_status_t;

Description: This represents the status of Touch measurement.

 

QTM_hysteresis_t

typedef enum tag_hysteresis_t {
    HYST_50,
    HYST_25,
    HYST_12_5,
    HYST_6_25,
    MAX_HYST
} QTM_hysteresis_t;

Description: This type represents the hysteresis setting.

 

QTM_aks_group_t

typedef enum tag_aks_group_t {
    NO_AKS_GROUP,
    AKS_GROUP_1,
    AKS_GROUP_2,
    AKS_GROUP_3,
    AKS_GROUP_4,
    AKS_GROUP_5,
    AKS_GROUP_6,
    AKS_GROUP_7,
    MAX_AKS_GROUP
} QTM_aks_group_t;

Description: This type represents the AKS group.

 

recal_threshold_t

typedef enum tag_recal_threshold_t {
    RECAL_100,
    RECAL_50,
    RECAL_25,
    RECAL_12_5,
    RECAL_6_25,
    MAX_RECAL
} recal_threshold_t;

Description: This type represents the recalibration threshold.

 

reburst_mode_t

typedef enum {
    REBURST_NONE,
    REBURST_UNRESOLVED,
    REBURST_ALL
} reburst_mode_t;

Description: This type represents the reburst mode.

0 = none (application calls only)
1 = Unresolved - i.e. sensors in process of calibration / filter in / filter out and AKS groups
2 = All keys

qtm_touch_key_control_t

typedef struct {
    qtm_touch_key_group_data_t (*qtm_touch_key_group_data);
    qtm_touch_key_group_config_t (*qtm_touch_key_group_config);
    qtm_touch_key_data_t (*qtm_touch_key_data);
    qtm_touch_key_config_t (*qtm_touch_key_config);
} qtm_touch_key_control_t;

Description: This structure acts as a container for key module control data.

 

Key Module Data Structures

qtm_touch_key_group_config_t

typedef struct {
   uint16_t num_key_sensors;              /* Number of sensors */
   uint8_t  sensor_touch_di;              /* Count in to Detect */
   uint8_t  sensor_max_on_time;           /* Max on duration x 200ms */
   uint8_t  sensor_anti_touch_di;         /* Count in to Anti-touch recal */
   uint8_t  sensor_anti_touch_recal_thr;  /* Anti-touch recal threshold % */
   uint8_t  sensor_touch_drift_rate;      /* One count per <200> ms */
   uint8_t  sensor_anti_touch_drift_rate; /* One count per <200> ms */
   uint8_t  sensor_drift_hold_time;       /* Drift hold time */
   uint8_t  sensor_reburst_mode;          /* None / Unresolved / All */
} qtm_touch_key_group_config_t;

Description: This structure contains the group configuration for touch key sensors.

More Info: Here is a description of each of the elements in this structure:

ParameterSizeRange/OptionsUsage
num_key_sensors2 bytes1-to-65535The number of sensor keys in the group
sensor_touch_di1 byte0-to-255The number of repeat measurements to confirm touch detection and out-of-touch detection
sensor_max_on_time1 byte0 (Disabled), 1-to-255The number of timer periods with sensor In Detect before automatic 'recal'
sensor_anti_touch_di1 byte0 (Disabled), 1-to-255The number of repeat measurements to confirm anti-touch recalibration required
sensor_anti_touch_recal_thr1 byte0-to-5Scale-down of touch threshold to set anti-touch threshold.
0 = 100% Touch Threshold
1 = 50%
2 = 25%
3 = 12.5%
4 = 6.25%
5 = Maximum Recalibration
sensor_touch_drift_rate1 byte0 (Disabled), 1-to-255The number of timer periods to countdown between towards touch drifts
sensor_anti_touch_drift_rate1 byte0 (Disabled), 1-to-255The number of timer periods to countdown between away from touch drifts
sensor_drift_hold_time1 byte0 (Disabled), 1-to-255The number of timer periods to stop drifting after touch event
sensor_reburst_mode1 byte0 = None1 = Unresolved (Quick reburst)2 = All

None – Reburst is never set, measurements according to application schedule

Unresolved – Reburst is set, all sensors suspended except those in same AKS as the target sensor

All – Reburst is set, no sensors are suspended

qtm_touch_key_config_t

typedef struct {
   uint8_t channel_threshold;   /* Touch detection threshold */
   uint8_t channel_hysteresis;  /* Percentage of threshold reduction to exit detect state */
   uint8_t channel_aks_group;   /* 0 = None, 1-255 = group number */
} qtm_touch_key_config_t;

Description: This structure contains the individual sensor configuration.

More Info: Here is a description of each of the elements in this structure:

ParameterSizeRange/OptionsUsage
channel_threshold1 byte0-to-255Minimum signal delta indicating touch contact
channel_hysteresis1 byte0 (50%)-to-4 (3.125%)Reduction of touch threshold to debounce when filtering out removed touch contact
channel_aks_group1 byte0-to-255Grouping of key sensors controlling simultaneous touch detect

Key Module Status and Output Data

qtm_touch_key_group_data_t

typedef struct {
   uint8_t  qtm_keys_status;        /* Status byte - bitfield: Bit 7 = REBURST_REQ, Bits 6:1 = Reserved, Bit 0 = Detect */
   uint16_t acq_group_timestamp;    /* For tracking this group drift etc */
   uint8_t  dht_count_in;           /* Count of drift hold time */
   uint8_t  tch_drift_count_in;     /* Count of towards touch drift */
   uint8_t  antitch_drift_count_in; /* Count of away from touch drift */
} qtm_touch_key_group_data_t;

Description: This structure contains sensor group data.

More Info: Here is a description of each of the elements in this structure:

ParameterSizeRange/OptionsUsage
qtm_keys_status1 byteBit 7: Reburst requiredBit 6-1: ReservedBit 0: Touch DetectionIndicates the current state of the Touch Key Group
acq_group_timestamp2 bytes0-to-65535Timestamp of last drift period processed
dht_count_in1 byte0-to-‘sensor_drift_hold_time’Countdown to drift hold release after a touch event
tch_drift_count_in1 byte0-to-‘sensor_touch_drift_rate’Countdown to next towards a touch drift period
antitch_drift_count_in1 byte0-to-‘sensor_anti_touch_drift_rate’Countdown to the next away from a touch drift period

qtm_touch_key_data_t

typedef struct {
   uint8_t sensor_state;                  /* Disabled, Off, On, Filter, Cal... */
   uint8_t sensor_state_counter;          /* State counter */
    qtm_acq_node_data_t* node_data_struct_ptr; /* Pointer to node data structure */
   uint16_t channel_reference;            /* Reference signal */
} qtm_touch_key_data_t;

Description: This structure contains key sensor run-time data.

More Info: Here is a description of each of the elements in this structure:

ParameterSizeRange/OptionsUsage
sensor_state1 byteBit fieldTouch key sensor state
sensor_state_counter1 byte0-to-255The number of repeat measurements to confirm a touch detection and an out-of-touch detection
*node_data_struct_ptr2/4 bytesPointerPointer to node data structure array
Channel_reference2 bytes0-to-65535Reference measurement, baseline for touch detection

Individual Key Sensor Data

#define QTM_KEY_STATE_DISABLE   0x00u
#define QTM_KEY_STATE_INIT      0x01u
#define QTM_KEY_STATE_CAL       0x02u
#define QTM_KEY_STATE_NO_DET    0x03u
#define QTM_KEY_STATE_FILT_IN   0x04u
#define QTM_KEY_STATE_DETECT    0x85u
#define QTM_KEY_STATE_FILT_OUT  0x86u
#define QTM_KEY_STATE_ANTI_TCH  0x07u
#define QTM_KEY_STATE_SUSPEND   0x08u
#define QTM_KEY_STATE_CAL_ERR   0x09u

Description: This byte represents the key sensor status.

More Info: Here is a description of each of the elements in this structure:

sensor_stateValue
QTM_KEY_STATE_DISABLE0x00
QTM_KEY_STATE_INIT0x01
QTM_KEY_STATE_CAL0x02
QTM_KEY_STATE_NO_DET0x03
QTM_KEY_STATE_FILT_IN0x04
QTM_KEY_STATE_DETECT0x85
QTM_KEY_STATE_FILT_OUT0x86
QTM_KEY_STATE_ANTI_TCH0x07
QTM_KEY_STATE_SUSPEND0x08
QTM_KEY_STATE_CAL_ERR0x09

Bit 7 (0x80u) is set in each state where the touch key sensor is ‘In Detect’.

Key Module APIs

qtm_init_sensor_key

touch_ret_t qtm_init_sensor_key(
    qtm_touch_key_control_t* qtm_lib_key_group_ptr,
   uint8_t which_sensor_key,
    qtm_acq_node_data_t* acq_lib_node_ptr
);

Description: This function initializes a touch key sensor and assigns the acquisition node pointer (to get the signal value).

Parameter:

TypeDescription
qtm_touch_key_control_t*Pointer to keys module control structure
uint8_tWhich key
qtm_acq_node_data_t*This node's corresponding acquisition data

Return: touch_ret_t - Touch Library Return Status  

qtm_key_sensors_process

touch_ret_t qtm_key_sensors_process(qtm_touch_key_control_t* qtm_lib_key_group_ptr)

Description: This function performs key sensors processing: executes touch detect state machine for all the keys. Responsible for performing drifting, anti-touch recalibration, Max-On-Duration (MOD), etc. Should be called after calling qtm_acquisition_process() (if frequency hopping is used, then after frequency hop process function).

Parameter: qtm_touch_key_control_t* - Pointer to Keys Module Control Structure

Return: touch_ret_t - Touch Library Return Status  

qtm_key_suspend

touch_ret_t qtm_key_suspend(uint16_t which_sensor_key, qtm_touch_key_control_t* qtm_lib_key_group_ptr)

Description: This function suspends touch measurements for the specified key.

Parameter: 

TypeDescription
uint16_tWhich key
qtm_touch_key_control_t*Pointer to Keys Module Control Structure

Return: touch_ret_t - Touch Library Return Status  

qtm_key_resume

touch_ret_t qtm_key_resume(uint16_t which_sensor_key, qtm_touch_key_control_t* qtm_lib_key_group_ptr)

Description: This function resumes touch measurements for the key.

Parameter: 

TypeDescription
uint16_tWhich key
qtm_touch_key_control_t*Pointer to keys module control structure

Return: touch_ret_t - Touch Library Return Status  

update_qtlib_timer

void update_qtlib_timer(uint16_t time_elapsed_since_update)

Description: The internal time tracking variable will be updated and used for computing various time-based functioning like Drift and MOD Call this function periodically (like 20 msec and pass 20 as the value).

Parameter: uint16_t - Timelapse since last call in milliseconds

Return: void  

qtm_get_touch_keys_module_id(

uint16_t qtm_get_touch_keys_module_id(void)

Description: This function returns the module ID.

Parameter: void

Return: void

qtm_get_touch_keys_module_ver

uint8_t qtm_get_touch_keys_module_ver(void)

Description: This function returns the module Firmware version.

Parameter: void

Return: void

Back to Top