1.1.2.1 Data Structures

The acquisition module implements all functionality required for making relative measurements of sensor capacitance. This is the only module uniquely built for an individual device, as it must access and control the pins used for touch sensor implementation.

As devices have different hardware features available, different configuration options are available on each device. For the most efficient use of system resources—ROM and RAM—different sensor configuration structures are required.

However, where the same variable name is used within the structure, the functionality controlled by that variable is identical. Any dependent function should utilize a reference to the variable, and NOT rely on a reference to the structure and pointer arithmetic.

Acquisition Group Configuration

A reference by a pointer to &ptc_qtlib_acq_gen1.freq_option_select will always point to the correct memory location, regardless of the device. However, any implementation based on pointer arithmetic will require refactoring if the code is to be reused from one device to another.


Parameter	Size	Range/Options	Usage
`num_sensor_nodes`	16-bit	0 to 65535	The number of sensor nodes configured in the group
`acq_sensor_type`	8-bit	`NODE_SELFCAP` `NODE_MUTUAL`	Defines the measurement method applied to this group of nodes
`calib_option_select`	1 byte	Bits 3:0 Calibration type: `CAL_AUTO_TUNE_NONE` `CAL_AUTO_TUNE_RSEL` `CAL_AUTO_TUNE_PRSC` `CAL_AUTO_TUNE_CSD`*	The calibration type selects which parameter should be automatically tuned for optimal charge transfer
`calib_option_select`	1 byte	Bits 7:4 Calibration target: `CAL_CHRG_2TAU` `CAL_CHRG_3TAU` `CAL_CHRG_4TAU` `CAL_CHRG_5TAU`	The calibration target applies a limit to the charge transfer loss allowed, where a higher setting of a target ensures a greater proportion of full charge is transferred
`freq_option_select`	1 byte	`FREQ_SEL_0` to `FREQ_SEL_15` or `FREQ_SEL_SPREAD`	`FREQ_SEL_0` to `FREQ_SEL_15` inserts a delay cycle between measurements during oversampling, where 0 is the shortest delay, 15 the longest. `FREQ_SEL_SPREAD` varies this delay from 0 to 15 in a sawtooth manner during the oversampling set.
`PTC_interrupt_priority`**	1 byte	1 to 3	Interrupt priority level for the PTC. Applicable for all Arm® Device’s except SAME5x.
`PTC_interrupt_priority`**	1 byte	1 to 7	Applicable for Arm® SAME5x
`wakeup_exp`*	1 byte	0 to15	The Wake-up Exponent is the exponent for the power of two, which represents the wake-up count in PTC core clocks
`cc_calib_precision*`	1 byte	0 to 255	The acceptable deviation in the measured signal value from the midpoint during calibration. Precision ensures that the calibrated signal value falls within the range of the PTC Signal Mid Value ± Precision
Note: * - Not available on all devices. ** - Applicable for Arm® Cortex devices only.

Node Configuration

Similarly, node configuration structures vary depending on which device is used.

Number of X lines
Number of Y lines
Feature availability


Parameter	Size	Range/Options	Usage
`node_xmask`	1/2/4/8 bytes	Bit field	Set the bit(s) at location(s) corresponding to the X line number(s). Example: X0 only = `0b00000001` = 0x01 X0 and X2 = `0b00000101` = 0x05 One byte is used for devices with up to eight X lines. Two bytes, four bytes, eight bytes are used for devices up to 16, 32 and 46* X lines, respectively. Note: *Can support up to 64 X lines.
`node_ymask`	1/2/4/8 bytes	Bit field	Set the bit(s) at location(s) corresponding to Y line number(s). Example: Y5 only = `0b00100000` = 0x20 Y1, Y2 and Y7 = `0b10000110` = 0x86 One byte is used for devices with up to eight Y lines Two bytes, four bytes, eight bytes are used for devices up to 16, 32, and 46* Y lines, respectively. Note: *Can support up to 64 Y lines.
`node_csd`*	1 byte	0 to 255	The number of delay cycles to ensure charging of sensor node capacitance. Applicable for the AVR® ATmega324PB, ATmega328PB, Arm® SAML10/L11/L22, SAMC20/C21, PIC32CM_LE/LS, PIC32CK_SG/GC , PIC32CMPL 10 family only.
	1 byte	0 o 31	Applicable for the AVR® ATtiny family only
	1 byte	0 to 63	Applicable for the ARM® SAMD51/E51/E53/E54 family only
	1 byte	0 to 127	Applicable for the AVR® DA family only
`node_rsel_prsc`	1 byte	Bits 7:4 = RSEL `RSEL_VAL_0` `RSEL_VAL_3`* `RSEL_VAL_6`* `RSEL_VAL_20` `RSEL_VAL_50` `RSEL_VAL_70`* `RSEL_VAL_75`* `RSEL_VAL_80`* `RSEL_VAL_100` `RSEL_VAL_120`* `RSEL_VAL_200`*	Internal Y line series resistor selection. * May not be available for all devices.
`node_rsel_prsc`	1 byte	Bits 3:0 = PRSC `PRSC_DIV_SEL_1` `PRSC_DIV_SEL_2` `PRSC_DIV_SEL_4` `PRSC_DIV_SEL_6`* `PRSC_DIV_SEL_8` `PRSC_DIV_SEL_10`* `PRSC_DIV_SEL_12`* `PRSC_DIV_SEL_14`* `PRSC_DIV_SEL_16`* `PRSC_DIV_SEL_18`* `PRSC_DIV_SEL_20`* `PRSC_DIV_SEL_22`* `PRSC_DIV_SEL_24`* `PRSC_DIV_SEL_26`* `PRSC_DIV_SEL_28`* `PRSC_DIV_SEL_30`* `PRSC_DIV_SEL_32`* `PRSC_DIV_SEL_64` * `PRSC_DIV_SEL_128`*	Clock Prescaler The acquisition clock is derived and scaled from CPU clock for AVR® devices. * May not be available for all devices.
`node_gain`	1 byte	Bits 7:4 = Analog Gain `GAIN_1` `GAIN_1_5`* `GAIN_2` `GAIN_4` `GAIN_8` `GAIN_16`	Analog Gain Setting Integration capacitor adjusted to control integrator gain
`node_gain`	1 byte	Bits 3:0 = Digital Gain `GAIN_1` `GAIN_2` `GAIN_4` `GAIN_8` `GAIN_16`	Digital Gain Setting The accumulated sum is scaled to digital gain
`node_oversampling`	1 byte	`FILTER_LEVEL_1` `FILTER_LEVEL_2` `FILTER_LEVEL_4` `FILTER_LEVEL_8` `FILTER_LEVEL_16` `FILTER_LEVEL_32` `FILTER_LEVEL_64` `FILTER_LEVEL_128`* `FILTER_LEVEL_256`* `FILTER_LEVEL_512`* `FILTER_LEVEL_1024`*	The number of samples to accumulate for each measurement. Note: Oversampling must be configured to be greater than or equal to digital gain for correct operation.
Note: * - Not available on all devices.

qtm_cvd_acq_dspic33ck_device_config_t

Note: This data structure is the specific configuration for dsPIC33CK family device’s.


Parameter	Size	Range/Options	Usage
`clk_src`	1 byte	`PERIPHERAL_CLK` `FOSC` `AFVCODIV` `FVCO_DIV`4 `FVCO_DIV`3 `INSTRUCTION_CLK`	Selects the ADC clock source
`clk_freq`	4 byte	Clock frequency based on the `clk_src` selection	Frequency (Hz) of the clock source selected for touch timing
`ext_clk_freq`	4 byte	External clock frequency	External clock frequency (Hz) when using primary Oscillator with PLL
`device_id`	1 byte	`DSPIC33_CK64MP` `DSPIC33_CK256MP` `DSPIC33_CK512MP` `DSPIC33_CK1024MP` `DSPIC33_CK64MC` `DSPIC33_CK256MC` `DSPIC33_CK2128_MASTER` `DSPIC33_CK128MP_SLAVE` `DSPIC33_CK512MP_MASTER` `DSPIC33_CK512MP_SLAVE`	Device selection

qtm_acq_pic32xx_xx_device_config_t*

Note: * - May not be available for all PIC32 devices.


Parameter	Size	Range/Options	Usage
`adc_interrupt_priority`	1 byte	1 to 3	Interrupt priority level for the ADC/PTC.
`adc_timebase`	1 byte	Based on the Clock frequency selection	The ADC timebase is a configurable parameter that defines the number of CLK_APB cycles corresponding to at least one microsecond (i.e. CLK_APB*0.000001). This setting ensures accurate internal timing for the ADC, independent of the ADC clock frequency, and is used to manage internal delays such as start-up times. If the CLK_APB clock frequency is modified and a new value is written to the TIMEBASE register, all timing counters will be reset.
`adc_pump_enable`	1 byte	Enable/Disable	The ADC voltage pump is an internal feature that must be managed depending on the operating conditions. Must be disabled when operating PTC above 4.5V, as leakage can affect PTC performance
`adc_prescaler`	1 byte	`ADC_PRSC_DIV_SEL_x` x= 2,3,4,5,….….29,30,31,32	ADC Clock Prescaler The ADC acquisition clock is derived and scaled from CPU clock .