For the QMatrix operation, the CAT_CLK and GCLK_CAT clocks must be setup appropriately as a first step. The QMatrix and Common configuration parameters in the touch_config_at32uc3l.h configuration must then be set up.
The burst length values of each Touch channel must be specified using the qm_burst_length[] array in the main.c file. The burst length must be specified in the same order of Touch Channel numbering.
The touch_qm_sensors_init API initializes the QTouch Library as well as the CAT module and does the QMatrix method specific pin, register and Global Sensor configuration. The touch_qm_sensor_config API is used to configure individual sensor. The Sensor specific configuration parameter can be provided as input to this API.
The touch_qm_sensors_calibrate API is used to calibrate all the configured sensors thereby preparing the sensors for acquisition. The touch_qm_sensors_start_acquisition API initiates a QMatrix method measurement on all the configured Sensors. This API takes the peripheral DMA channels as an input. When a filter_callback function is enabled, the touch_event_dispatcher function calls the filter_callback function as soon as the raw acquisition data from the Sensors is available. The user can now optionally apply any filtering routine on the raw acquisition data before the QTouch Library does any processing on this data (For an overview of Filter callback usage, refer to example code in Allocating unused Port Pins for User Application). Once the QTouch Library has finished processing the acquisition data from Sensors, the touch_event_dispatcher function calls the measure_complete_callback function indicating the end of a single Touch measurement operation. The measure_complete_callback provides the measured data and Touch status information. The measured data is available in the same order of Touch Channel numbering.
The Host Application code can execute once a QMatrix acquisition is initiated with the touch_qm_sensors_start_acqusition API. Care must be taken in the Host Application such that the touch_event_dispatcher function is called frequently in order to process the acquired data. For a single Touch measurement operation (between a touch_qm_sensors_start_acquisition API call and the measure_complete_callback function being called), the touch_event_dispatcher function may execute multiple times in order to resolve the Touch status of Sensors. Failing to call the touch_event_dispatcher frequently can adversely impact the Touch Sensitivity.
Once the Touch Library has been initialized for QMatrix method using the touch_qm_sensors_init API, a new qm_burst_length[x] value of a Touch channel must be updated only using the touch_qm_channel_update_burstlen API. It is recommended to have qm_burst_length array as global variable as the Touch Library updates this array when the touch_qm_channel_update_burstlen API is called.
QMatrix burst length setting recommendation.
For a given X Line, the burst length value of ALL enabled Y Lines MUST be the same or set to 0x01(disabled). For example, the burst length value corresponding to (X0,Y1),(X0,Y2)...(X0,Yn) must be the same. In case of a scenario, wherein it is required to have a different a burst length, then the following option can be tried out - Enable the 1k ohm drive resistors on all the enabled Y lines by setting the corresponding bit in the CSARES register.
For QMatrix operation, the Analog comparators channels are used (using the ACIFB interface) depending on the Y Lines enabled. For example, when Y lines Y2 and Y7 are enabled the Analog comparator channels 2 and 7 are used by the CAT module for QMatrix operation. The user can uses the rest of the Analog comparator channels in the main application. The QTouch Library enables the ACIFB using the Control register (if not already enabled by the main application) when the touch_qm_sensors_init API is called.