ATAVRTS2080B

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 PREFACE ..............................................................................................................................................8 2 INTRODUCTION .................................................................................................................................9 3 OVERVIEW ........................................................................................................................................10 4 ABBREVIATIONS AND DEFINITIONS .........................................................................................11 4.1 5 DEFINITIONS ...................................................................................................................................11 GENERIC QTOUCH LIBRARIES ...................................................................................................12 5.1 INTRODUCTION ...............................................................................................................................12 5.2 ACQUISITION METHODS .................................................................................................................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 GLOBAL 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 SENSOR 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 USING THE SENSORS.......................................................................................................................20 5.5.1 Avoiding Cross-talk ...............................................................................................................20 5.5.2 Multiple measurements ..........................................................................................................20 5.5.3 Guard Channel ......................................................................................................................21 5.6 QTOUCH API AND USAGE ..............................................................................................................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 5.6.5 2 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 Public Functions ....................................................................................................................28 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 5.6.6 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 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 5.6.8 5.6.9 5.6.10 Constraints.............................................................................................................................44 QTouch acquisition method constraints ........................................................................................... 44 QMatrix acquisition method constraints........................................................................................... 45 Design Guidelines for QMatrix acquisition method systems ........................................................... 46 Frequency of operation (Vs) Charge cycle/dwell cycle times: ..............................................46 Interrupts ...............................................................................................................................47 Integrating QTouch libraries in your application .................................................................48 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 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 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 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.7 LIBRARY VARIANTS .......................................................................................................................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 CONFIGURATION FOR QTOUCH LIBRARIES .............................................................................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 COMPLIANCE REPORT .....................................................................................................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 5.10 5.11 6 QTouch acquisition method libraries ............................................................................................. 110 QMatrix acquisition method libraries ............................................................................................. 111 KNOWN ISSUES.............................................................................................................................111 CHECKLIST ...................................................................................................................................112 DEVICE SPECIFIC LIBRARIES ...................................................................................................113 6.1 INTRODUCTION .............................................................................................................................113 6.2 DEVICES SUPPORTED ....................................................................................................................113 6.3 QTOUCH LIBRARY 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 6.3.2 6.3.3 QMatrix method sensor .................................................................................................................. 113 QTouch method sensor................................................................................................................... 113 Autonomous QTouch sensor .......................................................................................................... 114 Additional Features ........................................................................................................................ 114 Device variants supported for UC3L ...................................................................................114 Development tool support for UC3L ...................................................................................114 Table 8 Development tool support for UC3L QTouch Library ................................................................... 114 6.3.4 Overview of QTouch Library API for UC3L .......................................................................115 Figure 35 Overview diagram of QTouch Library for UC3L ....................................................................... 115 6.3.5 Acquisition method support for UC3L .................................................................................116 Table 9 Acquisition method specific API .................................................................................................... 116 6.3.6 API State machine for UC3L ...............................................................................................116 Figure 36 State Diagram of QTouch Library for UC3L .............................................................................. 117 6.3.7 QMatrix method sensor operation 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 Raw acquisition mode support for UC3L ............................................................................132 Figure 45 Raw acquisition mode API Flow diagram ................................................................................... 132 6.3.11 Library Configuration parameters for UC3L ......................................................................133 Table 13 QTouch Library for UC3L Configuration parameters .................................................................. 133 6.3.12 Example projects for QTouch Library for UC3L.................................................................134 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 6.3.15.2.12 6.3.15.2.13 6.3.16 Data structures ....................................................................................................................143 6.3.16.1 6.3.16.2 6.3.16.3 6.3.16.4 6.3.16.5 6.3.16.6 6.3.16.7 6.3.16.8 6.3.16.9 6.3.16.10 6.3.16.11 6.3.16.12 6.3.16.13 6.3.16.14 6.3.16.15 6.3.16.16 6.3.16.17 6.3.16.18 6.3.16.19 6.3.16.20 6.3.16.21 6.3.17 qt_pin_options_t ................................................................................................................... 142 general_pin_options_t .......................................................................................................... 142 sensor_t ...................................................................................................................................... 143 touch_global_param_t ............................................................................................................... 143 touch_filter_data_t ..................................................................................................................... 144 touch_measure_data_t ............................................................................................................... 144 touch_qm_param_t .................................................................................................................... 144 touch_at_param_t ...................................................................................................................... 145 touch_qt_param_t ...................................................................................................................... 146 touch_at_status .......................................................................................................................... 146 touch_qm_dma_t ....................................................................................................................... 146 touch_qm_pin_t ......................................................................................................................... 146 touch_at_pin_t ........................................................................................................................... 147 touch_qt_pin_t ........................................................................................................................... 147 touch_qm_reg_t ......................................................................................................................... 148 touch_at_reg_t ........................................................................................................................... 149 touch_qt_reg_t ........................................................................................................................... 149 touch_qm_config_t .................................................................................................................... 149 touch_at_config_t ...................................................................................................................... 150 touch_qt_config_t ...................................................................................................................... 151 touch_general_config_t.............................................................................................................. 151 touch_config_t ........................................................................................................................... 152 touch_info_t ............................................................................................................................... 152 Public Functions of QTouch Library for UC3L...................................................................152 6.3.17.1 QMatrix API .............................................................................................................................. 152 6.3.17.1.1 touch_qm_sensors_init ........................................................................................................... 152 6.3.17.1.2 touch_qm_sensor_config........................................................................................................ 153 6.3.17.1.3 touch_qm_sensor_update_config ........................................................................................... 154 6.3.17.1.4 touch_qm_sensor_get_config ................................................................................................. 154 6.3.17.1.5 touch_qm_channel_udpate_burstlen ...................................................................................... 154 6.3.17.1.6 touch_qm_update_global_param............................................................................................ 155 6.3.17.1.7 touch_qm_get_global_param ................................................................................................. 155 6.3.17.1.8 touch_qm_sensors_calibrate................................................................................................... 155 6.3.17.1.9 touch_qm_sensors_start_acquisition ...................................................................................... 156 6.3.17.1.10 touch_qm_get_libinfo .......................................................................................................... 156 6.3.17.1.11 touch_qm_sensor_get_delta ................................................................................................. 157 6.3.17.2 QTouch Group A and QTouch Group B API ............................................................................ 157 6.3.17.2.1 touch_qt_sensors_init ............................................................................................................. 157 6.3.17.2.2 touch_qt_sensor_config.......................................................................................................... 158 6.3.17.2.3 touch_qt_sensor_update_config ............................................................................................. 158 6.3.17.2.4 touch_qt_sensor_get_config ................................................................................................... 159 6.3.17.2.5 touch_qt_update_global_param.............................................................................................. 159 6.3.17.2.6 touch_qt_get_global_param ................................................................................................... 159 6.3.17.2.7 touch_qt_sensors_calibrate..................................................................................................... 160 6.3.17.2.8 touch_qt_sensors_start_acquisition ........................................................................................ 160 6.3.17.2.9 touch_qt _sensor_ disable....................................................................................................... 161 6.3.17.2.10 touch_qt _sensor_ reenable .................................................................................................. 161 6.3.17.2.11 touch_qt_get_libinfo ............................................................................................................ 162 6.3.17.2.12 touch_qt_sensor_get_delta ................................................................................................... 162 6.3.18 Autonomous touch API ........................................................................................................162 6.3.18.1.1 touch_at_sensor_init............................................................................................................... 162 6.3.18.1.2 touch_at_sensor_enable.......................................................................................................... 163 6.3.18.1.3 touch_at_sensor_disable ......................................................................................................... 163 6.3.18.1.4 touch_at_sensor_update_config ............................................................................................. 163 6.3.18.1.5 touch_at_sensor_get_config ................................................................................................... 164 6.3.18.1.6 touch_at_get_libinfo ............................................................................................................... 164 6.3.18.2 Common API ............................................................................................................................. 164 6.3.18.2.1 touch_event_dispatcher .......................................................................................................... 164 6.3.18.2.2 touch_deinit ............................................................................................................................ 164 6.3.19 6.3.20 6 Integrating QTouch libraries for AT32UC3L in your application ......................................165 MISRA Compliance Report of QTouch Library for UC3L ..................................................165 8207L-AT42-05/12 6.3.21 What is covered ...................................................................................................................165 6.3.22 Target Environment .............................................................................................................165 6.3.23 Deviations from MISRA C Standards ..................................................................................165 6.3.24 Known Issues with QTouch Library for UC3L ....................................................................166 6.4 QTOUCH LIBRARY FOR ATTINY20 DEVICE ..................................................................................167 6.4.1 Salient Features of QTouch Library for ATtiny20 ...............................................................167 6.4.1.1 6.4.2 QTouch method sensor................................................................................................................... 167 Compiler tool chain support for ATtiny20 ...........................................................................167 Table 17 Compiler tool chains support for ATtiny20 QTouch Library ....................................................... 167 6.4.3 Overview of QTouch Library for ATtiny20 ..........................................................................167 Figure 48 Schematic overview of QTouch on Tiny20 ................................................................................. 168 6.4.4 API Flow diagram for ATtiny20 ..........................................................................................168 Figure 49 Linker configuration options for Tiny20 ..................................................................................... 168 Figure 50 QTouch method for Tiny20 API Flow diagram .......................................................................... 169 6.4.5 QTouch Library configuration parameters for ATtiny20 ....................................................169 Table 18 QTouch Library for ATtiny20 Configuration parameters............................................................. 170 6.4.6 6.4.7 QTouch Library ATtiny20 Example projects .......................................................................171 QTouch Library ATtiny20 code and data memory requirements ........................................171 Table 19 QTouch Library for ATtiny20 Memory requirements .................................................................. 171 6.5 QTOUCH LIBRARY FOR ATTINY40 DEVICE ..................................................................................172 6.5.1 Salient Features of QTouch Library for ATtiny40 ...............................................................172 6.5.1.1 6.5.2 QTouch method sensor................................................................................................................... 172 Compiler tool chain support for ATtiny40 ...........................................................................173 Table 20 Compiler tool chains support for ATtiny40 QTouch Library ....................................................... 173 6.5.3 Overview of QTouch Library for ATtiny40 ..........................................................................173 Figure 51 Schematic overview of QTouch on Tiny40 ................................................................................. 173 6.5.4 API Flow diagram for ATtiny40 ..........................................................................................174 Figure 52 QTouch method for Tiny40 API Flow diagram .......................................................................... 175 6.5.5 QTouch Library configuration parameters for ATtiny40 ....................................................175 Table 21 QTouch Library for ATtiny40 Configuration parameters............................................................. 176 6.5.6 6.5.7 QTouch Library ATtiny40 Example projects .......................................................................177 QTouch Library ATtiny40 code and data memory requirements ........................................177 Table 22 QTouch Library for ATtiny40 Memory requirements .................................................................. 177 6.5.8 7 Interrupt Handling in QTouch ADC ....................................................................................177 GENERIC QTOUCH LIBRARIES FOR 2K DEVICES ...............................................................178 7.1 INTRODUCTION .............................................................................................................................178 7.2 DEVICES SUPPORTED ....................................................................................................................178 7.3 SALIENT FEATURES OF QTOUCH LIBRARY FOR 2K DEVICES........................................................178 7.4 LIBRARY VARIANTS .....................................................................................................................178 7.5 QTOUCH API FOR 2K DEVICES AND USAGE.................................................................................178 7.5.1 touch_api_2kdevice.h - public header file ...........................................................................178 7.5.2 Sequence of Operations and Using the API .........................................................................179 7.5.2.1 Channel Numbering ....................................................................................................................... 179 7.5.2.1.1 Channel numbering when routing SNS and SNSK pins to different ports ............................... 179 7.5.2.1.2 Channel numbering when routing SNS and SNSK pins to the same port ................................ 180 7.5.2.2 Rules For Configuring SNS and SNSK masks for 2K Devices ...................................................... 180 7.5.2.2.1 Configuring SNS and SNSK masks in case of Interport: ......................................................... 180 7.5.2.2.2 Configuring SNS and SNSK masks in case of Intraport: ......................................................... 181 7.5.3 Integrating QTouch libraries for 2K Devices in your application.......................................181 7.6 MISRA COMPLIANCE REPORT .....................................................................................................182 7.6.1 What is covered ...................................................................................................................182 7.6.2 Target Environment .............................................................................................................182 7.6.3 Deviations from MISRA C Standards ..................................................................................182 7.6.3.1 8 QTouch acquisition method libraries for 2K devices ..................................................................... 182 REVISION HISTORY ......................................................................................................................183 DISCLAIMER ...........................................................................................................................................185 7 1 Preface This manual contains information that enables customers to implement capacitive touch solutions ® on ATMEL AVR® microcontrollers and ARM -based AT91SAM microcontrollers using ATMEL QTouch libraries. This guide is a functional description of the library software, its programming interface and it also describes its use on the supported reference systems. Use of this software is bound by the Software License Agreement included with the Library. This user guide is applicable for Atmel QTouch® Library 5.0 . Related documents from ATMEL Documents related to QTouch capacitive sensing solutions from ATMEL are • TS2080A/B data sheet. • QT600 users guide • Release Notes for ATMEL QTouch libraries. • A library selection excel workbook that is used for the selection of the appropriate library variant from the package available under in the install directory. The default location is C:\Program Files\Atmel\Atmel_QTouch_Libraries_5.x\ • Capacitive touch sensor design guide http://www.atmel.com/dyn/resources/prod_documents/doc10620.pdf . If you need Assistance For assistance with QTouch capacitive sensing software libraries and related issues, contact your local ATMEL sales representative or send an email to touch@atmel.com for AVR libraries and at91support@atmel.com for SAM libraries. 8 8207L-AT42-05/12 2 Introduction ATMEL QTouch Library is a royalty free software library (available for GCC and IAR compiler tool chains) for developing touch applications on standard AVR and SAM microcontrollers. Customers can link the library into their applications in order to provide touch sensing capability in their projects. The Library can be used to develop single chip solutions for control applications which have touch sensing capabilities, or to develop standalone touch sensing solutions which interface with other host or control devices. Features of ATMEL QTouch Library include • • • • • • • • • • Capacitive touch sensing using patented charge-transfer signal acquisition for robust sensing. Support for a wide range of 8- and 32-bit AVRs. Support for 32-bit ARM microcontrollers. Support for 8-bit tiny AVRs having flash of 2K bytes. Support both QTouch and QMatrix acquisition methods and autonomous touch for UC3L. Support up to 64 touch sense channels for generic libraries and up to 136 channels for UC3L libraries. Flexible choice of touch sensing functionality (keys, sliders, wheels) in a variety of combinations. ® ® Includes Adjacent Key Suppression (AKS ) technology for the unambiguous detection of key events. Support for both IAR and GCC compiler tool chains. A comparison of various features and parameters between QTouch Libraries for Generic 8-bit and 32-bit AVRs as well as Device Specific Libraries is provided in the table below. Feature Comparison between Generic QTouch Libraries and Device Specific Libraries Parameter/Func Generic Tiny 2K Tiny20 Tiny40 Generic UC3L tionality Libraries, Libraries Libraries Libraries Libraries, Libraries Tiny_Meg 32 Bit a_Xmega AVR QTouch, QTouch QTouchQTouchQTouch, QTouch, Technology QTouch No ADC No ADC No QMatrix Yes QMatrix Yes Yes Yes Yes No Yes Yes Yes Yes Library Status Flags Yes Yes No Yes Yes Yes Library Signature Calibrate Sensing Yes No No Yes(Only Burst Again Flag) No Yes Yes Yes Yes No Yes Yes Yes Yes Reset Sensing Yes Yes (Only burst_again flag) Yes No Yes Yes Yes Yes Sensor Deltas Yes Yes No Yes Yes Yes Yes Maximum AKS Groups 7 7 1 7 7 7 7 Rotors/Sliders Support Filter Callback QMatrix Yes ATSAM Libraries 9 Maximum Channels, QT Maximum Rotors/Sliders, QT Maximum Channels, QM Maximum Rotors/Sliders, QM Autonomous Touch Sensor Reconfiguratio n Frequency Hopping SS Enabled 16 4 5 12 32 4 0 0 0 8 64 0 0 0 64 8 0 0 0 8 No No No No No Yes No Yes Yes No No Yes Yes Yes Always Never Never Always Programma ble Always Delay Cycles Parameter QT_DELAY _CLCYES (QT Values: 1 to 255 QM Values: 1,2,3,4,5,10 ,25,50) _DEBUG_I NTERFAC E_ If _POWER_ OPTIMIZA TION = 0 QT_DELAY _CLCYES (Value: 1 to 255) DEF_CHA RGE_SHA RE_DELAY (Value: 1 to 255) DEF_QT_C HARGE_S HARE_DEL AY (Value: 1 to 255) QT_DELAY _CYCLES (QT Values : 1 to 255 QM Values: 1,2,3,4,5,10 ,25,50) xx_CHLEN, xx_SELEN (QT/QM Value: 3 to 255) QT_DELAY _CLCYES (Value: 3 to 255) None NDEBUG _DEBUG_ QTOUCH_ STUDIO_ _DEBUG_I NTERFAC E_ DEF_TOU CH_QDEB UG_ENAB LE _DEBUG_I NTERFAC E_ Debug Interface Enable Macro 17 8 64 0 0 This user guide describes the content, design and use of the QTouch Libraries. This should be read in conjunction with all of the applicable documents listed below • Device datasheet for the selected ATMEL device used for touch sensing. • Data sheet for the selected evaluation board. • A library selection guide that is used for the selection of the appropriate library from the released package. Default path: C:\ Program Files\Atmel\Atmel_QTouch_Libaries_5.x\Library_Selection_Guide.xls The intended readers of this document are engineers, who use the QTouch Library on ATMEL microcontrollers to realize capacitive touch sensing solutions. 3 Overview This chapter gives a brief introduction to each of the chapters that make up this document 1. 2. 3. 4. Preface Introduction: Provides an introduction to the scope and use of the QTouch Library. Overview: This chapter Abbreviations and Definitions: Provides a description of the abbreviations and definitions used in this document 5. Generic QTouch Libraries: Provides an overview of the QTouch libraries and the different acquisition methods for generic ATMEL devices. 6. Device Specific Libraries: Provides an overview of the QTouch libraries and the different acquisition methods for ATMEL devices specific for touch sensing. 7. Revision History: Provides a revision history of this document 10 32 8207L-AT42-05/12 4 Abbreviations and Definitions 4.1 Definitions • AVR: refers to a device(s) in the tinyAVR®, megaAVR®, XMEGA™ and UC3 microcontroller family. • ARM: refers to a device in the ATSAM ARM® basedmicrocontroller family. • ATMEL QTouch Library: The combination of libraries for both touch sensing acquisition methods (QTouch and QMatrix). • QTouch Technology: A type of capacitive touch sensing technology using self capacitance - each channel has only one electrode. • QMatrix Technology: A type of capacitive touch sensing technology using mutual capacitance – each channel has an drive electrode (X) and an receive electrode (Y). • Sensor: A channel or group of channels used to form a touch sensor. Sensors are of 3 types (keys, rotors or sliders). • KEY: a single channel forms a single KEY type sensor, also known as a BUTTON • ROTOR, also known as a WHEEL, a group of channels forms a ROTOR sensor to detect angular position of touch. • o A Rotor is composed of 3 channels for a QTouch acquisition method. o A Rotor can be composed of 3 to 8 channels for QMatrix acquisition method. SLIDER, a group of channels forms a SLIDER sensor to detect the linear position of touch. o A Slider is composed of 3 channels for a QTouch acquisition method. o A Slider can be composed of 3 to 8 channels for QMatrix acquisition method. • AKS: Adjacent Key Suppression. See Section 5.4.5 • SNS PIN: Sense line for capacitive measurement using the QTouch Technology connected to Cs. • SNSK PIN: Sense Key line for capacitive measurement using the QTouch Technology connected to channel electrode through Rs. • X Line: The drive electrode (or drive line) used for QMatrix Technology. • Y Line: The receive electrode (or receive line) used for QMatrix Technology. • Port Pair: A combination of SNS port and SNSK port to which sensors are connected for QTouch technology. The SNS and SNSK ports used in a port pair can be located in the same AVR Port (8 pins for 4 sensors), or they may be in different 2 different AVR Ports (8+8 pins for 8 sensors). • Charge Cycle Period: It is the width of the charging pulse applied to the channel capacitor. • Dwell Cycle: In a QMatrix acquisition method, the duration in which charge coupled from X to Y is captured. • Acquisition: A single capacitive measurement process. • Electrode: Electrodes are typically areas of copper on a printed circuit board but can also be areas of clear conductive indium tin oxide (ITO) on a glass or plastic touch screen. 11 • Intra-port: A configuration for QTouch acquisition method libraries, when the sensor SNS and SNSK pins are available on the same port. • Inter-port: A configuration for QTouch acquisition method libraries, when the sensor SNS and SNSK pins are available on distinct ports. 5 Generic QTouch Libraries 5.1 Introduction ATMEL QTouch provides a simple to use solution to realize touch sensing solutions on a range of supported ATMEL AVR Microcontrollers. The QTouch libraries provide support for both QTouch and QMatrix acquisition methods. Touch sensing using QMatrix or QTouch acquisition methods can be added to an application by linking the appropriate ATMEL QTouch Library for the AVR Microcontroller and using a simple set of API to define the touch channels and sensors and then calling the touch sensing API’s periodically (or based on application needs) to retrieve the channel information and determine touch sensor states. Figure 5-1 shows a typical configuration of channels when using an AVR and using the ATMEL QTouch Library. The ATMEL QTouch Library has been added to a host application running on an AVR microcontroller. The sample configuration illustrates using the library that supports eight touch channels numbered 0 to 7. The sensors are configured in the following order, • Sensor 0 on channels 0 to 2 have been configured as a rotor sensor. • Sensor 1 on channels 3 to 5 have been configured as a slider sensor. • Sensor 2 on channel 6 is configured as key sensor. • Sensor 3 on channel 7 is configured as key sensor. The host application uses the QTouch Library API’s to configure these channels and sensors, and to initiate detection of a touch using capacitive measurements. channel 0 channel 1 channel 2 channel 3 Host Application Atmel QTouch Library sensor0 channel 4 sensor1 channel 5 channel 6 sensor2 channel 7 sensor3 Figure 5-1 : Typical interface of the ATMEL QTouch library with the host application. The QTouch libraries use minimal resources of the microcontroller. The sampling of the sensors is controlled by the QTouch library, while the sampling period is controlled by the application (possibly using timers, sleep periods, varying the CPU clock, external events like interrupts or communications, etc). 12 8207L-AT42-05/12 5.2 Acquisition Methods There are two methods available for touch acquisition namely 1. QTouch acquisition method. 2. QMatrix acquisition method. Libraries for AVR microcontrollers include both acquisition methods. Libraries for ATSAM microcontrollers include only QTouch acquisition method. 5.2.1 QTouch acquisition method The QTouch acquisition method charges an electrode of unknown capacitance to a known potential. The resulting charge is transferred into a measurement capacitor (Cs). The cycle is repeated until the voltage across Cs reaches a voltage Vih. The signal level is the number of charge transfer cycles it took to reach that voltage. Placing a finger on the touch surface introduces external capacitance that increases the amount of charge transferred each cycle, reducing the total number of cycles required for Cs to reach the voltage. When the signal level (number of cycles) goes below the present threshold, then the sensor is reported to be in detected. QTouch acquisition method sensors can drive single or multiple keys. Where multiple keys are used, each key can be set for an individual sensitivity level. Keys of different sizes and shapes can be used to meet both functional and aesthetic requirements. NOTE: It is recommended to keep the size of the keys larger than 6mmx6mm to ensure reliable and robust measurements, although actual key design requirements also depend on panel thickness and material. Refer to the ATMEL Capacitive touch sensor design guide for details. QTouch acquisition method can be used in two ways • normal touch contact (i.e. when pressing buttons on a panel), and • high sensitivity proximity mode (i.e. when a panel lights up before you actually contact it). Figure 5-2 : QTouch Acquisition QTouch circuits offers high signal-to-noise ratio, very good low power performance, and the easiest sensor layout. 13 5.2.1.1 Sensor schematics for a QTouch acquisition method design Sampling capacitor SNSK Rs PB1 Microcontroller Used for touch application Electrode Cs Typical Rs- 1k values: Cs- 22nF PC1 SNS ---------------Port requirements: SNS: generic I/O pin SNSK: generic I/O pin Rs- Series resistor, Cs – Sample capacitor, PB1- PortB bit1, and PC1- PortC bit1 Figure 5-3 : Schematics for a QTouch acquisition method design 5.2.2 QMatrix acquisition method QMatrix devices detect touch using a scanned passive matrix of electrode sets. A single QMatrix device can drive a large number of keys, enabling a very low cost-per-key to be achieved. Figure 5-4 : QMatrix Acquisition method 14 8207L-AT42-05/12 QMatrix uses a pair of sensing electrodes for each channel. One is an emitting electrode into which a charge consisting of logic pulses is driven in burst mode. The other is a receive electrode that couples to the emitter via the overlying panel dielectric. When a finger touches the panel the field coupling is changed, and touch is detected. The drive electrode (or drive line) used for QMatrix charge transfer is labeled as the X line. The receiver electrode (or receive line) used for QMatrix charge transfer is labeled as the Y line. QMatrix circuits offer good immunity to moisture films, extreme levels of temperature stability, superb low power characteristics, and small IC package sizes for a given key count. 5.2.3 Sensor schematics for a QMatrix acquisition method design Atmel MCU Sensors, X,Y RX0 X0 Sensor 0,0 Sensor 0,m Sensor n,0 Sensor n,m ... Xn RXn RY0 Y0A ... YmA RYm CS0 ... CSm Typical values: RX: 1k RY: 1k CS: 4.7nF RYB: 470k ---------------------------------Port-pin count = n + (2 * m) + 2 Y0B YmB RYB0 SMP RYBm n – number of X lines m – number of Y lines ---------------------------------Port requirements: X: Configurable I/O pin YA:Configurable I/O pin (*) YB: ADC port (*) SMP: Configurable I/O pin Vref: AIN0 (Comparator) Vref (*): The port I/O pin should be in consecutive order Figure 5-5 : Schematics for a QMatrix acquisition method design 5.3 Global settings common to all sensors of a specific acquisition method The touch sensing using QTouch library could be fine tuned by using a number of configurable settings. This section explains the settings that are common to all sensors of a specific acquisition method like QMatrix or QTouch. 15 For example, if recalibration threshold (one of the global settings) of QMatrix acquisition method is set as 1, all QMatrix sensors will have recalibration threshold of 1. 5.3.1 Recalibration Threshold Recalibration threshold is the level above which automatic recalibration occurs. Recalibration threshold is expressed as a percentage of the detection threshold setting. This setting is an enumerated value and its settings are as follows: • Setting of 0 = 100% of detect threshold (RECAL_100) • Setting of 1 = 50% of detect threshold (RECAL_50) • Setting of 2 = 25% of detect threshold (RECAL_25) • Setting of 3 = 12.5% of detect threshold (RECAL_12_5) • Setting of 4 = 6.25% of detect threshold (RECAL_6_25) However, an absolute value of 4 is the hard limit for this setting. For example, if the detection threshold is say, 40 and the Recalibration threshold value is set to 4. This implies an absolute value of 2 (40 * 6.25% = 2.5), but this is hard limited to 4. Setting Variable name Data Type Unit Min Max Typical Recalibration threshold qt_recal_threshold uint8_t Enum 4 1 Detect threshold 5.3.2 Detect Integration The QTouch Library features a detect integration mechanism, which acts to confirm detection in a robust fashion. The detect integrator (DI) acts as a simple signal filter to suppress false detections caused by spurious events like electrical noise. A counter is incremented each time the sensor delta has exceeded its threshold and stayed there for a specific number of acquisitions, without going below the threshold levels. When this counter reaches a preset limit (the DI value) the sensor is finally declared to be touched. If on any acquisition the delta is not seen to exceed the threshold level, the counter is cleared and the process has to start from the beginning. The DI process is applicable to a ‘release’ (going out of detect) event as well. For example, if the DI value is 10, then the device has to exceed its threshold and stay there for 10 acquisitions in succession without going below the threshold level, before the sensor is declared to be touched. Setting D I Variable name qt_ di Data Type uint8_ t Unit Min Cycle s Max 0 Typical 25 5 4 5.3.3 Drift Hold Time Drift Hold Time (DHT) is used to restrict drift on all sensors while one or more sensors are activated. It defines the length of time the drift is halted after a key detection. 16 8207L-AT42-05/12 This feature is useful in cases of high density keypads where touching a key or floating a finger over the keypad would cause untouched keys to drift, and therefore create a sensitivity shift, and ultimately inhibit any touch detection. Setting Drift hold time Variable name qt_drift_hold_time Data Type uint8_t Unit 200 ms Min 1 Max 255 Typical 20 (4s) 5.3.4 Maximum ON Duration If an object unintentionally contacts a sensor resulting in a touch detection for a prolonged interval it is usually desirable to recalibrate the sensor in order to restore its function, perhaps after a time delay of some seconds. The Maximum on Duration timer monitors such detections; if detection exceeds the timer’s settings, the sensor is automatically recalibrated. After a recalibration has taken place, the affected sensor once again functions normally even if it still in contact with the foreign object. Max on duration can be disabled by setting it to zero (infinite timeout) in which case the channel never recalibrates during a continuous detection (but the host could still command it). Setting Variable name Data Type Unit Min Max Typical Maximum ON Duration qt_max_on_duration uint8_t 200 ms 0 255 30 (6s) 5.3.5 Positive / Negative Drift Drift in a general sense means adjusting reference level (of a sensor) to allow compensation for temperature (or other factor) effect on physical sensor characteristics. Decreasing reference level for such compensation is called Negative drift & increasing reference level is called Positive drift. Specifically, the drift compensation should be set to compensate faster for increasing signals than for decreasing signals. Signals can drift because of changes in physical sensor characteristics over time and temperature. It is crucial that such drift be compensated for; otherwise false detections and sensitivity shifts can occur. Drift compensation occurs only while there is no detection in effect. Once a finger is sensed, the drift compensation mechanism ceases since the signal is legitimately detecting an object. Drift compensation works only when the signal in question has not crossed the ‘Detect threshold’ level. The drift compensation mechanism can be asymmetric; it can be made to occur in one direction faster than it does in the other simply by changing the appropriate setup parameters. Signal values of a sensor tend to decrease when an object (touch) is approaching it or a characteristic change of sensor over time and temperature. Decreasing signals should not be compensated for quickly, as an approaching finger could be compensated for partially or entirely before even touching the channel (negative drift). However, an object over the channel which does not cause detection, and for which the sensor has already made full allowance (over some period of time), could suddenly be removed leaving the sensor with an artificially suppressed reference level and thus become insensitive to touch. In the latter case, the sensor should compensate for the object’s removal by raising the reference level relatively quickly (positive drift). 17 Setting Negative Drift Positive Drift Variable name qt_neg_drift_rate qt_pos_drift_rate Data Type uint8_t uint8_t Unit 200 ms 200 ms Min 1 1 Max 127 127 Typical 20 (4s) 5 (1s) 5.3.6 Positive Recalibration Delay If any key is found to have a significant drop in signal delta, (on the negative side), it is deemed to be an error condition. If this condition persists for more than the positive recalibration delay, i.e., qt_pos_recal_delay period, then an automatic recalibration is carried out. A counter is incremented each time the sensor delta is equal to the positive recalibration threshold and stayed there for a specific number of acquisitions. When this counter reaches a preset limit (the PRD value) the sensor is finally recalibrated. If on any acquisition the delta is seen to be greater than the positive recalibration threshold level, the counter is cleared and the positive drifting is performed. For example, if the PRD value is 10, then the delta has to drop below the recalibration threshold and stay there for 10 acquisitions in succession without going below the threshold level, before the sensor is declared to be recalibrated. Setting Positive Recalibration Delay Variable name qt_pos_recal_delay Data Type uint8_t Unit cycles Min 1 Max 255 Typical 3 5.4 Sensor specific settings Apart from global settings as mentioned in the section above, touch sensing using QTouch library could also be fine tuned by more number of configurable settings. This section explains the settings that are specific to each sensor. For example, sensor 0 can have a detect threshold (one of the sensor specific setting) that is different from sensor 1. 5.4.1 Detect threshold A sensor’s negative (detect) threshold defines how much its signal must drop below its reference level to qualify as a potential touch detect. The final detection confirmation must however satisfy the Detect Integrator (DI) limit. Larger threshold values desensitize sensors since the signal must change more (i.e. requires larger touch) in order to exceed the threshold level. Conversely, lower threshold levels make sensors more sensitive. Threshold setting depends on the amount of signal swing that occurs when a sensor is touched. Thicker front panels or smaller electrodes usually have smaller signal swing on touch, thus require lower threshold levels. Setting Threshold Variable name threshold Data Type uint8_t Unit counts Min 3 Max 255 Typical 10 – 20 5.4.2 Hysteresis This setting is sensor detection hysteresis value. It is expressed as a percentage of the sensor detection threshold setting. Once a sensor goes into detect its threshold level is reduced (by the 18 8207L-AT42-05/12 hysteresis value) in order to avoid the sensor dither in and out of detect if the signal level is close to original threshold level. • Setting of 0 = 50% of detect threshold value (HYST_50) • Setting of 1 = 25% of detect threshold value (HYST_25) • Setting of 2 = 12.5% of detect threshold value (HYST_12_5) • Setting of 3 = 6.25% of detect threshold value (HYST_6_25) Setting Hysteresis Variable name detect_hysteresis Data Type uint8_t (2 bits) Unit Enum Min HYST_6_25 Max HYST_50 Typical HYST_6_25 5.4.3 Position Resolution The rotor or slider needs the position resolution (angle resolution in case of rotor and linear resolution in case of slider) to be set. Resolution is the number of bits needed to report the position of rotor or slider. It can have values from 2bits to 8 bits. Setting Position Resoluti on Variable name position_ resolution Data Type uint8_t (3 bits) Unit Min - 2 bits Reported position 0–3 Max 8 bits Reported position 0-255 Typica l 8 5.4.4 Position Hysteresis In case of QMatrix, the rotor or slider needs the position hysteresis (angle hysteresis in case of rotor and linear hysteresis in case of slider) to be set. It is the number of positions the user has to move back, before touch position is reported when the direction of scrolling is changed and during the first scrolling after the touch down. Hysteresis can range from 0 (1 position) to 7 ( 8 positions). The hysteresis is carried out at 8 bits resolution internally and scaled to desired resolution; therefore at resolutions lower than 8 bits there might be a difference of 1 reported position from the hysteresis setting, depending on where the touch is detected. At lower resolutions, where skipping of the reported positions is observed, hysteresis can be set to 0 (1 position). At Higher resolutions (6 ..8bits) , it would be recommended to have a hysteresis of at least 2 positions or more. NOTE: It is not valid to have a hysteresis value more than the available bit positions in the resolution. Ex: do not have a hysteresis value of 5 positions with a resolution of 2 bits (4 positions). Setting Position Hysteresis Variable name position_hysteresis Data Type uint8_t (3 bits) Unit - Min 0 Max 7 Typical 3 NOTE: Position hysteresis is not valid (unused) in case of QTouch acquisition method libraries. 19 5.4.5 Adjacent Key Suppression (AKS) In designs where the sensors are close together or set for high sensitivity, multiple sensors might report detect simultaneously if touch is near them. To allow applications to determine the intended single touch, the touch library provides the user the ability to configure a certain number of sensors in an AKS group. When a group of sensors are in the same AKS group, then only the first strongest sensor will report detection. The sensor reporting detection will continue to report detection even if another sensor’s delta becomes stronger. The sensor stays in detect until its delta falls below its detection threshold, and then if any more sensors in the AKS group are still in detect then the strongest will report detection. So at any given time only one sensor from each AKS group will be reported to be in detect. The library provides the ability to configure any sensor to be included in any one of the Adjacent Key Suppression Groups (AKS Group). Setting AKS Group Variable name aks_group Data Type uint8_t (3 bits) Unit Enum Min 0 (off) Max 7 Typical 0 (off) 5.5 Using the Sensors 5.5.1 Avoiding Cross-talk In ATMEL QTouch library variants that use QTouch acquisition technology, adjacent sensors are not measured at the same time. This prevents interference due to cross-talk between adjacent channels, but at the same time some sensor configurations take longer to measure than others. For example, if an 8-channel device is configured to support 8 keys, then the library will measure the keys on channels 0, 2, 4, and 6 parallely, followed by keys on channels 1, 3, 5, and 7. If the same device is configured, say, to support 4 keys, putting them either on all the odd channels or on all the even channels means that they can all be measured simultaneously. This means the library calls are faster, and the device can use less power. So, it is recommended that the appropriate channel numbers are used when using less than the maximum number of channels available for the device to ensure optimum performance. In a similar sense for faster execution and reduced power consumption, it is also advisable to use intra-port sensor configuration instead of inter-port sensor configuration while using 4 channels on the same port. 5.5.2 Multiple measurements The library will not automatically perform multiple measurements on a sensor (Ex: To resolve for instance Detect Integration or recalibration.). The user is given the option to perform the measurement multiple times if certain conditions are met. This will enable the user to implement the time critical code thereby making the qt_measure_sensors() a non-blocking API .The host application has to perform multiple measurements, based on the need. The global flag QTLIB_BURST_AGAIN indicating that multiple measurements are needed is passed to the user. This is BIT8 of the return value from the qt_measure_sensors( ) API. The main_.c has the example usage to perform multiple measurements. If QTLIB_BURST_AGAIN = 1, multiple measurements are needed to  To compensate for drift  Resolve re-calibration  Resolve calibration.  Resolve detect integration. 20 8207L-AT42-05/12 If QTLIB_BURST_AGAIN = 0, multiple measurements are not needed and the user can execute the host application code. Apart from QTLIB_BURST_AGAIN, various flags are provided to the user to perform the multiple measurements based on the need of the host application to act to specific situation. Description of the these flags can be found in the section5.6.5.6 Note: To maintain robustness and timing of the touch sensing measurement, it is recommended that the user calls the qt_measure_sensors() immediately if the flag QT_BURST_AGAIN=1. However, the user is allowed to run time- critical section (not more than few instructions) of the host application comprising on the touch sensing timing. 5.5.3 Guard Channel Guard channel in Qtouch Acquisition Method allows one key to be configured as a guard channel to help prevent false detection. Guard channel keys should be more sensitive than the other keys (physically bigger or larger Cs).To enable key as guard channel, the designated key is connected to a sensor pad which detects the presence of touch and overrides any output from the other keys using the AKS feature. The key can be configured to have a guard channel function by adjusting a number of independent settings. The Guard channel is designed so that it is likely to be activated unless a key is accurately touched. The guard channel sensor must be set up so that it is slightly more sensitive than the keys that it surrounds. The exact amount of increase depends on the application and is best determined by experimentation. There are three methods of increasing the sensor sensitivity that can be used in combination: 1. Increasing the size of the sensor. 2. Increasing the value of the Sample Capacitor (Cs). 3. Adjust the detection threshold for the sensor. The sensor size and capacitor values should be altered to establish the base sensitivity for the sensor. Once these values have been established, the detection threshold can be used to fine tune the sensor. MCU with SNS and SNSK Pins 21 The Above figure illustrates how a Guard sensor/key is to be visualized.It has six keys and five keys are surrounded by a Guard Channel. Please refer QTAN0031 for further information on Guard Channel. http://www.atmel.com/dyn/resources/prod_documents/QTAN0031(2).pdf 5.6 QTouch API and Usage The Atmel QTouch library provides support for many devices. This chapter explains the touch library for such devices without any hardware support. 5.6.1 QTouch Library API This section describes the QTouch library Application Programming Interface (API) for touch sensing using QTouch and QMatrix acquisition methods. Using the API, Touch sensors and the associated channels can be defined. Once touch sensing has been initiated by the user, the host application can use the API to make touch measurements and determine the status of the sensors. 5.6.2 touch_api.h - public header file The touch_api.h header file is the public header file which needs to be included in users application and it has the type definitions and function prototypes of the API’s listed in sections 5.6.3 , 5.6.4 and 5.6.5 The touch_api.h header file is located in the library distribution in the following directory. • ..\Atmel_QTouch_Libraries_5.x\Generic_QTouch_Libraries\include 5.6.3 Type Definitions and enumerations used in the library 5.6.3.1 Typedefs This section lists the type definitions used in the library. Typedef uint8_t int8_t uint16_t int16_t uint32_t threshold_t 5.6.3.2 Notes unsigned 8-bit integer signed 8-bit integer unsigned 16-bit integer signed 16-bit integer unsigned 32-bit integer unsigned 8-bit integer used for setting a sensor detection threshold Enumerations This section lists the enumerations used in the QTouch Library. 5.6.3.2.1 sensor_type_t Enumeration sensor_type_t Use Define the type of the sensor Values SENSOR_TYPE_UNASSIGNED SENSOR_TYPE_KEY SENSOR_TYPE_ROTOR 22 Comment Channel is not assigned to any sensor Sensor is of type KEY Sensor is of type ROTOR 8207L-AT42-05/12 SENSOR_TYPE_SLIDER Sensor is of type SLIDER 5.6.3.2.2 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 NO_AKS_GROUP AKS_GROUP_1 AKS_GROUP_2 AKS_GROUP_3 AKS_GROUP_4 AKS_GROUP_5 AKS_GROUP_6 AKS_GROUP_7 Comment NO AKS group selected for the sensor AKS Group number 1 AKS Group number 2 AKS Group number 3 AKS Group number 4 AKS Group number 5 AKS Group number 6 AKS Group number 7 5.6.3.2.3 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 CHANNEL_0 CHANNEL_1 CHANNEL_2 CHANNEL_3 ..... Upto CHANNEL ( N-1 ) Comment Channel number : 0 Channel number : 1 Channel number : 2 Channel number : 3 Channel number: .. 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 5.6.3.2.4 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 23 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 HYST_50 HYST_25 HYST_12_5 HYST_6_25 Comment 50% Hysteresis 25% Hysteresis 12.5% Hysteresis 6.25% Hysteresis 5.6.3.2.5 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 RES_1_BIT RES_2_BIT RES_3_BIT RES_4_BIT RES_5_BIT RES_6_BIT RES_7_BIT RES_8_BIT Comment 1 bit resolution : reported positions range 0 – 1 2 bit resolution : reported positions range 0 – 3 3 bit resolution : reported positions range 0 – 7 4 bit resolution : reported positions range 0 – 15 5 bit resolution : reported positions range 0 – 31 6 bit resolution : reported positions range 0 – 63 7 bit resolution : reported positions range 0 – 127 8 bit resolution : reported positions range 0 – 255 5.6.3.2.6 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 24 Comment 8207L-AT42-05/12 RECAL_100 RECAL_50 RECAL_25 RECAL_12_5 RECAL_6_25 100% recalibration threshold 50% recalibration threshold 25% recalibration threshold 12.5% recalibration threshold 6.25% recalibration threshold 5.6.4 Data structures This section lists the data structures that hold sensor status, settings, and diagnostics information 5.6.4.1 qt_touch_status_t Structure Input / Output Use qt_touch_status_t Output from the Library 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 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 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 ). 34 8207L-AT42-05/12 qt_reset_sensing() The host application (optionally) calls “qt_reset_sensing( )” to reset all channels and touch sensing parameters to their default states. This step is only required if the host wants to dynamically reconfigure the library at runtime qt_enable_xxx() The host application calls “qt_enable_key( )”, “qt_enable_rotor( )” and/or “qt_enable_slider()” as required to configure the touch sensors qt_init_sensing() The host application calls qt_init_sensing() to calibrate all the configured channels and prepare the sensors for capacitive measurement qt_set_parameters() The host application qt_set_parameters() to initialize the threshold parameters for the library. If the user needs to change the thresholds, edit the global data structure qt_config_data prior to calling this API init_timer_isr() The host application initializes the timer module required for capacitive measurement qt_measure_sensors() The host application periodically calls “qt_measure_sensors( )” to make capacitive measurements. Time-critical host application code Yes Part of host application which cannot wait till multiple measurements are complete (should be as minimal as possible) Check if multiple measurements are needed or not: To resolve calibration To resolve DI To resolve positive recalibration To compensate for drift Is QTLIB_BURST_A GAIN=1 No check qt_touch_status check the global status variable “qt_touch_status” to see if any sensors are in detect, and the angle or position of any enabled rotors or sliders Non-Time critical host application code Host application which can be executed after the completion of multiple measurements for all the channels Figure 5-6: Sequence of operations to add Touch capability 35 5.6.6.1.1.1 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. • • • 36 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. o For example, on a 8 channel configuration using a single pair of SNS and SNSK ports, if pin 2 is not used for touch sensing ( on both SNS and SNSK ports), channel number 2 is unavailable and care should be taken while configuring the channels and sensors to avoid using this channel. 8207L-AT42-05/12 Pin 0 Pin 1 Port A Pin 2 All SNSK pins terminated on this port Pin 3 Pin 4 channel 3 channel 4 Pin 6 channel 6 Pin 1 Port B Pin 2 All SNS pins terminated on this port Pin 3 Pin 4 channel 7 channel 3 channel 4 channel 6 Port C Pin 2 All SNSK pins terminated on this port Pin 3 Pin 4 channel 7 channel 8 channel 9 channel 11 channel 12 channel 13 Pin 6 channel 14 Pin 0 Pin 1 Port D Pin 2 All SNS pins terminated on this port Pin 3 Pin 4 channel 15 sensor5 sensor6 sensor7 channel 8 channel 9 channel 10 channel 11 channel 12 Pin 5 channel 13 Pin 6 channel 14 Pin 7 sensor4 channel 10 Pin 5 Pin 7 sensor3 channel 2 Pin 6 Pin 1 sensor2 channel 1 channel 5 Pin 0 sensor1 channel 0 Pin 5 Pin 7 sensor0 channel 2 channel 5 Pin 0 SNS – SNSK Port Pair two channel 1 Pin 5 Pin 7 SNS – SNSK Port Pair one channel 0 channel 15 Figure 5-7 : channel numbering for QTouch acquisition method when the SNS and SNSK pins are connected to different ports. 5.6.6.1.1.2 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: 37 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. 5.6.6.1.1.3 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 ) o 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. Pin 0 Port A Pin 1 Pin 2 All Pin 3 SNSK and Pin 4 SNS pins terminated Pin 5 on the same port Pin 6 Pin 7 channel 0 SNS pin SNSK pin SNS pin channel 1 SNSK pin channel 2 SNSK pin channel 3 SNSK pin sensor1 SNS pin SNS pin sensor2 Figure 5-8 : Channel numbering for QTouch acquisition method when the SNS and SNSK pins are connected to the same port 5.6.6.1.1.4 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. 38 8207L-AT42-05/12 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. 5.6.6.1.2 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: 1. All channels selected for a specific rotor or slider should be on a single Y line. 2. 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. X0 X1 Ch 0 Ch 4 Ch 8 Ch 12 Ch 1 Ch 5 Ch 9 Ch 13 Ch 6 Ch 10 Ch 14 Ch 11 Ch 15 ROTOR/SLIDER X2 X3 Ch 2 Ch 3 Ch 7 KEY Y0 QMatrix Channels Y1 Y2 Y3 QMatrix also supports such rotor/slider configuration. The channels selected for a Rotor / Slider MUST be on a single YA/YB line. Figure 5-9: Channel Numbering for QMatrix acquisition method libraries 39 Table 1 : Channel numbers for QMatrix configurations Line label Channel 0 Channel 1 Channel 2 Channel 3 Channel 4 Channel 5 Channel 6 Channel 7 Channel 8 Channel 9 Channel 10 Channel 11 Channel 12 Channel 13 Channel 14 Channel 15 Channel 16 Channel 17 Channel 18 Channel 19 Channel 20 Channel 21 Channel 22 Channel 23 Channel 24 Channel 25 Channel 26 Channel 27 Channel 28 Channel 29 Channel 30 Channel 31 Channel 32 Channel 33 Channel 34 Channel 35 Channel 36 Channel 37 Channel 38 Channel 39 Channel 40 Channel 41 Channel 42 Channel 43 Channel 44 Channel 45 Channel 46 Channel 47 Channel 48 Channel 49 Channel 50 Channel 51 40 4 channel configur ation (4 x 1) X0Y0 X1Y0 X2Y0 X3Y0 N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A 8 channel configurat ion (4 x 2) X0Y0 X1Y0 X2Y0 X3Y0 X0Y1 X1Y1 X2Y1 X3Y1 N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A 16 channel Configura tion (8 x 2) X0Y0 X1Y0 X2Y0 X3Y0 X4Y0 X5Y0 X6Y0 X7Y0 X0Y1 X1Y1 X2Y1 X3Y1 X4Y1 X5Y1 X6Y1 X7Y1 N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A 16 channel Configura tion (4 x 4) X0Y0 X1Y0 X2Y0 X3Y0 X0Y1 X1Y1 X2Y1 X3Y1 X0Y2 X1Y2 X2Y2 X3Y2 X0Y3 X1Y3 X2Y3 X3Y3 N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A 32 channel configurat ion (8 x 4) X0Y0 X1Y0 X2Y0 X3Y0 X4Y0 X5Y0 X6Y0 X7Y0 X0Y1 X1Y1 X2Y1 X3Y1 X4Y1 X5Y1 X6Y1 X7Y1 X0Y2 X1Y2 X2Y2 X3Y2 X4Y2 X5Y2 X6Y2 X7Y2 X0Y3 X1Y3 X2Y3 X3Y3 X4Y3 X5Y3 X6Y3 X7Y3 N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A 56 channel configurat ion (8 x 7) X0Y0 X1Y0 X2Y0 X3Y0 X4Y0 X5Y0 X6Y0 X7Y0 X0Y1 X1Y1 X2Y1 X3Y1 X4Y1 X5Y1 X6Y1 X7Y1 X0Y2 X1Y2 X2Y2 X3Y2 X4Y2 X5Y2 X6Y2 X7Y2 X0Y3 X1Y3 X2Y3 X3Y3 X4Y3 X5Y3 X6Y3 X7Y3 X0Y4 X1Y4 X2Y4 X3Y4 X4Y4 X5Y4 X6Y4 X7Y4 X0Y5 X1Y5 X2Y5 X3Y5 X4Y5 X5Y5 X6Y5 X7Y5 X0Y6 X1Y6 X2Y6 X3Y6 8207L-AT42-05/12 64 channel configurat ion (8 x 8) X0Y0 X1Y0 X2Y0 X3Y0 X4Y0 X5Y0 X6Y0 X7Y0 X0Y1 X1Y1 X2Y1 X3Y1 X4Y1 X5Y1 X6Y1 X7Y1 X0Y2 X1Y2 X2Y2 X3Y2 X4Y2 X5Y2 X6Y2 X7Y2 X0Y3 X1Y3 X2Y3 X3Y3 X4Y3 X5Y3 X6Y3 X7Y3 X0Y4 X1Y4 X2Y4 X3Y4 X4Y4 X5Y4 X6Y4 X7Y4 X0Y5 X1Y5 X2Y5 X3Y5 X4Y5 X5Y5 X6Y5 X7Y5 X0Y6 X1Y6 X2Y6 X3Y6 Channel 52 Channel 53 Channel 54 Channel 55 Channel 56 Channel 57 Channel 58 Channel 59 Channel 60 Channel 61 Channel 62 Channel 63 5.6.6.2 N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A X4Y6 X5Y6 X6Y6 X7Y6 N/A N/A N/A N/A N/A N/A N/A N/A X4Y6 X5Y6 X6Y6 X7Y6 X0Y7 X1Y7 X2Y7 X3Y7 X4Y7 X5Y7 X6Y7 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, HYST_6_25, RES_8_BIT, 0); CHANNEL_2, AKS_GROUP_1, 16, /* 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, HYST_6_25, RES_8_BIT, 0); CHANNEL_5, NO_AKS_GROUP, 16, /* 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, HYST_6_25, RES_8_BIT, 0); CHANNEL_2, NO_AKS_GROUP, 16, Now, the rotor is sensor 0, the keys are sensors 1 and 2, and the slider is sensor 3. 41 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. 1. 2. 5.6.6.3 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. channel 7 channel 6 channel 5 channel 4 channel 3 channel 2 channel 1 channel 0 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. QTouch/QMatrix Channel Acquisition Method channel_signals[] optional qt_filter_callback() function modified channel_signals[] post-processing modified channel_signals[] qt_touch_status.sensor_states[] qt_touch_status_rotor_slider_values[] Figure 5-10 : 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: 42 8207L-AT42-05/12 /* 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. 5.6.6.4 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™. Port Configuration: #define SNSK1 #define SNS1 #define SNSK2 #define SNS2 C D A B Channel/Pin Configuration: /* enable a key on channel 0 */ qt_enable_key( CHANNEL_0, AKS_GROUP_2, 10u, HYST_6_25 ); 43 /* 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, HYST_6_25, RES_8_BIT, 0u ); AKS_GROUP_1, 16u, /* 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. 5.6.6.5 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 48 0.05 0.02083 Pin Configuration Wizard.Pin configuration Figure 5-26: Selecting the pin configuration wizard for theDesign 5. Pin configuration Window will pop up with the information on the usage of the tool. Click Next to proceed to the configuration. 95 Figure 5-27: : Start page of the wizard 6. Select the MCU and click Next as shown below. 96 8207L-AT42-05/12 Figure 5-28: Selecting the MCU for the New Design 7. Select the SNS and SNSK ports needs for the design and click Next. Figure 5-29: Selecting SNS and SNSK ports in the New Design 97 8. Select the pins used for the design and click Next If there is error in the selection of the pins (Ex: conflictin pins used), a red marker will be appear and the user cannot proceed to next step in configuration until the user has done the correct pin selection. Now once the selection is done without errors, Click Next Figure 5-30: Selecting the SNS and SNSK Port Pins in the new Design( With Error) 98 8207L-AT42-05/12 Figure 5-31: Selecting the SNS and SNSK Port Pins in the new Design( Without Error) Once the pins are selected, Pin Wizard will provide the summary report .Check whether details are correct as specified.Click Next Figure 5-32: Summary report 99 Figure 5-33: Code Generation tab in Pin Configuration wizard 9. In the New Window Screen, the code is shown on the screen.QTOUCH_STUDIO_MASKS needs to be enabled in the project option or in touch_ config.h file. And in the main.c file, this code SNS_array and SNSK_array needs to be copied from here and put under QTOUCH_STUDIO_MASKS macro as shown below in the main.c file: #ifdef QTOUCH_STUDIO_MASKS SNS_array[0][0]=0x09; SNS_array[0][1]=0x22; SNS_array[1][0]=0x00; SNS_array[1][1]=0x00; SNSK_array[0][0]=0x14; SNSK_array[0][1]=0x88; SNSK_array[1][0]=0x00; SNSK_array[1][1]=0x00; #endif Note: 1. To use 4 and 8 channel libraries(interport case) for pin configurability _STATIC_PORT_PIN_CONF_ macro needs to be enabled in the touch_config.h file. 100 8207L-AT42-05/12 , 2. QTOUCH_STUDIO_MASKS needs to be enabled if using pin configurability .If not enabled then, static pin mapping will work same as in the earlier versions of the libraries 5.8.2 Pin Configuration for QMatrix Acquisition Method The QMatrix acquisition method libraries needs to be used after configuring X and YA and YB lines on IO pins of the port as described in the configuration rules described in the section below. The QTouch Studio Pin Configurator Wizard can be used to assign X, YA, YB, SMP lines on the pins and rules are internally taken care in the Qtouch Studio Pin Configurator Wizard. The snippets can be taken from the QTouch Studio Pin Configurator Wizard and copied to appropriate places in the main.c and touch_ config.h files in the example projects provided. 5.8.2.1 Configuration Rules: 1. The X lines can be configured on different ports up to a maximum of 3 ports Ex: NUM_X_PORTS = 3 (maximum value supported). However the possible values are NUM_X_PORTS = 1 or NUM_X_PORTS = 2 or NUM_X_PORTS = 3 2. The X lines can be configured on the three different ports. 3. The X lines can be configured on any pins of the ports selected above Ex: X0 on PB2, X1 on PD5, X2 on PE0, X3 on PD1( when NUM_X_LINES= 4), Provided that these pins do not conflict with the other pins for touch sensing or with the host application usage. 4. The Y lines can be configured on the any of the pins of the ports selected Ex: Any pins on the PORT_YA and PORT_YB selected. Suppose, PORT_YA is D, and PORT_YB is C Since, pin 5 and pin 1 PORTD are already used for X lines(X1, X3), the user can select any of the remaining pins for Y0A lines. Suppose that Y0 is on pin2 and Y1 is on pin6 Hence, Y0A – PD2, Y0B – PC2, Y1A – PD6, Y1B – PC6, 5. All the Qmatrix usage Pins X lines,YA lines, YB lines and SMP line can be on same port.Both YA and YB lines can share the same port. And the YA and YB need not be on same corresponding pins of the ports.The Macro SHARED_YAYB should be defined as 1 if YA and YB are on same port else should be defined as 0. 6. The PORT_YB is fixed for each device and should be same as the PORT on which the ADC input pins are available. 7. The SMP pin can be configured on any of the IO PORT pins available. Ex: PORT_SMP = D SMP_PIN = 7 as this pin is not being used by touch sensing. Note:  Please take care that the touch sensing pins do not conflict with other IO pins used by host application 101 5.8.2.2 How to use QTouch Studio for Pin Configurability: Note: The Qtouch Composer is available for few select set of devices.But user can use Qtouch Studio 4.4 for the devices which are not supported in Qtouch Composer. Also YA,YB shared on same port feature is available in Qtouch Composer and not available in Qtouch Studio 4.4.Please refer section 5.6.10.3 The following steps describe the details on how to use pin configurability for QMatix Acquisition method: 1. Open AVR Qtouch Studio .Enable the Design Mode Radio button on the left hand side of the screen.. Figure 5-34: Selecting the Design mode in the AVR QTouch Studio 2. Go to File Menu option and click New Design 102 8207L-AT42-05/12 Figure 5-35: Selecting New Design 3. In the Create New Design Window, give the Project name and Kit Technology (QMatrix in this case) and Number of sensors (Keys/Rotors/Sliders) and click Create Design. Figure 5-36 Creating New Design in the AVR QTouch Studio 103 After Creating Design , the new design mode shows the virtual kit view with sensors that have been created in some order. Figure 5-37: New Design Sensors in the AVR QTouch Studio 4. Now Go to Tools->Pin Configuration Wizard as shown below. Figure 5-38: Selecting the pin configuration wizard 5. Pin configuration Window will pop up with the information on the usage of the tool. Click Next to proceed. 104 8207L-AT42-05/12 Figure 5-39: Start window of the configuration wizard 6. .Select the MCU and click Next as shown below. Figure 5-40: MCU selection window from the configuration wizard. 7. Select the Channels needed for the design from the list provided and click Next. 105 If 6 channels are needed, the next immediate value that suits the design needs to be selected. Ie., 8 channels (4 x 2 ) configuration. Figure 5-41: Selecting channels and configuration in the New Design 8. Select the pins used for the design and click Next. If there is error in the selection of the pins (Ex: conflictin pins used), a red marker will be appear and the user cannot proceed to next step in configuration until the user has done the correct pin selection. Now once the selection is done without errors, Click Next. 106 8207L-AT42-05/12 Figure 5-42: Selecting the X,YA,YB,SMP Pins in the new Design with errors. Figure 5-43: Selecting the X,YA,YB,SMP Pins in the new Design without errors. Once the pins are selected, Pin Wizard will provide the summary report .Check whether details are correct as specified.Click Next. 107 If there are some errors that are found in the summary report, the user can click “back” button and modify the changes needed. Figure 5-44: Summary report Figure 5-45: Code Generation tab in Pin Configuration wizard 9. The code is shown in the New Window Screen. Note: Use FILL_OUT_YA_LINE_INFO and FILL_OUT_YB_LINE_INFO code instead of 108 8207L-AT42-05/12 FILL_OUT_Y_LINE_INFO as now YA and YB can be shared on same port. The code can be copied using the “copy code” and pasted in the main.c and touch_config .h file, a. In touch _config.h, Copy the following header definitions as part of the preprocessor directives in the project space or in the beginning of the file #define NUM_X_PORTS 2 #define PORT_X_1 B #define PORT_X_2 D #define PORT_YA D #define PORT_YB C #define SMP_PORT D #define SMP_PIN 7 #define SHARED_YAYB 0 b. In main.c , Copy the code as below x_line_info_t x_line_info[NUM_X_LINES]= { FILL_OUT_X_LINE_INFO(1,1); FILL_OUT_X_LINE_INFO(2,2); FILL_OUT_X_LINE_INFO(1,3); FILL_OUT_X_LINE_INFO(2,0); }; y_line_info_t ya_line_info[NUM_Y_LINES]= { FILL_OUT_YA_LINE_INFO(1); FILL_OUT_YA_LINE_INFO(3); }; y_line_info_t yb_line_info[NUM_Y_LINES]= { FILL_OUT_YB_LINE_INFO(1); FILL_OUT_YB_LINE_INFO(3); }; Note: If YA,YB shared on same port feature is needed , then apart from the above Macros #define SHARED_YAYB needs to be enabled as 1. 5.9 MISRA Compliance Report This section lists the compliance and deviations for MISRA standards of coding practice for the QTouch and QMatrix acquisition method libraries. 109 5.9.1 What is covered The QTouch and QMatrix acquisition method libraries adhere to the MISRA standards. The additional reference code provided in the form of sample applications is not guaranteed to be MISRA compliant. 5.9.2 Target Environment Development Environment MISRA Checking software MISRA Rule set applied IAR Embedded Workbench The MISRA C Compliance has been performed for the library using MISRA C 2004 Rules in IAR Workbench development environment. MISRAC 2004 Rule Set 5.9.3 Deviations from MISRA C Standards 5.9.3.1 QTouch acquisition method libraries The QTouch acquisition method libraries were subject to the above mentioned MISRA compliance rules. The following exceptions have not been fixed as they are required for the implementation of the library. Applicable Release Rule No 1.1 QTouch libraries version 5.0 Rule Description Rule states that all code shall conform to ISO 9899 standard C, with no extensions permitted. 10.1 Rule states that implicit conversion from Underlying long to unsigned long 10.6 This Rule says that a 'U' suffix shall be applied to all constants of 'unsigned' type 14.4 Rule states that go-to statement should not be used. 19.10 19.12 110 Rule states that In the definition of a function-like macro, each instance of a parameter shall be enclosed in parenthesis Rule states that there shall be at most one occurrence of the # or ## preprocessor operator in a single macro definition Exception noted / How it is addressed This Rule is not supported as the library implementation requires IAR extensions like __interrupt. These intrinsic functions relate to device hardware functionality, and cannot practically be avoided. The library uses macros to combine symbol definitions to form a unique expanded symbol name and in this, the usage of unsigned qualifiers for numeric constants (e.g. 98u) causes name mangling. This is the only occurrence of this error in the library. The library uses macros to combine symbol definitions to form a unique expanded symbol name and in this, the usage of unsigned qualifiers for numeric constants (e.g. 98u) causes name mangling. This is the only occurrence of this error in the library. The library uses conditional jump instructions to reduce the code footprint at a few locations and this is localized to small snippets of code. Hence this rule is not supported. There is one instance where the library breaks this rule where two macro definitions are combined to form a different symbol name. Usage of parenthesis cannot be used in this scenario. There is one instance in the library where this rule is violated where the library concatenates two macro definitions to arrive at a different definition. 8207L-AT42-05/12 5.9.3.2 QMatrix acquisition method libraries The QMatrix acquisition method software was subject to the above mentioned MISRA compliance rules. The following exceptions have not been fixed as they are required for the implementation of the library. Applicable release QTouch libraries ver 5.0 Rule No Rule Description Exceptions Reason 1.1 Rule states that all code shall conform to ISO 9899 standard C, with no extensions permitted. This Rule is not supported as the library implementation requires IAR extensions like __interrupt. These intrinsic functions relates to device hardware functionality, and cannot practically be avoided 10.1 Rule states that Illegal implicit conversion from Underlying long to unsigned long The library uses macros to combine symbol definitions to form a unique expanded symbol name and in this, the usage of unsigned qualifiers for numeric constants (e.g. 98u) causes name mangling. This is the only occurrence of this error in the library. 10.6 This Rule says that a 'U' suffix shall be applied to all constants of 'unsigned' type The library uses macros to combine symbol definitions to form a unique expanded symbol name and in this, the usage of unsigned qualifiers for numeric constants (e.g. 98u) causes name mangling. This is the only occurrence of this error in the library. Rule states that In the definition of a function-like macro, each instance of a parameter shall be enclosed in parenthesis There is one instance where the library breaks this rule where two macro definitions are combined to form a different symbol name. Usage of parenthesis cannot be used in this scenario. Rule states that there shall be at most one occurrence of the # or ## preprocessor operator in a single macro definition There is one instance in the library where this rule is violated where the library concatenates two macro definitions to arrive at a different definition. 19.10 19.12 5.10 Known Issues Issue Cause Remedy / workaround Buiding QTouch Libraries Release 5.0 with WinAVR Compiler results in Linker Error. (Skipping Library libavrxxx.a, File not found). QTouch Libraries Release 5.0 are build with Atmel Studio6 Native Toolchain Flavor. Always use Native Toolchain Flavor (Advanced Tab in Project properties) setting in Atmel Studio6 for Building QTouch Library Release. The GCC example projects for QMatrix does not compile the delay cycles (QT_DELAY_CYCLES) above a value of 5 because of the preprocessor expansions. Recommended to remove UL from the preprocessor constants and in the chain of macros used for QT_DELAY_CYCLES. Valid for QT_DELAY_CYCLES = 5,10,25,50. Compiling These variables are available in QT600 project files throws 111 unused variable warning. the debug protocol for future use. When using IAR workbench for ATSAM to integrate the touch libraries, the linker would generate a warning indicating: This is because we link the library in RW data section. Warning[Lp005]: placement includes a mix of sections with content (example "ro data section .data_init in xfiles.o(dl7M_tl_if.a)") and sections without content (example "rw data section .data in xfiles.o(dl7M_tl_if.a)") Warning[Lp006]: placement includes a mix of writable sections (example "rw data section .data in xfiles.o(dl7M_tl_if.a)") and non-writable sections (example "ro data section .data_init in xfiles.o(dl7M_tl_if.a)") 5.11 Checklist This section lists troubleshooting tips and common configuration tips. Symptom Sensors do not go into detect or have unknown results Cause Multiplexing pins used by QTouch libraries in your design Action Check the Pins used for QTouch or QMatrix acquisition methods do not overlap with the applications usage of the ports Check the sensor design and minimize stray capacitance interference in your design Signal values report arbitrary values Stray capacitance Waveforms of charging / discharging of channels do not show up properly in oscilloscopes JTAG ICE connected to the board Try disconnecting the JTAG ICE completely from the kit JTAG Pins are enabled in the target. JTAG Pins are explicitly needs to be disabled in the main.c file /* disable JTAG pins */ MCUCR |= (1u