6.4.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 re-factoring if code is to be re-used from one device for 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
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 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 AVR® ATmega324PB, ATmega328PB, Arm® SAML10/L11/L22, SAMC20/C21, PIC32CM_LE/LS, PIC32CK_SG/GC family only.
	1 byte	0 o 31	Applicable for AVR® ATtiny family only
	1 byte	0 to 63	Applicable for ARM® SAMD51/E51/E53/E54 family only
	1 byte	0 to 127	Applicable for 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. SAM E5x, SAM D5x: 3 kΩ, 6 kΩ, 75 kΩ, 200 kΩ SAM L22: 75 kΩ, 200 kΩ AVR® DA: 70 kΩ, 80 kΩ, 120 kΩ, 200 kΩ
`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_12`* `PRSC_DIV_SEL_14`* `PRSC_DIV_SEL_16`* `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. SAM E5x, SAM D5x, ATtiny: 16 kΩ, 32 kΩ, 64 kΩ, 128 kΩ AVR® DA: 6, 12, 14 * **The numbers correspond to the prescaler value.
`node_gain`	1 byte	Bits 7:4 = Analog Gain `GAIN_1` `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. (Higher filter level values > 64 are available only on Arm® SAM E54 family only.)
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