Acquisition Module
The acquisition module in Microchip’s Touch Modular Library is responsible for managing the sensor measurement process.
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.
Acquisition Module Typedefs and Data Structures
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 may utilize a reference to the variable, and NOT rely on a reference to the structure and pointer arithmetic.
touch_lib_state_t
/* Null - Not initialized */
TOUCH_STATE_NULL = 0u,
/* Initialized, no measurements yet */
TOUCH_STATE_INIT = 1u,
/* Ready to take a measurement */
TOUCH_STATE_READY = 2u,
/* Calibration set for some nodes */
TOUCH_STATE_CALIBRATE = 3u,
/* Measurement sequence in progress */
TOUCH_STATE_BUSY = 4u
} touch_lib_state_t;
Description: Touch library state
touch_ret_t
/* Successful completion of operation. */
TOUCH_SUCCESS = 0u,
/* Touch library is busy with pending previous touch measurement. */
TOUCH_ACQ_INCOMPLETE = 1u,
/* Invalid input parameter. */
TOUCH_INVALID_INPUT_PARAM = 2u,
/* Operation not allowed in the current state of the library module. */
TOUCH_INVALID_LIB_STATE = 3u,
/* Invalid pointer argument */
TOUCH_INVALID_POINTER = 11u,
/* Library is unable to calibrate node */
TOUCH_LIB_NODE_CAL_ERROR = 14u
} touch_ret_t;
Description: Touch library functions return a touch_ret_t
qtm_acq_node_group_config_t
/* Number of sensor nodes */
uint16_t num_sensor_nodes;
/* Self or mutual sensors */
uint8_t acq_sensor_type;
/* Hardware tuning: XX | TT 3/4/5 Tau | X | XX None/RSEL/PRSC/CSD */
uint8_t calib_option_select;
/* SDS or ASDV setting */
uint8_t freq_option_select;
/* Runtime priority of PTC interrupt */
uint8_t PTC_interrupt_priority;
/* Wakeup exponent */
uint8_t wakeup_exp;
} qtm_acq_node_group_config_t;
Description: Node group configuration
More Info: 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 code is to be reused from one device to another.
| Parameter | Size | Range/Options | Usage |
|---|---|---|---|
| num_sensor_nodes | 2 bytes | 0 to 65535 | The number of sensor nodes configured in the group |
| acq_sensor_type | 1 byte | 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 |
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 the target ensures a greater proportion of a 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, and 15 is 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 Peripheral Touch Controller (PTC) Applicable for all Arm® devices except SAME5x |
| 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 2, which represents the wake-up count in PTC core clocks |
Note: * - Not available on all devices - Applicable for Arm Cortex devices only | |||
qtm_acq_DEVICE_FAMILY_node_config_t
/* Selects the X pins for this node */
uint64_t node_xmask;
/* Selects the Y pins for this node */
uint64_t node_ymask;
/* Charge Share Delay */
uint8_t node_csd;
/* Bits 7:4 = Resistor, Bits 3:0 Prescaler */
uint8_t node_rsel_prsc;
/* Bits 7:4 = Analog gain, Bits 3:0 = Digital gain */
uint8_t node_gain;
/* Accumulator setting */
uint8_t node_oversampling;
} qtm_acq_avr_da_node_config_t;
Description: Node configuration
More Info: Similarly, node configuration structures vary depending on the device used. Therefore, the structure name contains the name of the device family in it for identification. In the example code, the device was a AVR128DA48 and so "avr_da" replaces "DEVICE_FAMILY" in the structure name.
The following describes the elements of this structure in more detail.
| 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 1 byte is used for devices with up to 8 “X” lines. 2 bytes, 4 bytes, 8 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 1 byte is used for devices with up to 8 “Y” lines. 2 bytes, 4 bytes, 8 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 the sensor node capacitances Applicable for ATmega324PB and ATmega324PB based on the AVR® architecture, and Arm® SAML10/L11/L22, SAMC20/C21, PIC32CM_LE/LS, PIC32CK_SG/GC family only |
| 1 byte | 0 o 31 | Applicable for the AVR ATtiny family only | |
| 1 byte | 0 to 63 | Applicable for the Arm SAMLD51/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. 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Ω |
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 the 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 |
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: *Not available on all devices | |||
qtm_acq_dspic33c_device_config_t
/* Selects the ADC clock source */
adc_clock_src_t adc_clk_src;
/* selected clock source frequency(Hz) for touch, min-16MHz and max 500MHz */
uint32_t adc_clk_src_freq;
/* Device Identifier */
dspic33c_device_id device_id;
} qtm_acq_dspic33c_device_config_t;
Description: Device information configuration
More Info:
| Parameter | Size | Range/Options | Usage |
|---|---|---|---|
| clk_src | 1 byte | PERIPHERAL_CLK FOSC AFVCODIV FVCO_DIV4 FVCO_DIV3 INSTRUCTION_CLK | Selects the Analog-to-Digital Converter (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 the primary oscillator with PLL |
| device_id | 1 byte | DSPIC33_CK64MP DSPIC33_CK256MP DSPIC33_CK512MP DSPIC33_CK1024MP DSPIC33_CK64MC DSPIC33_CK256MC DSPIC33_CH128_MASTER DSPIC33_CH512MP_MASTER | Device selection |
qtm_acq_node_data_t
uint8_t node_acq_status;
uint16_t node_acq_signals;
uint16_t node_comp_caps;
} qtm_acq_node_data_t;
Description: Acquisition Node run-time data
More Info: While different target hardware requires that the configuration structure for sensor nodes varies from one device to another, all acquisition modules conform to a standard sensor node data structure. Processed module output data are stored in this data structure during run-time.
The outputs/status information may be used by other post-processing modules or by the application.
| Parameter | Size | Range/Options | Usage. |
|---|---|---|---|
| node_acq_status | 1 byte | Bit 7 NODE_CAL_ERROR | Indicates node calibration error |
| Bit 6 | Rise Time calibration complete | ||
| Bit 5 | Reserved | ||
Bit <4:2> (three bits)Node calibration state NODE_MEASURE = 0 NODE_CC_CAL = 1 NODE_PRSC_CAL = 2 NODE_RSEL_CAL = 3 NODE_CSD_CAL* = 4 | Indicates whether a calibration is ongoing and its current stage | ||
| Bit 1 Calibration Request | Write to ‘1’ to trigger calibration sequence on this node.(Reset to ‘0’ by module once actioned.) | ||
| Bit 0 Enabled | Write to ‘1’ to enable this node for measurement | ||
| node_acq_signals | 2 bytes | Most recent measurement for this sensor node. | 16-bit unsigned value Accumulated and scaled as per node_oversampling and node_gain_digital settings |
| node_comp_caps | 2 bytes | Hardware calibration data | Indicates the tuning of the compensation circuit for this node |
Acquisition Module APIs
The Acquisition Module Application Programming Interfaces (APIs) in Microchip’s Touch Modular Library provide the interface for initializing, starting, and processing capacitive touch sensor measurements.
qtm_acquisition_process
Description: Processes the acquired values (signal) resulting from calling qtm_ptc_start_measurement_seq() API. This function should be called after the callback function passed to qtm_ptc_start_measurement_seq() is called by library
Parameter: void
Return: touch_ret_t - TOUCH_SUCCESS or TOUCH_CAL_ERROR
qtm_ptc_init_acquisition_module
*qtm_acq_control_ptr);
Description: This function initializes the Acquisition module and Peripheral Touch Controller (PTC).
Parameter: qtm_acquisition_control_t *qtm_acq_control_ptr - pointer to acquisition control structure
Return: touch_ret_t - TOUCH_SUCCESS or INVALID_PARAMETER
qtm_ptc_qtlib_assign_signal_memory
*qtm_signal_raw_data_ptr);
Description: Pass the pointer of an array. The unprocessed PTC output values for all the channels are stored in this array and used by qtm_acquisition_process() API
Parameter: uint16_t *qtm_signal_raw_data_ptr - pointer to raw data array
Return: touch_ret_t - TOUCH_SUCCESS
qtm_enable_sensor_node
*qtm_acq_control_ptr, uint16_t qtm_which_node_number);
Description: Enables a sensor node for measurement
Parameter: qtm_acquisition_control_t *qtm_acq_control_ptr - pointer to Acquisition Module control
uint16_t qtm_which_node_number - node (channel) number
Return: touch_ret_t
qtm_calibrate_sensor_node
*qtm_acq_control_ptr, uint16_t qtm_which_node_number);
Description: Configures the sensor for calibration. On the next measurement, the calibration process for this sensor will be started
Parameter: qtm_acquisition_control_t *qtm_acq_control_ptr - pointer to Acquisition Module control
uint16_t qtm_which_node_number - node (channel) number
Return: touch_ret_t
qtm_ptc_start_measurement_seq
*qtm_acq_control_pointer, void (*measure_complete_callback)(void));
Description: Loads touch configurations for first channel and starts the measurement. Subsequent channels will be configured in PTC interrupt till all channels are measured. When measurements on all channels are completed, the callback function passed on this API will be called
Parameter: qtm_acquisition_control_t *qtm_acq_control_ptr - pointer to Acquisition Module control
void (*measure_complete_callback)(void) - measure complete callback function pointer
Return: touch_ret_t
qtm_autoscan_sensor_node
*qtm_auto_scan_config_ptr, void (*auto_scan_callback)(void));
Description: Configures the PTC to start measurement using event system on a single node configured in qtm_auto_scan_config_ptr. When a touch is detected on the autoscan sensor, auto_scan_callback() will be called
Parameter: qtm_auto_scan_config_t *qtm_auto_scan_config_ptr - pointer to auto scan configuration structure
void (*auto_scan_callback)(void) - Autoscan Wakeup callback function pointer
Return: touch_ret_t
qtm_autoscan_node_cancel
Description: Cancels Event-system based measurement
Parameter: void
Return: touch_ret_t
qtm_ptc_de_init
Description: Clear PTC registers and set the library state to TOUCH_STATE_NULL. The library can only do a proper initialization after calling this API
Parameter: void
Return: void
qtm_DEVICE_FAMILY_acq_module_get_id
Description: Returns the module ID
Parameter: void
Return: 16-bit ID for the module
qtm_DEVICE_FAMILY_acq_module_get_version
Description: Returns the module firmware version
Parameter: void
Return: 8-bit Firmware version (4-bit Major / 4-bit Minor) for the module
qtm_ptc_clear_interrupt
Description: Clears the End-of-Conversion or Window-comparator interrupt flags
Parameter: void
Return: void
qtm_DEVICE_FAMILY_ptc_handler_eoc
Description: Captures the measurement, starts the next channel's measurement. If EOC occurred for last channel, call callback passed in qtm_ptc_start_measurement_seq() API
Parameter: void
Return: void
qtm_DEVICE_FAMILY_ptc_handler_wcomp
Description: Captures the measurement, calls the callback passed in qtm_autoscan_sensor_node() API
Parameter: void
Return: void