42
2016 Microchip Technology Inc. DS40001852A mTouch ® Capacitive Sensing Library Module for MPLAB ® X Code Configurator User’s Guide

mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

  • Upload
    others

  • View
    18

  • Download
    0

Embed Size (px)

Citation preview

Page 1: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

2016 Microchip Technology Inc. DS40001852A

mTouch® Capacitive Sensing

Library Module for MPLAB® XCode Configurator

User’s Guide

Page 2: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

DS40001852A-page 2 2016 Microchip Technology Inc.

Information contained in this publication regarding deviceapplications and the like is provided only for your convenienceand may be superseded by updates. It is your responsibility toensure that your application meets with your specifications.MICROCHIP MAKES NO REPRESENTATIONS ORWARRANTIES OF ANY KIND WHETHER EXPRESS ORIMPLIED, WRITTEN OR ORAL, STATUTORY OROTHERWISE, RELATED TO THE INFORMATION,INCLUDING BUT NOT LIMITED TO ITS CONDITION,QUALITY, PERFORMANCE, MERCHANTABILITY ORFITNESS FOR PURPOSE. Microchip disclaims all liabilityarising from this information and its use. Use of Microchipdevices in life support and/or safety applications is entirely atthe buyer’s risk, and the buyer agrees to defend, indemnify andhold harmless Microchip from any and all damages, claims,suits, or expenses resulting from such use. No licenses areconveyed, implicitly or otherwise, under any Microchipintellectual property rights unless otherwise stated.

Note the following details of the code protection feature on Microchip devices:

• Microchip products meet the specification contained in their particular Microchip Data Sheet.

• Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions.

• There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property.

• Microchip is willing to work with the customer who is concerned about the integrity of their code.

• Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.”

Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of ourproducts. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such actsallow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act.

Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified.

QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV

== ISO/TS 16949 ==

Trademarks

The Microchip name and logo, the Microchip logo, AnyRate, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KeeLoq, KeeLoq logo, Kleer, LANCheck, LINK MD, MediaLB, MOST, MOST logo, MPLAB, OptoLyzer, PIC, PICSTART, PIC32 logo, RightTouch, SpyNIC, SST, SST Logo, SuperFlash and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

ClockWorks, The Embedded Control Solutions Company, ETHERSYNCH, Hyper Speed Control, HyperLight Load, IntelliMOS, mTouch, Precision Edge, and QUIET-WIRE are registered trademarks of Microchip Technology Incorporated in the U.S.A.

Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BodyCom, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, MiWi, motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, PureSilicon, RightTouch logo, REAL ICE, Ripple Blocker, Serial Quad I/O, SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.

SQTP is a service mark of Microchip Technology Incorporated in the U.S.A.

Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries.

GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries.

All other trademarks mentioned herein are property of their respective companies.

© 2016, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved.

ISBN: 978-1-5224-0729-4

Page 3: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

2016 Microchip Technology Inc. DS40001852A-page 3

Object of Declaration: mTouch® Capacitive Sensing Library for MPLAB® X Code Configurator

Page 4: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® CAPACITIVE SENSING LIBRARY

MODULE FOR MPLAB® X CODE CONFIGURATOR

USER’S GUIDE

Table of Contents

Preface ........................................................................................................................... 8

Chapter 1. Overview1.1 Introduction ................................................................................................... 14

Chapter 2. mTouch® Capacitive Sensing Library Module2.1 Buttons and Proximity Configuration ............................................................ 17

2.1.1 Common Button Configuration Overview .................................................. 182.1.1.1 Create New Button .................................................................... 182.1.1.2 Interface Method ........................................................................ 182.1.1.3 Press Timeout ........................................................................... 192.1.1.4 Negative Capacitance Recovery ............................................... 192.1.1.5 Baseline Filtering ....................................................................... 19

2.1.2 Individual Button Configuration Overview .................................................. 202.1.2.1 Delete Item ................................................................................ 202.1.2.2 Name ......................................................................................... 202.1.2.3 Sensor ....................................................................................... 202.1.2.4 Threshold ................................................................................... 212.1.2.5 Deviation Scaling ....................................................................... 21

2.1.3 Common Proximity Sensor Configuration Overview ................................. 222.1.3.1 Create New Proximity Sensor ................................................... 222.1.3.2 The Interface Method ................................................................ 232.1.3.3 Activity Timeout ......................................................................... 232.1.3.4 Negative Capacitance Recovery ............................................... 232.1.3.5 Baseline Filtering ....................................................................... 23

2.1.4 Individual Proximity Sensor Configuration Overview ................................. 242.1.4.1 Delete Item ................................................................................ 242.1.4.2 Name ......................................................................................... 242.1.4.3 Sensor ....................................................................................... 242.1.4.4 Threshold ................................................................................... 242.1.4.5 Deviation Scaling ....................................................................... 25

2.1.5 Hardware Sensor Configuration Overview ................................................ 252.1.6 Individual Hardware Sensor Configuration Overview ................................ 26

2.1.6.1 Name ......................................................................................... 262.1.6.2 Pin ............................................................................................. 26

2.2 AFA (Automatic Frequency Adaptation) ....................................................... 272.2.1 Enabled AFA ............................................................................................. 272.2.2 AFA Filter Timer ........................................................................................ 27

2016 Microchip Technology Inc. DS40001852A-page 4

Page 5: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

Chapter 3. mTouch® Library Module API3.1 mTouch® Sensor Module ............................................................................. 28

3.1.1 enum mtouch_sensor_error MTOUCH_Sensor_Initialize(enum mtouch sensor_names sensor) ..........................................................................28

3.1.2 enum mtouch_sensor_error MTOUCH_Sensor_Service(enum mtouch_s_ensor_names sensor) ...........................................................28

3.1.3 bool MTOUCH_Sensor_wasSampled(enum mtouch_sensor_names sensor) ...................................................................................................28

3.1.4 void MTOUCH_Sensor_Sampled_Reset(void) .........................................283.1.5 void MTOUCH_Sensor_SetSampledCallback(void (*callback)(enum

mtouch_sensor_names sensor)) ...........................................................283.1.6 mtouch_sensor_sample_t MTOUCH_Sensor_RawSample_Get(enum

mtouch_sensor_names sensor) .............................................................28

3.2 mTouch® Button Module .............................................................................. 293.2.1 void MTOUCH_Button_Initialize(enum mtouch_button_names button) ...293.2.2 void MTOUCH_Button_Service(enum mtouch_button_names button) ....293.2.3 void MTOUCH_Button_Tick(void) .............................................................293.2.4 void MTOUCH_Button_Recalibrate(void) .................................................293.2.5 mtouch_button_deviation_t MTOUCH_Button_Deviation_Get(enum

mtouch_button_names button) ..............................................................293.2.6 mtouch_button_reading_t MTOUCH_Button_Reading_Get(enum

mtouch_button_names button) ..............................................................293.2.7 mtouch_button_reading_t MTOUCH_Button_Baseline_Get(enum

mtouch_button_names button) ..............................................................293.2.8 mtouch_button_scaling_t MTOUCH_Button_Scaling_Get(enum

mtouch_button_names button) ..............................................................293.2.9 void MTOUCH_Button_Scaling_Set(enum mtouch_button_names button,

mtouch_button_scaling_t scaling) ..........................................................293.2.10 mtouch_button_threshold_t MTOUCH_Button_Threshold_Get(enum

mtouch_button_names button) ..............................................................303.2.11 void MTOUCH_Button_Threshold_Set(enum mtouch_button_names

button, mtouch_button_threshold_t threshold) ......................................303.2.12 bool MTOUCH_Button_isPressed(enum mtouch_button_names button)

................................................................................................................303.2.13 mtouch_buttonmask_t MTOUCH_Button_Buttonmask_Get(void) ..........303.2.14 void MTOUCH_Button_SetPressedCallback(void (*callback)(enum

mtouch_button_names button)) .............................................................303.2.15 void MTOUCH_Button_SetNotPressedCallback(void (*callback)(enum

mtouch_button_names button)) .............................................................30

3.3 mTouch® Proximity Module .......................................................................... 303.3.1 void MTOUCH_Proximity_Initialize(enum mtouch_proximity_names prox)

...............................................................................................................303.3.2 void MTOUCH_Proximity_Service(enum mtouch_proximity_names prox)

................................................................................................................303.3.3 void MTOUCH_Proximity_Tick(void) ........................................................303.3.4 void MTOUCH_Proximity_Recalibrate(void) .............................................303.3.5 mtouch_prox_deviation_t MTOUCH_Proximity_Deviation_Get(enum

mtouch_proximity_names prox) .............................................................313.3.6 mtouch_prox_reading_t MTOUCH_Proximity_Reading_Get(enum

mtouch_proximity_names prox) .............................................................31

DS40001852A-page 5 2016 Microchip Technology Inc.

Page 6: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

Table of Contents

3.3.7 mtouch_prox_reading_t MTOUCH_Proximity_Baseline_Get(enum mtouch_proximity_names prox) ............................................................ 31

3.3.8 mtouch_prox_scaling_t MTOUCH_Proximity_Scaling_Get(enum mtouch_proximity_names prox) ............................................................ 31

3.3.9 void MTOUCH_Proximity_Scaling_Set(enum mtouch_proximity_names prox, mtouch_prox_scaling_t scaling) ................................................... 31

3.3.10 mtouch_prox_threshold_t MTOUCH_Proximity_Threshold_Get(enum mtouch_proximity_names prox) ............................................................ 31

3.3.11 void MTOUCH_Proximity_Threshold_Set(enum mtouch_proximity_names prox, mtouch_prox_threshold_t threshold) ............................................ 31

3.3.12 bool MTOUCH_Proximity_isPressed(enum mtouch_proximity_names prox) ...................................................................................................... 31

3.3.13 void MTOUCH_Proximity_SetActivatedCallback(void (*callback)(enum mtouch_proximity_names prox)) ........................................................... 32

3.3.14 void MTOUCH_Proximity_SetNotActivatedCallback(void (*callback)(enum mtouch_proximity_names prox)) ........................................................... 32

Chapter 4. Quick Setup for an mTouch® Library Project4.1 Setting Up the mTouch® Library Project ...................................................... 344.2 Adding the ADC, mTouch Hardware Sensor and mTouch Tx Guard Pins ... 354.3 Adding a Button and Proximity Sensor ......................................................... 364.4 Setting up MyButton ..................................................................................... 374.5 Setting up Proximity Sensor ......................................................................... 374.6 Configure Interrupt ....................................................................................... 384.7 Generating Code .......................................................................................... 384.8 Add Code to the Application’s Main Loop .................................................... 384.9 Use APIs to Get Button/Proximity State ....................................................... 39

4.9.1 Polling method ........................................................................................... 394.9.2 Callback Function ...................................................................................... 40

4.10 Use EUSART to Output Data ..................................................................... 414.10.1 Setting up the EUSART Module .............................................................. 414.10.2 Setting up the Code ................................................................................. 41

Worldwide Sales and Service .................................................................................... 42

2016 Microchip Technology Inc. DS40001852A-page 6

Page 7: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

NOTES:

DS40001852A-page 7 2016 Microchip Technology Inc.

Page 8: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® CAPACITIVE SENSING LIBRARYMODULE FOR MPLAB® X CODE CONFIGURATOR

USER’S GUIDE

Preface

INTRODUCTION

This chapter contains general information that will be useful to know before using the mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator. Items discussed in this chapter include:

• Document Layout

• Conventions Used in this Guide

• This manual uses the following documentation conventions:

• Recommended Reading

• The Microchip Website

• Development Systems Customer Change Notification Service

• Customer Support

• Revision History

DOCUMENT LAYOUT

This document describes how to use the mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator as a development tool to emulate and debug firmware on a target board, as well as how to program devices. The document is organized as follows:

• Chapter 1. “Overview” – Describes the purpose of the mTouch Capacitive Sensing module and library.

• Chapter 2. “mTouch® Capacitive Sensing Library Module” – Introduces the layout and options for the mTouch module in MCC.

• Chapter 3. “mTouch® Library Module API” – Describes the details of the mTouch library APIs.

• Chapter 4. “Quick Setup for an mTouch® Library Project” – Demonstrates an example of setting up a project using the mTouch library module.

NOTICE TO CUSTOMERS

All documentation becomes dated, and this manual is no exception. Microchip tools and documentation are constantly evolving to meet customer needs, so some actual dialogs and/or tool descriptions may differ from those in this document. Please refer to our website (www.microchip.com) to obtain the latest documentation available.

Documents are identified with a “DS” number. This number is located on the bottom of each page, in front of the page number. The numbering convention for the DS number is “DSXXXXXA”, where “XXXXX” is the document number and “A” is the revision level of the document.

For the most up-to-date information on development tools, see the MPLAB® IDE online help. Select the Help menu, and then Topics to open a list of available online help files.

2016 Microchip Technology Inc. DS40001852A-page 8

Page 9: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

CONVENTIONS USED IN THIS GUIDE

This manual uses the following documentation conventions:

DOCUMENTATION CONVENTIONS

Description Represents Examples

Arial font:

Italic characters Referenced books MPLAB® IDE User’s Guide

Emphasized text ...is the only compiler...

Initial caps A window the Output window

A dialog the Settings dialog

A menu selection select Enable Programmer

Quotes A field name in a window or dialog

“Save project before build”

Underlined, italic text with right angle bracket

A menu path File>Save

Bold characters A dialog button Click OK

A tab Click the Power tab

N‘Rnnnn A number in verilog format, where N is the total number of digits, R is the radix and n is a digit.

4‘b0010, 2‘hF1

Text in angle brackets < > A key on the keyboard Press <Enter>, <F1>

Courier New font:

Plain Courier New Sample source code #define START

Filenames autoexec.bat

File paths c:\mcc18\h

Keywords _asm, _endasm, static

Command-line options -Opa+, -Opa-

Bit values 0, 1

Constants 0xFF, ‘A’

Italic Courier New A variable argument file.o, where file can be any valid filename

Square brackets [ ] Optional arguments mcc18 [options] file [options]

Curly brackets and pipe character: { | }

Choice of mutually exclusive arguments; an OR selection

errorlevel {0|1}

Ellipses... Replaces repeated text var_name [, var_name...]

Represents code supplied by user

void main (void){ ...}

DS40001852A-page 9 2016 Microchip Technology Inc.

Page 10: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

Preface

RECOMMENDED READING

This user’s guide describes how to use the mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator. Other useful documents are listed below. The following Microchip documents are available and recommended as supplemental reference resources.

“MPLAB® Code Configurator v3.xx” User’s Guide (DS40001829)

This user’s guide provides detailed information about the MPLAB® Code Configurator v3.xx.

For further resources on MCC, refer to:

www.microchip.com/mplab/mplab-code-configurator

THE MICROCHIP WEBSITE

Microchip provides online support via our website at www.microchip.com. This website is used as a means to make files and information easily available to customers. Acces-sible by using your favorite Internet browser, the website contains the following infor-mation:

• Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software

• General Technical Support – Frequently Asked Questions (FAQs), technical support requests, online discussion groups, Microchip consultant program member listing

• Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives

2016 Microchip Technology Inc. DS40001852A-page 10

Page 11: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

DEVELOPMENT SYSTEMS CUSTOMER CHANGE NOTIFICATION SERVICE

Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest.

To register, access the Microchip website at www.microchip.com, click on Customer Change Notification and follow the registration instructions.

The Development Systems product group categories are:

• Compilers – The latest information on Microchip C compilers, assemblers, linkers and other language tools. These include all MPLAB C compilers; all MPLAB assemblers (including MPASM™ assembler); all MPLAB linkers (including MPLINK™ object linker); and all MPLAB librarians (including MPLIB™ object librarian).

• Emulators – The latest information on Microchip in-circuit emulators.This includes the MPLAB REAL ICE™ and MPLAB ICE 2000 in-circuit emulators.

• In-Circuit Debuggers – The latest information on the Microchip in-circuit debuggers. This includes MPLAB ICD 3 in-circuit debuggers and PICkit™ 3 debug express.

• MPLAB® IDE – The latest information on Microchip MPLAB IDE, the Windows® Integrated Development Environment for development systems tools. This list is focused on the MPLAB IDE, MPLAB IDE Project Manager, MPLAB Editor and MPLAB SIM simulator, as well as general editing and debugging features.

• Programmers – The latest information on Microchip programmers. These include production programmers such as MPLAB REAL ICE in-circuit emulator, MPLAB ICD 3 in-circuit debugger and MPLAB PM3 device programmers. Also included are nonproduction development programmers such as PICSTART® Plus and PICkit 2 and 3.

DS40001852A-page 11 2016 Microchip Technology Inc.

Page 12: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

Preface

CUSTOMER SUPPORT

Users of Microchip products can receive assistance through several channels:

• Distributor or Representative

• Local Sales Office

• Field Application Engineer (FAE)

• Technical Support

Customers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document.

Technical support is available through the website at:

http://www.microchip.com/support.

REVISION HISTORY

Revision A (June 2016)

This is the initial release of this document.

2016 Microchip Technology Inc. DS40001852A-page 12

Page 13: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

NOTES:

DS40001852A-page 13 2016 Microchip Technology Inc.

Page 14: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® CAPACITIVE SENSING LIBRARY

MODULE FOR MPLAB® X CODE CONFIGURATOR

USER’S GUIDE

Chapter 1. Overview

1.1 INTRODUCTION

The mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator allowsfor quick and easy C code generation of Microchip’s Capacitive Touch button and Proximitysensor solutions.

This library module uses a Graphical User Interface (GUI) to accomplish the following:

• Setting multiple mTouch parameters

• Enabling various mTouch features

• Generating the necessary C code to program onto a PIC® microcontroller

The following chapters of this user’s guide cover each component of the mTouch librarymodule and how to setup a basic mTouch project. Contact your local mTouch representativefor additional information or any questions you may have.

2016 Microchip Technology Inc. DS40001852A-page 14

Page 15: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

NOTES:

DS40001852A-page 15 2016 Microchip Technology Inc.

Page 16: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® CAPACITIVE SENSING LIBRARY

MODULE FOR MPLAB® X CODE CONFIGURATOR

USER’S GUIDE

Chapter 2. mTouch® Capacitive Sensing Library Module

®

FIGURE 2-1: mTouch CAPACITIVE SENSING LIBRARY MODULE

The mTouch® Capacitive Sensing Library module (Figure 2-1) is split into two sections:

• Buttons and Proximity Configuration

• Automatic Frequency Adaptation (AFA)

2016 Microchip Technology Inc. DS40001852A-page 16

Page 17: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

2.1 BUTTONS AND PROXIMITY CONFIGURATION

FIGURE 2-2: mTouch® PROJECT WITH TWO BUTTONS AND A PROXIMITY SENSOR

The Button and Proximity Configuration section (Figure 2-2) contains six areas which are accessed by clicking on the items found on the left tree. The six sections are:

1. Common Button Settings

2. Individual Button Settings

3. Common Proximity Sensor Settings

4. Individual Proximity Sensor Settings

5. Hardware Sensor Settings

6. Individual Hardware Sensor Settings

The following sub-chapters provide details about the contents of each area.

DS40001852A-page 17 2016 Microchip Technology Inc.

Page 18: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module

2.1.1 Common Button Configuration Overview

FIGURE 2-3: COMMON BUTTON SETTINGS

The Common Button Settings area (Figure 2-3) consists of five sub-areas:

1. Create New Button

2. Interface Method

3. Press Timeout

4. Negative Capacitance Recovery

5. Baseline Filtering

The following sub-chapters provide details about each sub-area.

2.1.1.1 CREATE NEW BUTTON

The Create New Button tab in the Common Button Settings area allows for the creation of an additional button for the mTouch project. When a new button is created, the default name will be Button#, where # will be the lowest number not currently used.

2.1.1.2 INTERFACE METHOD

The mTouch library allows user’s application code to obtain button status in two ways:

• Callback function

• Polling

The callback function method is more efficient than the polling method, but requires additional code space.

Note: The polling method will be available in both options for easy access to the button status.

2016 Microchip Technology Inc. DS40001852A-page 18

Page 19: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

2.1.1.3 PRESS TIMEOUT

The Press Timeout is a mechanism used to release a stuck button. If a button is pressed for a number of consecutive counts, the button’s state will be reset. Each button has its own time-out counter to track the press time.

Time Unit

The underlying press time-out counter will increment each time the MTOUCH_Service_Mainloop() call is performed.

Counts

The counts parameter acts as a threshold to each button’s press time-out counter. Upon the press time-out’s counter exceeding the counts value, the button state will be reset.

2.1.1.4 NEGATIVE CAPACITANCE RECOVERY

Enabling this feature will allow the quick recovery of a button’s baseline if negative capacitance is detected. The negative capacitance means the baseline value is greater than the reading for a button.

Consecutive Decodes

The consecutive decodes parameter specifies the number of consecutive decoding cycles (MTOUCH_Service_Mainloop() call) with negative capacitance that the program has to detect, before resetting the button’s state.

2.1.1.5 BASELINE FILTERING

The baseline of a touch button is the output of a conditionally low-pass filter, and the input of this low pass filter is the button’s raw reading. This allows the baseline to track and react to environmental changes such as temperature and humidity. Upon a button entering a pressed state the baseline will stop updating until released.

Gain

The filter gain parameter determines the baseline filtering strength. The larger the value, the stronger the filter gets, and the more slowly the baseline follows the button reading value.

Update

The update parameter determines how often the system will update the button’s baseline. The larger the value, the less often the system updates the baseline.

DS40001852A-page 19 2016 Microchip Technology Inc.

Page 20: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module

2.1.2 Individual Button Configuration Overview

FIGURE 2-4: INDIVIDUAL BUTTON SETTINGS

Each button for an mTouch project receives its own unique settings page. The button’s page (Figure 2-4) consists of five items:

1. Delete the button from the project

2. Name of the button

3. Hardware sensor the button is connected to

4. Threshold for the button

5. Deviation scaling

The following sub-sections provide further details about each component of a button.

2.1.2.1 DELETE ITEM

This button will delete the selected button from the mTouch project. The Delete button is useful when too many buttons have been added to the project and the selected button needs to be removed.

2.1.2.2 NAME

This input field allows users to modify the name of the selected button. An example can be the Play button on a media control panel project. This button can be renamed from Button0 to Play.

2.1.2.3 SENSOR

This selection box allows users to select a hardware sensor to be associated with this button. A hardware sensor can be associated with multiple buttons or proximity sensors. For example, if the user wants to achieve proximity detection and touch detection on the same physical sensor, this sensor can be associated with a button and a proximity sensor.

2016 Microchip Technology Inc. DS40001852A-page 20

Page 21: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

2.1.2.4 THRESHOLD

The signal deviation is defined as the difference between a button’s reading and the baseline value. The threshold input field allows users to determine the threshold value for signal deviation before the button will be in pressed state.

2.1.2.5 DEVIATION SCALING

The signal deviation will be scaled down from a signed 16-bit integer to a signed 8-bit. If the deviation after scaling down is greater than 127, then the value will be clipped to 127 (0x7F). The deviation scaling parameter controls how many bits will shift to the right. The smaller the value is, the more sensitive the button will get. The goal is to shift the scaled-down deviation to be a value between 64 and 127 when the button is pressed, in order to get the full dynamic range.

DS40001852A-page 21 2016 Microchip Technology Inc.

Page 22: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module

2.1.3 Common Proximity Sensor Configuration Overview

FIGURE 2-5: COMMON PROXIMITY SENSOR SETTINGS

The Common Proximity Senor Settings area (Figure 2-5) consists of five sub-areas:

1. Create a new proximity sensor

2. Interface Method

3. Activity Timeout

4. Negative Capacitance Recovery

5. Baseline Filtering

The following sub-sections provide details about each component.

2.1.3.1 CREATE NEW PROXIMITY SENSOR

The Create New Proximity Sensor in the Common Proximity Sensor Settings area allows for the creation of an additional proximity sensor for the mTouch project. When a new proximity sensor is created, the default name will be Proximity#, where # will be the lowest number not currently used.

2016 Microchip Technology Inc. DS40001852A-page 22

Page 23: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

2.1.3.2 THE INTERFACE METHOD

The mTouch library allows the user’s application code to obtain proximity sensor status in two ways:

• Callback function

• Polling

The callback function method is more efficient than the polling method, but requires additional code space.

2.1.3.3 ACTIVITY TIMEOUT

The Activity Timeout is a mechanism used to release a stuck proximity sensor. If a proximity sensor is pressed for a number of consecutive counts, the proximity sensor’s state will be reset. Each proximity sensor has its own time-out counter to track the press time.

Time Unit

The underlying activity time-out counter will increment each time the MTOUCH_Service_Mainloop() call is performed.

Counts

The counts parameter acts as a threshold to each proximity sensor’s activity time-out counter. Upon the activity time-out’s counter exceeding the counts value, the proximity sensor’s state will be reset.

2.1.3.4 NEGATIVE CAPACITANCE RECOVERY

Enabling this feature will allow the quick recovery of a bad baseline if negative capacitance is detected. The negative capacitance means the baseline value is greater than the reading for a proximity sensor.

Consecutive Decodes

The consecutive decodes parameter specifies the number of consecutive decoding cycles (MTOUCH_Service_Mainloop() call) with negative capacitance that the program has to detect, before resetting the proximity sensor state.

2.1.3.5 BASELINE FILTERING

The baseline of a proximity sensor is the output of a conditionally low-pass filter, and the input of this low-pass filter is the proximity sensor’s raw reading. This allows the baseline to track environmental changes, such as temperature and humidity. Upon a proximity sensor entering an activated state, the baseline will stop updating until released.

Gain

The filter gain parameter determines the baseline filtering strength. The larger the value, the stronger the filter gets, and the more slowly the baseline follows the button reading value.

Update

The update parameter determines how often the system will update the proximity sensor’s baseline. The larger the value, the less often the system updates the baseline.

Note: The polling method will be available in both options for easy access to the proximity sensor status.

DS40001852A-page 23 2016 Microchip Technology Inc.

Page 24: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module

2.1.4 Individual Proximity Sensor Configuration Overview

FIGURE 2-6: INDIVIDUAL PROXIMITY SENSOR SETTINGS

Each proximity sensor for an mTouch project receives its own unique settings page (Figure 2-6). The page consists of five items:

1. Delete the proximity sensor from the project

2. Name of the proximity sensor

3. Hardware sensor the proximity sensor is connected to

4. Threshold for the proximity sensor

5. Deviation Scaling

The following sub-sections provide greater detail about each component of a proximity sensor.

2.1.4.1 DELETE ITEM

This button will delete the selected proximity sensor from the mTouch project. The Delete button is useful when too many proximity sensors have been added to the project, and the selected proximity sensor needs to be removed.

2.1.4.2 NAME

This input field allows users to modify the name of the selected proximity sensor. Users can rename the field to something meaningful for their application.

2.1.4.3 SENSOR

This selection box allows users to select a hardware sensor to be associated with this proximity sensor. A hardware sensor may be associated with multiple buttons or proximity sensors.

2.1.4.4 THRESHOLD

The signal deviation for proximity sensor is defined as the difference between a proximity sensor’s reading and its baseline value. To get better sensitivity, the signal deviation is integrated through a low-pass filter and then compared with the threshold value to determine if the proximity sensor will be in an activated state.

2016 Microchip Technology Inc. DS40001852A-page 24

Page 25: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

2.1.4.5 DEVIATION SCALING

Similarly with a button, the smaller the value, the more sensitive the proximity sensor gets.

2.1.5 Hardware Sensor Configuration Overview

FIGURE 2-7: COMMON HARDWARE SENSOR SETTINGS

The Common Hardware Sensor Settings area (Figure 2-7) consists of two items. The first item is displaying the dedicated Tx guard pin, if one has been selected for the project. The other item is to determine the order each hardware sensor will be scanned. To change the scan order of a hardware sensor, first highlight the sensor to move in the Scan Order field list. The next step is to press the Up or Down buttons to change the hardware sensors’ order. The first item in the list will be scanned first, while the last item in the list is scanned last.

DS40001852A-page 25 2016 Microchip Technology Inc.

Page 26: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module

2.1.6 Individual Hardware Sensor Configuration Overview

FIGURE 2-8: INDIVIDUAL HARDWARE SENSOR SETTINGS

Each hardware sensor receives its own settings page which displays the name of the hardware sensor and the pin the hardware sensor is attached to. The following sub-sections provide greater detail on these two components, as shown in Figure 2-8 above.

2.1.6.1 NAME

This input field allows the user to modify the name of the selected hardware sensor. The user might want to add the package pin number for easy reference to the hardware.

2.1.6.2 PIN

This field allows users to always see which pin the hardware sensor is connected to.

2016 Microchip Technology Inc. DS40001852A-page 26

Page 27: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

2.2 AFA (AUTOMATIC FREQUENCY ADAPTATION)

FIGURE 2-9: AFA SETTINGS

The Automatic Frequency Adaptation (AFA) section (Figure 2-9) allows users to enable the advanced noise immunity algorithm. The automatic frequency adaptation routine continuously tracks the amount of noise that is on each sensor, and chooses a new scan frequency intelligently. The routine requires an 8-bit timer to precisely control the scanning frequency. Due to this requirement, mTouch will take ownership of the first available 8-bit timer module, if one is available, when the automatic frequency adaptation routine is enabled. The following sub-sections provide greater detail about the two components of the AFA section.

2.2.1 Enabled AFA

This check-box determines if the automatic frequency adaptation logic will be included when code is generated for the project. The AFA requires extra Flash and RAM memory so this feature may not work with RAM limited controllers.

2.2.2 AFA Filter Timer

This selection box determines which of the available 8-bit timers will be used for the automatic frequency adaptation logic. When a selection is made, the 8-bit timer will be owned by the mTouch library module. This means the timer will no longer be available from the timer peripheral module list. The user will need to enable the timer interrupt in the interrupt manager, as shown in Figure 2-10 below.

FIGURE 2-10: ENABLE TIMER INTERRUPT

DS40001852A-page 27 2016 Microchip Technology Inc.

Page 28: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® CAPACITIVE SENSING LIBRARY

MODULE FOR MPLAB® X CODE CONFIGURATOR

USER’S GUIDE

Chapter 3. mTouch® Library Module API

® ®

The mTouch library is customized and generated by the MPLAB X Code Configurator’s Graphical User Interface (GUI). The generated library will be responsible for signal acquisition, noise handling and button/proximity sensor decoding. An application will use the API provided by the mTouch library to obtain button and proximity sensor information. The following sections explain the APIs from sensor, button and proximity modules.

3.1 mTouch® SENSOR MODULE

The mTouch sensor module’s API provides low-level access to the hardware sensor.

3.1.1 enum mtouch_sensor_error MTOUCH_Sensor_Initialize(enum mtouch_sensor_names sensor)

This API function initializes the assigned hardware sensor pin.

3.1.2 enum mtouch_sensor_error MTOUCH_Sensor_Service(enum mtouch_sensor_names sensor)

This API function starts scanning the assigned sensor.

3.1.3 bool MTOUCH_Sensor_wasSampled(enum mtouch_sensor_names sensor)

This API function is used to check if the sensor has been scanned. The sampled status can only be cleared by calling MTOUCH_Sensor_Sampled_Reset().

3.1.4 void MTOUCH_Sensor_Sampled_Reset(void)

This API function is used to clear the sampled status for all the hardware sensors.

3.1.5 void MTOUCH_Sensor_SetSampledCallback(void (*callback)(enum mtouch_sensor_names sensor))

This API function is used to set the callback function that will be called immediately after a sensor has been scanned.

3.1.6 mtouch_sensor_sample_t MTOUCH_Sensor_RawSample_Get(enum mtouch_sensor_names sensor)

This API function is used to get the oversampled sensor reading from the ADC. It is useful if the user wants to implement their own high-level decoding, such as humidity sensor, liquid level sensor, etc.

2016 Microchip Technology Inc. DS40001852A-page 28

Page 29: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

3.2 mTouch® BUTTON MODULE

The mTouch button module’s API provides access to button data and status information.

3.2.1 void MTOUCH_Button_Initialize(enum mtouch_button_names button)

This API function is used to initialize the assigned button.

3.2.2 void MTOUCH_Button_Service(enum mtouch_button_names button)

This API function is used to service the assigned button, such as determining the button’s status. This function should be called after the associated hardware sensor has been sampled.

3.2.3 void MTOUCH_Button_Tick(void)

This API function is used to increment the pressed time-out counter.

3.2.4 void MTOUCH_Button_Recalibrate(void)

This API function is used to reset and recalibrate all buttons.

3.2.5 mtouch_button_deviation_t MTOUCH_Button_Deviation_Get(enum mtouch_button_names button)

This API function is used to get the signal deviation of the assigned button.

3.2.6 mtouch_button_reading_t MTOUCH_Button_Reading_Get(enum mtouch_button_names button)

This API function is used to get the reading of the assigned button.

3.2.7 mtouch_button_reading_t MTOUCH_Button_Baseline_Get(enum mtouch_button_names button)

This API function is used to get the baseline of the assigned button.

3.2.8 mtouch_button_scaling_t MTOUCH_Button_Scaling_Get(enum mtouch_button_names button)

This API function is used to get the scaling factor of the assigned button.

3.2.9 void MTOUCH_Button_Scaling_Set(enum mtouch_button_names button, mtouch_button_scaling_t scaling)

This API function is used to set the scaling factor of the assigned button.

Note: The scaling factor set using this API will be lost after a power cycle. The scaling factor’s permanent value may be changed through the MPLAB® X Code Configurator mentioned in Section 2.1.2.5 “Deviation Scaling” or through the initialization code prior to compiling

DS40001852A-page 29 2016 Microchip Technology Inc.

Page 30: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Library Module API

3.2.10 mtouch_button_threshold_t MTOUCH_Button_Threshold_Get(enum mtouch_button_names button)

This API function is used to get the deviation threshold of the assigned button.

3.2.11 void MTOUCH_Button_Threshold_Set(enum mtouch_button_names button, mtouch_button_threshold_t threshold)

This API function is used to set the deviation threshold of the assigned button. Similar to the MTOUCH_Button_Scaling_Set function, this change of threshold is only temporary.

3.2.12 bool MTOUCH_Button_isPressed(enum mtouch_button_names button)

This API function is used to get the current button state of the assigned button.

3.2.13 mtouch_buttonmask_t MTOUCH_Button_Buttonmask_Get(void)

This API function is used to get the current button state of all buttons.

3.2.14 void MTOUCH_Button_SetPressedCallback(void (*callback)(enum mtouch_button_names button))

This API function is used to set the user’s callback function for a button press event.

3.2.15 void MTOUCH_Button_SetNotPressedCallback(void (*callback)(enum mtouch_button_names button))

This API function is used to set the user’s callback function for a button release event.

3.3 mTouch® PROXIMITY MODULE

The mTouch proximity module API provides access to proximity sensor data and status information.

3.3.1 void MTOUCH_Proximity_Initialize(enum mtouch_proximity_names prox)

This API function is used to initialize the assigned proximity sensor.

3.3.2 void MTOUCH_Proximity_Service(enum mtouch_proximity_names prox)

This API function is used to service the assigned proximity sensor, such as determining its status. This function should be called after the associated sensor has been sampled.

3.3.3 void MTOUCH_Proximity_Tick(void)

This API function is used to increment the activation time-out counter.

3.3.4 void MTOUCH_Proximity_Recalibrate(void)

This API function is used to reset and recalibrate all proximity sensors.

2016 Microchip Technology Inc. DS40001852A-page 30

Page 31: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

3.3.5 mtouch_prox_deviation_t MTOUCH_Proximity_Deviation_Get(enum mtouch_proximity_names prox)

This API function is used to get the signal deviation of the assigned proximity sensor.

3.3.6 mtouch_prox_reading_t MTOUCH_Proximity_Reading_Get(enum mtouch_proximity_names prox)

This API function is used to get the reading of the assigned proximity sensor.

3.3.7 mtouch_prox_reading_t MTOUCH_Proximity_Baseline_Get(enum mtouch_proximity_names prox)

This API function is used to get the baseline of the assigned proximity sensor.

3.3.8 mtouch_prox_scaling_t MTOUCH_Proximity_Scaling_Get(enum mtouch_proximity_names prox)

This API function is used to get the scaling factor of the assigned proximity sensor.

3.3.9 void MTOUCH_Proximity_Scaling_Set(enum mtouch_proximity_names prox, mtouch_prox_scaling_t scaling)

This API function is used to set the scaling factor of the assigned proximity sensor.

3.3.10 mtouch_prox_threshold_t MTOUCH_Proximity_Threshold_Get(enum mtouch_proximity_names prox)

This API function is used to get the deviation threshold of the assigned proximity sensor.

3.3.11 void MTOUCH_Proximity_Threshold_Set(enum mtouch_proximity_names prox, mtouch_prox_threshold_t threshold)

This API function is used to set the deviation threshold of the assigned proximity sensor. Similar to the MTOUCH_Proximity_Scaling_Set function, this change of threshold is only temporary.

3.3.12 bool MTOUCH_Proximity_isPressed(enum mtouch_proximity_names prox)

This API function is used to get the current state of the assigned proximity sensor.

Note: The scaling factor that is set by using this function will be lost after a power cycle. The scaling factor’s permanent value may be changed through the MPLAB® X Code Configurator or through the initialization code prior to compiling.

DS40001852A-page 31 2016 Microchip Technology Inc.

Page 32: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Library Module API

3.3.13 void MTOUCH_Proximity_SetActivatedCallback(void (*callback)(enum mtouch_proximity_names prox))

This API function is used to set the user’s callback function for a proximity activation event.

3.3.14 void MTOUCH_Proximity_SetNotActivatedCallback(void (*callback)(enum mtouch_proximity_names prox))

This API function is used to set the user’s callback function for a proximity release event.

2016 Microchip Technology Inc. DS40001852A-page 32

Page 33: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

NOTES:

DS40001852A-page 33 2016 Microchip Technology Inc.

Page 34: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® CAPACITIVE SENSING LIBRARY

MODULE FOR MPLAB® X CODE CONFIGURATOR

USER’S GUIDE

Chapter 4. Quick Setup for an mTouch® Library Project

This chapter provides step-by-step instruction for creating and programming a basic mTouch® project onto a PIC® microcontroller. A PIC16F1619 is used for this example project, but the same steps will work with most mTouch compatible PIC microcontrollers. This example project includes the following:

• One button called MyButton

• One proximity sensor called MyProximity

• An ADC pin enabled

• AFA enabled

The button and proximity sensor also have to use separate hardware sensors.

4.1 SETTING UP THE mTouch® LIBRARY PROJECT

The first step of a MCC configuration is setting up the system module, as shown in Figure 4-1. For optimal performance, a fast system clock is recommended. In this example, the system clock is set to 32 MHz.

FIGURE 4-1: SYSTEM MODULE SETTING

The next step for this example project is to add the ADC and the mTouch library module to the Project Resources area, as indicated in Figure 4-2.

FIGURE 4-2: PROJECT RESOURCES

2016 Microchip Technology Inc. DS40001852A-page 34

Page 35: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

FIGURE 4-3: ADC PERIPHERAL MODULE IN DEVICE RESOURCES

To add the ADC module, navigate to the ADC item in the Device Resources panel, as shown in Figure 4-3 above. Click ADC such that the arrow to the left points downward. Select the ADC that does not have an arrow next to the ADC text. After the ADC has been selected it will be removed from the Device Resources list and it will be added into the Project Resources list. The center pane should also display the ADC module.

FIGURE 4-4: mTouch® LIBRARY MODULE IN DEVICE RESOURCES

The final part of this step is to add the mTouch library module. Navigate to the mTouch item in the Device Resources panel, as indicated in Figure 4-4. At this point, double clicking mTouch will add it to the Project Resources. The next step is enabling all of the pins for the example project.

4.2 ADDING THE ADC, mTouch HARDWARE SENSOR AND mTouch TX GUARD PINS

FIGURE 4-5: COMPLETED PIN MAPPER FOR mTouch® PROJECT

The above diagram in Figure 4-5 displays the completed pin layout for this example project. The following components need to be enabled: three ADC pins, two mTouch hardware sensor pins and an mTouch Tx guard pin.

The first step is to enable the ADC pins for this project. For this example, pins RA1, RA4 and RC0 will be used. To enable the ADC pins, click on the respective lock that is in the unlocked position. When clicked, the blue lock will switch to a green background and the icon will be in a locked position. When an icon has a green background and a locked icon it indicates the pin is enabled.

DS40001852A-page 35 2016 Microchip Technology Inc.

Page 36: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

Quick Setup for an mTouch® Library Project

After enabling the first ADC pin the mTouch module will appear in the Pin Mapper pane with a row called Sensor. After RA1 and RA4 have been enabled for the ADC module lock, the respective mTouch sensor pins will be enabled as well. After locking the mTouch sensor pins there will be a chain icon displayed instead of the locked icon. The chain icon means that two modules have linked ownership with the pin’s functionality.

Upon linking the two mTouch hardware sensors with ADC pins, it is time to assign a TX guard pin. The Tx guard assists in boosting the amount of signal for buttons and proximity sensors. For this example project the Tx guard will be assigned to pin RB6. After the PIC microcontroller’s pins are setup correctly, it is time to add the single button and single proximity sensor to the project.

4.3 ADDING A BUTTON AND PROXIMITY SENSOR

The next step for the mTouch project example is to create a button and proximity sensor. The mTouch module needs to be shown in the center pane. If another module is currently shown, go into the Project Resources area and click on the mTouch library module. Figure 4-6 shows how to add a new button. The Button and Proximity Configuration section needs to be expanded and the Common Button Settings pane needs to be displayed. Once the Common Button Settings pane is shown, click Create New Button in the upper right corner. After this button has been clicked, a Button0 will appear in the mTouch tree. To add a new proximity sensor, go to the Common Proximity Sensor Settings pane and click the Create New Proximity Sensor button. Upon completing this set the project will now have one button and one proximity sensor. The next steps involve setting up the button and proximity sensor.

FIGURE 4-6: ADDING A NEW BUTTON

2016 Microchip Technology Inc. DS40001852A-page 36

Page 37: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

4.4 SETTING UP MyBUTTON

For this project the button is to be renamed “MyButton”. To accomplish this step, click the Button0: No sensor selected in the mTouch tree, as indicated in Figure 4-7. In the Name field for this button’s settings change the text from “Button0” to “MyButton”. For the Sensor selection box select the “Sensor_AN1: RA1 / AN1” option. MyButton is now connected to the hardware sensor on the RA1 / AN1 pin. The next step is to setup the proximity sensor.

FIGURE 4-7: SETUP MyBUTTON

4.5 SETTING UP PROXIMITY SENSOR

For this project, the proximity sensor is to be renamed “MyProximity”. To accomplish this step first, click the “Proximity0: No sensor selected” option in the mTouch tree, as shown in Figure 4-8 below. In the name field for this proximity sensor’s settings change the text from “Proximity0” to “MyProximity”. For the Sensor selection box select the “Sensor_AN3: RA4 / AN3” option. This means MyProximity has been connected to the hardware sensor on the RA4 / AN3 pin.

FIGURE 4-8: SETUP MyPROXIMITY

DS40001852A-page 37 2016 Microchip Technology Inc.

Page 38: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

Quick Setup for an mTouch® Library Project

4.6 CONFIGURE INTERRUPT

FIGURE 4-9: INTERRUPT MODULE

If the AFA feature is enabled, then the interrupt of the selected 8-bit timer also needs to be enabled. To keep the timer’s interrupt as constant as possible, the selected 8-bit timer needs to be the first item in the interrupt vector’s list. Figure 4-9 displays the selected AFA timer as the first item in the interrupt vector list.

4.7 GENERATING CODE

At this point everything in the MPLAB® X Code Configurator’s project is complete. To recap, the mTouch module has a button and a proximity sensor and each of them are connected to a unique hardware sensor, and the AFA feature is enabled. To generate code, click the Generate button above the center pane. After the code has been generated there is one last step before the final code may be compiled and programmed onto the PIC® microcontroller.

4.8 ADD CODE TO THE APPLICATION’S MAIN LOOP

The mTouch routine needs to be continuously called from the main loop, and the globe and peripheral interrupt must be enabled for timer if AFA is enabled, as shown in Figure 4-10 below.

FIGURE 4-10: MAIN FUNCTION

At this point, the mTouch configuration is complete.

2016 Microchip Technology Inc. DS40001852A-page 38

Page 39: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

4.9 USE APIs TO GET BUTTON/PROXIMITY STATE

There are two ways to get the button/proximity sensor state:

• Polling Method

• Callback Function

4.9.1 Polling method

The mTouch button/proximity sensor provides the API to get the state for a particular button/proximity sensor. Users can call this API at any time to obtain the state, as shown in Figure 4-11 below.

FIGURE 4-11: POLLING BUTTON0’S STATE

DS40001852A-page 39 2016 Microchip Technology Inc.

Page 40: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

Quick Setup for an mTouch® Library Project

4.9.2 Callback Function

The callback function method requires the users to create a function to handle the press/touch event, and then pass the function pointer to the callback setter function, as shown in Figure 4-12 below.

FIGURE 4-12: CALLBACK FUNCTION TO HANDLE BUTTON PRESS EVENT

2016 Microchip Technology Inc. DS40001852A-page 40

Page 41: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

mTouch® Capacitive Sensing Library Module for MPLAB® X Code Configurator User’s Guide

4.10 USE EUSART TO OUTPUT DATA

It is always recommended to monitor the mTouch data in real-time for parameter tuning. In this example, a EUSART-based debugging interface will be used.

4.10.1 Setting up the EUSART Module

The first step is to load the EUSART module from the device resources, selecting Asynchronous mode. The MPLAB XC8 compiler has implemented the printf as a library function to format string and send to a destination. To use the printf function and send the string to EUSART, the EUSART module needs to be redirected to STDIO, as shown in Figure 4-13 below.

FIGURE 4-13: SETTING UP THE EUSART MODULE

4.10.2 Setting up the Code

Once the EUSART code is generated, the user will be able to output any variables and mTouch data as ASCII format via the serial communication interface. Any terminal software (HpyerTerm, CoolTerm) will be able to display the data in real-time on a PC. In this example, the deviation of MyButton and MyProximity will be output onto the EUSART TX pin.

FIGURE 4-14: OUTPUT MYBUTTON AND MYPROXIMITY DATA THROUGH EUSART

DS40001852A-page 41 2016 Microchip Technology Inc.

Page 42: mTouch Capacitive Sensing Library Module for MPLAB X Code ...ww1.microchip.com/downloads/en/DeviceDoc/40001852A.pdf · mTouch® CAPACITIVE SENSING LIBRARY MODULE FOR MPLAB® X CODE

2016 Microchip Technology Inc. DS40001852A-page 42

AMERICASCorporate Office2355 West Chandler Blvd.Chandler, AZ 85224-6199Tel: 480-792-7200 Fax: 480-792-7277Technical Support: http://www.microchip.com/supportWeb Address: www.microchip.com

AtlantaDuluth, GA Tel: 678-957-9614 Fax: 678-957-1455

Austin, TXTel: 512-257-3370

BostonWestborough, MA Tel: 774-760-0087 Fax: 774-760-0088

ChicagoItasca, IL Tel: 630-285-0071 Fax: 630-285-0075

ClevelandIndependence, OH Tel: 216-447-0464 Fax: 216-447-0643

DallasAddison, TX Tel: 972-818-7423 Fax: 972-818-2924

DetroitNovi, MI Tel: 248-848-4000

Houston, TX Tel: 281-894-5983

IndianapolisNoblesville, IN Tel: 317-773-8323Fax: 317-773-5453

Los AngelesMission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608

New York, NY Tel: 631-435-6000

San Jose, CA Tel: 408-735-9110

Canada - TorontoTel: 905-695-1980 Fax: 905-695-2078

ASIA/PACIFICAsia Pacific OfficeSuites 3707-14, 37th FloorTower 6, The GatewayHarbour City, Kowloon

Hong KongTel: 852-2943-5100Fax: 852-2401-3431

Australia - SydneyTel: 61-2-9868-6733Fax: 61-2-9868-6755

China - BeijingTel: 86-10-8569-7000 Fax: 86-10-8528-2104

China - ChengduTel: 86-28-8665-5511Fax: 86-28-8665-7889

China - ChongqingTel: 86-23-8980-9588Fax: 86-23-8980-9500

China - DongguanTel: 86-769-8702-9880

China - GuangzhouTel: 86-20-8755-8029

China - HangzhouTel: 86-571-8792-8115 Fax: 86-571-8792-8116

China - Hong Kong SARTel: 852-2943-5100 Fax: 852-2401-3431

China - NanjingTel: 86-25-8473-2460Fax: 86-25-8473-2470

China - QingdaoTel: 86-532-8502-7355Fax: 86-532-8502-7205

China - ShanghaiTel: 86-21-5407-5533 Fax: 86-21-5407-5066

China - ShenyangTel: 86-24-2334-2829Fax: 86-24-2334-2393

China - ShenzhenTel: 86-755-8864-2200 Fax: 86-755-8203-1760

China - WuhanTel: 86-27-5980-5300Fax: 86-27-5980-5118

China - XianTel: 86-29-8833-7252Fax: 86-29-8833-7256

ASIA/PACIFICChina - XiamenTel: 86-592-2388138 Fax: 86-592-2388130

China - ZhuhaiTel: 86-756-3210040 Fax: 86-756-3210049

India - BangaloreTel: 91-80-3090-4444 Fax: 91-80-3090-4123

India - New DelhiTel: 91-11-4160-8631Fax: 91-11-4160-8632

India - PuneTel: 91-20-3019-1500

Japan - OsakaTel: 81-6-6152-7160 Fax: 81-6-6152-9310

Japan - TokyoTel: 81-3-6880- 3770 Fax: 81-3-6880-3771

Korea - DaeguTel: 82-53-744-4301Fax: 82-53-744-4302

Korea - SeoulTel: 82-2-554-7200Fax: 82-2-558-5932 or 82-2-558-5934

Malaysia - Kuala LumpurTel: 60-3-6201-9857Fax: 60-3-6201-9859

Malaysia - PenangTel: 60-4-227-8870Fax: 60-4-227-4068

Philippines - ManilaTel: 63-2-634-9065Fax: 63-2-634-9069

SingaporeTel: 65-6334-8870Fax: 65-6334-8850

Taiwan - Hsin ChuTel: 886-3-5778-366Fax: 886-3-5770-955

Taiwan - KaohsiungTel: 886-7-213-7828

Taiwan - TaipeiTel: 886-2-2508-8600 Fax: 886-2-2508-0102

Thailand - BangkokTel: 66-2-694-1351Fax: 66-2-694-1350

EUROPEAustria - WelsTel: 43-7242-2244-39Fax: 43-7242-2244-393

Denmark - CopenhagenTel: 45-4450-2828 Fax: 45-4485-2829

France - ParisTel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79

Germany - DusseldorfTel: 49-2129-3766400

Germany - KarlsruheTel: 49-721-625370

Germany - MunichTel: 49-89-627-144-0 Fax: 49-89-627-144-44

Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781

Italy - VeniceTel: 39-049-7625286

Netherlands - DrunenTel: 31-416-690399 Fax: 31-416-690340

Poland - WarsawTel: 48-22-3325737

Spain - MadridTel: 34-91-708-08-90Fax: 34-91-708-08-91

Sweden - StockholmTel: 46-8-5090-4654

UK - WokinghamTel: 44-118-921-5800Fax: 44-118-921-5820

Worldwide Sales and Service

06/23/16