Surface Parameters
DO_NOT_REMOVE
In Microchip’s touch libraries, a surface refers to a 2D touch sensor array that enables detection of finger position (X, Y coordinates). Surface parameters are used to configure the acquisition, decoding, and gesture recognition behavior for these 2D touch surfaces.
This section covers parameters that control surface behaviors. The surface dimensions (horizontal x vertical), contact size threshold, position hysteresis, resolution, dead-band percentage, and position filter can be tuned according to the application.
SURFACE_CS_START_KEY_H
Description: This parameter defines the start key of the horizontal axis.
Range: 0 to 65534
SURFACE_CS_NUM_KEYS_H
Description: This parameter represents the number of channels forming the horizontal axis.
Range: 0 to 255
SURFACE_CS_START_KEY_V
Description: This parameter defines the start key of the vertical axis.
Range: 0 to 65534
SURFACE_CS_NUM_KEYS_V
Description: This parameter represents the number of channels forming the vertical axis.
Range: 0 to 255
SURFACE_CS_RESOL_DB
Description: This parameter is an 8-bit value with the upper four bits representing the surface resolution, and the lower four bits representing the dead-band as a percentage of the resolution.
Range: 0 to 255
More Info: The eight-bit format is defined in the scroller combined resolution and dead-band setting:
#define SCR_RESOL_DEADBAND(r, p) (uint8_t)(((r) << 4u) | (p)))
Where r is of type scr_resolution_t (RESOL_x_BIT in the code above) and p is of type scr_deadband_t (DB_x_PERCENT above), as defined in qtm_surface_cs_0x0021_api.h.
- RESOL_x_BIT: Represents the surface resolution. It defines the surface resolution by the number of bits, for example, a value of eight indicates 256 positions. The surface value would therefore be reported as a number from zero to 255.
- DB_x_PERCENT: Represents the surface dead-band. It defines the inactive area in percentage on the edge of the surface where no change in position is reported. For example, if the deadband is 10, then the inactive area is 10% of the surface range in each direction. If the surface has an 8-bit resolution (0-255), but the output can only reach 25-230 due to sensor layout, then the dead-band is 25, which is roughly 10% of the whole range. Setting 10% in the dead-band option removes this 10% inactive area and allows reaching the full range.
| Parameter | Range/Value |
|---|---|
| RESOL_x_BIT | RESOL_2_BIT, 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. |
| DB_x_PERCENT | 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. |
SURFACE_CS_FILT_CFG
Description: This 8-bit parameter is a combination of median filter enable/disable (bits 7:4) and IIR filter configuration (bits 3:0).
Range: 0 to 255
More Info: It is defined the same as the scroller position filtering setting:
#define SCR_MEDIAN_IIR(r, p) ((uint8_t)(((r) << 4u) | (p)))
Where r is the median filter, and p is the IIR filter.
- Median Filter: The median filter can be enabled to improve position accuracy under noisy conditions. Enabling the median filter increases the position response time. The values and the corresponding conditions for this field are explained in the following table.
Value Condition 0 Disable 1 Enable - IIR Filter: The IIR filter can be enabled to improve position accuracy under noisy conditions. Enabling the filter increases the position response time. The values and the corresponding conditions for these fields are explained in the following table. For example, if the IIR filter is configured as 25%, then the filtered position is 75% of the current position + 25% of the previous position.
Value Condition 0 None 1 25%. 2 50%. 3 75%
SURFACE_CS_POS_HYST
Description: This parameter defines the position hysteresis, which is the minimum travel distance to be reported after contact or direction change.
Range: 0 to 255
More Info: Position hysteresis is applied when the direction of the position is changed or when the surface is touched. This parameter determines the number of positions that must be moved in the opposite direction before the new touch position is reported.
It applies to horizontal and vertical directions.
SURFACE_CS_MIN_CONTACT
Description: This parameter defines the minimum contact size measurement for persistent contact tracking.
Range: 0 to 65534
More Info: This surface parameter has to be tuned based on the actual contact size of the touch when moved over the surface. The contact size of the moving touch can be observed from the contact_size parameter on the surface data structure. This value should be tuned to less than the lowest contact size reported by the surface module.