Atmel QTouch Library QTouch Library Peripheral Touch Controller USER GUIDE Description ® ® Atmel QTouch Peripheral Touch Controller (PTC) offers built-in hardware for capacitive touch measurement on sensors that function as buttons, sliders, and wheels. The PTC supports both mutual and self-capacitance measurement without the need for any external component. It offers superb sensitivity and noise tolerance, as well as self-calibration, and minimizes the sensitivity tuning effort by the user. The PTC is intended for autonomously performing capacitive touch sensor measurements. The external capacitive touch sensor is typically formed on a PCB, and the sensor electrodes are connected to the analog charge integrator of the PTC using the device I/O pins. The PTC supports mutual capacitance sensors organized as capacitive touch matrices in different X-Y configurations, including Indium Tin Oxide (ITO) sensor grids. In mutual capacitance mode, the PTC requires one pin per X-line (drive line) and one pin per Y-line (sense line). In self-capacitance mode, the PTC requires only one pin with a Y-line driver for each self-capacitance sensor. Features • • • • • • • • • • • • • Implements low-power, high-sensitivity, environmentally robust capacitive touch buttons, sliders, and wheels Supports mutual capacitance and self-capacitance sensing Up to 32 buttons in self-capacitance mode Up to 256 buttons in mutual capacitance mode Supports lumped mode configuration One pin per electrode - no external components Load compensating charge sensing Parasitic capacitance compensation for mutual capacitance mode Adjustable gain for superior sensitivity Zero drift over the temperature and VDD range No need for temperature or VDD compensation Hardware noise filtering and noise signal de-synchronization for high conducted immunity Atmel provided QTouch Library firmware and QTouch Composer tool Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 Product Support For assistance related to QTouch capacitive touch sensing software libraries and related issues, contact your local Atmel sales representative or log on to myAtmel Design Support portal to submit a support request or access a comprehensive knowledge base. If you do not have a myAtmel account, please visit http://www.atmel.com/design-support/ to create a new account by clicking on Create Account in the myAtmel menu at the top of the page. When logged in, you will be able to access the knowledge base, submit new support cases from the myAtmel page or review status of your ongoing cases. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 2 Table of Contents Description.......................................................................................................................1 Features.......................................................................................................................... 1 1. Development Tools ................................................................................................... 5 2. Device Variants Supported........................................................................................ 6 3. Capacitive Touch Technology.................................................................................... 8 3.1. 3.2. 3.3. 3.4. 3.5. 3.6. 3.7. 3.8. 3.9. 3.10. Capacitive Touch Sensors............................................................................................................8 Capacitance Measurement Methods............................................................................................8 Self-capacitance Measurement Method.......................................................................................8 Mutual Capacitance Measurement Method..................................................................................9 Capacitive Touch Lumped Sensors..............................................................................................9 Capacitive Touch Low Power Sensor......................................................................................... 11 PTC and its Benefits...................................................................................................................13 PTC Block Diagram for Self-capacitance and Mutual Capacitance Method.............................. 13 Design Approach with PTC........................................................................................................ 15 Capacitive Touch Development Cycle........................................................................................16 4. Touch Sensor Debug and Status Information.......................................................... 17 4.1. 4.2. 4.3. 4.4. Signal..........................................................................................................................................17 Reference...................................................................................................................................17 Delta........................................................................................................................................... 18 Touch Status & Slider/Wheel Position........................................................................................ 19 5. QTouch Library........................................................................................................ 20 5.1. 5.2. 5.3. 5.4. 5.5. 5.6. 5.7. 5.8. Overview.....................................................................................................................................20 Library Parameters.....................................................................................................................21 Moisture Tolerance..................................................................................................................... 42 Reading Sensor States...............................................................................................................44 Application Flow......................................................................................................................... 44 API Sequence.............................................................................................................................46 State Machine.............................................................................................................................47 Operation Modes........................................................................................................................50 5.9. Touch Library API Error.............................................................................................................. 52 6. Tuning for Noise Performance.................................................................................54 6.1. 6.2. Noise Sources............................................................................................................................ 54 Noise Counter Measures............................................................................................................54 7. Application Design................................................................................................... 60 7.1. 7.2. Touch Library and Associated Files............................................................................................60 Code and Data Memory Considerations.................................................................................... 60 8. Example Applications.............................................................................................. 63 8.1. Atmel Board Example Projects...................................................................................................63 8.2. 8.3. 8.4. 8.5. 8.6. 8.7. User Board Example Projects.................................................................................................... 66 Using Atmel Software Framework (ASF) with the Example Projects......................................... 67 Using Xplained Pro Kit to Program User Board......................................................................... 67 Using QDebug Touch Data Debug Communication Interface.................................................... 67 Using Xplained Pro Kit for QDebug Data Streaming from User Board...................................... 68 Using Atmel ICE for QDebug Data Streaming from User Board................................................ 70 9. Known Issues.......................................................................................................... 71 10. FAQ on PTC Qtouch................................................................................................72 11. Appendix..................................................................................................................73 11.1. 11.2. 11.3. 11.4. 11.5. 11.6. Macros........................................................................................................................................73 Typedef.......................................................................................................................................75 Enumeration............................................................................................................................... 75 Datastructures............................................................................................................................ 83 Global Variables......................................................................................................................... 91 API..............................................................................................................................................92 12. Revision History.......................................................................................................99 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 4 1. Development Tools The following development tools are required for developing QTouch library using PTC: • Development Environment for GCC Compiler: – QTouch Composer 5.9.108 or later versions – QTouch Library 5.9.191 or later versions Note: The QTouch Library and Composer extensions work only with Atmel Studio 7 which can be downloaded from http://www.atmel.com/ – Dependent Atmel Studio Extensions • Atmel Software Framework 3.30.1 or later versions • Atmel Kit Extension 7.0.44 or later versions • Development Environment for IAR Compiler: ® ® – IAR Embedded Workbench for ARM 7.50.1.10273 or later ® – IAR Embedded Workbench for Atmel AVR 6.70.1 or later – Atmel Software Framework 3.29.0 or later (optional) – Atmel QTouch Library 5.9.191 IAR Installer (available at http://www.atmel.com/tools/ qtouchlibraryptc.aspx) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 5 2. Device Variants Supported QTouch Library for SAM and ATmega devices are available for the following device variants: Series Variant SAM D20 J Series ATSAMD20J18, ATSAMD20J17, ATSAMD20J16, ATSAMD20J15, ATSAMD20J14 SAM D20 G Series ATSAMD20G18, ATSAMD20G18U, ATSAMD20G17, ATSAMD20G17U, ATSAMD20G16, ATSAMD20G15, ATSAMD20G14 SAM D20 E Series ATSAMD20E18, ATSAMD20E17, ATSAMD20E16, ATSAMD20E15, ATSAMD20E14 SAM D21 J Series ATSAMD21J18A, ATSAMD21J17A, ATSAMD21J16A, ATSAMD21J15A, ATSAMD21J16B, ATSAMD21J15B SAM D21 G Series ATSAMD21G18A, ATSAMD21G17A, ATSAMD21G16A, ATSAMD21G15A, ATSAMD21G15B, ATSAMD21G16B, ATSAMD21G17AU, ATSAMD21G18AU SAM D21 E Series ATSAMD21E18A, ATSAMD21E17A, ATSAMD21E16A, ATSAMD21E15A, ATSAMD21E15B, ATSAMD21E15BU, ATSAMD21E16B, ATSAMD21E16BU SAM D10 C Series ATSAMD10C14A SAM D10 D Series ATSAMD10D14AM, ATSAMD10D14AS, ATSAMD10D14AU SAM D11 C Series ATSAMD11C14A SAM D11 D Series ATSAMD11D14AM, ATSAMD11D14AS, ATSAMD11D14AU SAM L21 E Series ATSAML21E15B, ATSAML21E16B, ATSAML21E17B, ATSAML21E18B SAM L21 G Series ATSAML21G16B, ATSAML21G17B, ATSAML21G18B SAM L21 J Series ATSAML21J16B, ATSAML21J17B, ATSAML21J18B SAM R21 E Series ATSAMR21E16A, ATSAMR21E17A, ATSAMR21E18A, ATSAMR21E19A SAM R21 G Series ATSAMR21G16A, ATSAMR21G17A, ATSAMR21G18A SAM DA1 E Series ATSAMDA1E14A, ATSAMDA1E15A, ATSAMDA1E16A SAM DA1 G Series ATSAMDA1G14A, ATSAMDA1G15A, ATSAMDA1G16A SAM DA1 J Series ATSAMDA1J14A, ATSAMDA1J15A, ATSAMDA1J16A SAM C21 E Series ATSAMC21E15A, ATSAMC21E16A, ATSAMC21E17A, ATSAMC21E18A SAM C21 G Series ATSAMC21G15A, ATSAMC21G16A. ATSAMC21G17A, ATSAMC21G18A SAM C21 J Series ATSAMC21J16A, ATSAMC21J17A, ATSAMC21J18A SAM C20 E Series ATSAMC20E15A, ATSAMC20E16A, ATSAMC20E17A, ATSAMC20E18A SAM C20 G Series ATSAMC20G15A, ATSAMC20G16A. ATSAMC20G17A, ATSAMC20G18A SAM C20 J Series ATSAMC20J16A, ATSAMC20J17A, ATSAMC20J18A SAM L22 G Series ATSAML22G16A, ATSAML22G17A, ATSAML22G18A SAM L22 J Series ATSAML22J16A, ATSAML22J17A, ATSAML22J18A Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 6 Series Variant SAM L22 N Series ATSAML22N16A, ATSAML22N17A, ATSAML22N18A ATmega Series ATmega328PB, ATmega324PB Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 7 3. Capacitive Touch Technology 3.1. Capacitive Touch Sensors Capacitive touch sensors replace conventional mechanical interfaces and operate with no mechanical wear and are closed to the environment. They provide greater flexibility in industrial design and result in differentiating end product design. For more information, refer Capacitive Touch Lumped Sensors and Capacitive Touch Low Power Sensor. Figure 3-1. Sensor Types 3.2. Capacitance Measurement Methods Self-capacitance measurement method involves charging a sense electrode of unknown capacitance to a known potential. The resulting charge is transferred into a measurement circuit. By measuring the charge with one or more charge-and transfer cycles, the capacitance of the sense plate can be determined. Figure 3-2. Capacitance Measurement Principle Mutual capacitance measurement method uses a pair of sensing electrodes. One electrode acts as an emitter into which a charge consisting of logic pulses is driven in burst mode. The other electrode acts as a receiver that couples to the emitter using the overlying panel dielectric. When a finger touches the panel, the field coupling is reduced, and touch is detected. 3.3. Self-capacitance Measurement Method • • Uses a single sense electrode (Y-line) – Self-capacitance button can be formed using one channel – Self-capacitance slider and wheel is formed using 3 channels Robust and easy to use, ideal for low sensors count Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 8 Figure 3-3. Self-capacitance Method 3.4. Mutual Capacitance Measurement Method • • • Uses a pair of sense electrodes (X-Y lines) – Mutual capacitance buttons use one X-Y channel – Mutual capacitance sliders and wheels can be configured to use 3 to 8 X-Y channels, depending on the sensor size Suitable for high sensor count Better moisture tolerance Figure 3-4. Mutual Capacitance Method 3.5. Capacitive Touch Lumped Sensors Lumped sensor configuration is a combination of multiple sense lines (Self-capacitance measurement) or multiple drive and sense lines (Mutual capacitance measurement) to act as one single sensor. Lumped mode acts as a tool for application developers to improve overall system performance. Improved Power Efficiency When multiple sensors are lumped together and treated as one single sensor the time taken to perform scans is reduced. For battery powered applications using multiple buttons, a group of touch sensors can be lumped to form a single lumped sensor and this sensor alone can be scanned, thereby resulting in reduced power consumption. Upon user presence detection on the lumped sensor all configured sensors in the system can then be scanned individually. Improved Response Time Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 9 In high key-count applications, there can be a significant latency between touching a sensor and the detection of a touch contact. This is due to the time taken to sequentially measure the capacitance of each key on each measurement cycle.With a Lumped mode implementation this latency can be reduced by arranging the sensors into groups. When one of those lumped groups shows touch detection, only the keys within that group are individually measured to determine which is touched. E.g. A keyboard consisting 64 keys may be divided into 8 lumped groups of 8. Thus, each measurement cycle is reduced to measure only the 8 lumped sensors. When a touch contact is applied, first the lump sensor shows touch delta, then the 8 component keys are scanned and the location is resolved. Only 16 measurements are required to resolve the touch status of all keys, compared to 64 measurements in the traditional sequential scan of all keys. It offers an additional edge during low power acquisition as a group of keys [in lumped configuration] can be scanned thus reducing the power consumed drastically. Each sensor has its own pre-scaled clock and series resistor for improved noise immunity. Figure 3-5. Self-capacitance Sensors connected to PTC Figure 3-6. Lumped Self-capacitance Sensors connected to PTC In the preceeding figures, individual buttons are shown along with the lumped equivalent for selfcapacitance arrangement. Lumped Mode Pin and Sensor Configuration for Self-capacitance Method: #define DEF_SELFCAP_LINES Y(5), Y(4), Y(11), Y(10), Y(13), Y(7), Y(12), Y(6), LUMP_Y(5,4) touch_ret = touch_selfcap_sensor_config(SENSOR_TYPE_LUMP, CHANNEL_8, CHANNEL_8, NO_AKS_GROUP, 40u, HYST_6_25, RES_8_BIT, &sensor_id); Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 10 Figure 3-7. Lumped Sense Lines Mutual Capacitance Sensors connected to PTC In the preceeding figure, mutual capacitance lumped sensor configuration is presented. Lumped Mode Pin and Sensor Configuration for Mutual Capacitance Method: #define DEF_MUTLCAP_NODES X(8), Y(10), X(9), Y(10), X(2), Y(12), X(3), Y(12), \X(8), Y(12), X(9), Y(12), X(2), Y(13), X(3), Y(13), \X(8), Y(13), X(9), Y(13), LUMP_X(2,3,8,9), LUMP_Y(10,13) touch_ret = touch_mutlcap_sensor_config(SENSOR_TYPE_LUMP, CHANNEL_10, CHANNEL_10, NO_AKS_GROUP, 20u, HYST_6_25, RES_8_BIT, 0, &sensor_id); Limitations of Use Lumped sensor capacitive load should not exceed the maximum sensor load for individual sensors in either mutual or self-capacitance modes. Lumped mode treats the larger sensors as one single sensor therefore the maximum lumped sensor load should also observe this specification, else this will result in calibration error. In mutual capacitance measurement mode the capacitive load of each sensor is normally much lower than that of the self-capacitance method. It is therefore possible as a general rule to use more mutual sensors together as a single lumped sensor. The user can ensure that the lumped sensor does not result in a calibration error (value of 0x80) using p_xxxxcap_measure_data->p_sensors[<SENSOR>].state variable. 3.6. Capacitive Touch Low Power Sensor The QTouch Library may be configured to operate PTC touch sensing autonomously using the Event System. In this mode, a single sensor is designated as the ‘Low Power’ key and may be periodically measured for touch detection without any CPU action. The CPU may be held in deep sleep mode throughout the operation, minimizing power consumption. The low power key may be a discrete electrode with one Y (Sense) line for Self-capacitance or One X (Drive) plus one Y (Sense) for mutual capacitance, or it may be a combination of multiple Drive and/or Sense lines as a Lumped mode sensor. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 11 Figure 3-8. Low Power Flow Active Measurement Mode In the active measurement mode all configured sensors are measured at DEF_TOUCH_MEASUREMENT_PERIOD_MS millisecond scan interval. The user application arrangement could be designed such that when no touch activity is detected on any of the configured sensors for NO_ACTIVITY_TRIGGER_TIME milliseconds, then the application switches to low power measurement mode. Low Power Measurement Mode In the low power measurement mode, a designated sensor or a lumped sensor can be scanned as a single sensor. In this mode, the system is in standby sleep mode, the CPU and other peripherals are in sleep, excepting for the event system, the RTC and the PTC module / WDT and PTC module in SAM / Mega devices. A user touch on the designated low power sensor will cause the CPU to wake up and perform active measurement in order to resolve the touch. To keep reference tracking of the designated low power sensor, the RTC/WDT is configured to periodically wake up the CPU every DEF_LOWPOWER_SENSOR_DRIFT_PERIODICITY_MS millisecond to perform one active measurement. Switching between Active Mode and Low Power Mode Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 12 When switching from active to low power mode, all sensors except the lumped sensor are disabled. So, no reference tracking is performed on these sensors during the low power mode. When a touch is detected on the lumped sensor, all disabled sensors shall now be re-enabled and measurement is initiated on the sensors. If the device is in sleep for a very long time, then it is recommended to force calibration on the re-enabled sensors to ensure proper reference values on these sensors. 3.7. PTC and its Benefits • • • Mixed Hardware + Firmware solution, allows user to define sensor configuration – Peripheral Touch Controller + QTouch library PTC runs data acquisition autonomously, resulting in low CPU utilization and power consumption – User controlled power-performance trade-off – CPU can sleep during acquisition to save power – Alternatively, CPU can perform other time critical operations during touch acquisition Robust noise performance Figure 3-9. User Application with PTC Device 3.8. PTC Block Diagram for Self-capacitance and Mutual Capacitance Method The PTC block diagram for self-capacitance measurement is shown in the following figure. Only Y-lines can be connected to self-capacitance sensors and are selected using the Input control. X-lines remain unused and can be used for any other GPIO functionality. The acquisition module along with the compensation circuit helps in measuring the change in capacitance due to user touch. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 13 Figure 3-10. PTC Self-capacitance Method - Block Diagram The PTC block diagram for mutual capacitance measurement is as shown in the following figure. Both Xlines and Y-lines should be connected to mutual capacitance sensors and are selected using the Input control. Figure 3-11. PTC Mutual Capacitance Method - Block Diagram 3.8.1. Compensation Circuit The PTC has an internal compensation circuit which is used to compensate the sensor capacitance. Both self-capacitance and mutual capacitance sensing modes have the same compensation range. But the mutual capacitance mode can compensate more parasitic capacitance compared to self-capacitance mode. The tag_touch_measure_data_t structure contains the p_cc_calibration_vals parameter which represents the current channel's compensation circuit value. For more information, refer Measure Data Type (tag_touch_measure_data_t) . Compensation circuit value used in pF = (p_cc_calibration_vals[channel_no]& 0x0F)*0.00675 + ((p_cc_calibration_vals[channel_no] >> 4) & 0x0F)*0.0675 + ((p_cc_calibration_vals[channel_no] >> 8) & 0x0F)*0.675 + ((p_cc_calibration_vals[channel_no] >> 12) & 0x3 ) * 6.75 Also, the touch_xxxxcap_sensors_calibrate function helps the user to calibrate the compensation circuit according to the sensors used. If the routine fails to calibrate the compensation circuit due to saturation, the measurement will return TOUCH_CC_CALIB_ERROR. The compensation circuit could have Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 14 exceeded its limit. The specific sensor that has failed can be determined using p_xxxxcap_measure_data->p_sensors[<sensor>].statewhen it contains the value of SENSOR_CALIBRATION_ERROR(0x80u). • • • • 3.9. Typical compensation circuit value for the self-capacitance mode ranges from 10 to 25 pF and for the mutual capacitance mode it is around 2 pF. The compensation circuit value is affected by sensor size and the ground surrounding the sensor or trace. The compensation ciruit value ranges from 0.00675 pF to 31.48 pF. If the compensation circuit value exceeds the limit, to reduce the value, use a mesh instead of a solid plane in the sensor and ground plane. For detailed sensor design, refer http://www.atmel.com/images/doc10752.pdf. Design Approach with PTC Two design approaches are possible when using Atmel MCU along with PTC. The Atmel MCU could be predominantly used as an MCU for touch measurement. Else, the Atmel MCU can function as a Host MCU utilizing peripherals such as the USB, ADC, DAC, SERCOM, DMA and GPIO along with the PTC used for "on-chip" touch functionality. The design approaches are: • Atmel MCU with PTC predominantly functioning as a touch MCU – Used for touch sensor status and rotor/slider position detection – Additionally used to indicate touch status using LED, buzzer etc – Sends touch status and rotor/slider position information to a Host MCU • Atmel MCU functions as a Host MCU with on-chip touch functionality – Can be a cost saving design as a single chip solution with on-chip touch functionality – Utilizes other on-chip peripheral for a desired user application Figure 3-12. PTC Design Approach Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 15 3.10. Capacitive Touch Development Cycle The capacitive touch development cycle involves PCB board design to develop the user interface hardware as well as firmware application development. The QTouch Composer PC software available as part of Atmel Studio extension gallery allows for PTC QTouch Library projects to be generated automatically with a desired user configuration for touch sensors. The QTouch Composer also allows for touch sensor data analysis and performance tuning for sensitivity and noise. Figure 3-13. Capacitive Touch Development Cycle Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 16 4. Touch Sensor Debug and Status Information The touch sensor debug information necessary for tuning of the sensors are signal, reference, delta, and compensation capacitance. While the signal, reference and delta help in sensitivity and noise tuning the sensor parameters, the compensation capacitance is an indicator for extreme sensor design. The sensor status and position information are parameters that must be judged by the user application to initate the relevant touch action. 4.1. Signal Signal value is the raw measurement data on a given touch channel. The value increases upon touch. Figure 4-1. Channel Signal 4.2. Reference Reference value of a touch channel is the long term average measurement on a specific channel. It represents: • Resting signal when there is no touch • Initial value obtained during the calibration process • Reference is adapted by Drift Compensation algorithm Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 17 Figure 4-2. Channel Reference 4.3. Delta Delta value of a touch channel represents touch strength. • Delta = (signal - reference) • Deltas increase with touch Figure 4-3. Sensor Delta Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 18 4.4. Touch Status & Slider/Wheel Position The sensor touch status is the primary touch sensor information utilized by a user application. The sensor state can either be ON or OFF. For sliders and wheel, additionally the touch position is of interest. For an 8-bit resolution, the touch position ranges from 0 to 255 end-to-end. It is possible to configure with a lower resolution by configuring setting in the touch library. The sensor touch status and slider/wheel position must always be used once the library completes the measurements. The touch sensor state for mutual capacitance or self-capacitance sensor can be obtained by reading the following boolean variables. bool sensor_state_self = GET_SELFCAP_SENSOR_STATE(SENSOR_NUMBER); bool sensor_state_mutl = GET_MUTLCAP_SENSOR_STATE(SENSOR_NUMBER); The touch sensor rotor or slider position information for mutual capacitance or self-capacitance sensor can be obtained using the following parameters. uint8_t rotor_slider_position_self = GET_SELFCAP_ROTOR_SLIDER_POSITION(ROTOR_SLIDER_NUMBER); uint8_t rotor_slider_position_mutl = GET_MUTLCAP_ROTOR_SLIDER_POSITION(ROTOR_SLIDER_NUMBER); The touch sensor noise status for mutual capacitance or self-capacitance sensor can be obtained using the following parameters. bool sensor_noise_state_self = GET_SELFCAP_SENSOR_NOISE_STATUS(SENSOR_NUMBER); bool sensor_noise_state_mutl = GET_MUTLCAP_SENSOR_NOISE_STATUS(SENSOR_NUMBER); Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 19 5. QTouch Library Atmel QTouch Library makes it simple for developers to embed capacitive touch button, slider, wheel ® functionality into general purpose Atmel SMART | ARM and AVR microcontroller applications. The royalty- free QTouch Library provides several library files for each device and supports different numbers of touch channels, enabling both flexibility and efficiency in touch applications. QTouch Library can be used to develop single-chip solutions for many control applications, or to reduce chip count in more complex applications. Developers have the latitude to implement buttons, sliders, and wheels in a variety of combinations on a single interface. Figure 5-1. QTouch Library 5.1. Overview QTouch Library API for PTC can be used for touch sensor pin configuration, acquisition parameter setting as well as periodic sensor data capture and status update operations. The QTouch Library in turn interfaces with the PTC module to perform the necessary action. The PTC module interfaces with the external capacitive touch sensors and is capable of performing self and mutual capacitance method measurements. The library features low power and lumped mode configuration. Figure 5-2. QTouch Library Overview The QTouch Library API is arranged such that the user application can use standalone self-capacitance or mutual capacitance method or both methods, simultaneously. The following table captures the APIs available for each method. For normal operation, it is sufficient to use the set of Regular APIs for each method. The Helper APIs provides additional flexibility to the user application. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 20 Method Regular API Helper API Mutual capacitance touch_mutlcap_sensors_init touch_mutlcap_sensor_config touch_mutlcap_sensors_calibrate touch_mutlcap_sensors_measure touch_mutlcap_sensors_deinit touch_mutlcap_lowpower_sensor_enable_event_measure touch_mutlcap_sensor_get_delta touch_mutlcap_sensor_update_config touch_mutlcap_sensor_get_config touch_mutlcap_update_global_param touch_mutlcap_get_global_param touch_mutlcap_update_acq_config touch_mutlcap_get_acq_config touch_mutlcap_sensor_disable touch_mutlcap_sensor_reenable touch_multcap_mois_tolrnce_enable touch_multcap_mois_tolrnce_disable touch_mutlcap_cnfg_mois_threshold touch_mutlcap_cnfg_mois_mltchgrp touch_mutlcap_mois_tolrnce_quick_reburst_enable touch_mutlcap_mois_tolrnce_quick_reburst_disable touch_mutlcap_get_libinfo touch_library_get_version_info touch_resume_ptc touch_suspend_ptc Self-capacitance touch_selfcap_sensors_init touch_selfcap_sensor_config touch_selfcap_sensors_calibrate touch_selfcap_sensors_measure touch_selfcap_sensors_deinit touch_selfcap_lowpower_sensor_enable_event_measure touch_selfcap_sensor_get_delta touch_selfcap_sensor_update_config touch_selfcap_sensor_get_config touch_selfcap_update_global_param touch_selfcap_get_global_param touch_selfcap_update_acq_config touch_selfcap_get_acq_config touch_selfcap_sensor_disable touch_selfcap_sensor_reenable touch_selfcap_mois_tolrnce_enable touch_selfcap_mois_tolrnce_disable touch_selfcap_cnfg_mois_threshold touch_selfcap_cnfg_mois_mltchgrp touch_selfcap_mois_tolrnce_quick_reburst_enable touch_selfcap_mois_tolrnce_quick_reburst_disable touch_selfcap_get_libinfo touch_library_get_version_info touch_suspend_ptc touch_resume_ptc 5.2. Library Parameters The QTouch Library configuration parameters are listed in the following table: Configuration Mutual capacitance Self-capacitance Pin Configuration DEF_MUTLCAP_NODES DEF_SELFCAP_LINES Sensor Configuration DEF_MUTLCAP_NUM_CHANNELS DEF_MUTLCAP_NUM_SENSORS DEF_MUTLCAP_NUM_ROTORS_SLIDERS DEF_MUTLCAP_PTC_GPIO_STATE DEF_MUTLCAP_QUICK_REBURST_ENABLE DEF_SELFCAP_NUM_CHANNELS DEF_SELFCAP_NUM_SENSORS DEF_SELFCAP_NUM_ROTORS_SLIDERS DEF_SELFCAP_PTC_GPIO_STATE DEF_SELFCAP_QUICK_REBURST_ENABLE Sensor Individual Parameters Detect Threshold Detect Hysteresis Position Resolution Position Hysteresis AKS group Detect Threshold Detect Hysteresis Position Resolution AKS group Sensor Global Parameters DEF_MUTLCAP_DI DEF_MUTLCAP_TCH_DRIFT_RATE DEF_MUTLCAP_ATCH_DRIFT_RATE DEF_MUTLCAP_MAX_ON_DURATION DEF_MUTLCAP_DRIFT_HOLD_TIME DEF_MUTLCAP_ATCH_RECAL_DELAY DEF_MUTLCAP_ATCH_RECAL_THRESHOLD DEF_MUTLCAP_TOUCH_POSTPROCESS_MODE DEF_MUTLCAP_AKS_ENABLE DEF_MUTLCAP_CSD DEF_MUTLCAP_AUTO_OS_SIGNAL_STABILITY_LIMIT DEF_SELFCAP_DI DEF_SELFCAP_TCH_DRIFT_RATE DEF_SELFCAP_ATCH_DRIFT_RATE DEF_SELFCAP_MAX_ON_DURATION DEF_SELFCAP_DRIFT_HOLD_TIME DEF_SELFCAP_ATCH_RECAL_DELAY DEF_SELFCAP_ATCH_RECAL_THRESHOLD DEF_SELFCAP_TOUCH_POSTPROCESS_MODE DEF_SELFCAP_AKS_ENABLE DEF_SELFCAP_CSD DEF_SELFCAP_AUTO_OS_SIGNAL_STABILITY_ LIMIT Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 21 Configuration Mutual capacitance Self-capacitance Sensor Acquisition Parameters DEF_MUTLCAP_FILTER_LEVEL_PER_NODE DEF_MUTLCAP_AUTO_OS_PER_NODE DEF_MUTLCAP_GAIN_PER_NODE DEF_MUTLCAP_FREQ_MODE DEF_MUTLCAP_HOP_FREQS DEF_MUTLCAP_CLK_PRESCALE_PER_NODE DEF_MUTLCAP_SENSE_RESISTOR_PER_NODE DEF_SELFCAP_FILTER_LEVEL_PER_NODE DEF_SELFCAP_AUTO_OS_PER_NODE DEF_SELFCAP_GAIN_PER_NODE DEF_SELFCAP_FREQ_MODE DEF_SELFCAP_HOP_FREQS DEF_SELFCAP_CLK_PRESCALE_PER_NODE DEF_SELFCAP_SENSE_RESISTOR_PER_NODE Sensor Calibration Auto Tune Setting AUTO_TUNE_PRSC, AUTO_TUNE_RSEL, AUTO_TUNE_NONE AUTO_TUNE_PRSC, AUTO_TUNE_RSEL, AUTO_TUNE_NONE Sensor Noise measurement and Lockout Parameters DEF_MUTLCAP_NOISE_MEAS_ENABLE DEF_MUTLCAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT DEF_MUTLCAP_NOISE_LIMIT DEF_MUTLCAP_NOISE_MEAS_BUFFER_CNT DEF_MUTLCAP_LOCKOUT_SEL DEF_MUTLCAP_LOCKOUT_CNTDOWN DEF_SELFCAP_NOISE_MEAS_ENABLE DEF_SELFCAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT DEF_SELFCAP_NOISE_LIMIT DEF_SELFCAP_NOISE_MEAS_BUFFER_CNT DEF_SELFCAP_LOCKOUT_SEL DEF_SELFCAP_LOCKOUT_CNTDOWN Sensor Acquisition Frequency Auto-tuning Parameters DEF_MUTLCAP_FREQ_AUTO_TUNE_ENABLE DEF_MUTLCAP_FREQ_AUTO_TUNE_SIGNAL_STABILITY_LIMIT DEF_MUTLCAP_FREQ_AUTO_TUNE_IN_CNT DEF_SELFCAP_FREQ_AUTO_TUNE_ENABLE DEF_SELFCAP_FREQ_AUTO_TUNE_SIGNAL_STABILITY_LIMIT DEF_SELFCAP_FREQ_AUTO_TUNE_IN_CNT Common Parameters DEF_TOUCH_MEASUREMENT_PERIOD_MS, DEF_TOUCH_PTC_ISR_LVL Low Power Paramaters DEF_LOWPOWER_SENSOR_EVENT_PERIODICITY, DEF_LOWPOWER_SENSOR_DRIFT_PERIODICITY_MS, DEF_LOWPOWER_SENSOR_ID Moisture Parameters DEF_MUTLCAP_MOIS_TOLERANCE_ENABLE DEF_MUTLCAP_NUM_MOIS_GROUPS DEF_MUTLCAP_MOIS_QUICK_REBURST_ENABLE 5.2.1. DEF_SELFCAP_MOIS_TOLERANCE_ENABLE DEF_SELFCAP_NUM_MOIS_GROUPS DEF_SELFCAP_MOIS_QUICK_REBURST_ENABLE Pin, Channel, and Sensor Parameters Mutual capacitance method uses a pair of sensing electrodes for each touch channel. These electrodes are denoted as X and Y lines. Capacitance measurement is performed sequentially in the order in which touch (X-Y) nodes are specified in the DEF_MUTLCAP_NODES configuration parameter. A mutual capacitance touch button sensor is formed using a single X-Y channel, while a touch rotor or slider sensor is formed using three to eight X-Y channels. Mutual Capacitance Channel (X-Y Sense Node) • SAM D20J and SAM D21J (64 pins): up to 256 touch channels, 16 X and 16 Y-lines • SAM D20G and SAM D21G (48 pins): up to 120 touch channels, 12 X and 10 Y-lines • SAM D20E and SAM D21E (32 pins): up to 60 touch channels, 10 X and 6 Y-lines • SAM R21E(32 pins): up to 12 touch channels, 6 X and 2 Y-lines • SAM R21G(48 pins) up to 48 touch channels, 8 X and 6 Y-lines • SAM DA1J (64 pins): up to 256 touch channels, 16 X and 16 Y-lines • SAM DA1G (48 pins): up to 120 touch channels, 12 X and 10 Y-lines • SAM DA1E (32 pins): up to 60 touch channels, 10 X and 6 Y-lines • SAM D21G17AU and SAM D21G18AU (45 pins): up to 132 touch channels, 12 X and 11 Y-lines • SAM D21E15BU and SAM D21E16BU (35 pins): up to 60 touch channels, 10 X and 6 Y-lines The following devices have X and Y multiplexing option. • SAM D10C14A and SAM D11C14A (14 pins): up to 12 touch channels, 4 X and 3 Y-lines • SAM D10D14 AS/AU and SAM D11D14 AS/AU (20 pins): up to 42 touch channels, 7 X and 6 Ylines • SAM D10D14AM and SAM D11D14AM (24 pins): up to 72 touch channels, 9 X and 8 Y-lines • SAM L21E (32 pins): up to 42 touch channels, 7 X and 6 Y-lines • SAM L21G (48 pins): up to 81 touch channels, 9 X and 9 Y-lines • SAM L21J (64 pins): up to 169 touch channels, 13 X and 13 Y-lines Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 22 • • • • • • • • SAM L22G (48 pins): up to 132 touch channels, 11 X and 12 Y-lines SAM L22J (64 pins): up to 182 touch channels, 13 X and 14 Y-lines SAM L22N (100 pins): up to 256 touch channels, 16 X and 16 Y-lines SAM C21E and SAM C20E(32 pins): up to 60 touch channels,10 X and 6 Y-lines SAM C21G and SAM C20G(48 pins): up to 120 touch channels,12 X and 10-Y lines SAM C21J and SAM C20J(64 pins): up to 256 touch channels,16 X and 16 Y-lines ATmega328PB (32 pins): up to 144 touch channels, 12 X and 12 Y-lines ATmega324PB (44 pins): up to 256 touch channels, 16 X and 16 Y-lines A few pins can be used either as X-line or Y-line. The datasheets of individual devices provide more information about this multiplexing option. Figure 5-3. Mutual Capacitance Sensor Arrangement Figure 5-4. Mutual Capacitance - Channel to Sensor Mapping X-Y node pair can be specified using the configuration parameter DEF_MUTLCAP_NODES in a nonsequential order. The channel numbering is done in the same order as the X-Y node pair specified in the configuration parameter DEF_MUTLCAP_NODES. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 23 Setting Configuration Name Data Type Unit Min Max Mutual Cap Touch Channel Nodes DEF_MUTLCAP_NODES uint16_t array None 1 X-Y 256 X-Y node nodepair pair - Mutual Cap Number of Channels DEF_MUTLCAP_NUM_CHANNELS uint16_t None 1 - Mutual Cap Number of DEF_MUTLCAP_NUM_SENSORS 256 X-Y Typical nodepair uint16_t None 1 256 X-Y - nodepair Sensors Mutual Cap Number of DEF_MUTLCAP_NUM_ROTORS_SLIDERS uint8_t None 0 85 node pair - Rotors and Sliders Self-capacitance method uses a single sense electrode, denoted by a Y-line. Capacitance measurement is performed sequentially in the order in which Y-lines are specified in the DEF_SELFCAP_LINES configuration parameter. Self-capacitance touch button sensor is formed using a single - line channel, while a touch rotor or slider sensor can be formed using three Y-line channels. Self-capacitance Channel (Y-sense line) • SAM D20J and SAM D21J (64 pins): up to 16 channels • SAM D20G and SAM D21G (48 pins): up to 10 channels • SAM D20E and SAM D21E (32 pins): up to 6 channels • SAM D10C14A and SAMD 11C14A (14 pins): up to 7 touch channels • SAM D10D14 AS/AU and SAMD 11D14 AS/AU (20 pins): up to 13 touch channels • SAM D10D14AM and SAMD 11D14AM (24 pins): up to 16 touch channels • SAM L21E (32 pins): up to 7 touch channels • SAM L21G (48 pins): up to 10 touch channels • SAM L21J (64 pins): up to 16 touch channels • SAMR21E (32 pins): up to 2 touch channels • SAMR21G (48 pins): up to 6 touch channels • SAM DA1J (64 pins): up to 16 channels • SAM DA1G (48 pins): up to 10 channels • SAM DA1E (32 pins): up to 6 channels • SAM C21E and SAM C20E (32 pins): up to 16 touch channels • SAM C21G and SAM C20G (48 pins): up to 22 touch channels • SAM C21J and SAM C20J (64 pins): up to 32 touch channels • SAM L22G (48 pins): up to 15 touch channels • SAM L22J (64 pins): up to 19 touch channels • SAM L22N (100 pins): up to 24 touch channels • ATmega328PB (32 pins): up to 24 touch channels Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 24 • ATmega324PB (44 pins): up to 32 touch channels Figure 5-5. Self-capacitance Sensor Arrangement Figure 5-6. Self-capacitance Channel to Sensor Mapping Y sense line can be specified using the configuration parameter DEF_SELFCAP_LINES in non-sequential order. The channel numbering is done in the same order as the Y sense line specified in the configuration parameter DEF_SELFCAP_LINES. Setting Data Configuration Name Unit Min Max Typical Type Self Cap touch channel nodes DEF_SELFCAP_NODES uint16_t array None 1 Yline 32 Yline - Self Cap number of channels DEF_SELFCAP_NUM_CHANNELS uint16_t None 1 Yline 32 Yline - Self Cap number of Sensors DEF_SELFCAP_NUM_SENSORS uint16_t None 1 Yline 32 Yline - Self Cap number of Rotors and Sliders DEF_SELFCAP_NUM_ROTORS_SLIDERS uint8_t None 0 Yline 10 Yline - Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 25 The touch sensors must be enabled in the sequential order of the channels specified using the touch_xx_sensor_config() API. For improved EMC performance, a series resistor with value of 1 Kilo-ohm must be used on X and Y lines. For more information about designing the touch sensor, refer to Buttons, Sliders and Wheels Touch Sensor Design Guide available at www.atmel.com. 5.2.2. Sensor Individual Parameters This section explains the settings that are specific to the individual sensor. Detect Threshold A sensor's detect threshold defines how much its signal must increase above its reference level to qualify as a potential touch detect. However, the final detection confirmation must satisfy the Detect Integrator (DI) limit. Larger threshold values desensitize sensors since the signal must change more (i.e. requires larger touch) to exceed the threshold level. Conversely, lower threshold levels make sensors more sensitive. Threshold setting depends on the amount of signal swing when a sensor is touched. Usually, thicker front panels or smaller electrodes have smaller signal swing on touch, thus require lower threshold levels. Typically, detect threshold isset to 50% of touch delta. Desired touch delta for a buttons is ~30 to 80 counts and for wheels or sliders is ~50 to 120 counts. Setting Configuration Data Type Unit Min Max Typical Name Threshold detect_threshold threshold_t Counts 3 255 20-50(For buttons) 30-80(For sliders and wheels Detect 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 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 Configuration Data Type Unit Min Max Typical uint8_t Enum HYST_6_25 HYST_50 HYST_6_25 Name Hysteresis detect_threshold (2bits) 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 2 bits to 8 bits. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 26 Setting Configuration Name Data Type Unit Min Reported Max Reported Typical Position Position Resolution position_resolution uint8_t (3bits) None 2bits 0-3 Position 8bits 0-255 8 Position Hysteresis In case of Mutual Cap, 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 user press. 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 to 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. For instance, a hysteresis value of 5 positions with a resolution of 2 bits (4 positions) is invalid. Position hysteresis is invalid (unused) in case of self-capacitance method sensors. Setting Configuration Name Data Type Unit Min Max Typical Position position_hysteresis uint8_t - 0 7 8 Hysteresis (3bits) ® Adjacent Key Suppression (AKS ) In designs where the sensors are close together or configured for high sensitivity, multiple sensors might report a detect simultaneously. 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, 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 indetect until its delta falls lower than its detection threshold. If any more sensors in the AKS group are still in detect onlythe strongest will report detection. At a given time point, only one sensor from each AKS group is reported to be indetect. AKS feature can be enabled or disabled using a macro DEF_XXXXCAP_AKS_ENABLE • • 1u = AKS grouping functionality is enabled 0u = AKS grouping functionality is disabled The library provides the ability to configure a sensor to belong to one of the Adjacent Key Suppression Groups (AKS Group). Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 27 5.2.3. Sensor Global Parameters This section explains the settings that are common all sensors. For instance, if recalibration threshold (one of the global settings) of mutual cap sensors is set as RECAL_100, all mutual capacitance sensors will be configured for a recalibration threshold of 100%.These sensor global parameter settings can be independently set to self-capacitance and mutual capacitance sensors. Detect Integration The QTouch Library features a detect integration mechanism, which confirm detection in a robust environment. The detect integrator (DI) acts as a simple signal filter to suppress false detections caused by spurious events such as electrical noise. A counter is incremented each time the sensor delta has exceeded its threshold and stayed there for a specific numberof 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 below 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, the device has to exceed its threshold and stay there for (10 + 2) successive acquisitions without going below the threshold level, before the sensor is declared to be touched. Setting Configuration Name Data Type Unit Min Max Typical DI DEF_MUTLCAP_DI, DEF_SELFCAP_DI uint8_t Cycles 0 255 4 Max-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, after a time delay of a few 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 Configuration Name Data Type Unit Maximum ON Duration DEF_MUTLCAP_MAX_ON_DURATION, DEF_SELFCAP_MAX_ON_DURATION uint8_t Min Max Typical 200ms 0 255 30(6s) Away from Touch and Towards Touch Drift Rate 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. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 28 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 inquestion 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 increase when an object (touch) is approaching it or a characteristic change of sensor over time and temperature. Increasing signals should not be compensated quickly, as an approaching finger could be compensated for partially or entirely before even touching the channel (towards touch 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 (away from touch drift). Setting Towards touch Drift Away from touch Drift Configuration Name Data Type Unit Min Max Typical DEF_MUTLCAP_TCH_DRIFT_RATE, DEF_SELFCAP_TCH_DRIFT_RATE uint8_t 200ms 0 127 20(4s) DEF_MUTLCAP_ATCH_DRIFT_RATE, DEF_SELFCAP_ATCH_DRIFT_RATE uint8_t 200ms 0 127 5(1s) 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.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 Configuration Name Data Type Unit Drift Hold Time DEF_MUTLCAP_DRIFT_HOLD_TIME, DEF_SELFCAP_DRIFT_HOLD_TIME uint8_t Min Max Typical 200ms 0 255 20(4s) Away From Touch Recalibration Threshold Recalibration threshold is the level beyond 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) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 29 However, an absolute value of 4 is the hard limit for this setting. For example, if the detection threshold is, 40 and the Recalibration threshold value is set to 4. Although this implies an absolute value of 2 (40 * 6.25% = 2.5), it is hard limited to 4. Setting Recalibration threshold Configuration Name Data Type Unit DEF_MUTLCAP_ATCH_RECAL_THRESHOLD, DEF_SELFCAP_ATCH_RECAL_THRESHOLD uint8_t Min Max Enum RECAL_6_25 Detect threshold Typical RECAL_100 Away From Touch Recalibration Delay If any key is found to have a significant negative delta, it is deemed to be an error condition. If this condition persists for more than the away from touch 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 away from touch 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 away from touch recalibration threshold level, the counter is cleared and the away from touch drifting is performed. For example, if the away from touch recalibration delay setting 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. Away from touch recalibration can be disabled with a setting of 0. Setting Configuration Name Data Type Unit Away from touch Recalibration Delay DEF_MUTLCAP_ATCH_RECAL_DELAY, DEF_SELFCAP_ATCH_RECAL_DELAY uint8_t Min Max Typical Cycles 0 255 10 Sensor Post-Processing Mode When TOUCH_LIBRARY_DRIVEN mode is selected, the library self-initiates repeated touch measurements to resolve touch press, release and calibration. This mode is suited for best response time. When TOUCH_APPLN_DRIVEN mode is selected, the library does not initiate repeated touch measurement to resolve touch press, release and calibration. This mode suits deterministic PTC interrupt execution time for applications requiring stringent CPU time requirements. As repeated touch measurements are delayed due to other critical application code being executed. This mode can potentially affect the touch response time. In order to improve the touch response time with the TOUCH_APPLN_DRIVEN mode, the touch_xxxcap_sensors_measure API call should be modified as below to initiate touch measurements periodically or when the burst again acquisition status flag has been set. if ((touch_time.time_to_measure_touch == 1u) ||(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN) { /* Start a touch sensors measurement process. */ touch_ret = touch_mutlcap_sensors_measure(touch_time.current_time_ms,NORMAL_ACQ_MODE,touch_mutlcap_measure Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 30 _complete_callback); } Setting Configuration Name Data Type Options Typical Sensor postprocessing mode DEF_MUTLCAP_TOUCH_POSTPROCESS_MODE, DEF_SELFCAP_TOUCH_POSTPROCESS_MODE uint16_t TOUCH_LIBRARY_DR IVEN, TOUCH_APPLN_DRIV EN TOUCH_LIBRARY_DRIVEN Charge Share Delay Charge share delay indicates the number of additional charge cycles that are inserted within a capacitance measurement cycle to ensure that the touch sensor is fully charged. The CSD value is dependent on the sensor capacitance along with the series resistor on the Y line. Note: Any increase in the charge share delay also increases the measurement time for a specific configuration. When manual tuning is performed, the CSD value for the sensor with largest combination of capacitance along with series resistance should be considered. Setting Configuration Name Data Type Options CSD (Charge Share Delay) DEF_MUTL_CAP_CSD_VALUE, DEF_SELF_CAP_CSD_VALUE uint8_t Min Max Typical PTC cycles 0 250 0 How to tune the CSD setting manually? 1. 2. 3. Initially, use an arbitrarily large value such as 64 and note the signal value. A large value ensures that the charge time is enough for full charge transfer Reduce the CSD and verify the signal value drop, until signal is approximately 97-98% of the value used initially. This ensures a good charge transfer without any major loss in the signal. Continue the same procedure [Step 1 and 2] for all the sensors available in the system. Use the largest value of the CSD used in the system for the global setting. Note: For the same CSD setting, Mutual capacitance has a lower burst time than self-capacitance. A unit increase in mutual capacitance CSD consumes around 12 PTC cycles. Whereas for the selfcapacitance an increase in CSD consumes approximately twice the mutual capacitance CSD time with the same setting. Auto-OS Signal Stability Limit The parameter DEF_XXXXCAP_AUTO_OS_SIGNAL_STABILITY_LIMIT defines the stability limit of the signals for performing over-samples. Stability limit is the variance in sensor signal value under noisy environment. A high level of stability limit is set to auto trigger oversamples on large noise presence. It is recommended to keep this setting close to the lowest sensor detect threshold of the system and tune it further based on the noise. Range: 1 to 1000 5.2.4. Sensor Acquisition Parameters Filter Level The filter level setting controls the number of samples taken to resolve each acquisition. A higher filter level setting provides improved signal to noise ratio under noisy conditions, while increasing the total time Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 31 for measurement resulting in increased power consumption and response time. This setting is available on per channel basis, allowing easy tuning. Setting Configuration Name Data Type Options Min Max Typical Filter level DEF_MUTLCAP_FILTER_LEVEL_PER_NODE, DEF_SELFCAP_FILTER_LEVEL_PER_NODE filter_level_t Number of samples 1 64 16 Auto Oversamples Auto oversample controls the automatic oversampling of sensor channels when unstable signals are detected with the default setting of 'Filter level'. Enabling Auto oversample results in 'Filter level' x 'Auto Oversample' number of samples taken on the corresponding sensor channel when an unstable signal is observed. In a case where 'Filter level' is set to FILTER_LEVEL_4 and 'Auto Oversample' is set to AUTO_OS_4, 4 oversamples are taken with stable signal values and 16 oversamples are taken when unstable signal is detected. This setting is available on per channel basis, allowing easy tuning. A higher filter level setting provides improved signal to noise ratio under noisy conditions, while increasing the total time for measurement resulting in increased power consumption and response time. Figure 5-7. Auto oversamples Auto oversamples can be disabled to obtain best power consumption. Setting Configuration Name Data Type Options Min Max Typical Auto Oversamples DEF_MUTLCAP_AUTO_OS_PER_NODE, DEF_SELFCAP_AUTO_OS_PER_NODE auto_os_t Sample multiplier 2 128 AUTO_OS_NONE Gain Setting Gain setting is applied on a per-channel basis to allow a scaling-up of the touch delta upon contact. Gain setting depends on the sensor design and touch panel thickness. Setting Configuration Name Data Type Options Min Max Typical Gain DEF_MUTLCAP_GAIN_PER_NODE, DEF_SELFCAP_GAIN_PER_NODE gain_t Gain multiplier 1 32 1 (For selfcapacitance) 4 (For mutual capacitance) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 32 The figure shows the expected signal value for a given combination of gain setting and filter level setting. The values provided are only indicative and the actual sensor signal values might be close to the suggested levels. Figure 5-8. Average Settling Signal Value for FILTER LEVEL and GAIN Combination Prescalar Setting The prescaler parameter denotes the clock divider for the particular channel. It can be set on per channel basis and is independent to each sensor node/channel. This parameter is auto tuned based on the auto tune settings. Tuning this parameter allows for improved noise performance. Setting Configuration Name Data Type Options Min Max Typical Prescalar DEF_MUTLCAP_CLK_PRESCALE_PER_NODE, prsc_div_sel_t PRSC_DIV_SEL_1, PRSC_DIV_SEL_2, PRSC_DIV_SEL_4, PRSC_DIV_SEL_8 PRSC_DIV_SEL_1 PRSC_DIV_SEL_8 PRSC_DIV_SEL_1 DEF_SELFCAP_CLK_PRESCALE_PER_NODE Series Resistor Setting The series resistor denotes the resistor used on the particular channel for the acquisition. The value is tunable and allows both auto and manual tuning options. Tuning this parameter allows for improved noise performance. Settin g Configuration Name Data Type Options Min Max Typical Series Resist or DEF_MUTLCAP_SENSE_RESI STOR_PER_NODE rsel_val_t RSEL_VAL_0, RSEL_VAL_20, RSEL_VAL_50, RSEL_VAL_100 RSEL_VAL_0 RSEL_VAL_100 RSEL_VAL_100 DEF_SELFCAP_SENSE_RESI STOR_PER_NODE Boot Prescalar Setting The boot prescaler parameter denotes the clock divider for the particular channel. It can be set on per channel basis and is independent to each sensor node/channel. This setting is used for calibrating the sensors after a power-on. This parameter must be configured as the auto tune is not available. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 33 Setting Configuration Name Data Type Options Min Max Typical Boot Prescalar DEF_MUTLCAP_CC_CAL_CLK_PRESCALE_PER_NODE, DEF_SELFCAP_CC_CAL_CLK_PRESCALE_PER_NODE prsc_div_sel_t PRSC_DIV_SEL_1, PRSC_DIV_SEL_2, PRSC_DIV_SEL_4, PRSC_DIV_SEL_8 PRSC_DIV_SEL_1 PRSC_DIV_SEL_8 PRSC_DIV_SEL_1 Boot Series Resistor Setting The boot series resistor denotes the resistor used on the particular channel on device power-on calibration. This parameter must be configured as the auto tune is not available. Setting Configuration Name Data Type Options Min Max Typical Boot Series Resistor DEF_MUTLCAP_CC_CAL_SENSE_RESISTOR_PER_NODE rsel_val_t RSEL_VAL_0, RSEL_VAL_20, RSEL_VAL_50, RSEL_VAL_100 RSEL_VAL_0 RSEL_VAL_100 RSEL_VAL_100 DEF_SELFCAP_CC_CAL_SENSE_RESISTOR_PER_NODE Frequency Mode Frequency mode setting allows users to tune the PTC touch acquisition frequency characteristics to counter environment noise. FREQ_MODE_HOP When frequency mode hopping option is selected, the PTC runs a frequency hopping cycle with subsequent measurements done using the three PTC acquisition frequency delay settings as specified in DEF_SELFCAP_HOP_FREQS. In this case, an additional software median filter is applied to the measured signal values. FREQ_MODE_SPREAD When frequency mode spread spectrum option is selected, the PTC runs with spread spectrum enabled for jittered delay based acquisition. FREQ_MODE_SPREAD_MEDIAN When frequency mode spread spectrum median option is selected, the PTC runs with spread spectrum enabled. In this case, an additional software median filter is applied to the measured signal values. FREQ_MODE_NONE When frequency mode none option is selected, the PTC runs at constant speed. This mode is suited for best power consumption. Setting Configuration Name Data Type Options Frequency mode DEF_MUTLCAP_FREQ_MODE , DEF_SELFCAP_FREQ_MODE freq_mode_sel_t FREQ_MODE_NONE, FREQ_MODE_HOP, FREQ_MODE_SPREAD, FREQ_MODE_SPREAD_MEDIAN Min Max FREQ_MODE_NONE FREQ_MODE_SPREAD_MEDIAN Typical FREQ_MODE_NONE Frequency Hop Delay The frequency hop delay setting is used when the Frequency mode is set to FREQ_MODE_HOP. A set of three frequency hop delay settings should be specified. This delay setting inserts n PTC clock cycles between consecutive measurements on a given sensor, thereby changing the PTC acquisition frequency. FREQ_HOP_SEL_1 setting inserts 0 PTC clock cycle between consecutive measurements. FREQ_HOP_SEL_16 setting inserts 15 PTC clock cycles. Hence, higher delay setting will increase the total time taken for capacitance measurement on a given sensor as compared to a lower delay setting. A desired setting can be used to avoid noise around the same frequency as the acquisition frequency. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 34 5.2.5. Setting Configuration Name Data Type Unit Min Max Typical Frequency hop delay DEF_MUTLCAP_HOP_FREQS, DEF_SELFCAP_HOP_FREQS freq_hop_sel_t nPTC_clock_cycles FREQ_HOP_SEL_1 FREQ_HOP_ SEL_16 FREQ_HOP_SEL_1, FREQ_HOP_SEL_2, FREQ_HOP_SEL_3 Sensor Calibration Auto Tune Setting Auto tune parameter setting is passed to the touch_xx_sensors_calibrate API in order to allow users to tune the PTC module for power consumption or noise performance. AUTO_TUNE_PRSC When Auto tuning of pre-scaler is selected, the PTC uses the user defined internal series resistor setting (DEF_XXXXCAP_SENSE_RESISTOR_PER_NODE ) and the pre-scaler is adjusted to slow down the PTC operation to ensure full charge transfer. Auto tuning of pre-scaler with RSEL_VAL_100 as the series resistor results in least power consumption while resulting in increased power consumption and touch response time. AUTO_TUNE_RSEL When Auto tuning of the series resistor is selected, the PTC runs at user defined pre-scaler setting speed (DEF_XXXXCAP_CLK_PRESCALE_PER_NODE) and the internal series resistor is tuned automatically to the optimum value to allow for full charge transfer. Auto tuning of series resistor with PRSC_DIV_SEL_1 as the PTC pre-scale results in best case power consumption. AUTO_TUNE_NONE When manual tuning option is selected, the user defined values of PTC pre-scaler and series resistor is used for PTC operation as given in DEF_XXXXCAP_CLK_PRESCALE_PER_NODE and DEF_XXXXCAP_SENSE_RESISTOR_PER_NODE 5.2.6. Setting Configuration Name Data Type Unit Values Typical Auto tune Provided to touch_xxcap_sensors_calibrate API input auto_tune_type_t None AUTO_TUNE_NONE, AUTO_TUNE_PRSC,AU TO_TUNE_RSEL AUTO_TUNE_NONE Sensor Noise Measurement and Lockout Parameters Noise is measured on a per-channel basis after each channel acquisition, using historical data on a rolling window of successive measurements. Reported noise to exclude the instance of an applied or removed touch contact, but the noise indication must react sufficiently fast that false touch detection before noise lockout is prevented. Signal change from sample to sample during the window buffer is compared to the stability limit. Noise is reported only when two changes occur within the window period and both of which exceed the DEF_XXXXCAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT limit. Noise is calculated using the following algorithm: if (swing count > 2) { Nk = ((|Sn – Sn-1| > DEF_XXXXCAP_NOISE_MEAS_SIGNAL_STABILITY))?(0):(|Sn-Sn-1|DEF_XXXXCAP_NOISE_MEAS_SIGNAL_STABILITY)) } else { Nk = 0 } Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 35 The swing count is number of signal changes that exceed DEF_MUTLCAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT limit during buffer window period. When the measured noise exceeds DEF_MUTLCAP_NOISE_LIMIT, the touch library locks out sensors, reports no touch detection and drifting is stopped. Noise measurement is provided for all the channels. Each byte in p_xxxxcap_measure_data-> p_nm_ch_noise_val provides the noise level associated with that channel. Noise indication is provided for all the sensors configured by the application. A bit is available in p_xxxxcap_measure_data-> p_sensor_noise_status for each sensor to determine whether the sensor is noisy or not. The following code snippet provides the sample code to read the noise status of a particular sensor. Figure 5-9. Noise Calculation Noise Measurement Signal Stability Limit Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 36 The parameter DEF_XXXXAP_NOISE_MEAS_SIGNAL_STABILITY_LIMIT is the variance in sensor signal value under noisy environment. Any noise level over and above the noise signal stability limit contributes to the Noise limit. It is recommended to keep this setting close to the lowest sensor detect threshold of the system and tune it further based on the noise. Signal values can change from sample to sample during a window buffer period. The difference between adjacent buffer value is compared to the user configured stability limit. Noise is reported only when two changes occur within the specified window period and only if both of which exceed the stability limit. Range: 1 to 1000 Noise Limit The DEF_XXXXCAP_NOISE_LIMIT specifies the limit to the total noise accumulated over the noise buffer count. If the accumulated noise exceeds the noise limit, then lockout is triggered. There are two purposes for this parameter: • If the noise level calculated during a running window exceeds DEF_XXXXCAP_NOISE_LIMIT, then the corresponding sensor are declared noisy and sensor global noisy bit is set as '1'. • If the noise level calculated during a running window exceeds DEF_XXXXCAP_NOISE_LIMIT, then system triggers the sensor lockout functionality. Range: 1 to 255 Noise Measurement Buffer Count The DEF_XXXXCAP_NOISE_MEAS_BUFFER_CNT parameter is used to select the buffer count for noise measurement buffer. Range: 3 to 10 (If N number of samples differences have to be checked, define this parameter as "N + 1") If N = 4 then set DEF_XXXXCAP_NOISE_MEAS_BUFFER_CNT as 5u. Sensor Lockout Selection This feature locks out the sensors when the measured noise exceeds DEF_XXXXCAP_NOISE_LIMIT and does not report a touch. This prevents post-processing. So, the high level of noise cannot cause the channel to report false touch drift or recalibrate incorrectly. The DEF_XXXXCAP_LOCKOUT_SEL parameter is used to select the lockout functionality method. • • • If DEF_XXXXCAP_LOCKOUT_SEL is set to SINGLE_SENSOR_LOCKOUT and a sensor's noise level is greater than DEF_XXXXCAP_NOISE_LIMIT, then corresponding sensor is locked out from touch detection and drifting is disabled. If DEF_XXXXCAP_LOCKOUT_SEL is set to GLOBAL_SENSOR_LOCKOUT and any sensor's noise level is greater than DEF_XXXXCAP_NOISE_LIMIT, then all sensors are locked out from touch detection and drifting is disabled. If DEF_XXXXCAP_LOCKOUT_SEL is set to NO_LOCKOUT, then lockout feature is disabled. Note: Global sensors noisy bit will be available for SINGLE_SENSOR_LOCKOUT and GLOBAL_SENSOR_LOCKOUT. Global sensors noisy bit will not be available for NO_LOCK_OUT. Range: 0 to 2 Sensor Lockout Countdown Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 37 If the sensor signal moves from noisy to a good condition and stays there for a DEF_XXXXCAP_ LOCKOUT_CNTDOWN number of measurements, the sensor is unlocked and sensors are ready for touch detection and drifting is enabled. Note: This parameter is valid only for global lockout. Range: 1 to 255 5.2.7. Sensor Acquisition Frequency Auto Tuning Parameters The Frequency Auto Tune feature provides the best quality of signal data for touch detection by automatically selecting acquisition frequencies showing the best SNR in FREQ_MODE_HOP mode. During each measurement cycle, the signal change since the last acquisition at the same frequency is recorded for each sensor. After the cycle, when all sensors have been measured at the present acquisition frequency, the largest signal variation of all sensors is stored as the variance for that frequency stage. The variance for each frequency stage is compared to the DEF_XXXXCAP_FREQ_AUTO_SIGNAL_ STABILITY_LIMIT limit, and if the limit is exceeded, a per-stage counter is incremented. If the measured variance is lower than the limit, the counter is decremented, if it has not been set as zero. If all frequencies display noise exceeding the stability limit, only the counter for the specific frequency stage with the highest variance is incremented after its cycle. When a frequency counter reaches the DEF_XXXXCAP_FREQ_AUTO_TUNE_IN_CNT (auto-tune count in variable), that frequency stage is selected for auto-tuning. A new frequency selection is applied and the counters and variances for all frequencies are reset. After a frequency has been selected for auto-tuning, the count-in for that frequency stage is set to half the original count-in and the process is repeated until either all frequencies have been measured or a frequency is selected which does not re-trigger autotuning is determined. If all frequencies have been tested, and the variation exceeds the DEF_XXXXCAP_FREQ_AUTO_SIGNAL_STABILITY_LIMIT limit then the frequency with the lowest variance is selected for the frequency stage currently under tuning. The auto-tune process is re-initialized and further tuning does not take place until a frequency stage's high variance counter again reaches the count in limit. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 38 Figure 5-10. Frequency Auto Tune Frequency Auto Tune Signal Stability The DEF_XXXXCAP_FREQ_AUTO_SIGNAL_STABILITY_LIMIT is the variance in sensor signal value under noisy environment. A signal stability limit level is set to auto tune acquisition frequency on noise presence. It is recommended to keep this setting close to the lowest sensor detect threshold of the system and tune it further based on the noise. Range: 1 to 1000 Frequency Auto Tune in Counter The DEF_XXXXCAP_FREQ_AUTO_TUNE_IN_CNT parameter is used to trigger the frequency auto tune.If sensor signal change at each frequency exceeds the value specified as DEF_XXXXCAP_FREQ_AUTO_SIGNAL_STABILITY_LIMIT for DEF_XXXXCAP_FREQ_AUTO_TUNE_IN_CNT, then frequency auto tune will be triggered at this frequency. Range: 1 to 255 Note: The Frequency Auto Tune feature and related parameters are available only in FREQ_MODE_HOP mode. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 39 5.2.8. Quick Re-burst Parameter Quick Reburst This macro is used to enable or disable quick re-burst feature. When Quick re-burst is enabled, upon user touch and release, only that touched sensor or channel is subsequently measured to resolve detect integration (or debounce). Enabling this feature results in best touch response time. When Quick re-burst is disabled, upon user touch and release, all sensors or channels are measured to resolve detect integration (or debounce). This feature should only be disabled when developing any special application involving all sensor measurements during user activity. Within an AKS (Adjacent Key suppression) group, all the sensors within that group are measured during user touch independent of this feature being enabled or disabled. 5.2.9. Common Parameters Measurement Period The measurement period setting is used to set the periodic interval for touch sensor measurement. The minimum measurement period setting should be greater than the time taken to complete measurement on all sensors. This can be simply determined by calling the touch_xx_sensors_measure API in a while loop and then toggling a GPIO pin in the measurement complete callback. main() { while(1) { touch_ret = touch_mutlcap_sensors_measure(touch_time.current_time_ms,NORMAL_ACQ_MODE,touch_mutlcap_measure _complete_callback); } } void touch_mutlcap_measure_complete_callback( void ) { if (!(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { /* Set the Mutual Cap measurement done flag. */ p_mutlcap_measure_data->measurement_done_touch = 1u; port_pin_toggle_output_level(PIN_PB00); } } Setting Configuration Name Data Type Unit Values Max Typical DEF_TOUCH_MEASUREMENT_PERIOD_MS uint16_t millisecond Should be 65535 20 Sensor measurement found interval through GPIO pin toggle procedure. PTC Interrupt Priority Level The Nested Vectored Interrupt Controller (NVIC) in the SAM has four different priority levels. The priority level of thePTC end of conversion ISR can be selected based on application requirements to accommodate time critical operations. Setting the PTC interrupt priority level to lowest can have an impact on the touch response time, depending on the execution time taken by other higher priority interrupts. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 40 Setting Configuration Name Data Type Unit PTC interrupt priority level DEF_TOUCH_PTC_ISR_LVL uint8_t Min None 0 (Highest Priority) Max Typical 3 (Lowest Priority) 3 To avoid stack overflow, ensure that adequate stack size has been set in the user application.This configuration is applicable only for SAM devices. touch_suspend_app_cb Callback function pointer that must be initialized by the application before a touch library API is called. Touch library would call the function pointed by this function when suspension operation has to be carry on by the application. Setting Configuration Name Data Type Returns Suspend Callback touch_suspend_app_cb void(* volatile touch_suspend_app_cb) (void) void Low power Sensor Event Periodicity When the CPU returns to standby mode from active, the sensor configured as the low power sensor is scanned at this interval. A high value for this parameter will reduce power consumption but increase response time for a low power sensor. The following macros are used for configuring the low power sensor event periodicity: • The macro LOWPOWER_PER0_SCAN_3_P_9_MS sets the scan rate at 3.9ms • The macro LOWPOWER_PER1_SCAN_7_P_8_MS sets the scan rate at 7.8ms • The macro LOWPOWER_PER2_SCAN_15_P_625_MS sets the scan rate at 15.625ms • The macro LOWPOWER_PER3_SCAN_31_P_25_MS sets the scan rate at 31.25ms • The macro LOWPOWER_PER4_SCAN_62_P_5_MS sets the scan rate at 62.5ms • The macro LOWPOWER_PER5_SCAN_125_MS sets the scan rate at 125ms • The macro LOWPOWER_PER6_SCAN_250_MS sets the scan rate at 250ms • The macro LOWPOWER_PER7_SCAN_500_MS sets the scan rate at 500ms Low power Sensor Drift Periodicity This parameter configures the scan interval for a single active measurement during low power mode. This active measurement is required for reference tracking of low power sensor. Setting Configuration Name Low power sensor drift rate Data Type Unit Min Max DEF_LOWPOWER_SENSOR_DRIFT_PERIODICITY_MS uint16_t milliseconds 0 Typical 65535 2000 Low power sensor ID Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 41 The macro DEF_LOWPOWER_SENSOR_ID is used to configure a sensor as low power sensor. Only one sensor can be configured as low power sensor. Low power sensor can be a normal sensor or a lumped sensor. 5.2.10. Moisture Parameters Moisture Tolerance Enable The macro DEF_XXXXCAP_MOIS_TOLERANCE_ENABLE is used to Enable or disable Moisture detection feature. Moisture Quick Reburst The macro DEF_XXXXCAP_MOIS_QUICK_REBURST_ENABLE is used to enable or disable quick re-burst feature within a given moisture group. When enabled, if within a given moisture group, when any sensor is touched, repeated measurements are done only that sensor to resolve detect integration or de-bounce. When disabled, if within a given moisture group, when any sensor is touched, repeated measurements are done on all sensors within the moisture group to resolve detect integration or de-bounce. It is recommended to enable this feature for best touch response time. Moisture groups The macro DEF_XXXXCAP_NUM_MOIS_GROUPS specifies the total number of individual moisture group present the system. 5.2.11. PTC Lines Ground Feature PTC GPIO State The macro DEF_XXXXCAP_PTC_GPIO_STATE is used to set the unmeasured self/mutual capacitance PTC lines to Ground / Vcc in between PTC measurement cycle. Setting the PTC lines to GND_WHEN_NOT_MEASURED will set the state of the pin to low whenever the pin is unmeasured. Setting the PTC lines to PULLHIGH_WHEN_NOT_MEASURED will make the PTC lines to float in between sensor measurement in a measurement cycle. It is recommended to set GND_WHEN_NOT_MEASURED configuration to get low power. 5.3. Moisture Tolerance Moisture tolerance check executes at the end of each measurement cycle and compares the sum of delta of all sensors in a moisture tolerance group against pre-configured threshold. If delta sum is greater than sensor moisture lock threshold and less than system moisture lock threshold, then the ON-state sensors within moisture tolerance group will be considered as moisture affected. If delta sum is greater than system moisture lock threshold, all sensors within the moisture tolerance group will be considered as moisture affected. This condition is referred as moisture global lock out. The library will come out of the moisture global lock out state when delta sum is less than threshold for 5 consecutive measurements. Self cap and mutual cap sensors cannot be configured in a single moisture group, Self cap moisture tolerance and mutual cap Moisture tolerance features can be enabled or disabled separately. Note: Lumped sensor and the sensor which is part of the specific lump should not be assigned to same moisture group. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 42 Figure 5-11. Moisture Tolerance Algorithm 5.3.1. Moisture Tolerance Group This feature enables the customer application to group a set of sensors in to single moisture tolerance group. If moisture on one sensor might affect other sensors due to physical proximity, they must be grouped together into one Moisture tolerance group. Using this feature the application can disable moisture tolerance detection for a set of sensors, Multiple Moisture tolerance groups can be formed by the customer application. The library supports up to a maximum of 8 moisture groups. Note: Changing the moisture tolerance group configuration during runtime is not recommended. However, muti-touch group configuration can be changed during runtime. 5.3.2. Multi-touch Group If the user wants to touch multiple sensors within the moisture tolerance group simultaneously to indicate a specificrequest, then the application should configure those sensors into single multi-touch group. Multiple multi-touch groups can be formed by the customer application. The library supports a maximum of 8 multi-touch groups within a single moisture tolerance group. Moisture tolerance feature improves a system’s performance under the following scenarios: • Droplets of water sprayed on the front panel surface • Heavy water poured on the front panel surface • Large water puddle on multiple sensors Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 43 • Trickling water on multiple sensors Moisture tolerance feature is not expected to offer any significant performance improvement under the following scenarios: • Large isolated puddle on single sensor • Direct water pour on single sensor Within the same moisture group, user should not configure all the sensors to the single multi-touch group. 5.4. Reading Sensor States When noise immunity and moisture tolerance features are enabled the validity of the sensor sate is based on the moisture status and noise status. Refer Noise Counter Measures and Moisture Parameters for information on noise immunity and moisture tolerance status of sensors. The state of a sensor is valid only when the sensor is not affected by noise and moisture. If a sensor is noisy or affected by moisture, then the state of sensor must be considered as OFF. The code snippet below depicts the same for mutual-cap sensors. When a sensor is touched or released during DI, library will burst on channels corresponding to sensors whose state is other than OFF or DISABLED. If any sensor in an AKS group is in a state other than OFF or DISABLED, the library will burst channels corresponding sensors belong to that AKS group. If a sensor in any moisture group is in a state other than OFF or DISABLED, the library will burst on channels corresponding to sensors belonging to that moisture group. if(! (GET_MUTLCAP_SENSOR_NOISE_STATUS(SENSOR_NUMBER))) { if(! (GET_MUTLCAP_SENSOR_MOIS_STATUS (SENSOR_NUMBER))) { /*Sensor state is valid Read sensor state */ } else { /* Sensor is Moisture affected*/ } } else { /* Sensor is noisy */ } 5.5. Application Flow 5.5.1. Application Flow SAM The application periodically initiates a touch measurement on either mutual capacitance or selfcapacitance sensors. At the end of each sensor measurement, the PTC module generates an end of conversion (EOC) interrupt. The touch measurement is performed sequentially until all the sensors are measured. Additional post-processing is performed on the measured sensor data to determine touch status and rotor/slider position. An interrupt callback function is triggered to indicate completion of measurement. The recommended sequence of operation facilitates the CPU to either sleep or perform other functions during touch sensor measurement. Before using the PTC, the generic clock generator for the PTC peripheral should be set up by the Application. It is recommended to set the PTC generic clock to 4MHz. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 44 Figure 5-12. Application vs QTouch Library Flow 5.5.2. Application Flow - megaAVR The application periodically initiates a touch measurement on either mutual capacitance or selfcapacitance sensors either in polled or interrupt mode. In polling mode, touch API's are blocking API's and will consume more CPU time. In ISR mode, touch API's are non blocking and will generates an end of conversion (EOC) interrupt at the end of each sensor measurement.Touch measurement is intiated on first sensor by calling touch_xxxxcap_sensors_measure() API .The touch measurement is initiated sequentially and additional post-processing is performed on the measured sensor data to determine touch status and rotor/slider position by calling touch_ptc_process() API in application context instead of interrupt context. A callback function is triggered to indicate completion of measurement .The ISR mode sequence of operation facilitates the CPU to either sleep or perform other functions during touch sensor measurement. It is recommended to set the PTC clock to 4MHz. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 45 Figure 5-13. Application vs QTouch Library Flow 5.6. API Sequence The touch_xx_sensors_init API initializes the QTouch Library as well as the PTC module. It also initializes the mutual or self-capacitance method specific pin, register, and global sensor configuration. The touch_xx_sensor_config API configures the individual sensor. The sensor specific configuration parameters can be provided as input arguments to this API. The touch_xx_sensors_calibrate API calibrates all the configured sensors and prepares the sensors for normal operation. The touch_xx_sensors_measure API initiates a sensor measurement on all the configured sensors. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 46 Figure 5-14. API Sequence with Combined self and Mutual Capacitance Sensors Enabled 5.7. State Machine The PTC QTouch Library state machine that presents the various library States and Event transitions can be found in the figure below. The state machine is maintained separately for each of the touch acquisition method, which means the state of mutual capacitance sensor operation can be different from the state of self-capacitance allowing them to co-exist. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 47 Figure 5-15. Library State Machine The touch_xx_sensors_init API initializes the QTouch Library as well as the PTC module. It also initializes the mutual or self-capacitance method specific pin, register, and global sensor configuration. The touch_xx_sensor_config API configures the individual sensor. The sensor specific configuration parameters can be provided as input arguments to this API. The touch_xx_sensors_calibrate API calibrates all the configured sensors and prepares the sensors for normal operation. The touch_xx_sensors_measure API initiates a sensor measurement on all the configured sensors. The touch_xx_sensors_deinit function is used to clear the initialized library state. Used for clearing the internal library data and states. When called will modify the library state to TOUCH_STATE_NULL. The touch_xxxx_lowpower_sensor_enable_event_measure API is used to start a event trigger based low power sensor measurement. Touch Library Suspend Resume Operation The touch library provides touch_suspend_ptc, touch_resume_ptc API to suspend and resume the PTC. When suspend API is called, the touch library initiates the suspend operation and return to the application. After completing the current PTC conversion, the touch library will initiate suspend operation and call the application touch suspend callback function pointer. The suspend complete callback function pointer has to be registered by the application. Note: If it is not registered, then the suspend call will return TOUCH_INVALID_INPUT_PARAM. The application then should disable corresponding clock to reduce the power consumption. The following flowchart depicts the suspend sequence. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 48 Figure 5-16. Suspend Sequence SUPENSION_START Touch_suspend_ptc() No Is Callback Received? Wait for touch_suspend_callback if touch state is in TOUCH_STATE_BUSY or perform some other application code without calling any Touch _lib APIs Yes disable PTC GCLK disable APBCMASK disable GCLK generator disable GCLK source SUSPENSION_COMPLETE If the touch state is not TOUCH_STATE_BUSY the user can disable the clock and proceed to complete the suspend routine. To resume the operations, perform the following sequence: Figure 5-17. Resume Sequence The SAM controllers may be configured to operate PTC touch sensing autonomously using the Event System. In this mode, a single sensor channel is designated as the 'Low Power' key and may be periodically measured for touch detection without any CPU action. The CPU may be held in STANDBY throughout the operation, minimizing power consumption. The low power key may be a discrete electrode with one Y (Sense) line for self-capacitance or one X (Drive) plus one Y (Sense) for mutual capacitance, or it may be a combination of multiple Drive and/or Sense lines as a lumped mode sensor as described. With this method, a fast response may be achieved even in large key-count applications while operating at an extremely low power level, drawing less than 10uA at 3.3V. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 49 5.8. Operation Modes The QTouch Library can operate in the following sensor measurement modes. • Periodic measurement • Continuous measurement 5.8.1. Periodic Measurement In the periodic measurement mode, sensor measurement is initiated by the application through a periodic event such as timer interrupt. The periodic measurement mode scenario is when none of the sensors are touched. While a long measurement period can be used to achieve lower device power consumption, a short measurement period is required for better touch response time. Hence, the measurement period should be tuned to suit a given application. Typical measurement period can range between 20 millisecond to 250 millisecond. Figure 5-18. Periodic Measurement Mode Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 50 5.8.2. Continuous Measurement In the continuous measurement mode, back to back sensor measurement can be initiated from the touch library. This mode can be triggered to resolve user presence or resolve calibration under the following scenario. • Resolve user presence, when sensor is touched or released • Resolve calibration, when – Sensor is calibrated using the touch_xx_sensors_calibrate API – – Sensor is in Away from touch re-calibration condition Sensor is in Max-on duration condition The TOUCH_BURST_AGAIN acquisition status data bit field in the measure data structure is set to indicate continuous measurement mode. void touch_mutlcap_measure_complete_callback(void) { if (!(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { /* Set the Mutual Cap measurement done flag. */ p_mutlcap_measure_data->measurement_done_touch = 1u; } } Touch Library Acquisition Status Flags The touch library acquisition status information during continuous measurement mode is available using the touch_acq_status_t acq_status element of the touch_measure_data_t touch measure data structure. Table 5-1. Touch Acquisition Status Bit Fields Macro Bitfield Comment TOUCH_NO_ACTIVITY 0x0000u No Touch activity TOUCH_IN_DETECT 0x0001u Atleast one Touch channel is in detect TOUCH_STATUS_CHANGE 0x0002u Change in Touch status of atleast one Touch channel TOUCH_ROTOR_SLIDER_POS_C HANGE 0x0004u Change in Rotor or Slider position of atleast one rotor or slider TOUCH_CHANNEL_REF_CHANGE 0x0008u Change in Reference value of atleast one Touch channel TOUCH_BURST_AGAIN 0x0008u Indicates that reburst is required to resolve Filtering or Calibration state TOUCH_RESOLVE_CAL 0x0200u Indicates that reburst is needed to resolve Calibration TOUCH_RESOLVE_FILTERIN 0x0200u Indicates that reburst is needed to resolve Filtering TOUCH_RESOLVE_DI 0x0800u Indicates that reburst is needed to resolve Detect Integration TOUCH_RESOLVE_POS_RECAL 0x1000u Indicates that reburst is needed to resolve Recalibration Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 51 Macro Bitfield Comment TOUCH_CC_CALIB_ERROR 0x2000u Indicates that CC calibration failed on at least one channel TOUCH_AUTO_OS_IN_PROGRES S 0x4000u Indicates that Auto OS in progress to get stable channel signal The acquisition status flags can be monitored within the measure complete callback as shown. void touch_mutlcap_measure_complete_callback(void) { if ((p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { //Denotes acquisition is incomplete. } if ((p_mutlcap_measure_data->acq_status & TOUCH_RESOLVE_CAL)) { //Denotes sensor calibration is on-going. } if (!(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { //Denotes acquisition is completed. /* Set the Mutual Cap measurement done flag. */ p_mutlcap_measure_data->measurement_done_touch = 1u; } } Continuous Measurement Post Processing Mode The sensor data post-processing mode for QTouch library can be selected using the DEF_xxxxCAP_TOUCH_POSTPROCESS_MODE configuration item available as part of touch.h file. When TOUCH_LIBRARY_DRIVEN mode is selected, the library self-initiates repeated touch measurements to resolve touch press, release and calibration. This mode is suited for best response time. When TOUCH_APPLN_DRIVEN mode is selected, the library does not initiate repeated touch measurement to resolve touch press, release and calibration. This mode suits deterministic PTC interrupt execution time for applications requiring stringent CPU time requirements. As repeated touch measurements are delayed due to other critical application code being executed. This mode can potentially affect the touch response time. In order to improve the response time with the TOUCH_APPLN_DRIVEN mode, the following condition should be applied to initiate sensor measurement, so as to cater for additional measurements without any delay. The same condition can also be applied to other application scenario such as sleep to check for pending acquisitions to be completed before the system can go to sleep. if ((touch_time.time_to_measure_touch == 1u)||(p_mutlcap_measure_data->acq_status & TOUCH_BURST_AGAIN)) { /* Start a touch sensors measurement process periodically, or if there is a pending measurement. */ touch_ret = touch_mutlcap_sensors_measure(touch_time.current_time_ms,NORMAL_ACQ_MODE,touch_mutlcap_meas ure_complete_callback); } 5.9. Touch Library API Error The following table provides the touch library API error code information. The API error code type is touch_ret_t enum. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 52 ErrorCode Enumeration Comment TOUCH_SUCCESS Successful completion of operation TOUCH_ACQ_INCOMPLETE Touch Library is busy with pending previous touch measurement TOUCH_INVALID_INPUT_PARAM Invalid input parameter TOUCH_INVALID_LIB_STATE Operation not allowed in the current Touch Library state TOUCH_INVALID_SELFCAP_CONFIG_PARAM Invalid self-capacitance configuration input parameter TOUCH_INVALID_MUTLCAP_CONFIG_PARAM Invalid mutual capacitance configuration input parameter TOUCH_INVALID_RECAL_THRESHOLD Invalid Recalibration threshold input value TOUCH_INVALID_CHANNEL_NUM Channel number parameter exceeded total number of channels configured TOUCH_INVALID_SENSOR_TYPE Invalid sensor type. Sensor type can not be SENSOR_TYPE_UNASSIGNED TOUCH_INVALID_SENSOR_ID Invalid sensor number parameter TOUCH_INVALID_RS_NUM Number of Rotor/Sliders set as 0, when trying to configure a rotor/slider The application error codes in touch projects can be enabled or disabled using a macro DEF_TOUCH_APP_ERR_HANDLER. By default, the value of macro DEF_TOUCH_APP_ERR_HANDLER is set to 0 in order to disable the application error handler. To enable the application error handler, set the macro DEF_TOUCH_APP_ERR_HANDLER as 1. When it is enabled, while(1) is used to trap errors. Refer Application Error Code (tag_touch_app_err_t) for further information. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 53 6. Tuning for Noise Performance The PTC has been designed with great care making it easy to design a capacitive touch solution, while at the same time maintaining high quality of touch and performance. Nevertheless in any touch sensing application, the system designer must consider how electrical interference in the target environment may affect the performance of the sensors. Touch sensors with insufficient tuning can show failures in tests of either radiated or conducted noise, which can occur in the environment or power domain of the appliance or may be generated by the appliance itself during normal operation. In many applications there are quality standards which must be met where EMC performance criteria are clearly defined. However meeting the standards cannot be considered as proof that the system will never show EMC problems, as the standards include only the most commonly occurring types and sources of noise. Noise immunity comes at a cost of increased touch response time and power consumption. The system designer must carry out proper tuning of the touch sensors in order to ensure least power consumption. The PTC QTouch library has anumber of user configurable features which can be tuned to give the best balance between touch response time, noise immunity and power consumption. 6.1. Noise Sources Noise sources that affect touch sensor performance can be classified as follows. Self-generated • Motors • Piezo buzzers • PWM controls Radiated • Fluorescent lamp • Radio transmission • Inductive cook top Conducted • Power supply / charger • Mains supply Applicable EMC standards • Conducted Immunity EN61000-4-6 6.2. Noise Counter Measures The effects of noise are highly dependent on the amplitude of the noise signal induced or injected onto the sensors, and the frequency profile of that noise signal. Generally, this noise can be classified as • Broadband noise • Narrow band noise 6.2.1. Broadband Noise Counter Measures Broadband noise refers to noise signals whose frequency components are not harmonically related to the capacitance measurement acquisition frequencies of the PTC. Provided that the maximum and minimum voltage levels of the acquisition signal combined with noise signals are within the input range of the PTC and a sufficiently large number of samples are taken, Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 54 broadband noise interference can be averaged out by setting a high value of Filter level (DEF_MUTLCAP_FILTER_LEVEL_PER_NODE, DEF_SELFCAP_FILTER_LEVEL_PER_NODE) and Auto oversample (DEF_MUTLCAP_AUTO_OS_PER_NODE, DEF_SELFCAP_AUTO_OS_PER_NODE) settings. If the noise amplitude is excessive, then PTC components experience saturation of measurement. In this case the acquisition signals combined with the noise signals are outside the input range of the PTC, which results in clipping of the measurements. Often the clipping is not observable in the resolved measurement, as it occurs only on a portion of the measurement samples, but the presence of clipped samples prevents effective averaging of the sample points. In this case, averaging of samples will not result in a noise-free measurement even with large rates of oversampling. The resolved signal will show a shift from its correct level due to asymmetry of signal clipping. Configuration Parameter Setting DEF_MUTLCAP_FILTER_LEVEL_PER_NODE, DEF_SELFCAP_FILTER_LEVEL_PER_NODE FILTER_LEVEL_64 DEF_MUTLCAP_AUTO_OS_PER_NODE, DEF_SELFCAP_AUTO_OS_PER_NODE AUTO_OS_DISABLE DEF_MUTLCAP_FREQ_MODE, DEF_SELFCAP_FREQ_MODE FREQ_MODE_NONE DEF_MUTLCAP_CLK_PRESCALE_PER_NODE, DEF_SELFCAP_CLK_PRESCALE_PER_NODE PRSC_DIV_SEL_1 DEF_MUTLCAP_SENSE_RESISTOR_PER_NODE, DEF_SELFCAP_SENSE_RESISTOR_PER_NODE RSEL_VAL_100 Auto-tune input to touch_mutlcap_sensors_calibrate(), touch_selfcap_sensors_calibrate API AUTO_TUNE_PRSC STEP 1: PREVENT CLIPPING This requires the implementation of a hardware low pass filter in order to reduce the scale of the noise combined with acquisition signal. The sensor capacitance is combined with a series resistor on the Y (Sense) line, either the PTC internal resistor or externally mounted on the PCB. The external series resistor should be mounted between the Y line of the device to the Sensor, closest to the device pin. Note: Always use an external series resistor for self-capacitance applications in order to prevent clipping. The internal series resistor of the PTC is limited to 100K. Depending on the noise levels, external series resistors up to1 megaohms can be evaluated. STEP 2: CHARGE TRANSFER TEST As an effect of adding a series resistor to form a low pass filter, the time constant for charging the sensors is increased. It is essential to ensure that the sensor capacitance is fully charged and discharged during each measurement sampling. Insufficient charging can be observed as a reduced touch delta or it may be seen on an oscilloscope by connecting to the sense electrode. However, this problem may not be apparent in the touch sensor operation; the application may behave perfectly well even in the presence of low-level noise, but show much worse performance during noise tests with the addition of the resistor compared to a configuration which excludes the resistor. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 55 Charge transfer though Auto tuning setting: The QTouch library Auto tune setting provides a mechanism which carries out a charge transfer test on each enabled key and sets the prescalar to the fastest available setting ensuring full charge transfer. The following combination of setting should be used. • DEF_MUTLCAP_SENSE_RESISTOR_PER_NODE and DEF_SELFCAP_SENSE_RESISTOR_PER_NODE should be set to RSEL_VAL_100. • Auto tune pre-scaler AUTO_TUNE_PRSC should be provided as input parameter to touch_mutlcap_sensors_calibrate( AUTO_TUNE_PRSC )and touch_mutlcap_sensors_calibrate(AUTO_TUNE_PRSC) Testing for Charge transfer by Manual tuning: • If the AUTO_TUNE_NONE setting is provided as an input to the touch_mutlcap_sensors_calibrate(AUTO_TUNE_NONE ) and touch_mutlcap_sensors_calibrate (AUTO_TUNE_NONE) calibration API, then the PTC uses the user defined settings of the PTC Clock pre-scaler ( DEF_MUTLCAP_CLK_PRESCALE, DEF_SELFCAP_CLK_PRESCALE_PER_NODE) and internal series resistor (DEF_MUTLCAP_SENSE_RESISTOR_PER_NODE, DEF_SELFCAP_SENSE_RESISTOR_PER_NODE). • Reference measurement: An acquisition measurement (Signal value) is taken with the prescalar set to maximum, i.e. PRSC_DIV_SEL_8 Test measurement: A second measurement (Signal value) is taken with reduced prescalar: PRSC_DIV_SEL_4 If the difference between the two measurements is less than ~3% (1/32) of the first value, the conclusion is that fullcharge transfer is achieved with PRSC_DIV_SEL_4. This measurement is repeated for PRSC_DIV_SEL_2 and PRSC_DIV_SEL_1 to find the fastest PTC operating speed for which full charge transfer is achieved. STEP 3: ADJUST OVERSAMPLING Once clipping is prevented by hardware filtering and full charge transfer is ensured the next step is to find the best settings for Filter level ( DEF_MUTLCAP_FILTER_LEVEL_PER_NODE , DEF_SELFCAP_FILTER_LEVEL_PER_NODE ) and Auto over samples (DEF_MUTLCAP_AUTO_OS_PER_NODE , DEF_SELFCAP_AUTO_OS_PER_NODE). Auto over samples feature provides the advantage that additional samples are only taken on a sensor which has showna significant change. In the absence of such a change, the measurement cycle can be much shorter compared to applying ( * AUTO_OS) as the oversampling rate on every measurement. Care should be taken when using AUTO_OS to ensure that it does not occur too frequently. The measurement time for FILTER_LEVEL samples can be represented as: A+ (B * FILTER_LEVEL) Where A is the total time for PTC configuration and post-processing, and B is the oversampling period (the per sample measurement time) When AUTO_OS is applied, this time is increased to: A + (B * FILTER_LEVEL*( 1 + AUTO_OS )) FILTER_LEVEL should be sufficiently large to ensure that AUTO_OS is only applied during the worstcase noise circumstances. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 56 6.2.2. Narrowband Noise Counter Measures If the noise includes a frequency component which is related to the PTC capacitance measurement acquisition frequency, then no amount of oversampling will average out the noise effects. Any batch of measurement samples taken with the same sampling frequency will result in a measurement offset. The actual offset resulting from each measurement depends on the relative phase of the noise component and the sampling frequency. This effect is illustrated in the following diagram, where the noise is represented by a sine wave. STEP 4: SELECT FREQUENCY MODE Note: Step1, Step2 and Step3 provided in the previous section should be used in combination with this step in a system which has both broadband noise and narrow band noise. Default settings provided before STEP1 should be used as a starting point before starting noise tuning. With FREQUENCY_MODE_NONE, a single acquisition frequency is used and samples are taken at the fastest rate possible with the given pre-scalar setting. This gives the best response time, and with sufficient oversampling excellent noise immunity at all noise frequencies which are not related to the sampling frequency. However in the case where the noise is at (or close to) a frequency which is harmonically related to the sampling frequency then the noise issue becomes severe, as illustrated above. This is particularly important in applications where a frequency sweep test is required, such as EN61000-4-6. FREQUENCY_MODE_SPREAD applies a modification to the sampling rate, such that the period between successivesamples is modified in a saw-tooth fashion to apply a wider spectrum to the sampling frequency. The sampling frequency F0 is thus spread across the range (F0/2, F0). With relatively low noise amplitude, this can be effective atimproving performance with minimal cost in response time. FREQUENCY_MODE_HOP utilizes 3 base frequencies and a median filter to avoid using measurements taken at anaffected frequency. The frequencies should be selected to minimize the set of crossover harmonics within the problemfrequency band. Each of the 3 frequencies is used in sequence for each measurement cycle.i.e. • Cycle 1: All sensors measured with Frequency 0 • Cycle 2: All sensors measured with Frequency 1 • Cycle 3: All sensors measured with Frequency 2 • Cycle 4: All sensors measured with Frequency 0 • Cycle 5: All sensors measured with Frequency 1 Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 57 If Frequency 0 is related to the noise frequency, then the measurements taken with F0 will show high variation. Using a median filter, this ensures that the outlying measurements will be rejected. In some applications, self-generated noise may be present which affects one or more of the default HOP frequencies. Insuch a case, the HOP frequencies should be changed to avoid this frequency. Some noise frequencies can occur which are close to harmonics of two of the HOP frequencies, in which case thesystem must be tuned with higher settings of FILTER_LEVEL or AUTO_OS to provide enough samples to average the noise out of the measurement. Determining PTC Acquisition Frequency The PTC acquisition frequency is given by the following formula, PTC Acquisition Frequency = (1/ PTC Acquisition Time) The PTC acquisition time is given by the following formula, PTC Acquisition Time = (Cycles per Acquisition + Hop Freq) * PTC IO Clock Period Where, Cycles per Acquisition = Number of PTC clock cycles required for each acquisition. This is a fixed value of 15. Hop Freq = PTC acquisition frequency delay setting This parameter is represented in the touch.h file by the symbols DEF_MUTLCAP_HOP_FREQS and DEF_SELFCAP_HOP_FREQS. The PTC acquisition frequency is dependent on the Generic clock input to PTC and PTC clock pre- scaler setting. This delay setting inserts n PTC clock cycles between consecutive measurements on a given sensor, thereby changing the PTC acquisition frequency. FREQ_HOP_SEL_1 setting inserts 0 PTC clock cycles between consecutive measurements. FREQ_HOP_SEL_16 setting inserts 15 PTC clock cycles. Hence, higher delay setting will increase the total time taken for capacitance measurement on a given sensor as compared to a lower delay setting.A desired setting can be used to avoid noise around the same frequency as the acquisition frequency. Range: FREQ_HOP_SEL_1 to FREQ_HOP_SEL_16 Three frequency hop delay settings need to be specified when assigning values to this parameter. Duration of each PTC clock period is given by the following formula, Where, CLKPTC = Generic clock input to the PTC Refer touch_configure_ptc_clock() API in touch.c file for clock configuration. Prescaler = PTC clock prescaler setting This parameter is represented in the touch.h file by the symbols DEF_MUTLCAP_CLK_PRESCALE_PER_NODE and DEF_SELFCAP_CLK_PRESCALE_PER_NODE. Example: If Generic clock input to PTC = 4MHz, then: • PRSC_DIV_SEL_1 sets PTC Clock to 4MHz • PRSC_DIV_SEL_2 sets PTC Clock to 2MHz • PRSC_DIV_SEL_4 sets PTC Clock to 1MHz • PRSC_DIV_SEL_8 sets PTC Clock to 500KHz Example: Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 58 When CLKPTC = 4MHz, Prescaler = PRSC_DIV_SEL_1, the PTC Acquisition Frequencies obtained are as follows, Hop Freq PTC Acquisition Frequency(kHz) FREQ_HOP_SEL_1 66.67 FREQ_HOP_SEL_2 62.50 FREQ_HOP_SEL_3 58.82 FREQ_HOP_SEL_4 55.56 FREQ_HOP_SEL_5 52.63 FREQ_HOP_SEL_6 50.00 FREQ_HOP_SEL_7 47.62 FREQ_HOP_SEL_8 45.45 FREQ_HOP_SEL_9 43.48 FREQ_HOP_SEL_10 41.67 FREQ_HOP_SEL_11 40.00 FREQ_HOP_SEL_12 38.46 FREQ_HOP_SEL_13 37.04 FREQ_HOP_SEL_14 35.71 FREQ_HOP_SEL_15 34.48 FREQ_HOP_SEL_16 33.33 Note: The acquisition frequencies may vary based on the tolerance of the clock source. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 59 7. Application Design 7.1. Touch Library and Associated Files The table below provides the mandatory files required to use the QTouch library. In order to add QTouch functionality into an existing user example project, these files and associated library based on the compiler should be added to the user project. Table 7-1. Touch Library Files 7.2. File Description touch_api_ptc.h QTouch Library API header file, contains API and Data structure used to interface with the library touch.h QTouch library configuration header file touch.c A helper file to demonstrate QTouch library initialization and sensor configuration libsamxxx_qtouch_iar.a or libsamxxx_qtouch_gcc.a QTouch library compiled for IAR or GCC compiler that supports both self-capacitance and mutual capacitance sensors. Code and Data Memory Considerations The table below captures the typical code and data memory required for QTouch library. The typical memory requirements provided in the table are arrived considering only Regular API usage in the application. Usage of Helper API would consume additional code memory. Each measurement method requires additional data memory from the application for storing the signals, references, sensor configuration information, and touch status. This data memory is provided by the application as 'data block' array. The size of this data block depends on the number of sensors configured. The PRIV_xx_DATA_BLK_SIZE macro in touch_api_ptc.h calculates the size of this data memory block. Table 7-2. Mutual Capacitance Method Code Memory Keys with Rotor or Slider Data Memory Keys with Rotor or Slider 845 11114 861 9005 497 10377 513 libsamd2x-qtouch-gcc.a 9222 841 10734 857 libsamd2x-qtouch-iar.a 8881 497 10254 513 libsaml21-qtouch-gcc.a 9282 841 10794 857 libsaml21-qtouch-iar.a 9744 497 11115 513 libsamda1-qtouch-gcc.a 9222 841 10734 857 Series Code Memory Keys Only Data Memory Keys Only libsamd1x-qtouch-gcc.a 9602 libsamd1x-qtouch-iar.a Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 60 Code Memory Keys with Rotor or Slider Data Memory Keys with Rotor or Slider 497 10254 513 9752 841 11264 857 libsamc2x-qtouch-iar.a 9209 501 10567 517 libsamr21-qtouch-gcc.a 9246 841 10758 857 libsamr21-qtouch-iar.a 8905 497 10277 513 libsaml22-qtouch-gcc.a 9886 841 11078 857 libsaml22-qtouch-iar.a 9509 501 10981 517 libatmega328pb_qtouch_gcc.a 13338 503 15760 532 libMega328PB_qtouch.r90 10761 578 12391 607 libatmega324pb_qtouch_gcc.a 14082 482 16520 631 atmega324pb_qtouch_iar.r90 10646 441 12379 562 Series Code Memory Keys Only Data Memory Keys Only libsamda1-qtouch-iar.a 8881 libsamc2x-qtouch-gcc.a In case of ATmega328PB, for a single touch channel (mutual capacitance mode) without noise, moisture, auto-tune and qdebug features, RAM usage is 503 bytes. RAM usage gets increased by 36 bytes for each additional channel. Table 7-3. Self-capacitance Method Code Memory Keys with Rotor or Slider Data Memory Keys with Rotor or Slider 841 10884 849 8952 497 10216 505 libsamd2x-qtouch-gcc.a 9198 845 10506 845 libsamd2x-qtouch-iar.a 8841 497 10101 505 libsam121-qtouch-gcc.a 9258 841 10566 845 libsaml21-qtouch-iar.a 9806 497 11070 505 libsamda1-qtouch-gcc.a 9198 845 10506 845 libsamda1-qtouch-iar.a 8841 497 10101 505 libsamc2x-qtouch-gcc.a 9716 841 11024 845 libsamc2x-qtouch-iar.a 9148 501 10400 509 libsamr21-qtouch-gcc.a 9542 841 10850 845 Series Code Data Memory Memory Keys Only Keys Only libsamd1x-qtouch-gcc.a 9576 libsamd1x-qtouch-iar.a Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 61 Code Memory Keys with Rotor or Slider Data Memory Keys with Rotor or Slider 497 10115 505 9530 841 11158 845 libsaml22-qtouch-iar.a 9410 501 10733 509 libatmega328pb_qtouch_gcc.a 13274 500 15260 519 libMega328PB_qtouch.r90 10705 594 12041 613 libatmega324pb_qtouch_gcc.a 14026 478 16024 593 libMega328PB_qtouch.r90 10596 437 12329 558 Series Code Data Memory Memory Keys Only Keys Only libsamr21-qtouch-iar.a 8851 libsaml22-qtouch-gcc.a In case of ATmega328PB, for a single touch channel (self-capacitance mode) without noise, moisture, auto-tune and qdebug features, RAM usage is 500 bytes. RAM usage gets increased by 32 bytes for each additional channel. Note: 1. The total number of sensors supported by a specific device variant is limited by the number of XYlines as well as code, data, and stack memory requirements. 2. To save the memory utilized for code and data, new lib-nano C library has been used for GCC example projects. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 62 8. Example Applications 8.1. Atmel Board Example Projects The GCC Xplained Pro example projects can be accessed through File>New Example Project menu option in Atmel Studio. The IAR Xplained Pro example projects can be accessed through Atmel QTouch Library PTC Partpack. The following example projects are available for Xplained Pro kits: • SAM D20 Xplained Pro and QT1 Xplained Pro Mutual Capacitance example application • SAM D20 Xplained Pro and QT1 Xplained Pro Self Capacitance example application • SAM D21 Xplained Pro and QT1 Xplained Pro Mutual Capacitance example application • SAM D21 Xplained Pro and QT1 Xplained Pro Self Capacitance example application • SAM D20 Xplained Pro and QT1 Xplained Pro Mutual Capacitance example application with LumpLow Power configuration • SAM D20 Xplained Pro and QT1 Xplained Pro Self Capacitance example application with LumpLow Power configuration • SAM D11 Xplained Pro Self Capacitance example application • SAM D10 Xplained Mini Self Capacitance example application • SAM D20 QTouch Robustness Demo Moisture Example Application (self + mutual) • SAM C20 QTouch Robustness Demo Moisture Example Application • SAM D20 Xplained Pro and QT3 Xplained Pro Mutual Capacitance example application with LumpLow Power configuration • SAM L21 Xplained Pro and QT3 Xplained Pro Mutual Capacitance example application with LumpLow Power configuration • SAM DA1 Xplained Pro and QT4 Xplained Pro Self Capacitance example application • SAM C21 Xplained Pro and QT1 Xplained Pro Mutual Capacitance example application • SAM C21 Xplained Pro and QT1 Xplained Pro Self Capacitance example application • SAM C21 Xplained Pro Self Capacitance example application(on-board sensor) • SAM C21 Xplained Pro and QT5 Xplained Pro Mutual Capacitance example application • SAM L22 Xplained Pro and Touch Segment LCD Xplained Pro Mutual Capacitance example application • ATmega328PB Xplained Mini Self Capacitance example application • ATmega324PB Xplained Pro and QT5 Xplained Pro Mutual Capacitance example application Note: For SAM L22, it is recommended to set the PTC Clock to 8MHz. Clock Configuration Changes in Projects: • • • For SAM C20/C21 RevB devices, DPLL is used as the main clock and OSC32K is used as reference clock for the DPLL clock source. For SAM C20/C21 RevC devices, OSC48MHz is used as the main clock. This is demonstrated in the example projects by using the same project for both SAM C20/C21 RevB and SAM C20/C21 RevC devices. The example projects which have DFLL as main clock source use scaled OSC8MHz/OSC16MHz clock as the reference input clock. SAM L22 example project configures DFLL for 16MHZ (performance level - PL2) and utilizes it as the main clock. This clock setting offers high performance. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 63 • • SAM L22 low power user board project configures DFLL for 8MHZ (performance level - PL0) and utilizes it as the main clock. This clock setting offers low power consumption. SAM L21/L22 low power example projects are configured in PL0 (Low power oriented mode) with Buck regulator as the main regulator in standby sleep mode. This is the best suitable configuration to achieve low power numbers. The example projects make use of Xplained Pro boards and the extension kits for showcasing touch. Those extension kits are explained in the following sections. QT1 Xplained Pro kit: The QT1 Xplained Pro self-capacitance and mutual capacitance extension boards are supported by SAM D20, SAM D21, SAM DA1, SAM C21, and SAM L22 Xplained Pro Evaluation kits. Figure 8-1. QT1 Xplained Pro Mutual Capacitance and Self-capacitance Note: SAM C21 Xplained Pro can operate at 3.3V and 5V Vcc, while the QT1 Xplained Pro can operate at a maximum voltage of 3.6V. Please make sure to put the Vcc selection header on the SAM C21 Xplained Pro in the 3.3V position. The QT1 Xplained Pro boards demonstrate the following combinations of buttons, slider, and wheels. • 2 buttons + 2 yellow LED • 1 slider + 8 yellow LED • 1 wheel + 1 RGB LED QT3 Xplained Pro kit: The QT3 Xplained Pro extension board has 12 mutual capacitance buttons on it and it is supported by SAM D20, SAM D21, SAM DA1, SAM L21, SAM L22 and SAM C21 Xplained Pro Evaluation kits. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 64 Figure 8-2. QT3 Xplained Pro QT4 Xplained Pro kit: The QT4 Xplained Pro boards demonstrate the following arrangement. • Two self-capacitance buttons • One unshielded proximity sensor • One proximity sensor with driven shield with external op-amp driver • • One LED indicator for each self-capacitive button One LED indicator for each proximity sensor Figure 8-3. QT4 Xplained Pro QT5 Xplained Pro kit: The QT5 Xplained Pro board demonstrates the following arrangement. • One 4-channel (4X x 1Y) mutual capacitance curved slider • Two mutual capacitance buttons • 16 LEDs arranged as two 7-segment digits separated with a colon • IS31FL3728 I2C LED matrix controller from ISSI Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 65 Figure 8-4. QT5 Xplained Pro 8.2. User Board Example Projects Atmel Studio QTouch Composer can be used to create GCC projects based on the sensor and pin configuration defined by the requirements of a user board. The generated example projects also allow for QDebug data streaming to QTouch Analyzer. The User board example project can be generated by accessing the QTouch Composer using the following menu options in the Atmel Studio. File > New Project > GCC C QTouch Executable Project > Create QTouch Library Project The QTouch Project Builder wizard appears as shown in the screenshot. Selection of sensors, devices, pins, debug interface and tuning of parameters can be done according to user preferences and project can be generated. The figure shows one of the user board generated projects. Figure 8-5. QTouch Project Builder Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 66 Figure 8-6. User Board Example Project 8.3. Using Atmel Software Framework (ASF) with the Example Projects The example projects are based on Atmel Software Framework (ASF). For more information on ASF refer to Atmel Software Framework User Guide http://www.atmel.com/. The Atmel® Software Framework (ASF) is a MCU software library providing a large collection of embedded software for Atmel flash MCUs: mega AVR, AVR XMEGA, AVR UC3 and SAM devices. • It simplifies the usage of microcontrollers, providing an abstraction to the hardware and high- value middleware • ASF is designed to be used for evaluation, prototyping, design and production phases • ASF is integrated in the Atmel Studio IDE with a graphical user interface or available as standalone for GCC, IAR compilers • ASF can be downloaded for free 8.4. Using Xplained Pro Kit to Program User Board The SAM D20 Xplained Pro features a Cortex® Debug Connector (10-pin) for programming and debugging an external target. The connector is limited to the SWD interface and is intended for in-system programming and debugging of SAM D20 devices in the final product developed by the users. For more information refer SAM D20 Xplained Pro User Guide (www.atmel.com). 8.5. Using QDebug Touch Data Debug Communication Interface When using IAR and GCC example projects, QDebug touch data debug communication interface can be enabled. This allows the communication between the touch device and QTouch Analyzer. To enable or disable QDebug, configure DEF_TOUCH_QDEBUG_ENABLE in the touch.h file. When QDebug is enabled and touch debug data is being updated in the QTouch Analyzer, touch response time will be slower due to the debug communication data transfer which increases the delay in the response time. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 67 After tuning the touch sensors using QTouch Analyzer, disable the QDebug for optimized touch performance. Figure 8-7. Atmel DGI Interface for QDebug Data Figure 8-8. QTouch Analyzer view 8.6. Using Xplained Pro Kit for QDebug Data Streaming from User Board SAM D20 Xplained Pro contains Embedded Debugger (EDBG) that features an Atmel Data Gateway Interface (DGI) over SPI and TWI. The DGI can be used to transmit a variety of data from the Xplained Pro kit to the host PC. This arrangement can be used to send QDebug data from a user board to Atmel Studio QTouch Analyzer for touch sensor data analysis and tuning. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 68 Figure 8-9. Using Xplained Pro for Data Streaming from User Board The example project generated using QTouch composer makes use of SPI for data transfer. To stream QDebug data from user board, a relay firmware should be flashed onto the SAM D20/D21 microcontroller on the Xplained Pro kit. After connecting the SAM D20/D21 Xplained Pro to the PC, the device name appears in the connected kits of QTouch Start Page. Right click the device name and choose Enable User Board Analysis to flash the relay firmware. Figure 8-10. Flash Relay Firmware The following table indicates the SPI connection between SAM D20 Xplained Pro Kit and User Board: Table 8-1. SPI Connection Information SAMD20 Xplained Pro Extension header EXT3 UserBoard Pin Pin on EXT3 Function 16 SPIMOSI (PB22) MOSI 17 SPIMISO (PB16) MISO 18 SPISCK(PB23) SCK 19 SS-Connect to GND GND GND Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 69 8.7. Using Atmel ICE for QDebug Data Streaming from User Board Atmel ICE can be used to stream data from the user board. Refer the following table and connect the mini squid cable from AVR header of Atmel ICE to user board. Atmel-ICE AVR port pins Target pins Mini-squid pin Pin 1 (TCK) SCK 1 Pin 2 (GND) GND 2 Pin 3 (TDO) MISO 3 Pin 4 (VTG) VCC 4 Pin 5 (TMS) SS 5 Pin 6 (nSRST) - 6 Pin 7 (Not Connected) - 7 Pin 8 (nTRST) - 8 Pin 9 (TDI) MOSI 9 Pin 10 (GND) - 0 While creating the project using QTouch composer project builder wizard, the pins SCK, MISO, SS and MOSI can be chosen from the debug interface setup pane as shown in the figure. Figure 8-11. Debug Interface Setup Pane When the connections are made correctly and debug interface setup is also done in the project, flash the project in the user board. Data can be streamed and visualized via QTouch Analyzer. Note: Atmel ICE would be listed in QTouch Analyzer as QDEBUG_DGI. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 70 9. Known Issues PTC in Self-capacitance Mode The following errata is applicable for SAM D20 (Revision B): Description: The two lowest gain settings are not selectable and an attempt by the QTouch Library to set enable of these may result in a higher sensitivity than optimal for the sensor. The PTC will not detect all touches.This errata does not affect mutual capacitance mode which operates as specified. Fix/workaround: Use SAM D20 revision C or later for self-capacitance capacitive touch sensing. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 71 10. FAQ on PTC Qtouch Table 10-1. Frequently Asked Questions Query Answer When can we change an acquisition, sensor configuration or global sensor parameter? Its best to call the helper APIs to update these parameter when the measurement_done_touch flag (part of touch_measure_data_t structure) is true, which means the library is not in the middle of an (previously started) incomplete acquisition. Changing Gain and Filter level settings can affect the Signal value, so recalibration is mandatory by invoking the touch_sensors_calibrate() API. After changing an acquisition parameter do we need to recalibrate or reinitialize the sensors and PTC? Can sensors be disabled and reenabled run time? For example, scan 2 sensors while sleeping and then scan all sensors when the system wakes up. Yes, this is possible using the touch_xxxcap_sensor_disable() and touch_xxxcap_sensor_reenable() API. There is a low amplitude pulse prior These pulses are part of setting up the sense line's initial to the 16 acquisition samples and a conditions. large amplitude pulse after the 16 acquisition samples. Is Detect integration calculated inside the PTC or by QTouch library? This is done by QTouch library. When Auto Oversampling is enabled how can one determine touch timing? The absolute maximum cycle, is the case that auto oversamples is applied to all channels: (Normal acquisition time) x (1 + auto_os). Can sensor signal lines (Y or X lines) be used to drive LEDs, etc., when not being used for sensor acquisitions? No. This is not recommended This can only happen with a poorly tuned system, as FILTER_LEVEL should be sufficient to prevent AUTO_OS happening except on a touched key under noisy conditions. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 72 11. Appendix 11.1. Macros 11.1.1. Touch Library Acquisition Status Bit Fields Keyword Type TOUCH_NO_ACTIVITY 0x0000u No touch activity. TOUCH_IN_DETECT 0x0001u TOUCH_STATUS_CHANGE 0x0002u TOUCH_ROTOR_SLIDER_POS_CHANGE 0x0004u 11.1.2. Description Atleast one touch channel is in detect. Change in touch status of at least one Touch channel. Change in the position of at least one rotor or slider. TOUCH_CHANNEL_REF_CHANGE 0x0008u Changein the reference value of at least one touch channel. TOUCH_BURST_AGAIN 0x0100u Indicates that re-burst is required to resolve filtering or calibration state. TOUCH_RESOLVE_CAL 0X0200u Indicates that re-burst is required to resolve calibration. TOUCH_RESOLVE_FILTERIN 0x0400u Indicates that re-burst is required to resolve calibration. TOUCH_RESOLVE_DI 0x0800u Indicates that re-burst is needed to resolve Detect Integration. TOUCH_RESOLVE_POS_RECAL 0x1000u Indicates that re-burst is needed to resolve recalibration. TOUCH_CC_CALIB_ERROR 0X2000u Indicates that CC calibration failed on at least one channel. TOUCH_AUTO_OS_IN_PROGRESS 0X4000u Indicates that Auto-os in progress to get stable channel signal. Sensor State Configurations GET_SENSOR_STATE (SENSOR_NUMBER) To get the sensor state (whether detect or not) for parameter that corresponds to the sensor specified using the SENSOR_NUMBER. The macro returns either 0 or 1. If the bit value is 0, the sensor is not in detect. If the bit value is 1, the sensor is in detect. #define GET_XXXXCAP_SENSOR_STATE(SENSOR_NUMBER) >p_sensor_states p_xxxxcap_measure_data- [(SENSOR_NUMBER / 8)] & (1 << (SENSOR_NUMBER % 8))) >> (SENSOR_NUMBER %8) GET_XXXXCAP_SENSOR_MOIS_STATUS (SNSR_NUM) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 73 To get the moisture status of a particular sensor. The return value is 1 in case of sensor is affected by moisture and returns 0 if sensor is affected by moisture. #define GET_XXXXCAP_SENSOR_MOIS_STATUS(SNSR_NUM) ((p_xxxxcap_measure_data>p_sensor_mois_status [(SNSR_NUM)/8] & (1<<((SNSR_NUM)%8))) >>(SNSR_NUM %8)) GET_XXXXCAP_MOIS_GRP_SUM_DELTA (GRP_ID) To get the xxxxcap moisture group sum delta. The return value is 32 bit integer indicating the sum delta of moisture group. #define GET_XXXXCAP_MOIS_GRP_SUM_DELTA(GRP_ID)(mois_XXXX_grp_delta_arr[(GRP_ID)-1]) GET_XXXXCAP_MOIS_GRP_ADJ_DELTA (GRP_ID) To get the xxxxcap moisture group Adjacent delta .The return value is 32 bit integer indicating the adjacent delta of moisture group. #define GET_MUTLCAP_MOIS_GRP_ADJ_DELTA(GRP_ID)(mois_mutl_grp_adj_delta_arr[(GRP_ID)-1]) GET_MOIS_XXXX_GLOB_LOCK_STATE To get the moisture lock status of xxxxcap moisture groups. The return value is 1 if any moisture group is in moisture global lockout and 0 if no moisture group is in moisture global lockout. #define GET_MOIS_MUT_GLOB_LOCK_STATE(mois_lock_global_mutl) GET_XXXXCAP_SENSOR_NOISE_STATUS (SENSOR_NUMBER) To get the noise status of a particular sensor. The return value is 1 in case of sensor is noisy and returns 0 if sensor is not noisy. GET_XXXXCAP_SENSOR_NOISE_STATUS >p_sensor_noise_status #define (SENSOR_NUMBER)(p_xxxxcap_measure_data- [(SENSOR_NUMBER / 8)] & (1 <<(SENSOR_NUMBER % 8))) >> (SENSOR_NUMBER % 8) GET_ROTOR_SLIDER_POSITION (ROTOR_SLIDER_NUMBER) To get the rotor angle or slider position. These values are valid only when the sensor state for corresponding rotor or slider state is in detect. ROTOR_SLIDER_NUMBER is the parameter for which the position is being obtained. The macro returns rotor angle or sensor position. #define GET_XXXXCAP_ROTOR_SLIDER_POSITION(ROTOR_SLIDER_NUMBER)p_xxxxcap_measure_data>p_rotor_slider_values [ROTOR_SLIDER_NUMBER] DEF_TOUCH_MUTLCAP must be set to 1 in the application to enable the Mutual capacitance touch acquisition method. DEF_TOUCH_SELFCAP must be set to 1 in the application to enable the Self-capacitance touch acquisition method. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 74 11.2. Typedef Field Unit Description threshold_t uint8_t An unsigned 8-bit number setting a sensor detection threshold. sensor_id_t uint8_t Sensor number type. touch_current_time_t uint16_t Current time type. touch_delta_t int16_t touch_acq_status_t uint16_t Status of touch measurement. mois_snsr_threshold_t int32_t Moisture threshold for individual sensor. mois_system_threshold_t int32_t Moisture threshold for the entire system. 11.3. Enumeration 11.3.1. Gain Setting (tag_gain_t) Touch sensor delta value type. Gain per touch channel. Gain is applied on a per-channel basis to allow a scaling-up of the touch sensitivity on contact. Range: GAIN_1 (no scaling) to GAIN_32 (scale-up by32) Data Fields GAIN_1 • GAIN_2 • GAIN_4 • GAIN_8 • GAIN_16 • GAIN_32 • 11.3.2. Filter Level Setting (tag_filter_level_t) Touch library FILTER LEVEL setting. The filter level setting controls the number of samples acquired to resolve each acquisition. A higher filter level setting provides improved signal to noise ratio under noisy conditions, while increasing the total time for measurement which results in increased power consumption. Refer filter_level_t in touch_api_ptc.h Range: FILTER_LEVEL_1 (one sample) to FILTER_LEVEL_64 (64 samples). Data Fields FILTER_LEVEL_1 • FILTER_LEVEL_2 • FILTER_LEVEL_4 • FILTER_LEVEL_8 • FILTER_LEVEL_16 • FILTER_LEVEL_32 • Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 75 • 11.3.3. FILTER_LEVEL_64 Auto Oversample Setting (tag_auto_os_t) Auto oversample controls the automatic oversampling of sensor channels when unstable signals are detected with the default setting of 'Filter level'. Enabling Auto oversample results in 'Filter level' x 'Auto Oversample' number of samples taken on the corresponding sensor channel when an unstable signal is observed. In a case where 'Filter level' is set to FILTER_LEVEL_4 and 'Auto Oversample' is set to AUTO_OS_4, 4 oversamples are taken with stable signal values and 4+16 oversamples are taken when unstable signal is detected. Range: AUTO_OS_DISABLE (oversample disabled) to AUTO_OS_128 (128 oversamples). Data Fields AUTO_OS_DISABLE • AUTO_OS_2 • AUTO_OS_4 • AUTO_OS_8 • AUTO_OS_16 • AUTO_OS_32 • AUTO_OS_64 • AUTO_OS_128 • 11.3.4. Low Power Sensor Scan Rate (tag_lowpower_scan_int_t) When the CPU returns to standby mode from active, the sensor configured as the low power sensor is scanned at this interval. A high value for this parameter will reduce power consumption but increase response time for a low power sensor. Note: This enum is applicable only for ATmega devices. Range: LOWPOWER_PER0_SCAN_3_P_9_MS to LOWPOWER_PER7_SCAN_250_MS Data Fields • • • • • • • 11.3.5. LOWPOWER_PER0_SCAN_3_P_9_MS LOWPOWER_PER1_SCAN_7_P_8_MS LOWPOWER_PER2_SCAN_15_P_625_MS LOWPOWER_PER3_SCAN_31_P_25_MS LOWPOWER_PER4_SCAN_62_P_5_MS LOWPOWER_PER5_SCAN_125_MS LOWPOWER_PER6_SCAN_250_MS Library Error Code (tag_touch_ret_t) Touch Library error codes. Data Fields • TOUCH_SUCCESS Successful completion of touch operation. • TOUCH_ACQ_INCOMPLETE Library is busy with pending previous touch measurement. • TOUCH_INVALID_INPUT_PARAM Invalid input parameter. • TOUCH_INVALID_LIB_STATE Operation not allowed in the current touch library state. • TOUCH_INVALID_SELFCAP_CONFIG_PARAM Invalid self-capacitance configuration input parameter. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 76 • • • • 11.3.6. TOUCH_INVALID_MUTLCAP_CONFIG_PARAM Invalid mutual capacitance configuration input parameter. TOUCH_INVALID_RECAL_THRESHOLD Invalid recalibration threshold input value. TOUCH_INVALID_CHANNEL_NUM Channel number parameter exceeded total number of channels configured. TOUCH_INVALID_SENSOR_TYPE Invalid sensor type. Sensor type must NOT be SENSOR_TYPE_UNASSIGNED. • TOUCH_INVALID_SENSOR_ID Invalid sensor number parameter. • TOUCH_INVALID_RS_NUM Number of rotor/sliders set as 0, while trying to configure a rotor/slider. Application Error Code (tag_touch_app_err_t) The application error codes are listed below. Data Fields • • • TOUCH_INIT_CALIB_ERR The touch_xxxxcap_sensors_calibrate is fed with an invalid parameter / Touch Library state is TOUCH_STATE_NULL/ TOUCH_STATE_BUSY. • TOUCH_MEASURE_INCOMPLETE The touch_measure api has error due to an invalid input param / it was on an invalid Touch Library state. TOUCH_MEASURE_CC_CAL_FAILED Hardware calibration error; check the hardware and ensure it is proper. If the error persists, check the user manual for sensor design guidelines. • 11.3.7. TOUCH_INIT_CONFIG_ERR The touch_xxxxcap_sensors_init is fed with an incompatible / incomplete parameter. TOUCH_SENSOR_CONFIG_ERR The touch_xxxxcap_sensor_config is fed with an incompatible parameter / Touch Library state is not in TOUCH_STATE_INIT. Touch Channel (tag_channel_t) Sensor start and end channel type of a Sensor. Channel number starts with value 0. Data Fields CHANNEL_0 to CHANNEL_255 11.3.8. Touch Library State (tag_touch_lib_state_t) Touch library state. Data Fields • TOUCH_STATE_NULL Touch library is un-initialized. All sensors are disabled. 11.3.9. • TOUCH_STATE_INIT Touch library has been initialized • • TOUCH_STATE_READY Touch library is ready to start a new capacitance measurement on enabled sensors. TOUCH_STATE_CALIBRATE Touch library is performing calibration on all sensors. • TOUCH_STATE_BUSY Touch library is busy with on-going capacitance measurement. Sensor Type (tag_touch_lib_state_t) Sensor types available. Data Fields • SENSOR_TYPE_UNASSIGNED Sensor is not configured yet • SENSOR_TYPE_KEY Sensor type key Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 77 • SENSOR_TYPE_ROTOR Sensor type rotor • SENSOR_TYPE_LUMP Sensor type lump • SENSOR_TYPE_SLIDER Sensor type slider • MAX_SENSOR_TYPE Max value of enum type for testing 11.3.10. Touch Sensing Type (tag_touch_acq_t) Based on the two types of charge transfer technology, the capacitive touch sensing may be either mutual capacitance sensing or self-capacitance sensing. Data Fields • TOUCH_MUTUAL Mutual capacitance sensing • TOUCH_SELF Self-capacitance sensing • MAX_TOUCH_ACQ Max value of enum 11.3.11. Touch Library Acquisition Mode (tag_touch_acq_mode_t) Touch library acquisition mode. Data Fields RAW_ACQ_MODE When raw acquisition mode is used, the measure_complete_callback function is called immediately once a fresh value of signals are available. In this mode, the Touch Library does not perform any post processing. So, the references, sensor states or rotor/slider position values are not updated in this mode. NORMAL_ACQ_MODE When normal acquisition mode is used, the measure_complete_callback function is called only after the Touch Library completes processing of the signal values obtained. The references, sensor states and rotor/slider position values are updated in this mode. 11.3.12. Calibration Auto tune Setting (tag_auto_tune_type_t) Touch library PTC prescaler clock and series resistor auto tuning setting Data Fields • • • AUTO_TUNE_NONE Auto tuning mode disabled. This mode uses the user defined PTC prescaler and series resistor values. AUTO_TUNE_PRSC Auto tune PTC prescaler for best noise performance . This mode uses the user defined series resistor value. AUTO_TUNE_RSEL Auto tune series resistor for least power consumption. This mode uses the user defined PTC prescaler value. 11.3.13. PTC Acquisition Frequency Mode Setting (tag_freq_mode_sel_t) The frequency mode setting option enables the PTC acquisition to be configured for the following modes. • Frequency hopping and spread spectrum disabled. • Frequency hopping enabled with median filter. • Frequency spread spectrum enabled without median filter. • Frequency spread spectrum enabled with median filter. Range: FREQ_MODE_NONE (no frequency hopping & spread spectrum) to FREQ_MODE_SPREAD_MEDIAN (spread spectrum with median filter) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 78 Data Fields • FREQ_MODE_NONE 0u • FREQ_MODE_HOP 1u • FREQ_MODE_SPREAD 2u • FREQ_MODE_SPREAD_MEDIAN 3u 11.3.14. PTC Clock Pre-scaler Setting (tag_prsc_div_sel_t) Refer touch_configure_ptc_clock() API in touch.c Example: If generic clock input to PTC = 4 MHz, • PRSC_DIV_SEL_1 sets PTC Clock to 4 MHz. • PRSC_DIV_SEL_2 sets PTC Clock to 2 MHz. • PRSC_DIV_SEL_4 sets PTC Clock to 1 MHz. • PRSC_DIV_SEL_8 sets PTC Clock to 500 kHz. Data Fields PRSC_DIV_SEL_1 • PRSC_DIV_SEL_2 • PRSC_DIV_SEL_4 • PRSC_DIV_SEL_8 • 11.3.15. PTC Series Resistor Setting (tag_rsel_val_t) For mutual capacitance mode, this series resistor is switched internally on the Y-pin. For self-capacitance mode, the series resistor is switched internally on the sensor pin. Example: • RSEL_VAL_0 sets internal series resistor to 0 Ohms. • RSEL_VAL_20 sets internal series resistor to 20 Kohms. • RSEL_VAL_50 sets internal series resistor to 50 Kohms. • RSEL_VAL_100 sets internal series resistor to 100 Kohms. Data Fields RSEL_VAL_0 • RSEL_VAL_20 • RSEL_VAL_50 • RSEL_VAL_100 • 11.3.16. PTC Acquisition Frequency Delay Setting (tag_rsel_val_t) The PTC acquisition frequency is dependent on the generic clock input to PTC and PTC clock prescaler setting. This delay setting inserts n PTC clock cycles between consecutive measurements on a given sensor, thereby changing the PTC acquisition frequency. FREQ_HOP_SEL_1 setting inserts 0 PTC clock cycle between consecutive measurements. FREQ_HOP_SEL_16 setting inserts 15 PTC clock cycles. Hence, higher delay setting will increase the total time required for capacitance measurement on a given sensor as compared to a lower delay setting. A desired setting avoids noise in the same frequency as the acquisition frequency. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 79 • • • • • • • • • • • • • • • • FREQ_HOP_SEL_1 FREQ_HOP_SEL_2 FREQ_HOP_SEL_3 FREQ_HOP_SEL_4 FREQ_HOP_SEL_5 FREQ_HOP_SEL_6 FREQ_HOP_SEL_7 FREQ_HOP_SEL_8 FREQ_HOP_SEL_9 FREQ_HOP_SEL_10 FREQ_HOP_SEL_11 FREQ_HOP_SEL_12 FREQ_HOP_SEL_13 FREQ_HOP_SEL_14 FREQ_HOP_SEL_15 FREQ_HOP_SEL_16 11.3.17. AKS Group (tag_aks_group_t) It provides information about the sensors that belong to specific AKS group. NO_AKS_GROUP indicates that the sensor does not belong to any AKS group and cannot be suppressed. AKS_GROUP_x indicates that the sensor belongs to the AKS group x. Data Fields • • • • • • • • • NO_AKS_GROUP AKS_GROUP_1 AKS_GROUP_2 AKS_GROUP_3 AKS_GROUP_4 AKS_GROUP_5 AKS_GROUP_6 AKS_GROUP_7 MAX_AKS_GROUP Max value of enum type for testing. 11.3.18. Sensor Hysteresis Setting (tag_hysteresis_t) A sensor detection hysteresis value. This is expressed as a percentage of the sensor detection threshold. HYST_x = hysteresis value is x% of detection threshold value (rounded down). Note: A minimum value of 2 is used. Example: If detection threshold = 20, • HYST_50 = 10 (50% of 20) • HYST_25 = 5 (25% of 20) • HYST_12_5 = 2 (12.5% of 20) • HYST_6_25 = 2 (6.25% of 20 = 1, but value is hard limited to 2) Data Fields HYST_50 • Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 80 • • • • HYST_25 HYST_12_5 HYST_6_25 MAX_HYST Max value of enum type for testing. 11.3.19. Sensor Recalibration Threshold (tag_recal_threshold_t) This is expressed as a percentage of the sensor detection threshold. RECAL_x = recalibration threshold is x% of detection threshold value (rounded down). Note: A minimum value of 4 is used. Example: If detection threshold = 40, • RECAL_100 = 40 (100% of 40) • RECAL_50 = 20 (50% of 40) • RECAL_25 = 10 (25% of 40) • RECAL_12_5 = 5 (12.5% of 40) • RECAL_6_25 = 4 (6.25% of 40 = 2, but value is hard limited to 4) Data Fields RECAL_100 • RECAL_50 • RECAL_25 • RECAL_12_5 • RECAL_6_25 • • MAX_RECAL Max value of enum type for testing. 11.3.20. Rotor Slider Resolution (tag_resolution_t) 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. Data Fields • • • • • • • • • RES_1_BIT RES_2_BIT RES_3_BIT RES_4_BIT RES_5_BIT RES_6_BIT RES_7_BIT RES_8_BIT MAX_RES Max value of enum type for testing. 11.3.21. PTC Sensor Noise Lockout setting (nm_sensor_lockout_t) The sensor lockout setting option allows the system to be configured in the following modes. • SINGLE_SENSOR_LOCKOUT Single sensor can be locked out. • GLOBAL_SENSOR_LOCKOUT All the sensors are locked out for touch detection. • NO_LOCK_OUT All the sensors are available for touch detection. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 81 Range: SINGLE_SENSOR_LOCKOUT to NO_LOCK_OUT. Data Fields • SINGLE_SENSOR_LOCKOUT 0u • GLOBAL_SENSOR_LOCKOUT 1u • NO_LOCK_OUT 2u 11.3.22. 11_3_21_PTC_GPIO_STATE(ptc_gpio_state_t) Detailed Description PTC lines state in unmeasured condition can be set using this enum • PULLHIGH_WHEN_NOT_MEASURED Indicates that default state of PTC lines are at vcc. • GND_WHEN_NOT_MEASURED Indicates that default state PTC lines are grounded. Range: PULLHIGH_WHEN_NOT_MEASURED=0 and GND_WHEN_NOT_MEASURED. Data Fields PULLHIGH_WHEN_NOT_MEASURED • GND_WHEN_NOT_MEASURED • 11.3.23. Moisture Group Setting (moisture_grp_t) Detailed Description Sensor can be configured in the moisture group using this type. • MOIS_DISABLED Indicates that the sensor does not belong to any moisture group. • MOIS_GROUP_X Indicates that the sensor belongs to the moisture group x. Range: MOIS_DISABLED = 0 to MOIS_GROUP_7. Data Fields • • • • • • • • • • MOIS_DISABLED=0 MOIS_GROUP_0 MOIS_GROUP_1 MOIS_GROUP_2 MOIS_GROUP_3 MOIS_GROUP_4 MOIS_GROUP_5 MOIS_GROUP_6 MOIS_GROUP_7 MOIS_GROUPN 11.3.24. Multi-touch Group Setting (mltch_grp_t) Detailed Description Sensor can be configured in the multi-touch group using this type • MLTCH_NONE Indicates that the sensor does not belong to any multi-touch group. • MLTCH_GROUP_X Indicates that the sensor belongs to the multi-touch group x. Range: MLTCH_NONE=0 to MOIS_GROUP_7. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 82 • • • • • • • • • • MLTCH_NONE=0 MLTCH_GROUP_0 MLTCH_GROUP_1 MLTCH_GROUP_2 MLTCH_GROUP_3 MLTCH_GROUP_4 MLTCH_GROUP_5 MLTCH_GROUP_6 MLTCH_GROUP_7 MLTCH_GROUPN 11.3.25. Touch Mode Configuration (tag_tch_mode) Touch mode can be configured. Note: This is applicable only for ATmega devices. Data Fields • TCH_MODE_POLLED Polled mode • TCH_MODE_ISR Interrupt mode • TCH_MODE_NONE Touch mode is null. 11.3.26. Trigger Mode (tag_trigger_mode) Trigger source for continuous hardware PTC acquisition. It is n clock cycles of internal 128Khz clock. Note: This is applicable only for ATmega devices. Data Fields TCH_TRIGGER_128KHZ_4MS • TCH_TRIGGER_128KHZ_8MS • TCH_TRIGGER_128KHZ_16MS • TCH_TRIGGER_128KHZ_32MS • TCH_TRIGGER_128KHZ_64MS • TCH_TRIGGER_128KHZ_128MS • TCH_TRIGGER_128KHZ_256MS • 11.4. Datastructures 11.4.1. Touch Library Timing Info (tag_touch_time_t) Touch library time parameter. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 83 Field Unit Description measurement_period_ms uint16_t Touch measurement period in milliseconds. This variable determines how often a new touch measurement must be done. current_time_ms Current time set by timer ISR. volatile uint16_t time_to_measure_touch volatile uint8_t 11.4.2. Flag set by timer ISR when it is time to measure touch. Sensor Info (tag_sensor_t) Sensor structure for storing sensor related information. Data Fields Keyword Type Description state uint8_t Sensor state (calibrate, on, off, filter-in, filter-out, disable, pos-recal) general_counter uint8_t General purpose counter used for calibrating, drifting, etc ndil_counter uint8_t Counter used for detect integration type_aks_pos_hyst uint8_t bits 7..6: sensor type: {00: key,01: rotor,10: slider,11: reserved} bits 5..3: AKS group (0..7): 0 = no AKS group bit 2 : positive recal flag bits 1..0: hysteresis 11.4.3. threshold uint8_t Sensor detection threshold from_channel uint8_t Sensor from channel for keys: from channel = to channel. Rotors: Top channel. Sliders : Left most channel Note: We need to_channel for rotors/sliders only to_channel uint8_t For keys, this is unused. For rotors: Bottom left channel. For sliders: Middle channel index uint8_t Index into array of rotor/slider values Global Sensor Configuration Info (tag_touch_global_param_t) Touch library global parameter. Data Fields Field Unit Description di uint8_t Detect Integration (DI) limit. atch_drift_rate uint8_t Sensor away from touch drift rate. tch_drift_rate uint8_t Sensor towards touch drift rate. max_on_duration uint8_t MaximumON time duration. drift_hold_time uint8_t Sensor drift hold time. atch_recal_delay uint8_t Sensor away from touch recalibration delay. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 84 11.4.4. Field Unit Description cal_seq_1_count uint8_t Sensor calibration dummy burst count. cal_seq_2_count uint8_t Sensor calibration settling burst count. recal_threshold recal_threshold_t Sensor away from touch recalibration threshold. touch_postprocess_mode Uint16_t Sensor post-processing mode. auto_os_sig_stability_limit uint8_t Stability limit for Auto Oversample feature. auto_tune_sig_stability_limit uint16_t Stability limit for frequency auto tune feature. auto_freq_tune_in_cnt uint8_t Frequency auto tune In counter. nm_sig_stability_limit uint16_t Stability limit for noise measurement. nm_noise_limit uint8_t Noise limit. nm_enable_sensor_lock_out nm_sensor_lockout_t Sensor lockout feature variable. nm_lockout_countdown uint8_t Lockout countdown for noise measurement. Charge_share_delay uint8_t Charge share delay value; applicable only for SAM C20, SAM C21, SAM L22 and ATmega devices. Filter Callback Data Type (tag_touch_filter_data_t) Touch library filter callback data type. Data Fields 11.4.5. Field Unit Description num_channel_signals uint16_t Length of the measured signal values list. p_channel_signals uint16_t Pointer to measured signal values for each channel. Measure Data Type (tag_touch_measure_data_t) Touch library measure data type. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 85 Field Unit Description measurement_done_t volatile uint8_t ouch acq_status touch_acq_status_t Status of touch measurement. num_channel_signal uint16_t s Length of the measured signal values list. *p_channel_signals uint16_t Pointer to measured signal values for each channel. num_channel_refere uint16_t nces Length of the measured reference values list. *p_channel_referen uint16_t ces Pointer to measured reference values for each channel. num_sensor_states uint8_t Number of sensor state bytes. *p_sensor_states uint8_t Pointer to touch status of each sensor. num_rotor_slider_v uint8_t alues Length of the rotor and slider position values list. *p_rotor_slider_va uint8_t lues Pointer to rotor and slider position values. num_sensors Length of the sensors data list. uint16_t *p_cc_calibration_ uint16_t vals Pointer to calibrated compensation values for a given sensor channel. *p_sensors Pointer to sensor data. sensor_t *p_sensor_noise_st uint8_t atus Pointer to noise status of the sensors. *p_nm_ch_noise_val uint16_t Pointer to noise level value of each channel. *p_sensor_mois_sta uint8_t tus Pointer to moisture status *p_auto_os_status Pointer to auto-oversamples status uint8_t cc_calib_status_fl uint8_t ag 11.4.6. Flag set by touch_xxxxcap_measure_complete_callba ck() function when a latest Touch status is available. Flag is set when CC-calibration is ongoing. Sensor Configuration Parameter (tag_touch_selfcap_param_t,tag_touch_mutlcap_param_t) Touch library self-capacitance and mutual capacitance sensor parameter. Data Fields Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 86 Field Unit Description aks_group aks_group_t Which AKS group, the sensor belongs to. detect_threshold threshold_t An unsigned 8-bit number setting a sensor detection threshold. detect_hysteresis hysteresis_t A sensor detection hysteresis value. This is expressed as a percentage of the sensor detection threshold. HYST_x = hysteresis value is x% of detection threshold value (rounded down). A minimum value of 2 is used. Example: If detection threshold = 20, HYST_50= 10 (50% of 20) HYST_25= 5 (25% of 20) HYST_12_5 = 2 (12.5% of 20) HYST_6_25 = 2 (6.25% of 20 = 1, but value is hard limited to 2) position_resolution resolution_t 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 position_hysteresis uint8_t 11.4.7. Sensor position hysteresis. This is valid only for a rotor or slider. bits 1..0: hysteresis. Note: This parameter is valid only for mutual capacitance method. Sensor Acquisition Parameter (tag_touch_selfcap_acq_param_t,_tag_touch_mutlcap_acq_param_t) Sensor acquisition parameter. Data Fields Field Unit Description *p_xxxxcap_gain_per_node gain_t Pointer to gain per node. touch_xxxxcap_freq_mode Freq_mode_sel_t Set-up acquisition frequency mode. *xxxxcap_ptc_prsc prsc_div_sel_t Pointer to PTC clock pre-scaler value. *xxxxcap_resistor_value rsel_val_t Pointer to PTC series resistor value. p_xxxxcap_hop_freqs *freq_hop_sel_t Pointer to acquisition frequency settings. *p_xxxxcap_filter_level filter_level_t Pointer to filter level. *p_xxxxcap_auto_os auto_os_t Pointer to auto oversampling. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 87 Field Unit Description *xxxxcap_ptc_prsc_cc_cal prsc_div_sel_t Pointer to PTC clock prescale value during CC calibration. *xxxxcap_resistor_value_cc_cal rsel_val_t 11.4.8. Pointer to PTC sense resistor value during CC calibration. Self-capacitance Sensor Configuration (touch_selfcap_config_t) Touch Library self-capacitance configuration input type. Data Fields Field Unit Description num_channels uint16_t Number of channels. num_sensors uint16_t Number of sensors. num_rotors_and_sliders uint8_t Number of rotors/ sliders. global_param touch_global_param_t Global sensor configuration information. touch_selfcap_acq_param touch_selfcap_acq_param_t Sensor acquisition parameter information. *p_data_blk uint8_t Pointer to data block buffer. buffer_size uint16_t Size of data block buffer. *p_selfcap_y_nodes uint16_t Pointer to selfcapacitance nodes. self_quick_reburst_enable uint8_t Quick re-burst enable. (touch_filter_data_t *p_filter_data) void(*filter_callback) Self-capacitance filter callback. enable_freq_auto_tune uint8_t Frequency auto tune enable. enable_noise_measurement uint8_t Noise measurement enable. nm_buffer_cnt uint8_t Memory allocation buffer. self_mois_tlrnce_enable uint8_t Self-capacitance moisture tolerance enable flag. self_mois_groups uint8_t Number of selfcapacitance moisture groups. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 88 11.4.9. Field Unit Description self_mois_quick_reburst_enable uint8_t Moisture Quick re-burst enable. self_ptc_gpio_state ptc_gpio_state_t GPIO state for Selfcapacitance PTC pins tlib_feature_list tlib_init_fn_ptr Library feature list. Mutual Capacitance Sensor Configuration (touch_mutlcap_config_t) Touch Library mutual capacitance configuration input type. Data Fields Field Unit Description num_channels uint16_t Number of channels. num_sensors uint16_t Number of sensors. num_rotors_and_sliders uint8_t Number of rotors/ sliders. global_param touch_global_param_t Noise measurement enable/disable. touch_xxxxcap_acq_param touch_xxxxcap_acq_param_t Sensor acquisition parameter info. *p_data_blk uint8_t Pointer to data block buffer. *buffer_size uint16_t Size of data block buffer. *p_mutlcap_xy_nodes uint16_t Pointer to xy-nodes. mutl_quick_reburst_enable uint8_t Quick re-burst enable. (touch_filter_data_t *p_filter_data) void(* filter_callback ) Mutual capacitance filter callback. enable_freq_auto_tune uint8_t Frequency auto tune enable. enable_noise_measurement uint8_t Noise measurement enable. nm_buffer_cnt uint8_t Memory allocation buffer. mutl_mois_tlrnce_enable uint8_t Mutual capacitance moisture tolerance enable flag. mutl_mois_groups uint8_t Number of mutual capacitance moisture groups. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 89 Field Unit Description mutl_mois_quick_reburst_enable uint8_t Moisture Quick re-burst enable. mutl_ptc_gpio_state ptc_gpio_state_t GPIO state for mutual capacitance PTC pins tlib_feature_list tlib_init_fn_ptr Library feature list. 11.4.10. Moisture Structure (tag_snsr_mois_t) Structure for storing moisture and multi-touch group information. Data Fields Field Unit Description mois_grp uint8_t Moisture group member multch_grp uint8_t Multi-touch group member 11.4.11. Touch Library Input Configuration (touch_config_t) Touch Library Input Configuration Structure. Data Fields Field Unit Description p_mutlcap_config touch_mutlcap_config_t Pointer to mutual capacitance configuration structure. p_selfcap_config touch_selfcap_config_t Pointer to self-capacitance configuration structure. ptc_isr_lvl uint8_t PTC ISR priority level. Note: This is applicable only for SAM devices. tch_mode tch_mode_t Touch mode configuration. Note: This is applicable only for ATmega devices. 11.4.12. Library Function List (tag_tlib_init_fn_ptr_t) Touch Library support functions initializer. Data Fields Field Unit Description auto_tune_init void(*auto_tune_init) Auto-tune function initializer auto_os_init uint32_t (*auto_os_init) Auto-OS function initializer lk_chk void(*lk_chk) Sensor lock-out function initializer enable_aks void enable_aks(void) AKS function initializer 11.4.13. Touch Library Information (tag_touch_info_t) Touch Library information structure. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 90 Data Fields Field Unit Description tlib_state touch_tlib_state_t Touch library state is specified num_channels_in_use unit16_t Number of channels in use; irrespective of the corresponding sensor being disabled or enabled num_sensors_in_use uint16_t Number of sensors in use; irrespective of the sensor being disabled or enabled num_rotors_sliders_in_use uint8_t Number of rotor sliders in use; irrespective of the Rotor/Slider being disabled or enabled max_channels_per_rotor_slider uint8_t Max possible number of channels per rotor or slider 11.4.14. Touch Library Version Information (touch_libver_info_t) Touch Library version information structure. Data Fields Field Unit Description chip_id unit32_t Chip ID product_id uint16_t Product ID fw_version uint16_t Touch Library Version Bits[12:15] Reserved Bits[8:11] TLIB_MAJOR_VERSION Bits[4:7] TLIB_MINOR_VERSION Bits[0:3] TLIB_PATCH_VERSION 11.5. Global Variables Field Unit Description touch_time touch_time_t This holds the library timing info touch_acq_status touch_acq_status_t This holds the Touch Library acquisition status cc_cal_max_signal_limit uint16_t CC calibration maximum signal limit variable cc_cal_min_signal_limit uint16_t CC calibration minimum signal limit variable Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 91 Field Unit Description *p_selfcap_measure_data touch_measure_data_t This holds the self-capacitance method measure data pointer *p_mutlcap_measure_data touch_measure_data_t This holds the mutual capacitance method measure data pointer wake_up_touch uint8_t Wake up touch status from Library to Application low_power_mode uint8_t Low power mode status from Library to Application mois_lock_global_mutl uint8_t Moisture global lock variable for mutual capacitance method mois_lock_global_self uint8_t Moisture global lock variable for selfcapacitance method 11.6. API 11.6.1. Sensor Init and De-init touch_ret_t touch_mutlcap_sensors_init (touch_config_t * p_touch_config) touch_ret_t touch_selfcap_sensors_init (touch_config_t * p_touch_config) This API is used to initialize the Touch Library with Mutual cap or Self cap method pin, register and sensor configuration provided by the user. Parameters:p_touch_config Pointer to Touch configuration structure. Returns:touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensors_deinit(void) touch_ret_t touch_selfcap_sensors_deinit(void); This API can be used to de-initialize the sensor for specific sensing group. Parameters: void. Returns: touch_ret_t: Touch Library Error status. 11.6.2. Sensor Setup and Configuration touch_ret_t touch_mutlcap_sensor_config (sensor_type_t sensor_type, channel_t from_channel, channel_t to_channel, aks_group_t aks_group, threshold_t detect_threshold, hysteresis_t detect_hysteresis, resolution_tposition_resolution, uint8_t position_hysteresis, sensor_id_t * p_sensor_id) touch_ret_t touch_selfcap_sensor_config (sensor_type_t sensor_type, channel_t from_channel, channel_t to_channel, aks_group_t aks_group, threshold_t detect_threshold, hysteresis_t detect_hysteresis, resolution_tposition_resolution, sensor_id_t * p_sensor_id) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 92 This API can be used to configure a sensor of type key, rotor or slider. Data Fields: Field Description sensor_type can be of type key, lump, rotor, or slider. from_channel the first channel in the slider sensor. to_channel the last channel in the slider sensor. aks_group which AKS group (if any) the sensor is in. detect_threshold the sensor detection threshold. detect_hysteresis the sensor detection hysteresis value. position_resolution the resolution of the reported position value. position_hysteresis the hysteresis for position value (available only for mutual capacitance mode). p_sensor_id the sensor id value of the configured sensor is updated by the Touch Library. Returns: touch_ret_t: Touch Library Error status. 11.6.3. Sensor Calibration touch_ret_t touch_mutlcap_sensors_calibrate (auto_tune_type_t ) touch_ret_t touch_selfcap_sensors_calibrate (auto_tune_type_t ) This API is used to calibrate the sensors for the first time before starting a Touch measurement. This API can also beused to force calibration of sensors when any of the Touch sensor parameters are changed during runtime. Returns:touch_ret_t: Touch Library Error status. 11.6.4. Sensor Measure touch_ret_t touch_mutlcap_sensors_measure (touch_current_time_t current_time_ms, touch_acq_mode_tmutlcap_acq_mode, void(*)(void) measure_complete_callback) touch_ret_t touch_selfcap_sensors_measure (touch_current_time_t current_time_ms, touch_acq_mode_tselfcap_acq_mode, void(*)(void) measure_complete_callback) This API can be used to start a Touch measurement. Parameters: current_time_ms Current time in millisecond. measure_complete_callback Interrupt callback to indicate measurement completion. Returns: touch_ret_t: Touch Library Error status. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 93 11.6.5. Sensor Suspend and Resume touch_ret_t touch_suspend_ptc(void) touch_ret_t touch_resume_ptc(void) The touch_suspend_ptc function suspends the PTC library's current measurement cycle. The completion of the operation is indicated through callback pointer that must be initialized by the application. Refer Sensor Global Parameters. The touch_resume_ptc function resumes the PTC library's current measurement which was suspended using touch_suspend_ptc. After the touch_resume_ptc function is called by the application, the touch_xxxxcap_sensors_measure API should be called only after the measurement complete callback function is received. Parameters: void. Returns: touch_ret_t: Touch Library Error status. 11.6.6. Sensor Disable and Re-enable touch_ret_t touch_mutlcap_sensor_disable (sensor_id_t sensor_id) touch_ret_t touch_selfcap_sensor_disable (sensor_id_t sensor_id) This API can be used to disable any sensor. Parameters: sensor_id Sensor number which needs to be disabled Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensor_reenable (sensor_id_t sensor_id, uint8_t no_calib) touch_ret_t touch_selfcap_sensor_reenable (sensor_id_t sensor_id, uint8_t no_calib) This API can be used to re-enable a disabled sensor. Parameters: sensor_id Sensor number which needs to be reenabled no_calib When value is set to 1, force calibration is not applicable. When value is set to 0, force calibration is applied Returns: touch_ret_t: Touch Library Error status. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 94 11.6.7. Read-back Sensor Configuration touch_ret_t touch_mutlcap_sensor_get_acq_config (touch_mutlcap_acq_param_t * p_touch_mutlcap_acq_param) touch_ret_t touch_selfcap_sensor_get_acq_config (touch_selfcap_acq_param_t * p_touch_selfcap_acq_param) This API can be used to read back the sensor acquisition parameters. Parameters: p_touch_mutlcap_acq_param The acquisition parameters for the mutual capacitance. p_touch_selfcap_acq_param The acquisition parameters for the self-capacitance. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensor_get_config (sensor_id_t sensor_id, touch_mutlcap_param_t *p_touch_sensor_param) touch_ret_t touch_selfcap_sensor_get_config (sensor_id_t sensor_id, touch_selfcap_param_t *p_touch_sensor_param) This API can be used to read back the sensor configuration parameters. Parameters: sensor_id The sensor id for which the parameters has to be read-back. p_touch_sensor_param The sensor parameters for the mutual or self-capacitance. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensor_get_delta (sensor_id_t sensor_id, touch_delta_t * p_delta) touch_ret_t touch_selfcap_sensor_get_delta (sensor_id_t sensor_id, touch_delta_t * p_delta) This API can be used to retrieve the delta value corresponding to a given sensor. Parameters: sensor_id The sensor id for which delta value is being seeked. p_delta Pointer to the delta variable to be updated by the Touch Library. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_get_global_param (touch_global_param_t * p_global_param) touch_ret_t touch_selfcap_get_global_param (touch_global_param_t * p_global_param) This API can be used to read back the global parameter. Parameters: p_global_param The pointer to global sensor configuration. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 95 Returns: touch_ret_t: Touch Library Error status. 11.6.8. Update Sensor Configuration touch_ret_t touch_mutlcap_sensor_update_acq_config (touch_mutlcap_acq_param_t *p_touch_mutlcap_acq_param) touch_ret_t touch_selfcap_sensor_update_acq_config (touch_selfcap_acq_param_t * p_touch_selfcap_acq_param) This API can be used to update the sensor acquisition parameters. Parameters: p_touch_mutlcap_acq_param The acquisition parameters for the mutual capacitance. p_touch_selfcap_acq_param The acquisition parameters for the self-capacitance. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_sensor_update_config (sensor_id_t sensor_id, touch_mutlcap_param_t *p_touch_sensor_param) touch_ret_t touch_selfcap_sensor_update_config (sensor_id_t sensor_id, touch_selfcap_param_t *p_touch_sensor_param This API can be used to update the sensor configuration parameters. Parameters: sensor_id The sensor id whose configuration parameters has to be changed. p_touch_sensor_param The touch sensor parameter structure that will be used by the Touch Library to update. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_update_global_param (touch_global_param_t * p_global_param) touch_ret_t touch_selfcap_update_global_param (touch_global_param_t * p_global_param) This API can be used to update the global parameter. Parameters: p_global_param The pointer to global sensor configuration. Returns: touch_ret_t: Touch Library Error status. 11.6.9. Get Library Information and Version touch_ret_t touch_mutlcap_get_libinfo (touch_info_t * p_touch_info) touch_ret_t touch_selfcap_get_libinfo (touch_info_t * p_touch_info) Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 96 This API can be used to get the Touch Library configuration. Parameters: p_touch_info Pointer to the Touch info data structure that will be updated by the Touch Library. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_library_get_version_info (touch_libver_info_t * p_touch_libver_info) This API can be used to get the Touch Library version information. Parameters: p_touch_libver_info Pointer to the Touch Library Version info data structure that will be updated by the Touch Library. 11.6.10. Moisture Tolerance API touch_ret_t touch_mutlcap_cnfg_mois_mltchgrp(sensor_id_t snsr_id, moisture_grp_t mois_grpid, mltch_grp_t mltch_grpid) touch_ret_t touch_selfcap_cnfg_mois_mltchgrp(sensor_id_t snsr_id, moisture_grp_t mois_grpid, mltch_grp_t mltch_grpid) This API can be used to assign moisture group and multi touch group for a sensor. Parameters: snsr_id - sensor ID mois_grpid - moisture group ID mltch_grp_t - multi-touch group Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_cnfg_mois_threshold(moisture_grp_t mois_grpid, mois_snsr_threshold_t snsr_threshold, mois_system_threshold_t system_threshold) touch_ret_t touch_selfcap_cnfg_mois_threshold(moisture_grp_t mois_grpid, mois_snsr_threshold_t snsr_threshold, mois_system_threshold_t system_threshold) This API is used to assign moisture sensor threshold and moisture system threshold to a moisture group ID Parameters: mois_grpid - moisture group ID snsr_threshold - moisture sensor threshold system_threshold - moisture system threshold Returns: Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 97 touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_mois_tolrnce_enable(void) touch_ret_t touch_selfcap_mois_tolrnce_enable(void) This API is used to enable moisture tolerance check during run time. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_mois_tolrnce_quick_reburst_enable(void) touch_ret_t touch_selfcap_mois_tolrnce_quick_reburst_enable(void) This API is used to enable moisture tolerance quick re- burst feature during run time. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_mois_tolrnce_disable(void) touch_ret_t touch_selfcap_mois_tolrnce_disable(void) This API is used to disable moisture tolerance check during run time. Returns: touch_ret_t: Touch Library Error status. touch_ret_t touch_mutlcap_mois_tolrnce_quick_reburst_disable(void) touch_ret_t touch_selfcap_mois_tolrnce_quick_reburst_disable(void) This API is used to disable moisture tolerance quick re- burst feature during run time. Returns: touch_ret_t: Touch Library Error status. Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 98 12. Revision History Doc. Rev. Date Comments Rev.L 04/2016 Updated Sections 1, 5 and 8 with reference to the latest extension release Rev.K 02/2016 Added ATmega324PB support. Updated Sections 1, 5 and 8 with reference to the latest extension release Rev.J 01/2016 Included the following new sections: 1. Compensation Circuit 2. Using Atmel ICE for Qdebug Data Streaming 3. Application flow for megaAVR Updated Sections 5 and 8 with reference to the latest extension release Rev.I 09/2015 Included Charge share delay Updated Section 5 .2.8 and 5.2.10 - Library parameters for quick re-burst and moisture parameters added Updated Section 11.6.8 - Moisture API's Added Updated section 8 - Example projects updated Rev.H 06/2015 Revised Section 2 - Device Variants Supported and included information on device multiplexing option Updated Section 7.2 - Code and data memory considerations Updated Section 5.2.1 - Pin, Channel, and Sensor Parameters Rev.G 04/2015 Updated Section 2 - Device Variants Supported and included information on device multiplexing option Rev.F 02/2015 Included relevant information regarding low-power and lumped mode support Rev.E 11/2014 Included Section 5.2.6 and 5.2.7 regarding noise counter measures. Included Section 3 regarding overview of capacitive touch technology. Rev.D 02/2014 Global updates across the document related to QTouch Library and QTouch Composer 5.3 Rev.C 10/2013 Included Section 3.3.4, Using QDebug Touch Data Debug Communication Included a note on interrupt handler for IAR example project in Section 3.3.3 Rev.B 10/2013 Updated errata in Section 4, Known Issues Rev.A 09/2013 Initial document release Atmel QTouch Library Peripheral Touch Controller [USER GUIDE] Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 99 Atmel Corporation © 1600 Technology Drive, San Jose, CA 95110 USA T: (+1)(408) 441.0311 F: (+1)(408) 436.4200 | www.atmel.com 2016 Atmel Corporation. / Rev.: Atmel-42195L-Peripheral-Touch-Controller_User Guide-04/2016 ® ® ® ® ® Atmel , Atmel logo and combinations thereof, Enabling Unlimited Possibilities , AVR QTouch , AKS and others are registered trademarks or trademarks of Atmel ® ® Corporation in U.S. and other countries. ARM and Cortex are registered trademarks of ARM Limited. Other terms and product names may be trademarks of others. DISCLAIMER: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life. SAFETY-CRITICAL, MILITARY, AND AUTOMOTIVE APPLICATIONS DISCLAIMER: Atmel products are not designed for and will not be used in connection with any applications where the failure of such products would reasonably be expected to result in significant personal injury or death (“Safety-Critical Applications”) without an Atmel officer's specific written consent. Safety-Critical Applications include, without limitation, life support devices and systems, equipment or systems for the operation of nuclear facilities and weapons systems. Atmel products are not designed nor intended for use in military or aerospace applications or environments unless specifically designated by Atmel as military-grade. Atmel products are not designed nor intended for use in automotive applications unless specifically designated by Atmel as automotive-grade.