Configure Surface and Gesture Harmony v3 Touch Project


This article provides information on creating a Touch Surface and Gesture project in Microchip's MPLAB® Harmony v3 platform as well as configuring surface and gesture parameters. The generated project supports MPLAB® XC32 compiler in MPLAB® X IDE.



Launch Touch Configurator

Follow steps one through eight in the Generate a Touch Project with MPLAB® Harmony page to launch the Touch Configurator in the MPLAB Harmony 3 platform.


Add Surface Sensors

For information on Surface Sensor Design, please refer to the Guide for Surface Sensor Design.

Select the technology, click on the Surface Sensor, and configure as per sensor design.


Enter the Number of Horizontal Channels.


Enter the Number of Vertical Channels.


Select Gesture Type from the drop-down menu. The available options are:

  • No Gestures: 1 Touch Surface module is selected without Gesture option.
  • 1 Finger Gestures: 1 Touch Surface module is selected with Gesture option.
  • 1 & 2 Finger Gestures: 2 Touch Surface module is selected with Gesture option.


Click Add.


It loads the Surface with the selected configuration and a warning will pop up asking you to enter the CPU and Peripheral default clock settings (Peripheral Touch Controller (PTC), Timer, Universal Asynchronous Receiver Transmitter (UART)).

  • Click Yes to load CPU and Peripheral clock settings for optimized touch performance.
  • Click No to configure CPU and Peripheral clocks manually.

If No is chosen, then configure the main and PTC clocks in the clock configuration and Non-Volatile Memory (NVM) Wait States in the Non-Volatile Memory Controller (NVMCTRL), according to the documentation available in the harmony repo\touch\doc folder.


Pin Selection

Click on the Pins tab.

Click on the PTC lines to re-assign the pins as per your design.


Note: The red colored PTC line indicates that the pin is already used by a Button/Slider/Wheel sensor. Re-assign the pin in the Button/Slider/Wheel pin selection page to use it for surface configuration.




Select the Parameters tab.Under Channel, Channel Parameters such as Filter Levels, Digital Gain, Analog Gain, Series Resistor, Charge Share Delay (CSD) (additional cycles), Prescaler, Threshold, Hysteresis, and Sensor Adjacent Key Suppression (AKS™) Group can be modified.

Note: All keys forming a touch surface could be configured with similar threshold and hysteresis in the same AKS Group.



Under Sensor, Sensor Parameters such as Detect Integration, Away from Touch Recal Integration Count, Away from Touch Recal Threshold, Touch Drift Rate, Away from Touch Drift Rate, Drift Hold Time, Re-burst mode and Max ON Duration can be modified.

Note: Touch response may be sluggish if Detect Integration is more than two for surface and gesture projects.


Scroll down in the same tab to change Scan Rate, Acquisition Frequency and Noise Handling using Frequency Hop.


Under Surface, Surface Parameters such as Position Resolution, Deadband Percentage, Median Filter, Infinite Impulse Response (IIR) Filter, Position Hysteresis and Minimum Contact can be modified.

Note: When gesture feature is enabled, position resolution should be less than or equal to 8-bit.



Select the Gesture tab.

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.

The gesture parameters are 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 5 x 10 = 50 ms.

Note: While configuring Tap Release Timeout, Swipe Timeout, and Tap Hold Timeout follow the rule:
Tap Release Timeout < Swipe Timeout < Tap Hold Timeout.



To enable the DEBUG OPTION, click on Parameters from the panel on left, then click on the Sensor tab from the list of tabs on top.


Two options are possible:

  • Using 2D Touch Surface Utility
  • Using Data Visualizer


Follow the steps given in the Guide to Connect to Microchip 2D Touch Surface Utility to visualize surface and gesture data using 2D Touch Surface Utility software.



Follow the steps given in Visualize Touch Data using Data Visualizer to visualize surface and button data using Data Visualizer software.



Select the Serial Communication (SERCOM) module and the pins as per your design.




Click on the Notifications tab to check the notifications.




Select the Summary tab which displays the Project Configuration Summary and Touch Library Module Versions.



Generate Code

After Project Configuration, generate the code. The source and header files will be added to the project. Build the project and program the binary file to the device.

© 2024 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.