Skip to Content

2D Surface (One-Finger Touch) Charge Sharing (CS) Module

Last modified by Microchip on 2026/02/23 13:43

The 2D Surface (One-Finger Touch) Charge Sharing (CS) Module in Microchip’s Touch Modular Library enables capacitive touch detection and position tracking on a 2D surface using a matrix of electrodes. This module is designed for single-finger operation and is commonly used for touchpads, sliders, and gesture interfaces.

Surface CS/1T Typedefs and Data Structures

scr_resolution_t

typedef enum tag_resolution_t { RESOL_2_BIT = 2, RESOL_3_BIT, RESOL_4_BIT, RESOL_5_BIT, RESOL_6_BIT, RESOL_7_BIT, RESOL_8_BIT, RESOL_9_BIT, RESOL_10_BIT, RESOL_11_BIT, RESOL_12_BIT} scr_resolution_t;

Description: This enumeration defines the scroller resolution setting.

 

scr_deadband_t

typedef enum tag_deadband_t { DB_NONE, DB_1_PERCENT, DB_2_PERCENT, DB_3_PERCENT, DB_4_PERCENT, DB_5_PERCENT, DB_6_PERCENT, DB_7_PERCENT, DB_8_PERCENT, DB_9_PERCENT, DB_10_PERCENT, DB_11_PERCENT, DB_12_PERCENT, DB_13_PERCENT, DB_14_PERCENT, DB_15_PERCENT} scr_deadband_t;

Description: This enumeration defines the scroller dead-band percentage setting.

 

qtm_surface_cs_control_t

typedef struct { qtm_surface_contact_data_t *qtm_surface_contact_data; qtm_surface_cs_config_t *   qtm_surface_cs_config;} qtm_surface_cs_control_t;

Description: This structure serves as the top-level container for surface configuration. Contains pointers to data and configuration structures.

 

qtm_surface_contact_data_t

typedef struct { uint8_t  qt_surface_status; uint16_t h_position_abs; uint16_t h_position; uint16_t v_position_abs; uint16_t v_position; uint16_t contact_size;} qtm_surface_contact_data_t;

Description: This structure contains the run-time data for touch surface.

More Info: The following describes the individual members of the structure:

ParameterSizeRange/OptionsUsage
qt_surface_status1 byteBit field Bit 7: Reburst requiredReburst Required = 1 indicates that further measurements are required to resolve/update contact status
Bit 6: ——
Bit 5: POS_V_DECVertical position decreased
Bit 4: POS_V_INCVertical position increased
Bit 3: POS_H_DECHorizontal position decreased
Bit 2: POS_H_INCHorizontal position increased
Bit 1: POS_CHANGEChange in reported position
Bit 0: Touch detectionTouch Detection = 1 indicates that a touch contact is present on the surface
h_position_abs2 bytes0 to 4095Apparent horizontal position
h_position2 bytes0 to 4095Motion filtered horizontal position
v_position_abs2 bytes0 to 4095Apparent vertical position
v_position2 bytes0 to 4095Motion filtered vertical position
contact_size2 bytes—Sum of touch deltas at contact location

qtm_surface_cs_config_t

typedef struct {    uint16_t start_key_h;    uint8_t  number_of_keys_h;    uint16_t start_key_v;    uint8_t  number_of_keys_v;    uint8_t  resol_deadband;    uint8_t  position_hysteresis;    uint8_t  position_filter;    uint16_t contact_min_threshold;    qtm_touch_key_data_t *qtm_touch_key_data;} qtm_surface_cs_config_t;

Description: This structure defines the configuration parameters for the touch surface.

More Info: The following describes the individual members of the structure:

ParameterSizeRange/OptionsUsage
start_key_h2 bytes0 to 65534Start key of horizontal axis
number_of_keys_h1 byte0 to 255The number of keys forming horizontal axis
start_key_v2 bytes0 to 65534Start key of vertical axis
number_of_keys_v1 byte0 to 255The number of keys forming vertical axis
resol_deadband1 byteBits 7:4 = Resolution 2 to 12 bitsFull-scale position resolution reported for the axis
position_hysteresis1 byte0 to 255

The minimum travel distance to be reported after contact or direction change

Applies to Horizontal and Vertical

position_filter1 byteBits7:5: ——
Bit 4: Median FilterMedian filter enable
Bit3 : ——
Bit 2: ——
Bits 1:0: IIR ConfigIIR Config0 = None1 = 25%2 = 50%3 = 75%.
contact_min_threshold2 bytes0 to 65535

The minimum contact size measurement for persistent contact tracking

Contact size is the sum of neighboring keys’ touch deltas forming the touch contact

*qtm_touch_key_dataPointer2/4 bytesqtm_touch_key_data_tPointer to touch key data for the underlying set of touch keys

Back to Top

Surface CS/1T APIs

The Surface CS/1T Application Programming Interfaces (APIs) refer to the APIs for the 2D Surface (One-Finger Touch) CS Module in the Touch Modular Library. These APIs allow you to initialize, configure, process, and retrieve touch data from a 2D mutual-capacitance touch surface (matrix) supporting single-finger tracking.

qtm_init_surface_cs

touch_ret_t qtm_init_surface_cs(qtm_surface_cs_control_t *qtm_surface_cs_control)

Description: This function initializes a surface module.

Parameter: 

TypeDescription
qtm_surface_cs_control_t *Pointer to Surface Module Control Structure

Return:

TypeDescription
touch_ret_tTouch Library Return Status

qtm_surface_cs_process

touch_ret_t qtm_surface_cs_process(qtm_surface_cs_control_t *qtm_surface_cs_control)

Description: * This function performs surface processing * Calculates X and Y position for the surface *. It must be called after qtm_key_sensors_process() has been executed.

Parameter:

TypeDescription
qtm_surface_cs_control_t *Pointer to Surface Module Control Structure

Return:

TypeDescription
touch_ret_tTouch Library Return Status

qtm_get_surface_cs_module_id

uint16_t qtm_get_surface_cs_module_id(void)

Description: This function returns the module ID.

Parameter: void

Return:

TypeDescription
uint16_tModule ID

qtm_get_surface_cs_module_ver

uint8_t qtm_get_surface_cs_module_ver(void)

Description: This function returns the module firmware version.

Parameter: void

Return:

TypeDescription
uint8_tModule Version

Back to Top