QTouch API and Usage

Typedef	Notes
uint8_t	unsigned 8-bit integer
int8_t	signed 8-bit integer
uint16_t	unsigned 16-bit integer
int16_t	signed 16-bit integer
uint32_t	unsigned 32-bit integer
threshold_t	unsigned 8-bit integer used for setting a sensor detection threshold

Enumerations

sensor_type_t
aks_group_t
channel_t
hysteresis_t
resolution_t
recal_threshold_t

This section lists the enumerations used in the QTouch Library.

sensor_type_t

Enumeration	sensor_type_t
Use	Define the type of the sensor

Values	Comment
SENSOR_TYPE_UNASSIGNED	Channel is not assigned to any sensor
SENSOR_TYPE_KEY	Sensor is of type KEY
SENSOR_TYPE_ROTOR	Sensor is of type ROTOR
SENSOR_TYPE_SLIDER	Sensor is of type SLIDER

aks_group_t

Enumeration

aks_group_t

Use

Defines the Adjacent Key Suppression (AKS) groups each sensor may be associated with ( see section 5.3.4 Maximum ON Duration)

AKS is selectable by the system designer

7 AKS groups are supported by the library

Values	Comment
NO_AKS_GROUP	NO AKS group selected for the sensor
AKS_GROUP_1	AKS Group number 1
AKS_GROUP_2	AKS Group number 2
AKS_GROUP_3	AKS Group number 3
AKS_GROUP_4	AKS Group number 4
AKS_GROUP_5	AKS Group number 5
AKS_GROUP_6	AKS Group number 6
AKS_GROUP_7	AKS Group number 7

channel_t

Enumeration

channel_t

Use

The channel numbers used in the library.

When using the QTouch acquisition method, the channel numbers have a one to one mapping to the pin numbers of the port being used.

When using the QMatrix acquisition method, the channel numbers are ordered in a matrix sequence

Values	Comment
CHANNEL_0	Channel number : 0
CHANNEL_1	Channel number : 1
CHANNEL_2	Channel number : 2
CHANNEL_3	Channel number : 3
.....	Channel number: ..
Upto CHANNEL ( N-1 )	Channel number N-1 : for an N Channel library

The maximum number of channels supported is dependent on the library variant. Possible values of N are as listed below

Acquisition method	Device type	Possible values of N ( Maximum number of channels )
QTouch acquisition	8-bit	4,8,16
32-bit	8, 16, 32
QMatrix Acquisition	8-bit	8,16,32,64

Acquisition method

Device type

Possible values of N

( Maximum number of channels )

QTouch acquisition

8-bit

4,8,16

32-bit

8, 16, 32

QMatrix Acquisition

8-bit

8,16,32,64

hysteresis_t

Enumeration

Hysteresis_t

Use

Defines the sensor detection hysteresis value. This is expressed as a percentage of the sensor detection threshold.

This is configurable per sensor.

HYST_x = hysteresis value is x percent of detection threshold value (rounded down).

Note that a minimum value of 2 is used as a hard limit. Example: if detection threshold = 20, then:

HYST_50 = 10 (50 percent of 20)

HYST_25 = 5 (25 percent of 20)

HYST_12_5 = 2 (12.5 percent of 20)

HYST_6_25 = 2 (6.25 percent of 20 = 1, but set to the hard limit of 2)

Values	Comment
HYST_50	50% Hysteresis
HYST_25	25% Hysteresis
HYST_12_5	12.5% Hysteresis
HYST_6_25	6.25% Hysteresis

resolution_t

Enumeration

resolution_t

Use

For rotors and sliders, the resolution of the reported angle or position.

RES_x_BIT = rotor/slider reports x-bit values.

Example: if slider resolution is RES_7_BIT, then reported positions are in the range 0…127.

Values	Comment
RES_1_BIT	1 bit resolution : reported positions range 0 – 1
RES_2_BIT	2 bit resolution : reported positions range 0 – 3
RES_3_BIT	3 bit resolution : reported positions range 0 – 7
RES_4_BIT	4 bit resolution : reported positions range 0 – 15
RES_5_BIT	5 bit resolution : reported positions range 0 – 31
RES_6_BIT	6 bit resolution : reported positions range 0 – 63
RES_7_BIT	7 bit resolution : reported positions range 0 – 127
RES_8_BIT	8 bit resolution : reported positions range 0 – 255

recal_threshold_t

Enumeration

recal_threshold_t

Use

A sensor recalibration threshold. This is expressed as a percentage of the sensor detection threshold.

This is for automatic recovery from false conditions, such as a calibration while sensors were touched, or a significant step change in power supply voltage.

If the false condition persists the library will recalibrate according to the settings of the recalibration threshold.

This setting is applicable to all the configured sensors.

Usage :

RECAL_x = recalibration threshold is x percent of detection threshold value (rounded down).

Note: a minimum value of 4 is used.

Example: if detection threshold = 40, then:

RECAL_100 = 40 ( 100 percent of 40)

RECAL_50 = 20 ( 50 percent of 40)

RECAL_25 = 10 ( 25 percent of 40)

RECAL_12_5 = 5 ( 12.5 percent of 40)

RECAL_6_25 = 4 ( 6.25 percent of 40 = 2, but value is limited to 4)

Values	Comment
RECAL_100	100% recalibration threshold
RECAL_50	50% recalibration threshold
RECAL_25	25% recalibration threshold
RECAL_12_5	12.5% recalibration threshold
RECAL_6_25	6.25% recalibration threshold

Data structures

qt_touch_status_t
qt_touch_lib_config_data_t
qt_touch_lib_measure_data_t
qt_burst_lengths
tag_sensor_t
qt_lib_siginfo_t

This section lists the data structures that hold sensor status, settings, and diagnostics information

qt_touch_status_t

Structure	qt_touch_status_t
Input / Output	Output from the Library
Use	Holds the status ( On/ Off ) of the sensors and the linear and angular positions of sliders and rotors respectively

Fields	Comment
sensor_states[]	For Sensor, the sensor_states. Bit “n” = state of nth sensor : Bit Value 0 - indicates the sensor is not in detect Bit Value 1 - indicates the sensor is in detect
rotor_slider_values[]	Rotors angles or slider positions if rotors and sliders are used. These values are valid when sensor states shows that the corresponding rotor or slider is in detect

Fields

Comment

sensor_states[]

For Sensor, the sensor_states. Bit “n” = state of nth sensor :

Bit Value 0 - indicates the sensor is not in detect

Bit Value 1 - indicates the sensor is in detect

rotor_slider_values[]

Rotors angles or slider positions if rotors and sliders are used. These values are valid when sensor states shows that the corresponding rotor or slider is in detect

The macro that can get the sensor state when the sensor number is provided can be something as below:

#define GET_SENSOR_STATE(SENSOR_NUMBER) qt_measure_data.qt_touch_status.sensor_states[(SENSOR_NUMBER/8)] & (1 <<(SENSOR_NUMBER % 8))

The host application can use this macro to act accordingly, the following example shows how to toggle a IO pin (PD2) based on the sensor0 state.( Set PD2 if sensor0 is in detect, and clear PD2 if sensor0 is not in detect)

DDRD |= (1u << PORTD2);
if (GET_SENSOR_STATE(0) !=0)
{        
    PORTD |= (1u << PORTD2); /* Set PORTD2 */
}
else
{
    PORTD &= ~(1u << PORTD2); /* Clear PORTD2 */

qt_touch_lib_config_data_t

Structure	qt_touch_lib_config_data_t
Input / Output	Input to the library
Use	Global Configuration data settings for the library.

Fields	Type	Comment
qt_recal_threshold	recal_threshold_t	Sensor recalibration threshold. Default: RECAL_50 (recalibration threshold = 50 percent of detection threshold. Refer to section 5.3.1 Recalibration Threshold more details
qt_di	uint8_t	Sensor detect integration (DI) limit. Default value: 4. Refer to section 5.3.2 Detect Integration for more details
qt_drift_hold_time	uint8_t	Sensor drift hold time in units of 200 ms. Default value: 20 (20 x 200 ms = 4s), that is hold off drifting for 4 seconds after leaving detect. Refer to section 5.3.3 Drift Hold Time for more details
qt_max_on_duration	uint8_t	Sensor maximum on duration in units of 200 ms. For example: 150 = recalibrate after 30s (150 x 200 ms). 0 = recalibration disabled Default value: 0 (recalibration disabled). Refer to section 5.3.4 Maximum ON Duration for more details.
qt_neg_drift_rate	uint8_t	Sensor negative drift rate in units of 200 ms. Default value: 20 (20 x 200 ms = 4s per LSB). Refer to section 5.3.5 Positive / Negative Drift for more details
qt_pos_drift_rate	uint8_t	Sensor positive drift rate in units of 200 ms. Default value: 5 (5 x 200 ms = 1s per LSB). Refer to section 5.3.5 Positive / Negative Drift for more details
qt_pos_recal_delay	uint8_t	Sensor positive recalibration delay. Default: 3. Refer to section 5.3.6 for more details.

The measurement limit for touch sensing using QTouch acquisition method is hard coded as 8192.

The QTouch library exports a variable of this type so that the user can specify the threshold parameters for the library. The API qt_set_parameters() should be called to apply the parameters specified.

extern qt_touch_lib_config_data_t qt_config_data;

qt_touch_lib_measure_data_t

Structure	qt_touch_lib_measure_data_t
Input / Output	Output from the library
Use	Data structure which holds the sensor and channel states and values.

Fields	Type	Comment
channel_signals	uint16_t	The measured signal on each channel.
channel_references	uint16_t	The reference signal for each channel.
qt_touch_status	qt_touch_status_t	The state and position of the configured sensors

The QTouch library exports a variable of this type which can be accessed to retrieve the touch status of all the sensors.

extern qt_touch_lib_measure_data_t qt_measure_data;

qt_burst_lengths

Structure

qt_burst_lengths

Input / Output

Input to the library

Use

NOTE: Applicable only to the QMatrix acquisition method libraries

This data structure is used to specify the burst lengths for each of the QMatrix channels

Fields	Type	Comment
qt_burst_lengths[]	uint8_t	The burst length for each of the QMatrix channel in units of pulses. Default value: 64 pulses. These values can be configured for each channel individually.

Fields

Type

Comment

qt_burst_lengths[]

uint8_t

The burst length for each of the QMatrix channel in units of pulses. Default value: 64 pulses.

These values can be configured for each channel individually.

The signal gain for each sensor is controlled by circuit parameters as well as the burst length. The burst length is simply the number of times the charge-transfer (‘QT’) process is performed on a given sensor. Each QT process is simply the pulsing of an X line once, with a corresponding Y line enabled to capture the resulting charge passed through the sensor’s capacitance Cx.

The QMatrix acquisition method library exports a variable of this type which can be accessed to set the burst length for each of the QMatrix channels

extern uint8_t qt_burst_lengths[QT_NUM_CHANNELS];

tag_sensor_t

Structure	tag_sensor_t
Input / Output	Output from the library
Use	Data structure which holds the internal sensor state variables used by the library.

Fields

Type

Comment

State

uint8_t

internal sensor state

general_counter

uint8_t

general purpose counter: used for calibration, drifting, etc

ndil_counter

uint8_t

drift Integration counter

Threshold

uint8_t

sensor detection threshold. Refer to section 5.4.1 Detect threshold for more details

type_aks_pos_hyst

uint8_t

holds information for sensor type, AKS group, positive recalibration flag, and hysteresis value

Bit fields	Use
B1 : B0	Hysteresis. Refer to section 5.4.2 Hysteresis for more details
B2	positive recalibration flag
B5:B3	AKS group. Refer to section 5.4.5 for more details
B7:B6	sensor type

from_channel

uint8_t

starting channel number for sensor

to_channel

uint8_t

ending channel number for sensor

Index

uint8_t

index for array of rotor/slider values

qt_lib_siginfo_t

Structure	qt_lib_siginfo_t
Input / Output	Output from the library
Use	Data structure which holds the information about the library variant and its version information.

qt_lib_siginfo_t structure definition for a QTouch acquisition method library variant is shown below.

Fields

Type

Comment

library_version

uint16_t

Holds the library version information.

Bit fields	Use
B3 : B0	Patch version of the library
B7 : B4	Minor version of the library
B15:B8	Major version of the library

lib_sig_lword

uint16_t

Holds the general information about the library

Bit fields	Use
B1 : B0	Library Type : 00 : QTouch acquisition method 01 : QMatrix acquisition method
B2	Compiler tool chain used 0 – GCC 1 – IAR
B9 : B3	Maximum number of channels supported by the library
B10	0 – Library supports only keys 1 – Library supports keys and rotors
B15 : B11	Maximum number of rotors and sliders supported by the library

lib_sig_hword

uint16_t

Reserved

qt_lib_siginfo_t structure definition for a QMatrix acquisition method library variant is shown below.

Fields

Type

Comment

library_version

uint16_t

Holds the library version information.

Bit fields	Use
B3 : B0	Patch version of the library
B7 : B4	Minor version of the library
B15:B8	Major version of the library

lib_sig_lword

uint16_t

Holds the general information about the library

Bit fields	Use
B1 : B0	Library Type : 00 : QTouch acquisition method 01 : QMatrix acquisition method
B2	Compiler tool chain used 0 – GCC 1 – IAR
B9 : B3	Maximum number of channels supported by the library
B10	0 – Library supports only keys 1 – Library supports keys and rotors
B15 : B11	Maximum number of rotors and sliders supported by the library

lib_sig_hword

uint16_t

Holds information about the X and Y lines for a QMatrix library variant

Bit fields	Use
B4 : B0	Number of X Lines
B8 : B5	Number of Y Lines
B9	0

Public Functions

qt_set_parameters
qt_enable_key
qt_enable_rotor
qt_enable_slider
qt_init_sensing
qt_measure_sensors
qt_calibrate_sensing
qt_reset_sensing
qt_get_sensor_delta
qt_get_library_sig

This section lists the public functions available in the QTouch libraries and its usage.

qt_set_parameters

This function is used to initialize the global configuration settings in the variable qt_config_data of the QTouch and QMatrix acquisition method libraries.

void qt_set_parameters ( void )

Arguments	Type	Comment
Void	-	This function will initialize the parameters required by the library to default values .But the default values can be changed by the user by modifying the global threshold values as defined in qt_touch_lib_config_data_t . See section 5.6.4.1 for details.

NOTE:

This function can be called any time to apply the threshold parameters of the library as specified by modifying the global data structure qt_config_data exported by the library.

qt_enable_key

This function is used to configure a channel as a key.

void qt_enable_key (
    channel_t channel,
    aks_group_t aks_group,
    threshold_t detect_threshold,
    hysteresis_t detect_hysteresis
    )

Arguments	Type	Comment
Channel	channel_t	Specifies the channel number to be configured for use as a “key”
aks_group	aks_group	Specifies the aks group associated with the sensor being configured as “key”
detect_threshold	threshold_t	Specifies the detect threshold for the sensor
detect_hysteresis	hysteresis_t	Specifies the detection hysteresis for the sensor

qt_enable_rotor

This function is used to configure a set of channels as a rotor.

void qt_enable_rotor (

channel_t from_channel ,

channel_t to_channel ,

aks_group_t aks_group ,

threshold_t detect_threshold ,

hysterisis_t detect_hysterisis ,

resoulution_t angle_resolution ,

uint8_t angle_hysterisis

)

Arguments	Type	Comment
from_channel	Channel_t	Specifies the starting channel number to be configured for use as a “Rotor”
to_channel	Channel_t	Specifies the end channel number to be configured for use as a “Rotor”
aks_group	aks_group	Specifies the aks group associated with the sensor being configured as “ROTOR”
detect_threshold	threshold_t	Specifies the detect threshold for the sensor
detect_hysterisis	hysterisis_t	Specifies the detection hysteresis for the sensor
angle_resolution	resolution_t	Specifies the resolution of the reported angle value
angle_hysterisis	uint8_t	Specifies the hysteresis of the reported angle value

NOTE:

A “Rotor” sensor requires contiguous channel numbers.
The rotor / slider number depends on the order in which the rotor or sliders are enabled. The first rotor or slider enabled will use “rotor_slider_values[0]”, the second will use “rotor_slider_values[1]”, and so on. The reported rotor value is valid when the rotor is reported as being in detect.
In case of QMatrix acquisition method library, the from_channel and to_channel can be between 3 to 8 channel numbers apart (i.e. it can support 3 to 8 channel rotors).
In case of QTouch acquisition method library, the from_channel and to_channel can be 3 channels apart (i.e. can support only 3 channel rotors).

qt_enable_slider

This function is used to configure a set of channels as a rotor.

void qt_enable_slider (

channel_t from_channel ,

channel_t to_channel ,

aks_group_t aks_group ,

threshold_t detect_threshold ,

hysterisis_t detect_hysterisis ,

resolution_t position_resolution ,

uint8_t position_hysteresis

)

Arguments	Type	Comment
from_channel	Channel_t	Specifies the starting channel number to be configured for use as a “Slider”
to_channel	Channel_t	Specifies the end channel number to be configured for use as a “Slider”
aks_group	aks_group	Specifies the aks group associated with the sensor being configured as “Slider”
detect_threshold	threshold_t	Specifies the detect threshold for the sensor
detect_hysterisis	hysterisis_t	Specifies the detection hysteresis for the sensor
position_resolution	resolution_t	Specifies the resolution of the reported position value
position_hysterisis	uint8_t	Specifies the hysteresis of the reported position value

NOTE:

A “Slider” sensor requires a contiguous numbers of channels.
The rotor / slider number depends on the order in which the rotor or sliders are enabled. The first rotor or slider enabled will use “rotor_slider_values[0]”, the second will use. “rotor_slider_values[1]”, and so on. The reported rotor value is valid when the slider is reported as being in detect.
In case of QMatrix acquisition method library, the from_channel and to_channel can be between 3 to 8 channels apart (i.e. it can support 3 to 8 channel sliders).
In case of QTouch acquisition method library, the from_channel and to_channel can be 3 channels apart (i.e. can support only 3 channel sliders).

qt_init_sensing

This function is used to initialize the touch sensing for all enabled channels. All required sensors should be configured before calling this function.

void qt_init_sensing ( void )

Arguments	Type	Comment
Void	-	-

NOTE:

All sensors must be configured (using qt_enable_key, qt_enable_rotor or qt_enable_slider ) before calling this function.
This functions initializes all the configured sensors, performs calibration.

qt_measure_sensors

This function performs a capacitive measurement on all enabled sensors. The measured signals for each sensor are then processed to check for user touches, releases, changes in rotor angle and changes in slider position. The function returns the status of the Library as a combination of bit fields in an uint16_t value.

unit16_t qt_measure_sensors( uint16_t current_time_ms )

Arguments	Type	Comment
current_time_ms	uint16	The current time in milliseconds

Return value(s)	Bit definition	Comments
QTLIB_NO_ACTIVITY	0x0000	No activity detected on any of the sensors
QTLIB_IN_DETECT	0x0001	At least one sensor is in detect
QTLIB_STATUS_CHANGE	0x0002	At least one sensor has changed ON/OFF state since the last call to qt_measure_sensor()
QTLIB_ROTOR_SLIDER_POS_CHANGE	0x0004	At least one rotor/slider has changed position since the last call to qt_measure_sensors()
QTLIB_CHANNEL_REF_CHANGE	0x0008	At least one reference value has changed since last call to qt_measure_sensors()
QTLIB_BURST_AGAIN	0x0100	Flag to indicate Multiple measurements needed.
QTLIB_RESOLVE_CAL	0x0200	Multiple measurements needed to resolve calibration. Call qt_measure_sensors( ) once again.
QTLIB_RESOLVE_FILTERIN	0x0400	Multiple measurements needed to resolve filtering. Call qt_measure_sensors( ) once again.
QTLIB_RESOLVE_DI	0x0800	Multiple measurements needed to resolve detect integration. Call qt_measure_sensors( ) once again.
QTLIB_RESOLVE_POS_RECAL	0x1000	Multiple measurements needed to resolve positive recalibration. Call qt_measure_sensors( ) once again.

NOTE:

All sensors must be configured (using qt_enable_key or qt_enable_rotor or qt_enable_slider) and initialized by calling qt_init_sensing before calling this function.

qt_calibrate_sensing

This function forces a recalibration of all enabled sensors.

void qt_calibrate_sensing( void )

Arguments	Type	Comment
Void	-	-

NOTE:

Recalibration may be useful if, for example, it is desired to globally recalibrate all sensors on a change in application operating mode.
This function must be called only when the sensors have been configured and initialized.

qt_reset_sensing

This function disables all sensors and resets all configuration settings (for example, “qt_di”) to their default values.

void qt_reset_sensing( void )

Arguments	Type	Comment
Void	-	-

NOTE:

This may be useful if it is desired to dynamically reconfigure sensing. After calling this function, any required sensors must be re-enabled, filter callback needs to be re-initialized, and “qt_init_sensing()” must be called before “qt_measure_sensors()” is called again.
In case of QMatrix, the burst lengths for all channels are set to zero.

qt_get_sensor_delta

This function returns the delta value for a given channel.

int16_t qt_get_sensor_delta( uint8_t sensor_number )

Arguments	Type	Comment
sensor_number	unit8_t	sensor id for which the delta is required

Return type	Comment
int16_t	The delta value of the sensor specified

NOTE:

All sensors must be configured (using qt_enable_key or qt_enable_rotor or qt_enable_slider) and initialized by calling qt_init_sensing before calling this function.

qt_get_library_sig

This function is used to retrieve the library version and signature from the library.

void qt_get_library_sig( qt_lib_siginfo_t *lib_sig_ptr )

Arguments	Type	Comment
lib_sig_ptr	qt_lib_siginfo_t *	Pointer to the structure which needs to be updated with the library signature information

NOTE:

The function qt_measure_sensors() should have been called at least once prior to calling this function.

Sequence of Operations and Using the API

Channel numbering when using QTouch acquisition method
Channel numbering when using QMatrix acquisition method
Sensor Numbering
Filtering Signal Measurements
Allocating unused Port Pins for User Application
Disabling and Enabling of Pull-up for AVR devices

Figure 6 illustrates the sequence of operations required to be performed to add touch to an end application. By using the simple API’s as illustrated in the sequence flowchart, the user can add touch sensing in his design.

Channel numbering when using QTouch acquisition method

Channel numbering when routing SNS and SNSK pins to different ports
Channel numbering when routing SNS and SNSK pins to different ports with pin configurability
Channel numbering when routing SNS and SNSK pins to the same port
Channel numbering when routing SNS and SNSK pins to the same port with pin configurability

QTouch acquisition method libraries require 2 GPIO pins per channel. QTouch libraries can be configured to use 1 to 16 channels requiring 2 to 32 pins respectively. There are two options provided for connecting the SNS and SNSK pins.

The SNS and SNSK pins are connected to separate ports. ( i.e. Interport)
The SNS and SNSK pins are connected to the same port. ( i.e. Intraport)

For 8bit AVR libraries, the following list provides a look at various combinations supported.

When pin configurability is not used:

4-channel library – supports up to 4 channels using 4 consecutive pins on different SNS and SNSK ports (or) supports up to 4 channels using 8 consecutive pins on the same port used for both SNS and SNSK lines. This library requires 1 or 2 ports.
8-channel library – supports up to 8 channels using 8 consecutive pins on different SNS and SNSK ports (or) supports up to 8 channels using 16 pins spread over two ports (SNS and SNSK are on alternate pins) with SNS1 and SNSK1 pins on the first port and SNS2 and SNSK2 pins on the second port. This library requires 2 ports.
12-channel library (available only for 8bit AVR devices) – supports up to 12 channels out of which, 8 channels with 8 consecutive pins for SNS1 and SNSK1 are available on different ports and the other 4 channels with 8 consecutive pins available on the same port for both SNS and SNSK lines. This library requires a total of 3 ports.
16-channel library – supports up to 16 channels out of which, 8 channels with 8 consecutive pins for SNS1 and SNSK1 are available on different ports and the other 8 channels with 8 consecutive pins are available on a different pair of SNS2 and SNSK2 ports. This library requires a total of 4 ports.

When pin configurability is used:

4-channel library – supports up to 4 channels using any 4 pins on different SNS and SNSK ports (or) supports up to 4 channels using pins on the same port used for both SNS and SNSK lines. This library requires 1 or 2 ports.
8-channel library – supports up to 8 channels using 8 pins on different SNS and SNSK ports (or) supports up to 8 channels using pins spread over two ports (SNS and SNSK are on alternate pins) with SNS1 and SNSK1 pins on the first port and SNS2 and SNSK2 pins on the second port. This library requires 2 ports.
12-channel library (available only for 8bit AVR devices) – supports up to 12 channels out of which, 8 channels with 8 pins for SNS1 and SNSK1 are available on different ports and the other 4 channels with 8 pins available on the same port for both SNS and SNSK lines. This library requires a total of 3 ports.
16-channel library – supports up to 16 channels out of which, 8 channels with 8 pins for SNS1 and SNSK1 are available on different ports and the other 8 channels with 8 pins are available on a different pair of SNS2 and SNSK2 ports. This library requires a total of 4 ports.

Note:

When a library supports 4 channels using 8 consecutive pins on the same port, the SNS and SNSK pins are allocated alternately. This is valid for all the libraries mentioned above.
Usage of intraport configuration requires more code memory than the interport configuration. The values mentioned in the Library_selection_Guide.xls are for interport configurations. The memory consumption for intra-port will be higher to the values mentioned in the Library_selection_Guide.xls
The configurations on pin configurability should be used in conjunction with the rules for assigning the pins that are described in section 5.8.2

For UC3 and ATSAM libraries, an n- channel library supports up to n channels using n consecutive pins on different SNS and SNSK ports (or) supports up to n channels using (2*n) consecutive pins on the same port used for both SNS and SNSK lines. This library requires 1 or 2 UC3 or ATSAM ports. In addition to this, for the ATSAM libraries the pins can be configured on 3 ports based on the configuration selected.

NOTE:

Some of the devices in UC3 family has ports having more than 32 pins or less than 32 pins.In those devices, the mapping is given as below:

GPIO Port0 -> A

GPIO Port1 -> B

GPIO Port2 -> C

GPIO Port3 -> X

Example SNS=A and SNSK=X, So channel 0 will be (SNS0 = GPIO0_Pin0 and SNSK0 = GPIO3_Pin0 ).

Similarly,Example SNS=X and SNSK=X, So channel 0 will be (SNS0 = GPIO3_Pin0 and SNSK0 = GPIO3_Pin1 ).

Figure 5‑7 : Sequence of operations to add Touch capability

Channel numbering when routing SNS and SNSK pins to different ports

Figure 5-7 illustrates a sample QTouch capacitive sensing solution which uses four ports (two port pairs ) on a device for routing the SNS and SNSK lines required.

When SNS and SNSK pins are available on different ports, the channel numbering follows the pin numbering in the ports selected, when pin configurability is not used.

The channel numbers follow the pin numbers starting with the LSB (pin 0 is channel 0 and pin 7 is channel 7).
When a library on corresponding device is configured to use more than two ports for SNS and SNSK pins, the channel numbers in the second set of SNS/SNSK port pair continue from the preceding pair as illustrated in Figure 5-7(pin 0 of next port pair is channel 8 and pin 7 of the next port pair is channel 15).
Support for more than one pair of SNS and SNSK ports are not available for UC3™ devices.
SNS pins within a single port and SNSK pins within another single port can only be used as channels for slider/rotor. Slider/Rotor channels cannot share SNS/SNSK pins on different ports.
Since the channel numbers are fixed to the pins of the SNS and SNSK ports, if the design calls for use of a subset of the pins available in the SNS and SNSK ports, the user has to skip the channel numbers of the unused SNS and SNSK pins.

Figure 5‑8 : channel numbering for QTouch acquisition method when the SNS and SNSK pins are connected to different ports.

Channel numbering when routing SNS and SNSK pins to different ports with pin configurability

When SNS and SNSK pins are available on different ports, the channel numbering follows the pin numbering in the ports selected based on SNS_array and SNSK_array bits enabled.The pins which needs to be used for touch should be provided in the Pin Configurator Wizard in QTouch Studio and the pin configurator Wizard tool will generate the SNS_array and SNSK_array masks and channel numbering will be based on which pins are enabled for touch in consecutive way.Below is an example to illustrate the same:

Example:

SNS and SNSK pins are configured with few rules keeping in mind as illustrated in section

Pins A0 ,A1,A4 and A6 of PORT A are SNS pins and pins B2,B3,B5,B7 are SNSK pins of PORT B.

Channel 0 will be forming a SNS-SNSK pair as A0B2.

Channel 1 will be forming a SNS-SNSK pair as A1B3

Channel 2 will be forming a SNS-SNSK pair as A4B5

Channel 3 will be forming a SNS-SNSK pair as A6B7.

The channel numbering is not dependent on the pin numbering.

Channel numbering when routing SNS and SNSK pins to the same port

When SNS and SNSK pins are connected to the same port, the even pin numbers will be used as SNS pins and the odd pins will be used as the SNSK pins.

The number of channels supported will be limited 4 channels for an 8-bit device and 16 channels for a 32-bit device (e.g. UC3).
For e.g., for a 4 channel configuration where the SNS and SNSK pins are connected to Port B, the port pins 0&1 are used for channel 0.
The channel number is derived from the position of the pins used for SNS and SNSK lines for any channel.

channel number = floor( [SNS(or SNSK) pin number] / 2 )

For e.g., pins 4 and 5 are connected to a SNS/SNSK pair and the channel number associated with the SNS/SNSK pin is 2.

Figure 5‑9 : Channel numbering for QTouch acquisition method when the SNS and SNSK pins are connected to the same port

Channel numbering when routing SNS and SNSK pins to the same port with pin configurability

When SNS and SNSK pins are connected to the same port, different pins can be used as SNS and SNSK pins.But SNS and SNSK pins are configured with few rules keeping in mind as illustrated in section

Example:

Pins A0 ,A3 and A5 of PORT A are SNS pins and pins A2,A4,A7 are SNSK pins of PORT A.

Channel 0 will be forming a SNS-SNSK pair as A0A2.

Channel 1 will be forming a SNS-SNSK pair as A3A4

Channel 2 will be forming a SNS-SNSK pair as A5A7.

The channel numbering is not dependent on the pin numbering.

Channel numbering when using QMatrix acquisition method

Figure 5-9 illustrates a QMatrix capacitive sensing solution which uses 4 X lines and 4 Y lines thereby providing a 16 channel solution.

Note:

All channels selected for a specific rotor or slider should be on a single Y line.
The choice of ports for X and Y lines is left to the user to based on the availability of the pins available in the particular device selected. Please refer to the section 5.8.2 for more details configuring of touch sensing pins for QMatrix.

The channel numbering for QMatrix configuration follows a matrix pattern with the channel numbers starting from 0 for the matrix intersection (X0Y0 ) and increasing along the X lines for a given Y line ( Channel 1 is X1Y0 ) and then moving on to the row number 0 for the next column. Table 1 lists the possible channel numbers and the associated X/Y line associations for the different configurations of QMatrix library variants.

A group of channels form a sensor and the sensor numbering is determined by the order in which the user defines the association of channels and uses them as a sensor.

The channel numbering is fixed for a specific library variant based on the number of X and Y lines used whereas the sensor numbering is determined at the time of usage based on the order in which the user defines the association of the channels to create a sensor.

Figure 5‑10: Channel Numbering for QMatrix acquisition method libraries

Table 1 : Channel numbers for QMatrix configurations

Line label	4 channel configuration (4 x 1)	8 channel configuration (4 x 2)	16 channel Configuration (8 x 2)	16 channel Configuration (4 x 4)	32 channel configuration (8 x 4)	56 channel configuration (8 x 7)	64 channel configuration (8 x 8)
Channel 0	X0Y0	X0Y0	X0Y0	X0Y0	X0Y0	X0Y0	X0Y0
Channel 1	X1Y0	X1Y0	X1Y0	X1Y0	X1Y0	X1Y0	X1Y0
Channel 2	X2Y0	X2Y0	X2Y0	X2Y0	X2Y0	X2Y0	X2Y0
Channel 3	X3Y0	X3Y0	X3Y0	X3Y0	X3Y0	X3Y0	X3Y0
Channel 4	N/A	X0Y1	X4Y0	X0Y1	X4Y0	X4Y0	X4Y0
Channel 5	N/A	X1Y1	X5Y0	X1Y1	X5Y0	X5Y0	X5Y0
Channel 6	N/A	X2Y1	X6Y0	X2Y1	X6Y0	X6Y0	X6Y0
Channel 7	N/A	X3Y1	X7Y0	X3Y1	X7Y0	X7Y0	X7Y0
Channel 8	N/A	N/A	X0Y1	X0Y2	X0Y1	X0Y1	X0Y1
Channel 9	N/A	N/A	X1Y1	X1Y2	X1Y1	X1Y1	X1Y1
Channel 10	N/A	N/A	X2Y1	X2Y2	X2Y1	X2Y1	X2Y1
Channel 11	N/A	N/A	X3Y1	X3Y2	X3Y1	X3Y1	X3Y1
Channel 12	N/A	N/A	X4Y1	X0Y3	X4Y1	X4Y1	X4Y1
Channel 13	N/A	N/A	X5Y1	X1Y3	X5Y1	X5Y1	X5Y1
Channel 14	N/A	N/A	X6Y1	X2Y3	X6Y1	X6Y1	X6Y1
Channel 15	N/A	N/A	X7Y1	X3Y3	X7Y1	X7Y1	X7Y1
Channel 16	N/A	N/A	N/A	N/A	X0Y2	X0Y2	X0Y2
Channel 17	N/A	N/A	N/A	N/A	X1Y2	X1Y2	X1Y2
Channel 18	N/A	N/A	N/A	N/A	X2Y2	X2Y2	X2Y2
Channel 19	N/A	N/A	N/A	N/A	X3Y2	X3Y2	X3Y2
Channel 20	N/A	N/A	N/A	N/A	X4Y2	X4Y2	X4Y2
Channel 21	N/A	N/A	N/A	N/A	X5Y2	X5Y2	X5Y2
Channel 22	N/A	N/A	N/A	N/A	X6Y2	X6Y2	X6Y2
Channel 23	N/A	N/A	N/A	N/A	X7Y2	X7Y2	X7Y2
Channel 24	N/A	N/A	N/A	N/A	X0Y3	X0Y3	X0Y3
Channel 25	N/A	N/A	N/A	N/A	X1Y3	X1Y3	X1Y3
Channel 26	N/A	N/A	N/A	N/A	X2Y3	X2Y3	X2Y3
Channel 27	N/A	N/A	N/A	N/A	X3Y3	X3Y3	X3Y3
Channel 28	N/A	N/A	N/A	N/A	X4Y3	X4Y3	X4Y3
Channel 29	N/A	N/A	N/A	N/A	X5Y3	X5Y3	X5Y3
Channel 30	N/A	N/A	N/A	N/A	X6Y3	X6Y3	X6Y3
Channel 31	N/A	N/A	N/A	N/A	X7Y3	X7Y3	X7Y3
Channel 32	N/A	N/A	N/A	N/A	N/A	X0Y4	X0Y4
Channel 33	N/A	N/A	N/A	N/A	N/A	X1Y4	X1Y4
Channel 34	N/A	N/A	N/A	N/A	N/A	X2Y4	X2Y4
Channel 35	N/A	N/A	N/A	N/A	N/A	X3Y4	X3Y4
Channel 36	N/A	N/A	N/A	N/A	N/A	X4Y4	X4Y4
Channel 37	N/A	N/A	N/A	N/A	N/A	X5Y4	X5Y4
Channel 38	N/A	N/A	N/A	N/A	N/A	X6Y4	X6Y4
Channel 39	N/A	N/A	N/A	N/A	N/A	X7Y4	X7Y4
Channel 40	N/A	N/A	N/A	N/A	N/A	X0Y5	X0Y5
Channel 41	N/A	N/A	N/A	N/A	N/A	X1Y5	X1Y5
Channel 42	N/A	N/A	N/A	N/A	N/A	X2Y5	X2Y5
Channel 43	N/A	N/A	N/A	N/A	N/A	X3Y5	X3Y5
Channel 44	N/A	N/A	N/A	N/A	N/A	X4Y5	X4Y5
Channel 45	N/A	N/A	N/A	N/A	N/A	X5Y5	X5Y5
Channel 46	N/A	N/A	N/A	N/A	N/A	X6Y5	X6Y5
Channel 47	N/A	N/A	N/A	N/A	N/A	X7Y5	X7Y5
Channel 48	N/A	N/A	N/A	N/A	N/A	X0Y6	X0Y6
Channel 49	N/A	N/A	N/A	N/A	N/A	X1Y6	X1Y6
Channel 50	N/A	N/A	N/A	N/A	N/A	X2Y6	X2Y6
Channel 51	N/A	N/A	N/A	N/A	N/A	X3Y6	X3Y6
Channel 52	N/A	N/A	N/A	N/A	N/A	X4Y6	X4Y6
Channel 53	N/A	N/A	N/A	N/A	N/A	X5Y6	X5Y6
Channel 54	N/A	N/A	N/A	N/A	N/A	X6Y6	X6Y6
Channel 55	N/A	N/A	N/A	N/A	N/A	X7Y6	X7Y6
Channel 56	N/A	N/A	N/A	N/A	N/A	N/A	X0Y7
Channel 57	N/A	N/A	N/A	N/A	N/A	N/A	X1Y7
Channel 58	N/A	N/A	N/A	N/A	N/A	N/A	X2Y7
Channel 59	N/A	N/A	N/A	N/A	N/A	N/A	X3Y7
Channel 60	N/A	N/A	N/A	N/A	N/A	N/A	X4Y7
Channel 61	N/A	N/A	N/A	N/A	N/A	N/A	X5Y7
Channel 62	N/A	N/A	N/A	N/A	N/A	N/A	X6Y7
Channel 63	N/A	N/A	N/A	N/A	N/A	N/A	X7Y7

Sensor Numbering

The ordering and numbering of sensors is related to the order in which the sensors are enabled. This is independent of the acquisition method (QMatrix or QTouch acquisition method libraries).

For example, consider this code snippet:

….

/* enable slider */

qt_enable_slider (CHANNEL_0, CHANNEL_2, AKS_GROUP_1, 16, HYST_6_25, RES_8_BIT, 0);

/* enable rotor */

qt_enable_rotor (CHANNEL_3, CHANNEL_5, AKS_GROUP_1, 16, HYST_6_25, RES_8_BIT, 0);

/* enable keys */

qt_enable_key (CHANNEL_6, AKS_GROUP_2, 10, HYST_6_25);

qt_enable_key (CHANNEL_7, AKS_GROUP_2, 10, HYST_6_25);

In the case above, the slider on channels 0 to 2 will be sensor 0, the rotor on channels 3-to-5 is sensor 1 and the keys on channels 6 and 7 are sensor numbers 3 and 4 respectively.

When the touch status is reported or queried, the corresponding sensor positions and status indicate the touch status. For example, the slider is in detect if “qt_measure_data. qt_touch_status.sensor_states” bit position 0 is set. Similarly, the rotor on channels 3 to 5 is sensor 1, and the keys on channels 6 and 7 are sensors 2 and 3 respectively.

However, the code could be re-arranged as follows to give a different sensor numbering.

/* enable rotor */

qt_enable_rotor (CHANNEL_3, CHANNEL_5, NO_AKS_GROUP, 16, HYST_6_25, RES_8_BIT, 0);

/* enable keys */

qt_enable_key (CHANNEL_6, AKS_GROUP_2, 10, HYST_6_25);

qt_enable_key (CHANNEL_7, AKS_GROUP_2, 10, HYST_6_25);

/* enable slider */

qt_enable_slider (CHANNEL_0, CHANNEL_2, NO_AKS_GROUP, 16, HYST_6_25, RES_8_BIT, 0);

Now, the rotor is sensor 0, the keys are sensors 1 and 2, and the slider is sensor 3.

So, the order in which the user enables the sensors is the order in which the sensors are numbered. Depending on the user requirements, the sensors can be configured in the preferred order.

NOTE: In case of QMatrix, the channels on the Unused X lines (or) unused Y lines should be ignored and not to be used as arguments in this API.

Ex: If the host application needs only 24 channels , there are two possible options.

In 32 (8x4 configuration), if X6 and X7 are unused, channel6, channel7, channel14, channel15, channel 22, channel23, channel30, channel 31 cannot be used
In 32 (8x4 configuration), if Y3 is unused, channe24, channel25, channel26, channel27, channel 28, channel29, channel30, channel 31 cannot be used

Filtering Signal Measurements

The ATMEL QTouch Library API provides a function pointer called “qt_filter_callback”. The user can use this hook to apply filter functions to the measured signal values.

If the pointer is non-NULL, the library calls the function after library has made capacitive channel measurements, but before the library has processed the channel information and determining the sensor states.

Figure 5‑11 : Block diagram to represent usage of filter callback function

Example: Averaging the Last Four Signal Values

1. Add a static variable in the main module:

/* filter for channel signals */

static uint16_t filter[QT_NUM_CHANNELS][4];

2. Add a filter function prototype to the main module:

/* example signal filtering function */

static void filter_data_mean_4( void );

3. When configuring the ATMEL QTouch library, set the callback function pointer:

/* set callback function */

qt_filter_callback = filter_data_mean_4;

4. Add the filter function:

void filter_data_mean_4( void )

{

uint8_t i;

/*

* Shift previously stored channel signal data.

* Store new channel signal data.

* Set library channel signal data = mean of last 4 values.

*/

for( i = 0u; i < QT_NUM_CHANNELS; i++ )

{

filter[i][0] = filter[i][1];

filter[i][1] = filter[i][2];

filter[i][2] = filter[i][3];

filter[i][3] = qt_measure_data.channel_signals[i];

qt_measure_data.channel_signals[i] = ( ( filter[i][0] +

filter[i][1] +

filter[i][2] +

filter[i][3] ) / 4u );

}

The signal values processed by the ATMEL QTouch Library are now the mean of the last four actual signal values.

Allocating unused Port Pins for User Application

The GPIO pins within a port that are not used for QTouch or QMatrix acquisition methods can be used for user application. The usage of pins for QTouch is based on the channels that are being configured while enabling the sensors (keys/rotors/sliders).

The example below configuring 4 keys, a rotor and a slider shows how the pin configurability is achieved by configuring the sensor channels. The code snippet configures a specific 10 channels of a 16 channel library based on the GPIO port pins available for QTouch™.

Channel/Pin Configuration:

/* enable a key on channel 0 */

qt_enable_key( CHANNEL_0, AKS_GROUP_2, 10u, HYST_6_25 );

/* enable a slider on channels 2 to 4 */

qt_enable_slider( CHANNEL_2, CHANNEL_4, AKS_GROUP_1, 16u, HYST_6_25, RES_8_BIT, 0u );

/* enable a key on channel 6 */

qt_enable_key( CHANNEL_6, AKS_GROUP_2, 10u, HYST_6_25 );

/* enable a key on channel 7 */

qt_enable_key( CHANNEL_7, AKS_GROUP_2, 10u, HYST_6_25 );

/* enable a rotor on channels 12 to14 */

qt_enable_rotor( CHANNEL_12, CHANNEL_14, AKS_GROUP_1, 16u, HYST_6_25, RES_8_BIT, 0u );

/* enable a key on channel 15 */

qt_enable_key( CHANNEL_15, AKS_GROUP_2, 10u, HYST_6_25 );

The channel numbers 0,2,3,4,6,7 are allocated to pins 0,2,3,4,6,7 of (D,C) port pair respectively. Pins 1 and 5 of ports C and D can be used for user application. Similarly the channel numbers 12,13,14,15 are allocated to pins 4,5,6,7 of (B,A) port pair respectively. Pins 1, 2, 3 and 4 of ports B and A are again unused by the QTouch library and can be used for user application.

Disabling and Enabling of Pull-up for AVR devices

The Pull-up circuit available (in AVR devices) for each GPIO pin has to be disabled before QTouch acquisition is performed. For tinyAVR and megaAVR devices the Pull-up circuit for all GPIO port pins are enabled and disabled together. When user needs to configure the pins that are not used by QTouch library for his application, he may enable the Pull-up circuit after QTouch measurements are performed and disable them before the touch acquisition starts once again (as shown in the code snippet below).

/* Disable pull-ups for all pins */

MCUCR |= (1u << PUD); //MCUCR_PUD = 1u;

/* perform QTouch measurements */

qt_measure_sensors ( current_time_ms_touch );

/* Enable pull-ups for all pins */

MCUCR &= ~ (1u << PUD); //MCUCR_PUD = 0u;

For XMEGA devices the Pull-up circuit for each individual GPIO port pins can be configured individually, by writing to the PINnCTRL register of the ports being used.

Constraints

QTouch acquisition method constraints
QMatrix acquisition method constraints
Design Guidelines for QMatrix acquisition method systems

QTouch acquisition method constraints

QTouch acquisition method libraries are available for different port combinations.

Some of the key constraints while configuring the sensors are

Rotors/sliders have to be connected on three adjacent channels. (e.g. (1,2,3) or (3,4,5) …) within the same port. Possible combinations are (0,1,2), (1,2,3) for a configuration which supports 4 channels. Possible combinations (0,1,2), (1,2,3), (2,3,4), (3,4,5), (4,5,6), (5,6,7) for a configuration which supports 8 channels.
If two port pairs are used for the design, all the channels for a sensor have to be connected on a single port pair. Combining channels from multiple ports is not possible when designing sensors. e.g. It is not possible to have a rotor with channel numbers ( 7,8,9 ) on a 16 channel library variant which uses two port-pairs.

Note: The above constraints are explained with respect to 8bit AVR. The same could be extended to 32bit AVR and ATSAM for 32 channel libraries where each port has 32 pins.

QMatrix acquisition method constraints

QMatrix acquisition method libraries are available for a set of AVRs The library variants can be configured to have port and pin assignments for X, Ya, Yb and SMP. Please refer to section 5.8.2 for port-pin configurability.

Some of the key constraints are

The QMatrix acquisition method libraries internally use TIMER1 for the operation,

TIMER1 will not be available for critical sections of the code where the library is called. But resources are available to the host application when the normal user’s application is running.

In case of XMEGA™ devices, the resources are used internal to the library and hence cannot be used by the host application
The sensor channel number and the relation with X and Y lines strictly follows from the table provided in the section Table 1.
A rotor /slider sensor can be configured with 3 to 8 channels per rotor or slider depending on the requirement of the application subject to the total number of channels available in the library variant selected as listed below.

Number of channels	X x Y	Maximum Channels per ROTOR_SLIDER
4	4 x 1	4
8	4 x 2	4
16	4 x 4	4
16	8 x 2	8
32	8 x 4	8
56	8 x 7	8
64	8 x 8	8

For example, 16 channel libraries with 4X and 4Y lines supports maximum of 4 channels per Rotor/Slider. But, a 16 channel with 8X and 2Y lines supports maximum of 8 channels per Rotor/Slider.
If the lines of the Drive and Receive electrode (X lines or the Y lines) share the same lines with the JTAG, JTAG needs to be disabled. Please check the data sheet to ensure that there are no conflicts between the X/Y lines and JTAG lines used for the device.
YB line for a particular device cannot be changed and it has to be the configured to be the ADC port of the selected device.
The AIN0 pin of the device needs to be connected to the GND.
In case of XMEGA devices, the reference pin for input to analog comparator is Pin7 of PORTA with all the combinations of libraries supported. Hence, this needs to be connected to GND
Proper grounding should be taken care when the controller board and touch sensing board are different.
The channels used for an individual rotor or slider should all be on the same Y line.
The maximum number of Rotors / Sliders supported by the QMatrix acquisition method depends on the configuration. Refer to the Library_Selection_Guide.xls for details.
Vcc should be kept at 4.5V or lower for reliable operation

Design Guidelines for QMatrix acquisition method systems

AVR Microcontrollers can use a number of clock sources, ranging from high precision external crystals to less accurate resonators down to simple external RC circuits. Most AVR devices also come with integrated RC oscillators. This provides a system clock source without additional cost or board space. When using internal RC oscillators some considerations need to be taken. The accuracy i.e. frequency of CMOS RC oscillators will vary slightly from device to device due to process variance.

QMatrix acquisition method uses an internal timer to measure the discharge time of a capacitor, and any frequency variation or fluctuation in the RC Oscillator will thus show up as a variance in the measurement data. The application should for this reason be designed and tuned to allow for such variance in the internal RC oscillator frequency. For most AVR microcontrollers, the rated accuracy of the internal RC oscillator is 2%, and to have some headroom and guarantee a robust and stable system, the designer should aim to follow these design rules:

Reference Value should be in the 150-300 range
Typical delta when touched should be at least 10% of the Reference Value
Recommended threshold should be at least 5% of the reference value and at least 50% of the typical delta (Higher value gives better robustness)
Hysteresis should be as high as possible in noisy systems (50%)
DI should be set to at least 4

If the design of the system does not comply with the rules above, special attention should be taken when testing it to make sure that the design meets the desired performance. In systems with big signal values and small deltas (i.e. less than 10%) it is recommended to either change component values to conform to the 10% delta rule, or change to a higher precision clock source.

QTouch Composer is the preferred tool when checking and validating any QTouch Designs.

Frequency of operation (Vs) Charge cycle/dwell cycle times:

The library needs different charge / dwell cycles based on the operation and design. The charge/dwell cycles are determined by the QT_DELAY_CYCLES parameter defined by the user. The recommended range of charge/dwell cycle times that the user must select based on the operating clock frequency of the Microcontroller is provided in the table below.

Fine tuning of the QT_DELAY_CYCLES to match the sensor design may be done by monitoring the reference levels, and finding the charge/dwell time where the reference level has reached >99% of maximum reference value seen. For QTouch acquisition method, the reference value will decrease as the QT_DELAY_CYCLES is increased. For QMatrix acquisition method, the reference value will increase with increase in QT_DELAY_CYCLES. If the cycle time is not optimum, the design may experience temperature sensitivity.

Possible values:

The following table lists the possible values of QT_DELAY_CYCLES for both QTouch and QMatrix acquisition method libraries.

Acquisition method	Possible values
QTouch	Any value from 1- 255 for 8bit AVR 3,4,5,10,25,50 for UC3 and ATSAM libraries
QMatrix	1,2,3,4,5,10,25,50

Acquisition method

Possible values

QTouch

Any value from 1- 255 for 8bit AVR

3,4,5,10,25,50 for UC3 and ATSAM libraries

QMatrix

1,2,3,4,5,10,25,50

Example:

When operating at 4 MHz, 1~10 cycle charge times are recommended (0.125us to 1.25us).

Table 2 : Frequency of operation

Frequency of Microcontroller (MHz))	microcontroller Cycle time (us)	Suitable Charge Cycle times (or) Suitable Dwell Cycle times (us)
1	1	1 to 2 cycles (1us to 2us)
2	0.5	1 to 5 cycles (0.5us to 2.5us)
4	0.25	1 to 10 cycles (0.25us to 2.5us)
8	0.125	1 to 10 cycles (0.125us to 1.25us)
10	0.1	2 to 25 cycles (0.2us to 2.5us)
16	0.0625	2 to 25 cycles (0.125us to 1.5625us)
20	0.05	3 to 50 cycles (0.15us to 2.5us)
48	0.02083	5~50 cycles (0.104us to 1.04us)
>48	<0.02083	5 to < 50 (up to 255 cycles for 8bit AVR)

Note:

For UC3 and ATSAM devices, 1 & 2 charge cycle delay times are not supported.

If the microcontroller is only used for Touch detection then running at the lowest frequency possible for the desired touch response may provide the best power and EMC performance. If it is also used for other functions then running at a higher frequency may be necessary. In some power critical applications it may be worth switching the frequency on the fly, such as lowering the frequency during touch detect API instead of using long cycle times, and then switching to a higher frequency for non-touch code. It is necessary to carefully design timer operation when change frequencies.

Interrupts

This section illustrates the usage of interrupts during qt_measure_sensors call. The library disables interrupts for time-critical periods during touch sensing. These periods are generally only a few cycles long, and so host application interrupts should remain responsive during touch sensing. However, any interrupt service routines (ISRs) during touch sensing should be as short as possible to avoid affecting the touch measurements or the application responsiveness.

Interrupts are disabled once for each signal count/burst pulse and this is typically 65 instruction cycles when Delay cycles (QT_DELAY_CYCLE=1).

The number of times interrupts are disabled during one measurement will depend on signal count of a channel as well as the number of channels and port configuration like interport (SNS and SNSK on different port)/intraport (SNS and SNSK on same port).

Example- 4 channel intraport case:

Channel0 is formed by PA0 and PA1 pin with signal count 300.

Channel1 is formed by PA2 and PA3 pin with signal count 200.

Channel2 is formed by PA4 and PA5 pin with signal count 250

Channel3 is formed by PA6 and PA7 pin with signal count 150

In the above case, the no of times interrupts disabled will be 300 (maximum signal count) as all four channels burst together in case of intraport.

Example- 4 channel interport case:

Channel0 is formed by PA0 and PB0 pin with signal count 300.

Channel1 is formed by PA1 and PB1 pin with signal count 200.

Channel2 is formed by PA2 and PB2 pin with signal count 250

Channel3 is formed by PA3 and PB3 pin with signal count 150

In the above case, as bursting happens in odd and even pairs, so maximum signal counts in case of both even and odd channels will be taken. Maximum signal count out of even channels channel0 and channel2 is 300 and maximum signal count out of odd channels channel1 and channel3 is 250.So total number of times interrupts disabled will be (300 + 250 = 550).

If the ISR load is constant and synced with the acquisition (meaning the ISR takes a constant amount of time and executes in the same amount of time during each burst sequence), the signal will not suffer at all since the self discharge will be the same every time the acquisition is run. If there is a strong variation in the total ISR execution time during acquisition this will appear as noise in the signal due to the variable self discharge of the sample cap.

The time to execute one measurement will depend on various parameters like sampling capacitor, operating voltage, and different software parameters like QT_DELAY_CYCLES, CPU frequency.

For single button with below parameters

Sampling Capacitor = 10 nf

CPU Freq= 4 MHZ

VCC= 5V

QT_DELAY_CYCLES=1

Qtouch takes around 2.6 msec for one channel.

Please note that none of the API functions should be called from a user interrupt.

Integrating QTouch libraries in your application

Directory structure of the library files
Integrating QTouch acquisition method libraries in your application
Integrating QMatrix acquisition method libraries in your application
Common checklist items

This section illustrates the key steps required in integrating the QTouch library in your application.

Directory structure of the library files

Table 1 :The QTouch library directory structure is as listed below

What	Where			Comments
Root Installation	Default directory is C:\Program Files\Atmel\ Atmel_QTouch_Libraries_5.x\Generic_QTouch_Libraries			This is the default directory path but the user can install the directory in desired location.
Header File	..\include			touch_api.h is located in this directory.touch_api_2kdevic.h for 2K devices support is also added in this directory
Configuration and assembler routines for acquisition	QTouch acquisition method libraries	8-bit devices	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AVR_Tiny_Mega_XMega\QTouch\ common_files	qt_asm_avr.h, qt_asm_tiny_mega.S, qt_asm_xmega.S, qt_asm_avr_config_2kdevice.h, qt_asm_tiny_mega_2kdevice.S
		UC3	Not needed for UC3 devices
		ATSAM	Not needed for ATSAM devices
	QMatrix acquisition method libraries	8-bit devices	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AVR_Tiny_Mega_XMega\QMatrix\ common_files	qm_asm_avr.h, qm_asm_tiny_mega.S, qm_asm_m8535_m16.S, qm_asm_xmega.S, qm_asm_tiny_mega_m64_v3g4_avr51g1.S
	QMatrix acquisition method libraries	UC3	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries\32bit_AVR\UC3\QMatrix\ common_files	touch_config.h, touch_qm_config32_assembler.h, qm_asm_uc3c_gcc.x, qm_asm_uc3c_iar.s82
Library files	QTouch acquisition method libraries	8-bit devices	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AVR_Tiny_Mega_XMega\QTouch\ library_files	All libraries ( .r90 for IAR and .a for GCC) for the supported 8 bit devices are in this location. Also r82 libraries for AVR 32 bit devices are also here
		UC3	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \32bit_AVR\UC3\QTouch\library_files
		ATSAM	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AT91SAM\SAM3\QTouch\library_files, ..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AT91SAM\SAM4\QTouch\library_files
	QMatrix acquisition method libraries	8-bit devices	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AVR_Tiny_Mega_XMega\QMatrix\library_files
	QMatrix acquisition method libraries	UC3	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries\32bit_AVR\UC3\QMatrix\ library_files
Example Projects	QTouch acquisition method libraries	8-bit devices	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AVR_Tiny_Mega_XMega\QTouch\ example_projects	All example projects using the libraries above (IAR and GCC) for the supported devices are in this location
		UC3	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \32bit_AVR\UC3\QTouch\example_projects
		ATSAM	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries\AT91SAM\SAM3\QTouch\example_projects, ..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries\AT91SAM\SAM4\QTouch\ example_projects\SAM4S_XPLAINED_DEMO_APPLICATION1
	QMatrix acquisition method libraries	8-bit devices	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AVR_Tiny_Mega_XMega\ QMatrix\example_projects
	QMatrix acquisition method libraries	UC3	..\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries\32bit_AVR\UC3\QMatrix\ example_projects

Integrating QTouch acquisition method libraries in your application

Example for 8bit AVR
Example for ATSAM
Checklist of items for integrating QTouch acquisition method libraries

The following steps illustrate how to add QTouch acquisition method support in your application.

QTouch acquisition method library variants are offered for IAR and AVR Studio/GCC tool chains. First step is to select the compiler tool chain to be used based on the code and data memory requirements. The list of supported compiler tool chains can be found in 5.7.1.2.
Use the library selection guide (C:\ Program Files\Atmel\Atmel_QTouch_Libraries_5.x\ Library_Selection_Guide.xls) to select the QTouch acquisition method library variant required for the device.
1. There are specific library variants distributed for each microcontroller. You would need the following parameters to identify the right library variant to be used in your application
  1. The microcontroller to be used for the application.
  2. The acquisition method to be used for the application.
  3. The number of channels you need for the application.
  4. Whether Rotor and/or Slider support required in the application.
  5. The number of rotors and/or slider needed for the application.
2. There are specific variants of the library which is pre-built with a specific configuration set supported. Use the library selection guide (C:\ Program Files\Atmel\ Atmel_QTouch_Libaries_5.x\Library_Selection_Guide.xls) to find the sample project using the QTouch acquisition method library variant.

Define the constants and symbol names required

The next step is to define certain constants and symbols required in the host application files where the touch API is going to be used.
The constant/symbol names are as listed in the table below.

The constant/symbol definitions can be placed in the touch_config.h file. The user may modify these defined values based on the requirements.

Table 2 : Constant and symbol name definitions required to use the QTouch acquisition method libraries

Symbol / Constant name	Range of values	Comments
_QTOUCH_	This macro has to be defined in order to use QTouch libraries.
SNS1 & SNSK1	Refer to library selection guide.	To be used if only single port pair is needed for the design.
SNS1 – SNSK1 & SNS2 – SNSK2	Refer to library selection guide.	To be used if two port pairs are needed for the design.
_SNS1_SNSK1_SAME_PORT_	Comment/uncomment define	To be enabled if the same port is used for SNSK1 and SNS1 pins for QTouch. If SNSK1 and SNS1 pins are on different ports then this definition is not required.
_SNS2_SNSK2_SAME_PORT_	Comment/uncomment define	To be enabled if the same port is used for SNSK2 and SNS2 pins for QTouch. If SNSK1 and SNS1 pins are on different ports then this definition is not required.
QT_NUM_CHANNELS	4, 8, 12, 16 for tinyAVR, megaAVR and XMEGA device libraries and 8, 16, 32 for UC3 device libraries.
_ROTOR_SLIDER_	Rotor / slider can be added to the design, if this macro is enabled.	A library with rotor / slider functionality already available needs to be selected if this macro is to be enabled.
QT_DELAY_CYCLES	1 to 255	Please refer to section 5.6.8.
_POWER_OPTIMIZATION_ (Required only for ATtiny and ATmega libraries. ATxmega and UC3 libraries by default optimized for power without any limitations)	0 or 1	Used to reduce the power consumed by the library. When power optimization is enabled the unused pins, within a port used for QTouch, may not be usable for interrupt driven applications. Spread spectrum noise reduction is also disabled when power optimization is enabled.
_TOUCH_ARM_	To be defined when using ATSAM libraries	For ATSAM libraries only.
QTOUCH_STUDIO_MASKS	This macro needs to be defined if QTouch Studio Pin Configurator Wizard.is used to generate the SNS and SNSK masks.	Please refer to section 5.8.1
_STATIC_PORT_PIN_CONF_	This macro needs to be defined only in case of 4 and 8 channel libraries with interport configuration and pin configurability.	Please refer to section 5.8.1

Using QTouch API’s in your application to add touch functionality
1. The clock, host application and other peripherals needed by the host application needs to be initialized.
2. In your application, create, initialize and configure the sensors.
  1. The APIs of interest are qt_enable_key/rotor/slider(). see sections 5.6.5.2, 5.6.5.3 and 5.6.5.4.
3. The channel configuration parameters need to be set by calling the qt_set_parameters() ( see section 5.6.5.1).
4. Once the sensors are configured, qt_init_sensing() has to be called to trigger the initialization of the sensors with the configuration defined in steps above.
5. Provide timing for the QTouch libraries to operate. i,e the QTouch libraries do not use any timer resources of the microcontroller. The Host application has to provide the required timing and also call the API’s at the appropriate intervals to perform touch sense detect operations.
  NOTE: The ATSAM example applications provided with the libraries illustrate the usage for the evaluation kits supported by the library. Please refer to the main.c files for reference.
Adding the necessary source files
The following files are to be added along with the touch library and user application before compilation:
1. ATtiny, ATmega devices - touch_api.h, qt_asm_avr.h, touch_config.h and qt_asm_tiny_mega.S.
2. ATxmega devices - touch_api.h, qt_asm_avr.h, touch_config.h and qt_asm_xmega.S.
3. UC3 devices – touch_api.h.
4. ATSAM devices - touch_api.h and touch_config.h.
General application notes
1. The clock, host application and other peripherals needed by the host application needs to be initialized.
2. Ensure that there are no conflicts between the resources used by the touch library and the host application.
3. Ensure that the stack size for your application is adjusted to factor in the stack depth required for the operation of the touch libraries.

Example for 8bit AVR

Table 3 :The example below will explain in detail the steps to follow for library selection.

Criteria	Selection		Notes
Microcontroller	AVR STUDIO® IDE and GNU compiler		The GCC compiled variant of the libraries for the device selected needs to be used.
Number of Keys required for the application	3		Each key requires 1 QTouch acquisition channel
Rotors and sliders required	Yes
Number of Rotors and Sliders required	3		Each rotor / slider will require 3 channels.
Number of Channels required for the application ( should be the sum of all channels required for all the keys ,rotors and sliders used in the design )	12		3 Keys + ( 3 rotors x 3 channels per rotor/slider )  12 channels
Charge cycle time required for the design	1 cycle		Assuming the device is configured with a clock frequency of 4Mhz
Number of ports needed	3 ports		This is determined based on the number of channels required and the routing required for the channels SNS and SNSK pins to the ports For this design, 24 pins are required and we need 3 ports to support the sensors.
Choice of ports available for the design	SNS/ SNSK Pair1 ports	SNS1 Port : A	The choice of ports for the port pairs is limited and can be found in the section 5.7.1.5
	SNS/ SNSK Pair1 ports	SNSK1 Port : A
	SNS/ SNSK Pair 2 ports	SNS2 Port : B
	SNS/ SNSK Pair 2 ports	SNSK2 Port : C
Is there a need for reduced power consumption (and reduced execution time)?	_POWER_ OPTIMIZATION_ = 1		Enabling _POWER_OPTIMIZATION_ will lead to a 40% reduction in power consumed by the library, but at the expense of reduced external noise immunity. When power optimization is enabled, the unused pins within a port used for QTouch, may not be usable for interrupt driven applications. This option is available only for ATtiny and ATmega devices.
SNS1 and SNSK1 pins use the same port.	_SNS1_SNSK1_SAME_PORT_		The _SNS1_SNSK1_SAME_PORT_ symbol needs to be defined as port A is used for both SNS1 and SNSK1 pins.

Given the above requirements for the applications, the first step is to select the right library variant required.

Step 1: Selecting the right library variant

Referring to the library selection guide, we see that there are a few variants of libraries supported for ATmega1280. Since the application requires 12 channels and rotor slider support, one has to select a library variant which supports at least 12 channels or more along with 3 Rotors/Sliders. Hence we select the 12 channel library variant for GCC complier which supports the required number of sensors/channels. This works out to be libavr51g1_12qt_k_3rs.a

Step 2: Defining the constants / symbols in the project space

In the host application file (say main.c), define the following constants and symbols

#define QTOUCH_

#define QT_NUM_CHANNELS 12

#define QT_DELAY_CYCLES 1

#define _POWER_OPTIMIZATION_ 1

#define _SNS1_SNSK1_SAME_PORT_

NOTE: The above definitions are available in touch_config.h file. Alternatively, you can define these in your IDE’s project options or have them defined in a separate header file.

Step 3: Usage of library API’s

Now, you can use the touch API’s to create, initialize and perform touch sensing. Please refer to the sample applications in section 5.6.11.2 for reference. These sample applications illustrate the usage of the API’s and the sequence of operation.

Step 4: Adding necessary source files for compilation

The source files needed for compiling your application along with the touch library are touch_api.h, touch_config.h and qt_asm_tiny_mega.S.

Example for ATSAM

Table 4 : The example below will explain in detail the steps to follow for library selection.

Criteria	Selection		Notes
Microcontroller	AT91SAM3S
IDE and compiler tool chain used	IAR Workbench and GNU compiler		The GCC compiled variant of the libraries for the device selected needs to be used.
Number of Keys required for the application	3		Each key requires 1 QTouch acquisition channel
Rotors and sliders required	Yes
Number of Rotors and Sliders required	3		Each rotor / slider will require 3 channels.
Number of Channels required for the application ( should be the sum of all channels required for all the keys ,rotors and sliders used in the design )	12		3 Keys + ( 3 rotors x 3 channels per rotor/slider )  12 channels
Charge cycle time required for the design	5 cycles		Assuming the device is configured with a clock frequency of 48Mhz
Number of SNS/SNSK port pairs needed	2 pairs		This is determined based on the free PIO of the board
Choice of ports available for the design	SNS/ SNSK Pair1 ports	SNS1 Port : A	The choice of ports for the port pairs is limited and can be found in the section 5.7.1.5
	SNS/ SNSK Pair1 ports	SNSK1 Port : A
	SNS/ SNSK Pair 2 ports	SNS2 Port : B
	SNS/ SNSK Pair 2 ports	SNSK2 Port : B

Given the above requirements for the applications, the first step is to select the right library variant required.

Step 1: Selecting the right library variant

Referring to the library selection guide, we see that there are a few variants of libraries supported for AT91SAM3S. One library is for IAR and the other is for GNU. If we want to use IAR Workbench, we use the library name: libsam3s-32qt-k-8rs-iar.a.

Step 2: Defining the constants / symbols in the project space

In IAR, change preprocessor options by adding the good defines:

_SNS1_SNSK1_SAME_PORT_

_SNS2_SNSK2_SAME_PORT_

Step3: Usage of library API’s

Now, you can use the touch API’s to create, initialize and perform touch sensing.

Checklist of items for integrating QTouch acquisition method libraries

The following is a checklist of items which needs to be ensured when integrating QTouch acquisition method libraries

The clock prescaler register (e.g. CLKPR, XDIV) needs to be configured correctly based on the device selected. Some devices have clock frequency selection based on fuses. It has to be ensured the fuses are set correctly in such cases.
It is recommended to disable PULL-UP resistor on all port pins used for touch sensing on the device selected (e.g. PUD bit in MCUCR, SFIOR for a few of the tinyAVR and megaAVR devices Please refer to the Data sheet of the selected device).
The 16 bit timer in each device has been used for performing touch measurements periodically. The datasheet for all the devices have to be checked to ensure that the correct timer peripheral and its registers are used (file: main.c).
The interrupt vector macro may also change from device to device and this needs to be verified in the datasheet for the device used.
Check if the timer is configured correctly to support the measurement period needed (e.g. 25msec or 50 msec).
The sample applications for the evaluation kits and supported devices illustrate the proper initialization sequence and usage of the timer resources (file: main.c). Please use this as a reference for your application design.

The host application must provide the current time to the library. This information is passed to the library as an argument to the function qt_measure_sensors()”. This is used for time-based library operations such as drift compensation.

Integrating QMatrix acquisition method libraries in your application

Example for 8bit AVR
Example for 32bit AVR
Checklist of items for integrating QMatrix Capacitive sensing libraries

Example for 8bit AVR

Example
Resources used by QMatrix acquisition method libraries

Based on the application design needs, the user needs to select the right library variant and the configuration to be used along with the variant. This section illustrates the steps required to select the right QMatrix acquisition method library variant and configuration for your application. QMatrix acquisition method library Variants are offered for IAR and AVR-GCC tool chains. First step is to select the compiler tool chain for which the libraries are required. The list of supported compiler tool chains can be found in section 5.7.2.2

There are specific library variants distributed for each microcontroller. For your design, you would need the following information to select the correct library variant

Device to be used for the design
The number of touch sensing channels needed by the application – Then identify the Maximum number of channels required for the design that are supported by the library.
Number of X lines to be used in the design
1. The ports on which your design permits to have the X lines.
2. The X lines can be spread on a maximum of three ports, the more ports used the more is the code memory requirement by the library.
Number of Y lines to be used in the design
1. The port-pins ports on which your design permits to have the Y lines.
Do you need support for Rotors and/or Sliders in your design
1. If yes, how many rotors/sliders would be needed?
2. Based on a) above, identify the maximum number of rotors sliders that the library supports.
Which compiler platform you intend to use to integrate the libraries – IAR or AVR -GCC

Follow the steps listed below to arrive at the right library variant

Select the device from the list of supported devices listed in 5.7.2.4.1
Select the right library variant for the device selected from the selection guide available in
C:\ Program Files\Atmel\Atmel_QTouch_Libraries_5.x\Library_Selection_Guide.xls
Each variant supports
1. a specific number of channels,
2. Supports a specific configuration of X x Y matrix pins ( eg 4 x 2 for 4 - X pins & 2 - Y pins )
3. has support for Rotor / Slider ( either supported or not )
4. support is available for IAR and/or GCC compiler tool chain
5. support for specific number of rotors sliders.

Define the constants and symbol names required

The next step is to define certain constants and symbols required in the host application files where the touch API is going to be used. These values are derived from the parameters defined in step 2 for your application.
The constant/symbol names are as listed in the table below
The constant/symbol definitions can be placed in any of the following
1. In the user’s ‘C’ file prior to include touch_api.h in the file.
2. Modifying the defines in a touch_config.h available in the project folder.

Table 5 :List of configurable parameters for touch library usage.

Symbol / Constant name	Range of values	Comments
_QMATRIX_	Symbol defined to indicate QMatrix acquisition method is required	Define this symbol to indicate QMatrix acquisition method is required
QT_NUM_CHANNELS	The number of channels the library supports.( Possible values:4,8,16,32,56,64). Note: 56 channel for only ATxmega Devices.	Value should be same as the number of channels that the library supports
NUM_X_LINES	The number of X lines the library supports.( Possible values:4,8)	Value should be same as the number of X lines that the library supports. Refer to library selection guide
NUM_Y_LINES	The number of Y lines the library supports.( Possible values:1,2,4,7,8) Note: 7 Y-lines for only ATxmega Devices)	Value should be same as the number of Y lines that the library supports. Refer to library selection guide
_ROTOR_SLIDER_	Symbol defined if Rotor and/or slider is required	Needs to be added in case user needs to configure ROTOR/SLIDER Needs to be removed for ALL KEYS configuration
QT_MAX_NUM_ROTORS_SLIDERS	Maximum number of rotors/sliders the library supports( possible values:0,2,4,8)	Subject to support for rotors/sliders in the library selected.
QT_DELAY_CYCLES	Possible values :1,2,3,4,5,10,25,50	Please refer to section 5.6.8
NUM_X_PORTS	Number of ports on which the X lines needs to be spread. (Possible values 1,2,3)	Maximum number of ports that the X lines can spread is 3. Note: Code memory required increases with the increase in NUM_X_PORTS
PORT_X_1	First IO port for configuring the X lines.Any IO port available with the device.	Drive electrode for touch sensing using QMatrix acquisition Valid when NUM_X_PORTS =1,2,3
PORT_NUM_1	1	Please donot edit this macro Valid when NUM_X_PORTS =1,2,3
PORT_X_2	Second IO port for configuring the X lines. Any IO port available with the device.	Drive electrode for touch sensing using QMatrix acquisition Valid when NUM_X_PORTS =2,3
PORT_NUM_2	2	Please donot edit this macro Valid when NUM_X_PORTS =2,3
PORT_X_3	Third IO port for configuring the X lines. Any IO port available with the device.	Drive electrode for touch sensing using QMatrix acquisition Valid when NUM_X_PORTS =3
PORT_NUM_3	3	Please donot edit this macro Valid when NUM_X_PORTS =3
PORT_YA	Any IO port available with the device.	Receive electrode for touch sensing using QMatrix acquisition
PORT_YB	ADC port available for the device.	Receive electrode for touch sensing using QMatrix acquisition
PORT_SMP	Any IO port available with the device.	Port of the Sampling pin for touch sensing using QMatrix acquisition
SMP_PIN	Any IO port available with the device.	Sampling pin for touch sensing using QMatrix acquisition
_ATXMEGA_	Symbol defined if an ATxmega Device is used for QMatrix sensing technology	Needs to be added if the device to be supported is ATxmegaxxxx
SHARED_YAYB	Possible values: 0 or 1	#define SHARED_YAYB 1 in case YA and YB are on same port else 0.

Once you have selected the right library variant and configuration parameters for the application, follow the steps outlined below to integrate the library variant in your application.

Fill in the arrays x_line_info_t x_line_info[NUM_X_LINES] y_line_info_t ya_line_info[NUM_Y_LINES] and y_line_info_t yb_line_info[NUM_Y_LINES] using the pin configuration wizard provided by the QTouch Studio.
Copy the library variant that was selected in step one to your project’s working directory or update your project to point to the library selected.
Include the “touch_api.h” header file and assembler source file from the QTouch library in your application. The touch_api.h can be found in the release package at C:\Program Files\Atmel\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AVR_Tiny_Mega_XMega\QMatrix\common_files. The assembler files mentioned below could be found at the location C:\Program Files\Atmel\Atmel_QTouch_Libraries_5.x\ Generic_QTouch_Libraries \AVR_Tiny_Mega_XMega\QMatrix\common_ files
1. qm_asm_tiny_mega.S in case of ATtiny and ATmega devices.
2. qm_asm_xmega.S in case of ATxmega devices.
3. qm_asm_m8535_m16.S in case of ATmega8535 and ATmega16 devices.
Initialize/create and use the touch api’s in your application
1. In your application, create, initialize and configure the sensors.
  1. The APIs of interest are qt_enable_key/rotor/slider(). see sections 5.6.5.2, 5.6.5.3 and 5.6.5.4
2. configure the global configuration parameters valid for all the sensors in the library
3. Provide timing for the QTouch libraries to operate. i,e. the QTouch libraries do not use any timer resources of the microcontroller. The Host application has to provide the required timing and also call the API’s at the appropriate intervals to perform touch sense detect operations
General application notes
1. The clock, host application and other peripherals needed by the host application needs to be initialized.
2. The QMatrix acquisition method libraries internally use TIMER1 for their operation.
3. Ensure that there are no conflicts between the resources used by the touch library and the host application
4. Ensure that the stack size is adjusted to factor in the stack depth required for the operation of the touch libraries.

Example

Table 6 : Example details.

Criteria	Selection	Notes
Microcontroller	ATTiny88	List of supported devices can be found at Library_Selection_Guide.xls
Number of channels required for the application	6	number channels available for a Tiny88 is listed in Library_Selection_Guide.xls
Number of X lines needed	Based on the number of channels, since 8 channels is needed, 4 X lines are supported. NUM_X_LINES is 4	Since 3 X- lines (6 channels ) are used, Do not initialize 4th element in x_line_info[NUM_X_LINES]. Hence channel6, channel7 need not be used.
Number of Y lines needed	Based on the number of channels, since 8 channels is needed, 2 Y lines are supported	NUM_Y_LINES is 2.
Rotors and sliders required and Number of ROTOR/SLIDERS	Yes - 2	Library variants supported for ATTiny88 is listed in the Library_Selection_Guide.xls
X_LINES on pins as below(4-X lines) X0- B0, X1- D2,X3 – B7, X4 – B5	FILL_OUT_X_LINE_INFO(1,0), FILL_OUT_X_LINE_INFO(2,2), FILL_OUT_X_LINE_INFO(1,7),	Main file has to be edited based on the configuration. Refer to section 5.8.2.1 . Refer channel numbering from the section5.6.6.1.2 Or This can be filled from the output of the pin configurator tool in QTouch Studio. Please refer to section 5.8.2
Y_LINES on pins as below (2 Y-Lines) Y0A- D0, Y0B- C1, Y1A-D5, Y1B-C4,	FILL_OUT_YA_LINE_INFO(0), FILL_OUT_YA_LINE_INFO(5), FILL_OUT_YB_LINE_INFO(1), FILL_OUT_YB_LINE_INFO(4),	Main file has to be edited based on the configuration. Refer to section 5.8.2.1 Or This can be filled from the output of the pin configurator tool in QTouch Studio. Please refer to section 5.8.2
NUM_X_PORTS	2	Since X lines are spread on a multiple(2) ports: PORTB, PORTD
Compiler tool chain	IAR	Supported compiler tool chains listed in 5.7.2.2
Choice of ports available for the design	PORT_X_1 = B PORT_X_2 = D	Any pins that are not conflicting with the host application and follow the configuration supported by library can be used. Or This can be filled from the output of the pin configurator tool in QTouch Studio. Please refer to section 5.8.2
	YA Line on PORTD
	YB Line on PORTC
	SMP Pin on PORTD pin 7
	QT_DELAY_CYCLES of 4
Choice of Shared Ya and Yb on same port	SHARED_YAYB	This should be defined as 0 if YA and YB not shared on same port else 1 if shared on same port

Given the above requirements for the applications, the first step is to select the right library variant required.

Step 1:

Select the Device that suits the requirements based on the touch sensing channels needed from the library selection guide available at C:\ Program Files\Atmel\ Atmel_QTouch_Libraries_5.x\ Library_Selection_Guide.xls

Step 2:

From the Library_selection_Guide.xls list,, we see that there are a few variants of libraries supported for AT Tiny device. Since the application requires 6 channels and rotor slider support, one has to select a library variant which supports at least 6 channels or more. Hence we select the 8 channel library which supports the required Port combination and the delay cycle preferred which works out to be the variant

libv1g1s1_8qm_4x_2y_krs_2rs.r90

Step 3:

Defining the constants / symbols in the project space or modifying in touch_config.h

In the host application file (say main.c), define the following constants and symbols

#define _QMATRIX_

#define QT_NUM_CHANNELS 8

#define NUM_X_LINES 4

#define NUM_Y_LINES 2

#define NUM_X_PORTS 2

#define QT_DELAY_CYCLES 4

#define ROTOR_SLIDER_

#define QT_MAX_NUM_ROTORS_SLIDERS 2

#define SHARED_YAYB 0

Note1: The above definitions are available in touch_config.h file. Alternatively, you can define these in your IDE's project options or have them defined in a separate header file.

Note2:

Some of these macro’s can be taken from the output of the Pin configurator tool from QTouch Studio. Refer to section 5.8.2
These can also be modified in the touch_config.h, after defining the _QMATRIX_ in the project space.
In case XMEGA device is used for QMatrix the symbol __ATXMEGA_ has to be included in the Project space along with the symbols mentioned above.

Step 4:

Filling Arrays in the main.c file

According to the pin availability for the touch sensing, initialize the arrays in the main.c file as below:

x_line_info_t x_line_info[NUM_X_LINES]= {

FILL_OUT_X_LINE_INFO( 1,0u ),

FILL_OUT_X_LINE_INFO( 2,2u ),

FILL_OUT_X_LINE_INFO( 1,7u ),

};

y_line_info_t ya_line_info[NUM_Y_LINES]= {

FILL_OUT_YA_LINE_INFO( 0u ),

FILL_OUT_YA_LINE_INFO( 5u ),

};

y_line_info_t yb_line_info[NUM_Y_LINES]= {

FILL_OUT_YB_LINE_INFO( 0u ),

FILL_OUT_YB_LINE_INFO( 5u ),

};

Note:

This part of the snippet can be taken from the output of the Pin configurator tool from QTouch Studio.

Step 5:

Usage of libraries

Now, you can use the touch API’s to create, initialize and perform touch sensing. Please refer to the sample applications in section 5.6.11.3 for reference. These sample applications illustrate the usage of the API’s and the sequence of operation

Resources used by QMatrix acquisition method libraries

The following additional resources are used by the QMatrix acquisition method libraries.

One Analog Comparator
One internal Timer ( Usually Timer1 depending on the availability on particular microcontroller)
One ADC Multiplexer( The critical section of the touch sensing library disables the use of ADC as conversion unit and enables the same ADC as a multiplexer, but the user can use the ADC for conversion in rest of his application code )
The ADCMUX is used by the library during the touch sensing acquisition, however it is restored with the value from host application before exiting the qt_measure_sensors(). Such that the ADC is available to the host application for conversion.

In case of XMega devices, the resources are used internal to the library and hence cannot be used by the host application

Analog Comparator0 on PORTA (AC0 on PORTA)
Timer/Counter1 on PORTC (TCC1)
Event System Channel0 (EVSYS_CH0)

Example for 32bit AVR

Resources used by QMatrix acquisition method libraries for 32 Bit device

Based on the application design, the user needs to select the right library variant and the configuration to be used along with the variant. This section illustrates the steps required to select the right QMatrix acquisition method library variant and configuration for your application.

For your design, you would need the following information to select the correct library variant

Device to be used for the design(only AT32UC3C0512 supported)
The number of touch sensing channels needed by the application – Then identify the Maximum number of channels required for the design that are supported by the library.
Number of X lines to be used in the design
1. The port on which your design permits to have the X lines
2. The X lines can be spread on a single port.
Number of Y lines to be used in the design
1. The port-pins ports on which your design permits to have the Y lines
Do you need support for Rotors and/or Sliders in your design
1. If yes, how many rotors/sliders would be needed?
2. Based on a) above, identify the maximum number of rotors sliders that the library supports
Which compiler platform you intend to use to integrate the libraries – IAR or AVR -GCC

After selecting the right library variant, following steps are to be performed

Define the constants and symbol names required

The next step is to define certain constants and symbols required in the host application files where the touch API is going to be used. These values are derived from the parameters defined in step 2 for your application
The constant/symbol names are as listed in the table below

The constant/symbol definitions can be placed in any of the following:

In the user’s ‘C’ file prior to include touch_api.h in the file
Defined user’s project options.
Modify the defines in a touch_config.h
Table 7 : List of configuration parameters/macros.

Symbol / Constant name	Range of values	Comments
_QMATRIX_	Symbol defined to indicate QMatrix acquisition method is required	Define this symbol to indicate QMatrix acquisition method is required
QT_NUM_CHANNELS	The number of channels the library supports.( Possible values:4,8,16,24,32,64).	Value should be same as the number of channels that the library supports
NUM_X_LINES	The number of X lines the library supports.( Possible values:4,8)	Value should be same as the number of X lines that the library supports. Refer to library selection guide
NUM_Y_LINES	The number of Y lines the library supports.( Possible values:1,2,3,4,8)	Value should be same as the number of Y lines that the library supports. Refer to library selection guide
_ROTOR_SLIDER_	Symbol defined if Rotor and/or slider is required	Needs to be added in case user needs to configure ROTOR/SLIDER Needs to be removed for ALL KEYS configuration
QT_MAX_NUM_ROTORS_SLIDERS	Maximum number of rotors/sliders the library supports( possible values:0,2,3,4,8)	Subject to support for rotors/sliders in the library selected.
QT_DELAY_CYCLES	Possible values :1,2,3,4,5,10,25,50	Please refer to section 5.6.8
PORT_X_1	First IO port for configuring the X lines.Any IO port available with the device.	Drive electrode for touch sensing using QMatrix acquisition
PORT_YA	Any IO port available with the device.	Receive electrode for touch sensing using QMatrix acquisition
PORT_YB	Analog Comparator port available for the device.	Receive electrode for touch sensing using QMatrix acquisition
PORT_SMP	Any IO port available with the device.	Port of the Sampling pin for touch sensing using QMatrix acquisition
SMP_PIN	Any IO port available with the device.	Sampling pin for touch sensing using QMatrix acquisition
SHARED_YAYB	Possible Values 0 or 1.	Value should be 0 if Ya and Yb are not on same port else 1 if they are on same port.

Once you have selected the right library variant and configuration parameters for the application, follow the steps outlined below to integrate the library variant in your application.

Fill in the arrays x_line_info_t x_line_info[NUM_X_LINES] y_line_info_t ya_line_info[NUM_Y_LINES] and y_line_info_t yb_line_info[NUM_Y_LINES] as given in main.c file.
Filling Arrays in the main.c file
According to the pin availability for the touch sensing, initialize the arrays in the main.c file as below:
x_line_info_t x_line_info[NUM_X_LINES]= {
FILL_OUT_X_LINE_INFO( 1,0u ),
FILL_OUT_X_LINE_INFO( 1,2u ),
FILL_OUT_X_LINE_INFO( 1,7u ),
FILL_OUT_X_LINE_INFO( 1,15u ),
};
First argument of FILL_OUT_X_LINE_INFO should always be 1 as X port is only on one port.Second arguments denotes the pins on that particular port.
y_line_info_t ya_line_info[NUM_Y_LINES]= {
FILL_OUT_YA_LINE_INFO( 0u ),
FILL_OUT_YA_LINE_INFO( 5u ),
};
y_line_info_t yb_line_info[NUM_Y_LINES]= {
FILL_OUT_YB_LINE_INFO( 7u ),
FILL_OUT_YB_LINE_INFO( 22u ),
};
Yb lines are one of the inputs of the Analog Comparators.
Copy the library variant that was selected in step 1 to your project’s working directory or update your project to point to the library selected.
Include the “touch_api.h” header file and assembler source file from the QTouch library in your application. The touch_api.h can be found in the release package at C:\Program Files\Atmel\Atmel_QTouch_Libraries_5.x\Generic_QTouch_Libraries\include. The assembler files mentioned below could be found at the location C:\Program Files\Atmel\Atmel_QTouch_Libraries_5.x\Generic_QTouch_Libraries\32bit_AVR\UC3\QMatrix\common_files
1. qm_asm_uc3c_gcc.x in case of GCC compiler
2. qm_asm_uc3c_iar.s82 in case of IAR compiler.
Initialize/create and use the touch api’s in your application
1. In your application, create, initialize and configure the sensors.
  1. The APIs of interest are qt_enable_key/rotor/slider().see sections 5.6.5.2, 5.6.5.3 and 5.6.5.4
2. configure the global configuration parameters valid for all the sensors in the library
3. Provide timing for the QTouch libraries to operate. i,e. the QTouch libraries do not use any timer resources of the microcontroller. The Host application has to provide the required timing and also call the API’s at the appropriate intervals to perform touch sense detect operations
General application notes
1. The clock, host application and other peripherals needed by the host application needs to be initialized.
2. The QMatrix acquisition method libraries for 32 Bit devices internally use TIMER0 with channel0 for their operation.
3. Ensure that there are no conflicts between the resources used by the touch library and the host application

Resources used by QMatrix acquisition method libraries for 32 Bit device

Devices supported by 32 Bit Qmatrix Acquisition libraries are:

The following additional resources are used by the QMatrix acquisition method libraries.

Four Analog Comparator
One internal Timer ( Timer0 with channel0 )
Two Analog Comparator Interface ACIFA0/1.
Event System Channel 16 is used.

The device has two Analog comparator interfaces ACIFA0 and ACIFA1 .Each interface provides the flexibility to configure two analog comparators ACA and ACB comparators..UC3C has Four Comparators (AC0A , AC1A , AC0B , AC1B), So there are 10 Possible Yb lines as given in table below.

User has flexibility to configure maximum 8 Yb lines for maximum 64 channel libraries.

Table 8 : Below table states the Yblines which can be configured.

Yb LInes of the Four Analog Comparators	Port A Pins
AC0AN0(AC0A Comparator)	PA22
AC0AN1(AC0A Comparator)	PA27
AC0BP0(AC0A Comparator)	PA23
AC1AN0(AC1A Comparator)	PA13
AC1AN1(AC1A Comparator)	PA07
AC1BP0(AC1A Comparator)	PA14
AC0BN0(AC0B Comparator)	PA21
AC0BN1(AC0B Comparator)	PA29
AC1BN0(AC1B Comparator)	PA15
AC1BN1(AC1B Comparator)	PA09

These Yb lines are the negative input pins of the analog comparator.

Table 9 : To use the library, the below table shows the lines which are externally grounded for Proper Qmatrix operation.

Positive Input Pins of the Four Analog Comparators	Port A Pins
AC0AP0(AC0A Comparator)	PA20
AC0BP1(AC0B Comparator)	PA28
AC1AP0(AC1A Comparator)	PA12
AC1BP1(AC1B Comparator)	PA08

If only one comparator is used , then the corresponding pin of that comparator is properly externally grounded.Above table shows the Analog comparator usage and the corresponding lines which needs to be grounded.

The Port pin configurability is provided in the library to select any port for Ya or X lines.The Port for Yb lines is fixed which is PORTA as these lines are inputs of the Analog comparators which are fixed pins of PORTA.

Table 10 : Port pin configurability.

X,YA,YB,SMP Configurations	Ports on UC3C
X,YA,YB,SMP Configurations	PORTA	PORTB	PORTC	PORTD
X	Yes	Yes	Yes	Yes
YA	Yes	Yes	Yes	Yes
YB	Yes(only few pins of PortA can be configured as Yb Lines)	No	No	No
SMP	Yes	Yes	Yes	Yes

The configurability is provided to select X,SMP and YA lines on Same Port ,X,SMP and YB lines on same port.

Number of X ports should be 1 means the X lines should be connected to a single port.

Note: YA and YB cannot be on the same port.

SMP Pin should be less than equal to 19th pin of any Port

Checklist of items for integrating QMatrix Capacitive sensing libraries

When integrating QMatrix acquisition method libraries, ensure the following

Check that the CLKPR register is available for the selected device. If not remove the CLKPR statements.
Ensure that the configuration for the QMatrix is done in touch_config.h and the arrays of the x_line_info and y_line info are filled as indicated section 5.8.2
MCUCR register is available and if so disable pullups
Check if the timer registers and bit fields used are correct and change them if necessary.
The above settings can be modified by the user by changing the API’s that are available to the user. The API’s include
1. qt_set_parameters ( )
The host application must provide the current time.
This information is passed to the library as an argument to the function qt_measure_sensors()”. This is used for time-based library operations such as drift compensation.
The GPIO internal pull-ups must be disabled for all port pins used for touch sensing when calling the library.
For 8-bit AVR devices, this can be done by
1. Setting the “PUD” bit in the “MCUCR” register or
2. Setting the “PUD” bit in the “SFIOR” register.
Setting the JTD bit in the “MCUCR” register to disable JTAG Interface in MCU ( if available ). This can be done only when the JTAG lines are in conflict with the desired touch sensing lines
The library must be called often enough to provide a reasonable response time to user touches. The typical time to call the library is from 25 ms to 50 ms.
Care should be taken while using the ADC conversion logic and QMatrix library such that the host application waits for approximately 1msec before actually calling the qt_measure_sensors() API depending upon the ADC clock.

For 8-bit AVR devices, this can be done by

Common checklist items

Configuring the stack size for the application

Configuring the stack size for the application

The stack requirements for the QTouch library should be accounted for and the stack size adjusted in the user’s project for proper operation of the software when using the IAR IDE. This section lists the stack usage for the different variants of the QTouch and QMatrix acquisition method libraries applicable to the IAR compiler tool chain.

Note: When using the IAR IDE / compiler tool chain, the map file generated for the application will list total CSTACK & RSTACK requirements. Please adjust the total CSTACK and RSTACK values in the IAR project options to be greater than the values listed in the map file. Refer to section 5.6.11.4 which illustrates how to change the settings in IAR IDE.

Table 11 : Stack requirements of the QTouch capacitive sensing libraries when using IAR IDE projects

QTouch Acquisition method Libraries : Stack usage for IAR compiler tool chain
Configuration	CSTACK size	RSTACK size
Single port pair - only keys ( 4 / 8 channels )	0x30	0x28
Single port pair – keys/ rotors/ sliders (4/8 channel)	0x40	0x2C
Two port pairs - only keys keys (16 channel)	0x50	0x28
Two port pairs – keys/ rotors/ sliders (16 channel)	0x60	0x2C

Table 12 : Stack requirements of the QMatrix capacitive sensing libraries when using IAR IDE projects

QMatrix Acquisition method Libraries : Stack usage for IAR compiler tool chain
Number of channels	Configuration	CSTACK size	RSTACK size
4	ONLY KEYS	0x20	0x20
4	KEYS/ROTOR/SLIDER	0x30	0x20
8	ONLY KEYS	0x25	0x20
8	KEYS/ROTOR/SLIDER	0x35	0x20
16	ONLY KEYS	0x30	0x20
16	KEYS/ROTOR/SLIDER	0x40	0x20
32	ONLY KEYS	0x35	0x25
32	KEYS/ROTOR/SLIDER	0x45	0x25
56	ONLY KEYS	0x45	0x25
56	KEYS/ROTOR/SLIDER	0x55	0x25
64	ONLY KEYS	0x45	0x25
64	KEYS/ROTOR/SLIDER	0x55	0x25

Example project files

Using the Sample projects
Example applications for QTouch acquisition method libraries
Example applications for QMatrix acquisition method libraries
Adjusting the Stack size when using IAR IDE
Optimization levels
Debug Support in Example applications

The QTouch library is shipped with various example projects to illustrate the usage of the touch API’s to add touch sensing to an application across various devices

Sample applications are also provided for the following kits

TS2080A, QT600_ATtiny88_QT8, QT600_ATxmega128a1_QT16 : QTouch Technology evaluation Kits
TS2080B, QT600_ATmega324_QM64 : QMatrix Technology evaluation Kits

Note: Example projects must be built in the installed folder, and if moved/copied elsewhere then paths must be edited appropriately.

Using the Sample projects

The sample applications are shipped with the complete set of files required to configure, build and download the application for both IAR-workbench and AVR Studio IDE.

Since more than one device may use the same library (applicable for QTouch acquisition method libraries), example project files and applications have been provided only for select devices which use these libraries.

Example applications for QTouch acquisition method libraries

Selecting the right configuration
Changing the settings to match your device
Changing the library configuration parameters
Using the example projects

Selecting the right configuration

Each example project for a device can support multiple configurations (i.e a. keys only, b. with rotors and sliders c.16 channel etc…). The configuration sets determine the configuration options for using the library and also the right library variant to link with the project.

Table 13 : The configuration sets for IAR IDE are named according to the convention listed below

Configuration set for IAR IDE Naming convention : <vP>g<Q>_<CH>qt_k_<RS>rs
Field Name	Values	Comments
vP	v1, v3, xmega, uc3a, uc3b, uc3c	VersionP of the core AVR device supported by this library variant
Q	1 to 6	GroupQ of the core AVR device supported by this library variant
CH	4, 8, 12, 16, 32	Total number of channels supported by each library.
RS	1, 2, 3, 4, 8	Total number of rotors / sliders supported for the respective channel counts mentioned in previous row.

Table 14 : The configuration sets for AVR Studio IDE are named according to the convention listed below

Configuration set for AVR Studio IDE <avrP>g<Q>_<CH>qt_k_<RS>rs
Field Name	Values	Comments
avrP	avr25, avr4, avr 51, avr5, xmega, uc3a, uc3b, uc3c	VersionP of the core AVR device supported by this library variant
Q	1 to 6	GroupQ of the core AVR device supported by this library variant
CH	4, 8, 12, 16, 32	Total number of channels supported by each library.
RS	1, 2, 3, 4, 8	Total number of rotors / sliders supported for the respective channel counts mentioned in previous row.

Depending on your need, you need to select the right configuration required and build the project.

Figure 5‑11: Selecting the right configuration in the QTouch acquisition method example applications in IAR –IDE

Figure 5‑12 : Selecting the right configuration in QTouch acquisition method example applications in AVR-6 IDE

Changing the settings to match your device

Processor settings

Processor settings

Once you have selected the appropriate example project and the configuration, you need to ensure that the settings in the project are configured to reflect the correct device. The settings include

Figure 5‑13 : Changing the processor settings for the examples in IAR IDE

Figure 5‑14 : Changing the processor settings for the examples in AVR-Studio 6

Changing the library configuration parameters

The configuration parameters required for the library are specified in the touch_config.h file of the examples under the custom user configuration section. Please refer to the example projects provided with the QTouch libraries release for more information. The mandatory constants to be defined are as listed below .

Table 14 : The mandatory constants to be defined are as listed below .

Symbol / Constant name	Range of values	Comments
_QTOUCH_	This macro has to be defined in order to use QTouch libraries.
SNS & SNSK	Section 5.7.1.5 provides details on the range of values allowed.	To be used if only single port pair is needed for the design
SNS1 – SNSK1 & SNS2 – SNSK2	Section 5.7.1.5.2 has details on the range of values allowed	To be used if two port pairs are needed for the design
QT_NUM_CHANNELS	4, 8, 12, 16 for tinyAVR, megaAVR and XMEGA device libraries and 8, 16, 32 for UC3 device libraries.
_ROTOR_SLIDER_	Rotor / slider can be added to the design, if this symbol is defined	A library with rotor / slider functionality already available needs to be selected if this macro is to be enabled
_DEBUG_INTERFACE_	The debug interface code in the example application will be enabled if this macro is enabled.	This will enable the application to output QTouch measurement values to GPIO pins, which can be used by a USB bridge to view the output on Hawkeye or QTouch Studio. This feature is currently supported by EVK/TS 2080A and QT600 boards.
QT_DELAY_CYCLES	1 to 255	Please refer to section
QTOUCH_STUDIO_MASKS	This macro needs to be defined if QTouch Studio Pin Configurator Wizard.is used to generate the SNS and SNSK masks.	Please refer to section 5.8.1
_STATIC_PORT_PIN_CONF_	This macro needs to be defined only in case of 4 and 8 channel libraries with interport configuration and pin configurability.	Please refer to section 5.8.1

Figure 5‑15 : Specifying the QTouch acquisition method library configuration parameters for QTouch example projects

Using the example projects

The sample applications are shipped with the complete set of files required to configure, build, execute and test the application for both IAR-workbench and AVR Studio IDEs.

The sample applications are provided for the evaluation kits and a few configurations for select devices. The user can use the sample applications as a reference or baseline to configure different configurations. Please ensure to change the configuration settings in the project options to match the device selected.

To change the configuration settings of the sample applications,

Select the configuration from the list of configurations available.
If the user wishes to have a new name for the configuration to be used, a new configuration can be added to the project.
If a different variant of the library needs to be used, remove the existing library in that particular configuration and add the library variant that you require. Please refer to 5.7.1.4 for details on the different library variants. Update the linker options to specify the library to be linked.
Specify the tunable configuration parameters for the project as illustrated in sections 5.6.11.2.2 and 5.6.11.2.3.

Example applications for QMatrix acquisition method libraries

Selecting the right configuration
Changing the library configuration parameters
Using the example projects

The QMatrix acquisition method libraries include example projects for some of the supported devices. Example projects for both IAR IDE and AVR Studio IDE along with example applications are provided for select devices using the QMatrix acquisition libraries. These sample applications demonstrate the usage of the touch API’s to add touch sensing to an application. Refer to the library selection guide for details on the example projects and sample applications supported for the release.

Selecting the right configuration

The sample applications are built to support a maximum channel support configuration available for that particular device for both IAR & AVR IDEs.

Internally there are two configurations for each device.

ALL KEYS configuration : Supports only keys
KEYS/ROTORS/SLIDERS configuration : Supports keys or rotors or sliders concurrently

These configurations enable a set of stored options and a specific library to be selected in order to build application using the specific library.

Figure 5‑16 : Selecting the right configuration in the QMatrix acquisition method example applications in IAR -IDE

Figure 5‑17 : Selecting the right configuration in the QMatrix acquisition method example applications in AVR Studio IDE

Changing the library configuration parameters

The configuration parameters required for the library are specified in the touch_config.h file of the examples. Please refer to the example projects provided with the QTouch libraries release for more information .

Figure 5‑18 : Specifying QMatrix acquisition library parameters in touch_config.h for QMatrix projects

Using the example projects

The sample applications are shipped with the complete set of files required to configure, build, execute and test the application for both IAR-workbench and AVR Studio IDEs.

The sample applications are provided for the evaluation kits and a few configurations for select devices.

The user can use the sample applications as a reference or baseline to configure different configurations. Please ensure to change the configuration settings in the project options to match the device selected

To change the configuration settings of the sample applications,

Select the configuration from the list of configurations available as shown in section 5.6.11.3.1
If the user wishes to have a new name for the configuration to be used, a new configuration can be added to the project
If a different variant of the library needs to be used, remove the existing library in that particular configuration and add the library variant that you require. Please refer to library selection guide for details on the different library variants. Update the linker options to specify the library to be linked
Specify the tunable configuration parameters for the project as illustrated in 5.6.11.3.2
For QMatrix on XMEGA devices, please check if the pre-processor symbol _ATXMEGA_ is added in the project space or not.

Adjusting the Stack size when using IAR IDE

The example projects for IAR IDE, the CSTACK and RSTACK values are configured to account for the requirements of the QTouch libraries and the included main.c file which illustrates the usage of the touch API.

Adjust the CSTACK and RSTACK values appropriately based on additional software integrated or added to the examples.

Figure 5‑29 : Modifying the stack size in IAR IDE

Optimization levels

The default configuration settings in sample projects which ship with the library are set to the highest level of optimization for IAR and GCC variants of the libraries. The user might be required to change this setting for debugging purposes

In case of IAR, The optimizations tab in project configuration options specifies High.
In case of GCC, the libraries are compiled with the –Os which signifies that the Optimization for generating the library is maximum.

Figure 5‑20 : Specifying the optimization level in IAR IDE

Debug Support in Example applications

Debug Support in the sample applications for EVK2080 and QT600 boards
How to turn on the debug option
Debug Interface if USB Bridge board is not available

The EVK2080 and QT600 applications provide output debug information on standard GPIO pins through the USB Bridge IC to PC software for display by AVR QTouch Studio. Similarly for ATMEL devices that are not supported through EVK or QT600 kits, the output measurement values can be viewed through AVR QTouch Studio using the same QDebug protocol and QT600 USB bridge.

If a QT600 bridge is not available, please refer to section 5.6.11.6.3 for more information on observing the output touch measurement data without the use of a USB bridge or AVR QTouch Studio.