Configure Surface and Gesture MH3 Touch Project

Last modified by Microchip on 2023/11/10 11:18

Warning: This tutorial uses the old Harmony configuration tool (MPLAB® Harmony Configurator (MHC)). New Harmony projects should use the MPLAB Code Configurator (MCC) instead.



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 the 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.

Back to Top

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 it as per the 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 the Gesture option.
  • 1 Finger Gestures: 1 Touch Surface module is selected with the Gesture option.
  • 1 & 2 Finger Gestures: 2 Touch Surface module is selected with the Gesture option.

Click Add.

Select Gesture Type from the drop-down menu

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.

Warning Message: Select Yes

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.

Back to Top

Pin Selection

Click on the Pins tab.

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

Pins tab.  Click on the PTC lines to re-assign the pins

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.

Back to Top


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 thresholds and hysteresis in the same AKS Group.

Parameters tab: Select Channel


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.

Sensor Tab

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 the gesture feature is enabled, position resolution should be less than or equal to 8-bit.

Surface Tab


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:

Gesture Tab

All the gesture time-related parameters are timed with a 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.

Back to Top


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

DEBUG OPTION: Click on Parameters, 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.

Debut Option.  Select 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.

Debug Option:  Select Data Visualizer

Back to Top


Click on the Notifications tab to check the notifications.

Notifications tab

Back to Top


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

Summary tab

Back to Top

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.

Back to Top