Cypress CapSense Middleware Library 2.0
Cypress CapSense Middleware Library

CapSense is a Cypress capacitive sensing solution. Capacitive sensing can be used in a variety of applications and products where conventional mechanical buttons can be replaced with sleek human interfaces to transform the way users interact with electronic systems. These include home appliances, and automotive, IoT, and industrial applications. CapSense supports multiple interfaces (widgets) using both CSX and CSD sensing methods with robust performance.

CapSense has become a popular technology to replace conventional mechanical- and optical-based user interfaces. There are fewer parts involved, which saves cost and increases reliability with no wear-and-tear. The main advantages of CapSense compared with other solutions are: robust performance in harsh environmental conditions and rejection of a wide range of external noise sources.

Use CapSense for:

  • Touch and gesture detection for various interfaces
  • Proximity detection for innovative user experiences and low-power optimization
  • Contactless liquid-level sensing in a variety of applications
  • Touch-free operations in hazardous materials

General Description

The CSD HW block enables multiple sensing capabilities on PSoC devices including self-cap and mutual-cap capacitive touch sensing solution, a 10-bit ADC, IDAC, and Comparator. The CSD driver is a low-level peripheral driver, a wrapper to manage access to the CSD HW block. Each middleware access to the CSD HW block is through the CSD Driver.

The CSD HW block can support only one function at a time. However, all supported functionality (like CapSense, ADC, etc.) can be time-multiplexed in a design. I.e. you can save the existing state of the CapSense middleware, restore the state of the ADC middleware, perform ADC measurements, and then switch back to the CapSense functionality. For more details and code examples refer to the description of the Cy_CapSense_Save() and Cy_CapSense_Restore() functions.

capsense_solution.png
CapSense Solution

This section describes only CapSense middleware. Refer to the corresponding sections for documentation of other middleware supported by the CSD HW block.

A CapSense solution includes:

  • The CapSense Configurator tool, which is a configuration wizard to create and configure CapSense widgets. It could be launched in ModusToolbox from the CSD personality as well as in standalone mode. It contains a separate document about how to create and configure widgets, parameters and algorithm descriptions.
  • API to control the design from the application program. This documentation describes API with code snippets of how to use them.
  • The CapSense Tuner tool for real-time tuning, testing, and debugging, for easy and smooth designing of human interfaces on customer products. The Tuner tool communicates with a device through a HW bridge and communication drivers (EzI2C, UART, etc.) and allows to monitor widget statuses, sensor signals, detected touch positions, gestures, etc. The application program does not need to interact with the CSD driver and/or other drivers such as GPIO, SysClk directly. All of that is configured and managed by middleware.

Include cy_capsense.h to get access to all functions and other declarations in this library. If you are using the ModusToolbox CapSense Configurator tool, you can include cycfg_capsense.h only.

Features

  • Offers best-in-class signal-to-noise ratio (SNR)
  • Supports Self-Capacitance (CSD) and Mutual-Capacitance (CSX) sensing methods
  • Features SmartSense auto-tuning technology for CSD sensing to avoid complex manual tuning process
  • Supports various Widgets, such as Buttons, Matrix Buttons, Sliders, Touchpads, and Proximity Sensors
  • Provides ultra-low power consumption and liquid-tolerant capacitive sensing technology
  • Contains the integrated graphical CapSense Tuner tool for real-time tuning, testing, and debugging
  • Provides superior immunity against external noise and low-radiated emission
  • Offers best-in-class liquid tolerance
  • Supports one-finger and two-finger gestures

Quick Start Guide

Cypress CapSense middleware can be used in various Development Environments such as ModusToolbox, MBED, etc. Refer to the Supported Software and Tools. The quickest way to get started is using the Code Examples. Cypress Semiconductor continuously extends its portfolio of the code examples at the Cypress Semiconductor website and at the Cypress Semiconductor GitHub.

This quick start guide assumes that the environment is configured to use the PSoC 6 Peripheral Driver Library(psoc6pdl) for development and the PSoC 6 Peripheral Driver Library(psoc6pdl) is included in the project. It also assumes the ModusToolbox Device Configurator Tool, ModusToolbox CapSense Configurator Tool, and ModusToolbox CapSense Tuner Tool are installed on your machine.

MBED OS Quick Start Guide

You can immediately start with the following MBED OS code example available at the Cypress Semiconductor GitHub:

If you are doing your own project, remember to include cycfg.h file:

#include "cycfg.h"

and call the resource initialization functions in main() at the beginning:

init_cycfg_clocks();
init_cycfg_routing();
init_cycfg_peripherals();

Summary of Application Programming Interface (API)

The CapSense operates on the top of the CapSense Sigma Delta (CSD) driver. Refer to the PDL API Reference Manual.

This document provides descriptions of the functions in the CapSense middleware library, and descriptions of the data structures (register map) used by the middleware library.

The Application Programming Interface (API) routines allow controlling and executing specific tasks using the CapSense middleware. The CapSense API is described in the following sections:

Supported Software and Tools

This version of the CapSense Middleware was validated for compatibility with the following Software and Tools:

Software and Tools Version
ModusToolbox Software Environment 2.0
- ModusToolbox Device Configurator 2.0
- ModusToolbox CSD Personality in Device Configurator 2.0
- ModusToolbox CapSense Configurator tool 2.0
- ModusToolbox CapSense Tuner tool 2.0
PSoC6 Peripheral Driver Library (PDL) 1.2.0
GCC Compiler 7.2.1
IAR Compiler 8.32
Arm Compiler 6 (Note 1) 6.11
MBED OS 5.13.1
FreeRTOS 10.0.1

Note 1 The CapSense middleware includes the pre-compiled libraries for Arm Compiler 6. They are built with the following options to be compatible with ModusToolbox and MBED:

  • -fshort-enums – Set the size of an enumeration type to the smallest data type that can hold all enumerator values
  • -fshort-wchar - Set the size of wchar_t to 2 bytes

To operate in custom environments with Arm Compiler 6, apply the above mentioned build options.

Update to Newer Versions

Refer to the Changelog to learn about the design impact of the newer version. Set up your environment in accordance with Supported Software and Tools.

Ensure:

  • The specified version of the ModusToolbox Device Configurator and the CSD personality are used to re-generate the device configuration.
  • The specified version of the ModusToolbox CapSense Configurator is used to re-generate the middleware configuration.
  • The toolchains are set up properly for your environment per the settings outlined in the Supported Software and Tools.
  • The project is re-built once the the toolchains are configured and the configuration is completed.

You might need to re-generate the configuration structures for either the device initialization code or the middleware initialization code.

  • Launch the ModusToolbox Device Configurator and perform the File->Save command to re-generate the device initialization code.
  • From the ModusToolbox Device Configurator, launch the ModusToolbox CapSense Configurator and perform the File->Save command to re-generate the middleware initialization code.

Memory Usage

The CapSense middleware Flash and RAM memory consumption varies:

  • marginally - depending on the compiler and device
  • significantly - depending on the project CapSense configuration and number of APIs called by the application program.

The table below provides the middleware total memory consumption for specific CapSense configurations. Memory consumption for any custom design/configuration can be determined by analyzing a *.map file generated by the compiler.

The measurements were done with GCC compiler configured in the Release mode with optimization set for Size.

Configuration:Configuration 1Configuration 2Configuration 3Configuration 4Configuration 5
Flash:
< 12000
< 14050
< 17400
< 18600
< 27000
SRAM:
< 370
< 700
< 2180
< 1050
< 4250
Widgets
CSD Button1 (6 sensors)1 (6 sensors)1 (2 sensors)1 (6 sensors)
CSD Matrix Buttons
CSD Slider1 (9 segments)1 (9 segments)
CSD Touchpad1 (9 Cols and 8 Rows)1 (9 Cols and 8 Rows)
CSD Proximity1 (1 sensor)1 (1 sensor)1 (1 sensor)
CSX Button
CSX Matrix Buttons1 (3 Rx and 3 Tx)
CSX Touchpad1 (9 Rx and 8 Tx)1 (9 Rx and 8 Tx)
Features
Gestureenabledenabledenabled
Ballistic Multiplierenabledenabled
Centroid Type3x33x35x5 CSD, 3x3 CSX
Supported fingers on touchpad212
Shieldenabledenabledenabled
SmartSenseenabled
CSD auto-calibrationenabledenabledenabledenabled
CSX auto-calibrationenabledenabled
Raw Count Filters
IIRenabledenabledenabled
Medianenabledenabledenabled
Average
Position Filters
IIR
Medianenabledenabledenabled
Average
Adaptive IIRenabledenabledenabled
Jitterenabledenabledenabled

MISRA-C Compliance

MISRA Rule Rule Class (Required/Advisory) Rule Description Description of Deviation(s)
11.4 A A conversion should not be performed between a pointer to object and an integer type. Such conversion is performed with CapSense context in two cases: interrupt handler and DeepSleepCallback function. Both cases are verified on correct operation.
12.13 A The increment (++) and decrement (–) operators should not be mixed with other operators in an expression. These violations are reported for the GCC ARM optimized form of the "for" loop that have the following syntax: for(index = COUNT; index –> 0u;) It is used to improve performance.
1.2 R Constant: Dereference of NULL pointer. These violations are reported as a result of using of offset macros of CSD Driver with corresponding documented violation 20.6. Refer to CSD Driver API Ref Guide.
20.3

Errata

This section lists the known problems with the CapSense middleware.

Cypress IDKnown IssueWorkaround
319100 GPIO simultaneous operation with unrestricted strength and frequency creates noise that can affect CapSense operation. Refer to the errata section of the device datasheet for details.
PSoC 63 with BLE Datasheet Programmable System-on-Chip

Changelog

VersionChangesReason for Change
2.0 Added memory usage section to the CapSense API Ref Guide User experience improvement
Updated documentation User experience improvement
Added the errata section to the CapSense API Ref Guide User experience improvement
CapSense MW sources are enclosed with the conditional compilation to ensure a successful compilation for non-CapSense-capable devices Fixing a compilation error for non CapSense-capable devices
Optimized flash memory consumption based on user's configuration Flash foot-print optimization
Renamed function Cy_CapSense_CheckCommandIntegrity() to Cy_CapSense_CheckTunerCmdIntegrity() User experience improvement
1.20 Added Arm Compiler 6 support Feature enhancement
Changed the hierarchy of the binary files folders MBED OS compatibility
1.1

The following functions made obsolete:

Two simple functions introduced to replace the listed above functions:

User experience improvement
Fixed the shield operation when Csh is disabled Defect fixing
Fixed the implementation of the position filtering for the Radial Slider widget Defect fixing
Added restoring hardware to its default state in the Cy_CapSense_DeInit() implementation Defect fixing
Added the capability to enable the shield electrode without dedicated electrodes Feature enhancement
Added support of a protocol-agnostic tuner interface (UART, SPI, etc.) Feature enhancement
1.0 The initial version

More Information

Important information about the CapSense-technology overview, appropriate Cypress device for the design, CapSense system and sensor design guidelines, different interfaces and tuning guidelines necessary for a successful design of a CapSense system is available in the Getting Started with CapSense document and the product-specific CapSense design guide. Cypress highly recommends starting with these documents. They can be found on the Cypress web site at www.cypress.com. For details about application notes, code examples, and kits, see the References section in this datasheet.

For more information, refer to the following documents:

Note
The links to another software component’s documentation (middleware and PDL) point to GitHub to the latest available version of the software. To get documentation of the specified version, download from GitHub and unzip the component archive. The documentation is available in the docs folder.