Generate QTouch® Surface Gesture Project

Last modified by Microchip on 2023/11/09 08:55


The following lab shows you how to create a QTouch® Surface project in Atmel® START, where you can add horizontal and vertical sensors, and configure surface and gesture parameters. The resulting project supports GCC and IAR compilers. This project is generated for the ATTiny1617 Water Tolerant 2D Touch Surface Kit.


Hardware Tools

Software Tools


Open Atmel START

Go to and select the CREATE NEW PROJECT option.

Screenshot of the site with Create New Project Button highlighted

Select Device and Create New Project

Start typing attiny1617 on the Filter on device… box. Select 'ATtiny1617-MFR' and proceed to click on CREATE NEW PROJECT.

Selecting ATTiny1617 device by typing part number into search box in Create New Project window

Add Software Components

After project creation, the project dashboard will open as follows. Click Add software component to add the QTouch Library.

Project Dashboard with 'Add Software Component' button highlighted

You can type touch in the Filter box to be able to find the library faster. Add the QTouch Library by clicking the + icon and then clicking on Add Component.

Add Software Component window with QTouch Library selected

QTouch Library Middleware will be added to the project.

QTouch Library listed as Middleware in the Project Dashboard

Add Sensors

The ATtiny1617 Water Tolerant Touch Surface Kit has six self-cap channels in the horizontal (X-axis) direction and five self-cap channels in the vertical (Y-axis) direction.

Adding Surface
Select the 'QTouch' tab and then click on the 2D Surface drop-down menu.
Enter the Number of Horizontal channels as 6 and the Number of Vertical channels as 5.
Select 'Selfcap' from the Technology drop-down menu.
Select '1 & 2 Finger gestures' from the Gesture Type drop-down menu.
Click Add button

Screenshot of QTouch Configurator with '2D Surface' drop down menu open to configure the surface

Atmel START loads the surface with the selected configuration and a warning pops up asking you to enter the CPU and Peripheral (PTC, Timer, UART) default clock settings.

  • Click Yes to load QTouch default settings for the CPU and peripheral clocks.
  • Click No to configure CPU and peripheral clocks manually.

Guidelines to Configure Clocks Manually

Screenshot of 'Clock Warning' message after adding Surface, it's normal

Touch and Debug Interface Pin Selection

Click on the 'Pins' tab on the left side.

Highlighted 'Pins' button in QTouch Configurator side panel

Refer to ATtiny1617 Water Tolerant Touch Surface Kit design files

Based on the design files, Y lines should be selected as follows:

Pin assignments for ATTiny1617 according to the 2D Surface Kit design guidelines

Pin Selection

Click on each channel to modify the assigned pin.

Clicking on a channel to assign a pin in the Sensor Matrix view of the Configurator

Select the channel from the channels list as per the hardware design files.

After clicking on a channel, select the pin from the pop-up list according to the table

Driven Shield

Click on the 'Driven Shield' tab to enable and configure the driven shield.

This feature is not supported on all devices. The Enable Driven Shield check box is greyed out when not supported.

The driven shield tab of Pins setup page

  • Click on the Enable Driven Shield check box
  • Select the driven shield pin from the shield pin drop-down menu.

After enabling Driven Shield, you have the option to set which pin to use for it


Click on the 'Debug' tab to enable and configure debug port pins.

  • Configure UART TXD and RXD pins as per the hardware.
  • UART default baud rate is 38400 bps for AVR devices and 115200 bps for SAM Devices.
  • To modify default UART settings click on View/Configure UART
  • Uncheck the Enable Data streamer check box to disable the debug port to save memory in the final application.

Enable and configure the 'Data Streamer' UART on the Debug tab of the Configurator


Select the 'Parameters' tab. Channel properties such as Oversamples, Digital Gain, Analog Gain, Series Resistor, CSD (additional cycles), Prescaler, Threshold, Hysteresis, and Sensor Adjacent Key Suppression (AKS™) Group can be modified in this tab.

Note: All keys forming a touch surface should be configured with similar threshold and hysteresis, and all in the same Adjacent Key Suppression (AKS™) Group.

Screenshot of Parameters/Channel tab of Configurator showing common settings for all sensors in the surface


Select the 'Sensor' tab. Sensor parameters such as Detect Integration, Away from Touch Recal Integration Count, Away from Touch Recalibration Threshold, Touch Drift Rate, Away from Touch Drift Rate, Drift Hold Time, Re-burst mode and Max on Duration can be modified in this tab.

Note: Detect Integration should not be more than two in surface and gesture projects.

Screenshot of Parameters/Sensor tab of Configurator

Scroll down in the same tab to change Scan Rate, Acquisition Frequency, and Noise Handling using Frequency Hop. Frequency Hop can be enabled by selecting the Enable Frequency Hop check box.

Screenshot of Parameters/Sensor tab of Configurator scrolled down to Scan Rate and Frequency Hop settings

The Frequency Hop auto-tune feature can be enabled by the Enable Frequency Auto Tune check box. When Frequency Hop is enabled, configuration parameters related to frequency hopping can be modified. Similarly, Frequency Hop auto-tune configuration parameters can be changed when Frequency Hop Auto Tune is enabled.

Screenshot of Frequency Hop settings page with Auto tuning enabled


Select the 'Surface' tab. Surface parameters such as Position Resolution, Deadband Percentage, Median Filter, IIR Filter, Position Hysteresis, and Minimum Contact can be changed in this tab.

Note: Position resolution should be less than or equal to 8-bit when gestures are enabled.

Screenshot of Parameters/Surface tab of Configurator with Position Resolution set to 8-bit in the surface settings


Select the 'Gesture' tab. This tab displays gesture parameters when the check boxes are ticked. Otherwise, gestures are enabled and loaded with default settings for gesture parameters.

Note: All '1 Finger' or both '1 & 2 Finger' gestures are enabled based on the gesture selection during surface sensor creation.

To disable the gestures after surface sensor creation, uncheck the Enable Gesture check box.

Screenshot of Parameters/Gesture tab of Configurator where 1-2 finger gestures are enabled/disabled

When all the gesture check boxes are enabled, it displays the gesture parameters as shown below. All the gesture time-related parameters are timed with 10 ms timer, e.g. if Tap Release Timeout is configured as 5, this means 5x10 = 50 ms.

Note: Ensure that while configuring Tap Release Timeout, Swipe Timeout, and Tap Hold Timeout you follow the equation:Tap Release Timeout < Swipe Timeout < Tap Hold Timeout

Screenshot of Parameters/Gesture tab of Configurator with selected gesture parameters displayed


Click on 'Notifications' tab to check the notifications triggered by Atmel START.

Check the Notifications tab for errors or warnings from START


Select 'Summary' tab which displays Project Configuration Summary and QTouch Library Module Versions. Click on Download Summary to download the summary information.

Screenshot of the Summary tab with project details and 'Download Summary" button


After completing all the configuration, click the EXPORT PROJECT option. Atmel Studio IDE is selected by default. Aditionally, you can select the IAR IDE if required for the project, then enter the file name and click Download Pack.

Screenshot of Export Project page