CAPSENSE™ Middleware Library 3.0
CAPSENSE™ Middleware Library 3.0

CAPSENSE™ is a CYPRESS™ capacitive sensing solution from Infineon.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 CAPSENSE™ middleware Library supports operation with fourth-generation and fifth-generation of CAPSENSE™ HW. CAPSENSE™ HW enables multiple sensing capabilities on PSoC™ devices including the self-cap (CSD) and mutual-cap (CSX) capacitive touch sensing solutions, inductive sensing, impedance measurement, and other features.

Middleware access available the CAPSENSE™ HW block through the corresponding peripheral Driver:

  • CSD (CAPSENSE™ Sigma-Delta) driver for the forth-generation of the CAPSENSE™ HW;
  • MSC (Multi-Sensor Converter) driver for the fifth-generation of the CAPSENSE™ HW;

The CAPSENSE™ peripheral driver does not provide any system-level functions. It only implements the interface to the CAPSENSE™ HW resource.

The supported CAPSENSE™ HW blocks can perform only one function at a time. However, all supported functionality (like CAPSENSE™, CSDADC, 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 the CSDADC middleware, perform CSDADC measurements, and then switch back to the CAPSENSE™ functionality. For 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 the CAPSENSE™ middleware. Refer to the corresponding sections of documentation for other middleware supported by the CAPSENSE™ HW.

A CAPSENSE™ solution includes:

  • The CAPSENSE™ Configurator to create and configure CAPSENSE™ widgets. It can be launched in ModusToolbox™ from the CAPSENSE™ superblock personality and in Stand-alone 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
  • 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

The quickest way to get started with CAPSENSE™ is using code examples. Infineon Technologies continuously extends their portfolio of code examples at the Infineon Technologies and at the Infineon Technologies GitHub. The following are the links to code examples for different PSoC™ families presented on GitHub.

Code Examples for PSoC™ 4 Devices with fourth-generation CAPSENSE™

Code Examples for PSoC™ 4 Devices with fifth-generation CAPSENSE™

Code Examples for PSoC™ 6 Devices with fourth-generation CAPSENSE™

The CAPSENSE™ middleware can be used in various development environments such as ModusToolbox™, MBED, etc. Refer to the Supported Software and Tools. The following are the configuration considerations for the different environments.

ModusToolbox™ Configuration Considerations

This quick start guide assumes that the environment is configured:

Note
Ensure to set up the device power voltages correctly to the proper operation of the device power domains. The Setup is on the System Tab of the Device Configurator. Enable the Power check box and set up the voltages as they are red-outlined in the picture below.
check_power.png
Power Setup

MBED OS Configuration Considerations

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_all();

Summary of Application Programming Interface (API)

The CAPSENSE™ middleware operates on the top of the MSC/CSD HW 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.4
- ModusToolbox™ Device Configurator 3.10.0
- ModusToolbox™ MSC Superblock Personality for for PSoC™ 4 devices in the Device Configurator 1.0
- ModusToolbox™ MSC Personality for PSoC™ 4 devices in the Device Configurator 1.1
- ModusToolbox™ CSD Personality for PSoC™ 4 devices in the Device Configurator 1.1
- ModusToolbox™ CSD Personality for PSoC™ 6 devices in the Device Configurator 2.0
- ModusToolbox™ CAPSENSE™ Configurator tool 4.0.0
- ModusToolbox™ CAPSENSE™ Tuner tool 4.0.0
CAT1 Peripheral Driver Library (PDL) 2.3.0
CAT2 Peripheral Driver Library (PDL) 1.4.0
GCC Compiler 9.3.1
IAR Compiler 8.42.1
Arm Compiler 6 (Note 1) 6.13
MBED OS (only for PSoC™ 6) 5.15.8
FreeRTOS 10.4.5

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 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 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:ModeSensor Connection TypeMemory TypeConfiguration 1Configuration 2Configuration 3Configuration 4Configuration 5Configuration 6Configuration 7Configuration 8Configuration 9
4th GenIntDrvAMUXFlash:< 5.9 kB< 8.5 kB< 11.7 kB< 5.5 kB < 6.8 kB< 7.8 kB< 9.1 kB< 9.4 kB< 18.7 kB
SRAM:< 0.6 kB< 0.8 kB< 0.8 kB< 0.8 kB< 0.8 kB< 1.1 kB< 1.8 kB< 0.7 kB< 2.4 kB
5th GenIntDrvAMUXFlash:< 7.3 kB< 10.3 kB< 11.5 kB< 7.4 kB < 8.8 kB< 9.9 kB< 11.0 kB< 11.3 kB< 15.0 kB
SRAM:< 1.1 kB< 1.2 kB< 1.1 kB< 1.3 kB< 1.3 kB< 1.7 kB< 2.3 kB< 1.7 kB< 3.3 kB
CTRL_MUXFlash:Flash memory consumption 1000 bytes higher then CTRL_MUX - DMA
SRAM:SRAM memory consumption is the same as in CTRL_MUX - DMA
DMACTRL_MUXFlash:< 7.7 kB< 11.0 kB< 11.1 kB< 7.8 kB< 9.6 kB< 10.2 kB< 11.4 kB< 11.7 kB< 15.4 kB
SRAM:< 1.3 kB< 1.5 kB< 1.4 kB< 2.1 kB< 2.1 kB< 2.6 kB< 3.3 kB< 2.1 kB< 5.4 kB
Widgets
CSD Button3(10 sensors)3(10 sensors)3(10 sensors)    1(1 sensor)1(1 sensor)
CSD Matrix Buttons         
CSD Slider         
CSD Touchpad       1(8x8)1(8x8)
CSD Proximity         
CSX Button         
CSX Matrix Buttons   1(4x8)1(4x8)    
CSX Touchpad     1(9x4)1(9x4) 1(8x8)
Features
Gesture         
Ballistic Multiplier         
Centroid Type         
Supported fingers on touchpad         
Shield       enabledenabled
SmartSense enabled       
CSD auto-calibration         
CSX auto-calibration    enabled    
Self-test  enabled      
Raw Count Filters
IIR      enabledenabledenabled
Median      enabled  
Average      enabled  
Position Filters
IIR      enabled  
Median      enabled  
Average      enabled  
Adaptive IIR      enabled  
Jitter      enabled  
Note
  • To select values for the Scan mode and Sensor connection method parameters (for the fifth-generation of the CAPSENSE™ HW) navigate to the Advanced tab in the CAPSENSE™ Configurator tool, and then select the General settings sub-tab.
  • For the forth-generation of the CAPSENSE™ HW, the IntDrv mode with the AMUX sensor connection type is available only.

MISRA-C:2012 Compliance

This page describes MISRA-C:2012 compliance and deviations for the CAPSENSE™ middleware.

MISRA stands for Motor Industry Software Reliability Association. The MISRA specification covers a set of 10 mandatory rules, 110 required rules and 39 advisory rules that apply to firmware design and has been put together by the Automotive Industry to enhance the quality and robustness of the firmware code embedded in automotive devices.

CAPSENSE™ Middleware Deviation

Rule ID Rule Description Description of Deviation(s)
Directive 4.8 If a pointer to a structure or union is never dereferenced within a translation unit, then the implementation of the object should be hidden. Advisory. The middleware library consists of several modules. One of them is CapSense Data Structure. All communication between the other modules is performed through CapSense Data Structure.
Rule 2.3 A project should not contain unused type declarations. Advisory. The middleware library provides API to the hardware. The type is part of API, which is defined for application-level only.
Rule 2.5 A project should not contain unused macro declarations. Advisory. The middleware library provides API to the hardware. The macro is part of API, which is defined for application-level only.
Rule 5.1 External identifiers shall be distinct. Toolchains from Supported Software and Tools documentation section are verified to work with functions, names of which have similar first 31 symbols.
Rule 5.4 Macro identifiers shall be distinct. Toolchains from Supported Software and Tools documentation section are verified to work with macros, names of which have similar first 31 symbols.
Rule 5.6 A typedef name shall be a unique identifier. During the code analysis, the same source files are compiled multiple times with device-specific options. All typedef names are unique for each specific run.
Rule 5.8 Identifiers that define objects or functions with external linkage shall be unique. During the code analysis, the same source files are compiled multiple times with device-specific options. All object and function identifiers are unique for each specific run.
Rule 5.9 Identifiers that define objects or functions with internal linkage should be unique. Advisory. During the code analysis, the same source files are compiled multiple times with device-specific options. All object and function identifiers are unique for each specific run.
Rule 8.3 All declarations of an object or function shall use the same names and type qualifiers. During the code analysis, the same source files are compiled multiple times with device-specific options. All object and function identifiers are unique for each specific run.
Rule 8.5 An external object or function shall be declared once in one and only one file. During the code analysis, the same source files are compiled multiple times with device-specific options. All object and function identifiers are unique for each specific run.
Rule 8.6 An identifier with external linkage shall have exactly one external definition. During the code analysis, the same source files are compiled multiple times with device-specific options. All object and function identifiers are unique for each specific run.
Rule 8.7 Functions and objects should not be defined with external linkage if they are referenced in only one translation unit. Advisory. During the code analysis, the same source files are compiled multiple times with device-specific options. All object and function identifiers are unique for each specific run.
Rule 8.13 A pointer should point to const-qualified type whenever possible. Advisory. During the code analysis, the same source files are compiled multiple times with device-specific options. A function argument can be const for some specific run.
Rule 11.5 A conversion should not be performed from pointer to void into pointer to object. Advisory. The cast from void pointer to an object pointer does not have any unintended effect, as it is a consequence of the definition of a structure based on function pointers.
Rule 14.2 A for loop shall be well-formed. The third clause of the for loop is empty to improve execution time.
Rule 18.4 The +, -, += and -= operators should not be applied to an expression of pointer type. Advisory. There are several instances of pointer arithmetic in drivers. They cannot be avoided, so are manually checked and reviewed to be safe.

CAPSENSE™ Configurator Generated Sources Deviation

Rule ID Rule Description Description of Deviation(s)
Rule 3.1 The character sequences / * and / / shall not be used within a comment. Using of the special comment symbols is need for Doxygen comment support, it does not have any impact on functionality.
Rule 8.4 A compatible declaration shall be visible when an object or function with external linkage is defined. The CAPSENSE™ middleware library consists of several modules. One of them is CapSense Built-in Self Test (BIST). All the BIST variables are used in other data structures and accessed using pointers.
Rule 11.4 A conversion should not be performed between a pointer to object and an integer type. Advisory. There are several instances of pointer conversions in Generated Source. They are manually checked and reviewed to be safe.

Errata

This section lists the known problems with the CAPSENSE™ middleware.

IDKnown IssueWorkaround
319100 GPIO simultaneous operation with unrestricted strength and frequency creates noise that can affect CAPSENSE™ operation. This issue is applicable for the fourth CAPSENSE™ generation devices. For detail, refer to the errata section of the device datasheet.
3159 Scanning a sensor with low capacitance (about 8pF and less) with low frequency (around 300kHz and less) might lead to raw count variation from scan to scan. This issue is applicable for the fourth CAPSENSE™ generation devices. There are several possible workarounds:
  1. Increase the Scan resolution.
  2. Increase the Sense clock frequency. For the best results, perform scanning with as high as possible Sense clock frequency.
  3. If shield is required for a design, enable the shield tank (Csh) capacitor.
  4. Increase the sensor capacitance by changing its layout or introduce extra capacitor between the sensor pin and ground.
  5. Increase number of Fine initialization cycles. Open the cycfg_capsense.c file and modify the .csdFineInitTime field of the cy_capsense_commonConfig structure.
  6. Increase the CSD init switch resistance. Open the cycfg_capsense.c file and update the .csdInitSwRes field of the cy_capsense_commonConfig structure with the CY_CAPSENSE_INIT_SW_RES_HIGH value.

Changelog

VersionChangesReason for Change
3.0

This version is not backward compatible with the previous version due to implemented memory consumption optimization. We tried to keep the established API, but your design may need to be updated to operate with CAPSENSE™ middleware v3.0.

Also, if you use the CAPSENSE™ middleware v3.0 version then you must use the CAPSENSE™ Configurator v4.0 tool or later. This MW version is not compatible with the previous Configurator tool versions.

Added fifth-generation CAPSENSE™ device support which includes but not limited:
  • Scanning mode: DMA and Interrupt Driven
  • Sensor connection method: Analog mux bus and Control mux bus
  • Re-designed multi-frequency scan feature
  • Multi-phase TX feature
  • Improved signal-to-noise ratio
  • Improved refresh rate
New CAPSENSE™ MSC platform covering
The following rows show changes related to fourth-generation CAPSENSE™
Removed usage of deprecated return error and status codes, cy_status enum was replaced with the cy_capsense_status_t variable Defect fixing
Removed usage of deprecated types, such as uint32 and uint16 Defect fixing
Changed the default IDAC gain index for the CSX auto-calibration to the configured one Defect fixing
The following functions were made obsolete:
  • Cy_CapSense_CSDConnectSns()
  • Cy_CapSense_CSDDisconnectSns()
  • Cy_CapSense_CSXConnectRx()
  • Cy_CapSense_CSXConnectTx()
  • Cy_CapSense_CSXDisconnectRx()
  • Cy_CapSense_CSXDisconnectTx()
  • Cy_CapSense_CalibrateAllCsdWidgets()
  • Cy_CapSense_CalibrateAllCsxWidgets()
User experience improvement
For fourth-generation CAPSENSE™ devices callbacks were moved from ptrCommonContext to ptrInternalContext structure User experience improvement
Updated the description of the Cy_CapSense_RunSelfTest() function Documentation defect fixing
Specified measurement units in the following function descriptions: Documentation defect fixing
Added call of the Cy_CapSense_Wakeup() function to the registered callback in the Cy_CapSense_DeepSleepCallback() function Improved robustness of a sensing module
Added a possibility to enable / disable independent features of BIST module Expanded flexibility
2.10 Added Built-in Self-test (BIST) library Support Class B (IEC-60730), safety integrity-level compliant design
Improved the Csh and Cmod coarse initialization functionality. Feature enhancement
Improved the shield performance when Csh is enabled Feature enhancement
Fixed Cy_CapSense_ScanExt() operation Defect fixing
Fixed the bug in the Cy_CapSense_SetPinState() function Defect fixing
Optimized software watch-dog values used in monitoring CAPSENSE™ scanning duration User experience improvement
Improved IDAC auto-calibration Operation accuracy increasing
Added the following functions: Feature enhancement
Changed the type of context argument to const in the following functions:
  • Cy_CapSense_CSDConnectSns()
  • Cy_CapSense_CSXConnectRx()
  • Cy_CapSense_CSXConnectTx()
  • Cy_CapSense_CSXDisconnectRx()
  • Cy_CapSense_CSXDisconnectTx()
  • Cy_CapSense_SetPinState()
Defect fixing
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:

  • Cy_CapSense_CSDSetupWidget()
  • Cy_CapSense_CSDSetupWidgetExt()
  • Cy_CapSense_CSDScan()
  • Cy_CapSense_CSDScanExt()
  • Cy_CapSense_CSDCalibrateWidget()
  • Cy_CapSense_CSXSetupWidget()
  • Cy_CapSense_CSXSetupWidgetExt()
  • Cy_CapSense_CSXScan()
  • Cy_CapSense_CSXScanExt()
  • Cy_CapSense_CSXCalibrateWidget()

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 from Infineon 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 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.