Atmel QTouch Library
User Guide
Supports QTouch and QMatrix acquisition for Keys, Sliders
and Rotors
®
®
Rev. 8207L-AT42-05/12
Rev. 8207L-AT42-05/12
Table of Contents
TABLE OF CONTENTS ..............................................................................................................................2
1
2
3
4
PREFACE ..............................................................................................................................................8
INTRODUCTION .................................................................................................................................9
OVERVIEW ........................................................................................................................................10
ABBREVIATIONS AND DEFINITIONS .........................................................................................11
4.1
5
D
EFINITIONS
...................................................................................................................................11
GENERIC QTOUCH LIBRARIES ...................................................................................................12
5.1
I
NTRODUCTION
...............................................................................................................................12
5.2
A
CQUISITION
M
ETHODS
.................................................................................................................13
5.2.1
QTouch acquisition method ...................................................................................................13
5.2.1.1
Sensor schematics for a QTouch acquisition method design ............................................................ 14
5.2.2
QMatrix acquisition method ..................................................................................................14
5.2.3
Sensor schematics for a QMatrix acquisition method design ................................................15
5.3
G
LOBAL SETTINGS COMMON TO ALL SENSORS OF A SPECIFIC ACQUISITION METHOD
......................15
5.3.1
Recalibration Threshold ........................................................................................................16
5.3.2
Detect Integration ..................................................................................................................16
5.3.3
Drift Hold Time .....................................................................................................................16
5.3.4
Maximum ON Duration .........................................................................................................17
5.3.5
Positive / Negative Drift ........................................................................................................17
5.3.6
Positive Recalibration Delay .................................................................................................18
5.4
S
ENSOR SPECIFIC SETTINGS
............................................................................................................18
5.4.1
Detect threshold .....................................................................................................................18
5.4.2
Hysteresis...............................................................................................................................18
5.4.3
Position Resolution ................................................................................................................19
5.4.4
Position Hysteresis ................................................................................................................19
5.4.5
Adjacent Key Suppression (AKS) ...........................................................................................20
5.5
U
SING THE
S
ENSORS
.......................................................................................................................20
5.5.1
Avoiding Cross-talk ...............................................................................................................20
5.5.2
Multiple measurements ..........................................................................................................20
5.5.3
Guard Channel ......................................................................................................................21
5.6
QT
OUCH
API
AND
U
SAGE
..............................................................................................................22
5.6.1
QTouch Library API ..............................................................................................................22
5.6.2
touch_api.h - public header file .............................................................................................22
5.6.3
Type Definitions and enumerations used in the library .........................................................22
5.6.3.1
Typedefs ........................................................................................................................................... 22
5.6.3.2
Enumerations ................................................................................................................................... 22
5.6.3.2.1 sensor_type_t.............................................................................................................................. 22
5.6.3.2.2 aks_group_t ................................................................................................................................ 23
5.6.3.2.3 channel_t .................................................................................................................................... 23
5.6.3.2.4 hysteresis_t ................................................................................................................................. 23
5.6.3.2.5 resolution_t................................................................................................................................. 24
5.6.3.2.6 recal_threshold_t ........................................................................................................................ 24
5.6.4
5.6.4.1
5.6.4.2
5.6.4.3
5.6.4.4
5.6.4.5
5.6.4.6
Data structures ......................................................................................................................25
qt_touch_status_t.............................................................................................................................. 25
qt_touch_lib_config_data_t .............................................................................................................. 25
qt_touch_lib_measure_data_t ........................................................................................................... 26
qt_burst_lengths ............................................................................................................................... 26
tag_sensor_t ..................................................................................................................................... 27
qt_lib_siginfo_t ................................................................................................................................ 27
5.6.5
Public Functions ....................................................................................................................28
2
8207L-AT42-05/12
5.6.5.1
5.6.5.2
5.6.5.3
5.6.5.4
5.6.5.5
5.6.5.6
5.6.5.7
5.6.5.8
5.6.5.9
5.6.5.10
qt_set_parameters ............................................................................................................................. 28
qt_enable_key .................................................................................................................................. 29
qt_enable_rotor ................................................................................................................................ 29
qt_enable_slider ............................................................................................................................... 30
qt_init_sensing ................................................................................................................................. 30
qt_measure_sensors.......................................................................................................................... 31
qt_calibrate_sensing ......................................................................................................................... 31
qt_reset_sensing ............................................................................................................................... 32
qt_get_sensor_delta .......................................................................................................................... 32
qt_get_library_sig ........................................................................................................................ 32
5.6.6
Sequence of Operations and Using the API ...........................................................................33
5.6.6.1
Channel Numbering ......................................................................................................................... 33
5.6.6.1.1 Channel numbering when using QTouch acquisition method .................................................... 33
5.6.6.1.2 Channel numbering when using QMatrix acquisition method ................................................... 39
5.6.6.2
Sensor Numbering ............................................................................................................................ 41
5.6.6.3
Filtering Signal Measurements ......................................................................................................... 42
5.6.6.4
Allocating unused Port Pins for User Application............................................................................ 43
5.6.6.5
Disabling and Enabling of Pull-up for AVR devices........................................................................ 44
5.6.7
5.6.7.1
5.6.7.2
5.6.7.3
Constraints.............................................................................................................................44
QTouch acquisition method constraints ........................................................................................... 44
QMatrix acquisition method constraints........................................................................................... 45
Design Guidelines for QMatrix acquisition method systems ........................................................... 46
5.6.8
5.6.9
5.6.10
Frequency of operation (Vs) Charge cycle/dwell cycle times: ..............................................46
Interrupts ...............................................................................................................................47
Integrating QTouch libraries in your application .................................................................48
Directory structure of the library files .......................................................................................... 48
Integrating QTouch acquisition method libraries in your application .......................................... 50
Example for 8bit AVR ............................................................................................................. 52
Example for ATSAM ............................................................................................................... 54
Checklist of items for integrating QTouch acquisition method libraries .................................. 55
Integrating QMatrix acquisition method libraries in your application ......................................... 55
Example for 8bit AVR ............................................................................................................. 55
Example for 32bit AVR ........................................................................................................... 62
Checklist of items for integrating QMatrix Capacitive sensing libraries .................................. 66
Common checklist items .............................................................................................................. 66
Configuring the stack size for the application .......................................................................... 66
Using the Sample projects ........................................................................................................... 68
Example applications for QTouch acquisition method libraries .................................................. 68
Selecting the right configuration .............................................................................................. 68
Changing the settings to match your device ............................................................................. 69
Changing the library configuration parameters ........................................................................ 70
Using the example projects ...................................................................................................... 72
Example applications for QMatrix acquisition method libraries.................................................. 73
Selecting the right configuration .............................................................................................. 73
Changing the library configuration parameters ........................................................................ 74
Using the example projects ...................................................................................................... 75
Adjusting the Stack size when using IAR IDE ............................................................................ 76
Optimization levels ...................................................................................................................... 76
Debug Support in Example applications ...................................................................................... 77
Debug Support in the sample applications for EVK2080 and QT600 boards .......................... 77
How to turn on the debug option .............................................................................................. 77
Debug Interface if USB Bridge board is not available ............................................................. 78
5.6.10.1
5.6.10.2
5.6.10.2.1
5.6.10.2.2
5.6.10.2.3
5.6.10.3
5.6.10.3.1
5.6.10.3.2
5.6.10.3.3
5.6.10.4
5.6.10.4.1
5.6.11
Example project files .............................................................................................................67
5.6.11.1
5.6.11.2
5.6.11.2.1
5.6.11.2.2
5.6.11.2.3
5.6.11.2.4
5.6.11.3
5.6.11.3.1
5.6.11.3.2
5.6.11.3.3
5.6.11.4
5.6.11.5
5.6.11.6
5.6.11.6.1
5.6.11.6.2
5.6.11.6.3
5.7
L
IBRARY
V
ARIANTS
.......................................................................................................................79
5.7.1
QTouch Acquisition method library variants.........................................................................79
5.7.1.1
Introduction ...................................................................................................................................... 79
5.7.1.2
Support for different compiler tool chains........................................................................................ 79
5.7.1.3
QTouch Acquisition method library naming conventions ................................................................ 79
5.7.1.3.1 Naming convention for libraries to be used with GCC tool chain .............................................. 79
5.7.1.3.2 Naming convention for libraries to be used with IAR Embedded Workbench ........................... 80
5.7.1.4
QTouch acquisition method library variants .................................................................................... 80
3
5.7.1.5
Port combinations supported for SNS and SNSK pin configurations............................................... 81
5.7.1.5.1 Tips on pin assignments for the sensor design using one pair of SNS/SNSK ports ................... 81
5.7.1.5.2 Port combinations supported for two port pair SNS and SNSK pin configurations ................... 83
5.7.1.6
Sample applications and Memory requirements for QTouch acquisition method libraries .............. 84
5.7.2
QMatrix acquisition method library variants ........................................................................84
5.7.2.1
Introduction ...................................................................................................................................... 84
5.7.2.2
Support for different compiler tool chains........................................................................................ 84
5.7.2.3
QMatrix Acquisition method library naming conventions ............................................................... 84
5.7.2.4
QMatrix acquisition method library variants .................................................................................... 87
5.7.2.4.1 Devices supported for QMatrix Acquisition............................................................................... 87
5.8
PIN C
ONFIGURATION FOR
QT
OUCH
L
IBRARIES
.............................................................................87
5.8.1
Pin Configuration for QTouch Acquisition Method ..............................................................87
5.8.1.1
Rules for configurable SNS-SNSK Mask Generation ...................................................................... 88
5.8.1.1.1 Example for 8 channel interport mask Calculation with one port pair ....................................... 89
5.8.1.1.2 Example for 8 channel intraport mask Calculation with two port pairs...................................... 90
5.8.1.1.3 Example for 12 channel intraport-interport mask Calculation with two port pairs .................... 91
5.8.1.1.4 Example for 16 channel intreport-interport mask Calculation with two port pairs .................... 92
5.8.1.2
How to Use QTouch Studio For Pin Configurability ....................................................................... 93
5.8.2
5.8.2.1
5.8.2.2
Pin Configuration for QMatrix Acquisition Method............................................................101
Configuration Rules: ...................................................................................................................... 101
How to use QTouch Studio for Pin Configurability: ...................................................................... 102
5.9
MISRA C
OMPLIANCE
R
EPORT
.....................................................................................................109
5.9.1
What is covered ...................................................................................................................110
5.9.2
Target Environment .............................................................................................................110
5.9.3
Deviations from MISRA C Standards ..................................................................................110
5.9.3.1
5.9.3.2
QTouch acquisition method libraries ............................................................................................. 110
QMatrix acquisition method libraries ............................................................................................. 111
5.10
5.11
6
K
NOWN
I
SSUES
.............................................................................................................................111
C
HECKLIST
...................................................................................................................................112
DEVICE SPECIFIC LIBRARIES ...................................................................................................113
6.1
I
NTRODUCTION
.............................................................................................................................113
6.2
D
EVICES SUPPORTED
....................................................................................................................113
6.3
QT
OUCH
L
IBRARY FOR
AT32UC3L
DEVICES
..............................................................................113
6.3.1
Salient Features of QTouch Library for UC3L ....................................................................113
6.3.1.1
6.3.1.2
6.3.1.3
6.3.1.4
QMatrix method sensor .................................................................................................................. 113
QTouch method sensor................................................................................................................... 113
Autonomous QTouch sensor .......................................................................................................... 114
Additional Features ........................................................................................................................ 114
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.3.7
Device variants supported for UC3L ...................................................................................114
Development tool support for UC3L ...................................................................................114
Overview of QTouch Library API for UC3L .......................................................................115
Acquisition method support for UC3L .................................................................................116
API State machine for UC3L ...............................................................................................116
QMatrix method sensor operation for UC3L.......................................................................117
Table 8 Development tool support for UC3L QTouch Library ................................................................... 114
Figure 35 Overview diagram of QTouch Library for UC3L ....................................................................... 115
Table 9 Acquisition method specific API .................................................................................................... 116
Figure 36 State Diagram of QTouch Library for UC3L .............................................................................. 117
6.3.7.1
QMatrix method pin selection for UC3L........................................................................................ 117
Table 10 QMatrix Resistive drive pin option .............................................................................................. 118
6.3.7.2
QMatrix method Schematic for UC3L ........................................................................................... 118
6.3.7.2.1 Internal Discharge mode .......................................................................................................... 118
6.3.7.2.2 External Discharge mode ......................................................................................................... 119
6.3.7.2.3 SMP Discharge Mode .............................................................................................................. 119
6.3.7.2.4 VDIVEN Voltage Divider Enable option ................................................................................. 119
6.3.7.2.5 SYNC pin option ...................................................................................................................... 119
Figure 37 QMatrix method schematic ......................................................................................................... 120
6.3.7.3
QMatrix method hardware resource requirement for UC3L .......................................................... 121
6.3.7.4
QMatrix method Channel and Sensor numbering for UC3L .......................................................... 121
4
8207L-AT42-05/12
Figure 38 QMatrix channel numbering for UC3L ....................................................................................... 121
6.3.7.5
QMatrix method API Flow for UC3L ............................................................................................ 121
Figure 39 QMatrix API Flow diagram for UC3L ........................................................................................ 122
6.3.7.6
QMatrix method Disable and Re-enable Sensor for UC3L ............................................................ 124
6.3.8
QTouch Group A/B method sensor operation for UC3L .....................................................124
6.3.8.1
QTouch Group A/B method pin selection for UC3L...................................................................... 124
Table 11 QTouch Resistive drive pin option ............................................................................................... 125
6.3.8.2
QTouch Group A/B method Schematic for UC3L ......................................................................... 125
6.3.8.2.1 Resistive Drive option .............................................................................................................. 125
6.3.8.2.2 SYNC pin option ...................................................................................................................... 125
Figure 40 QTouch Group A/B and Autonomous QTouch schematic arrangement ..................................... 126
6.3.8.3
QTouch Group A/B method hardware resource requirement for UC3L ........................................ 126
6.3.8.4
QTouch Group A/B method Channel and Sensor numbering for UC3L ........................................ 127
Figure 41 QTouch method Channel/Sensor numbering............................................................................... 127
Figure 42 QTouch method Channel/Sensor numbering when Group A and B are used together ................ 127
6.3.8.5
QTouch Group A/B method API Flow for UC3L .......................................................................... 128
Figure 43 QTouch method API Flow diagram ............................................................................................ 129
6.3.8.6
QTouch Group A/B method Disable and Re-enable Sensor for UC3L .......................................... 130
6.3.9
Autonomous QTouch sensor operation for UC3L ...............................................................130
6.3.9.1
Autonomous QTouch Sensor pin selection for UC3L .................................................................... 130
6.3.9.2
Autonomous QTouch sensor Schematic for UC3L ........................................................................ 130
6.3.9.3
Autonomous QTouch method hardware resource requirement for UC3L ...................................... 130
Table 12 Sleep mode support for Autonomous QTouch ............................................................................. 130
6.3.9.4
Autonomous QTouch Sensor API Flow for UC3L ........................................................................ 131
Figure 44 Autonomous QTouch API Flow diagram .................................................................................... 131
6.3.9.5
Autonomous QTouch method Enable and Disable Sensor for UC3L ............................................ 131
6.3.10
6.3.11
6.3.12
Raw acquisition mode support for UC3L ............................................................................132
Library Configuration parameters for UC3L ......................................................................133
Example projects for QTouch Library for UC3L.................................................................134
Figure 45 Raw acquisition mode API Flow diagram ................................................................................... 132
Table 13 QTouch Library for UC3L Configuration parameters .................................................................. 133
6.3.12.1
Example Project usage ............................................................................................................... 134
Figure 46 GNU Example project usage with AVR32 Studio ...................................................................... 134
Figure 47 IAR Example project usage with IAR Embedded Workbench for AVR32 ................................. 134
6.3.12.2
QMatrix Example Project .......................................................................................................... 135
6.3.12.3
QTouch Group A Example Project ............................................................................................ 135
6.3.12.4
Autonomous QTouch Example Project ..................................................................................... 135
6.3.13
Code and Data Memory requirements for UC3L ................................................................136
6.3.13.1
QMatrix method memory requirement ...................................................................................... 136
Table 14 Typical Code and Data memory for Standalone QMatrix operation ........................................... 136
6.3.13.2
QTouch Group A/B method memory requirement .................................................................... 136
Table 15 Typical Code and Data memory for Standalone QTouch Group A/B operation .......................... 137
6.3.13.3
Autonomous QTouch memory requirement .............................................................................. 137
Table 16 Minimum Code and Data for Standalone Autonomous QTouch sensor ....................................... 137
6.3.14
6.3.15
Public header files of QTouch Library for UC3L ................................................................137
Type Definitions and enumerations used in the library .......................................................137
6.3.15.1
Typedefs .................................................................................................................................... 137
6.3.15.1.1 touch_acq_status_t ................................................................................................................. 138
6.3.15.1.2 touch_qt_grp_t ....................................................................................................................... 138
6.3.15.2
Enumerations ............................................................................................................................. 138
6.3.15.2.1 touch_ret_t.............................................................................................................................. 139
6.3.15.2.2 touch_lib_state_t .................................................................................................................... 139
6.3.15.2.3 touch_acq_mode_t ................................................................................................................. 140
6.3.15.2.4 sensor_type_t.......................................................................................................................... 140
6.3.15.2.5 aks_group_t ............................................................................................................................ 140
6.3.15.2.6 hysteresis_t ............................................................................................................................. 140
6.3.15.2.7 recal_threshold_t .................................................................................................................... 141
6.3.15.2.8 resolution_t............................................................................................................................. 141
6.3.15.2.9 at_status_change_t ................................................................................................................. 142
6.3.15.2.10 x_pin_options_t .................................................................................................................... 142
6.3.15.2.11 y_pin_options_t .................................................................................................................... 142
5
京公网安备 11010802033920号
EEWORLD
