CapSense Middleware Library

group index

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 MSCv3 HW block enables multiple sensing capabilities on PSoC devices including the self-cap and mutual-cap capacitive touch sensing solutions, inductive sensing, impedance measurement, and other features. The MSC driver is a low-level peripheral driver, a wrapper to access the MSCv3 HW block. Middleware access available MSC HW blocks through the MSC Driver.

The MSCv3 HW block can support only one function at a time. However, all supported functionality (like CapSense, IndSense, 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 IndSense middleware, perform IndSense scans, and then switch back to the CapSense functionality. For detail and code examples, refer to the description of the Cy_CapSense_Save() and Cy_CapSense_Restore() functions.

../../../_images/CAPSENSE_SOLUTION_MSC_V31.png

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

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 RM) and Mutual-Capacitance (CSX RM) ratio metric 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

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.

ModusToolbox Quick Start Guide

This quick start guide assumes that the environment is configured to use the PSoC 4 Peripheral Driver Library(psoc4pdl) for development and the PSoC 4 Peripheral Driver Library(psoc4pdl) 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.

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.

../../../_images/check_power1.png

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

Summary of Application Programming Interface (API)

CapSense operates on the top of the CapSense MSC (Multi-Sensor Converter) 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.2

- ModusToolbox Device Configurator

2.20

- ModusToolbox CapSense Superblock Personality for PSoC4AS4 devices in the Device Configurator

1.0

- ModusToolbox MSC Personality for PSoC4AS4 devices in the Device Configurator

1.0

- ModusToolbox CSD Personality for PSoC6 devices in the Device Configurator

2.0

- ModusToolbox CapSense Configurator tool

3.20

- ModusToolbox CapSense Tuner tool

3.20

CAT1 Peripheral Driver Library (PDL)

1.5.0

CAT2 Peripheral Driver Library (PDL)

1.0.0

GCC Compiler

9.3.1

IAR Compiler

8.42.2

Arm Compiler 6 (Note 1)

6.13

MBED OS (only for PSoC6)

5.15.1

FreeRTOS

10.3.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 MSC 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.

Memory consumption for any custom design/configuration can be determined by analyzing a *.map file generated by the compiler.

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 and MSC Driver API Ref Guide.

20.3

Errata

This section lists the known problems with the CapSense middleware.

ID

Known Issue

Workaround

319100

GPIO simultaneous operation with unrestricted strength and frequency creates noise that can affect CapSense operation.

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.

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_capsernse.c file and update the .csdInitSwRes field of the cy_capsense_commonConfig structure with the CY_CAPSENSE_INIT_SW_RES_HIGH value.

3191

Channel 0 is scanned with the incorrect settings when all of the following conditions are met:

  1. Multi-frequency scan is enabled.

  2. The Cy_CapSense_CSDSetupWidgetExt() function called only once.

  3. The Cy_CapSense_CSDScanExt() function called multiple times.

Call the Cy_CapSense_CSDSetupWidgetExt() function before each call of the Cy_CapSense_CSDScanExt() function.

Changelog

Version

Changes

Reason for Change

3.0

Added fifth CapSense generation device support

New CapSense MSC platform covering

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 CSDv2 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 callbacs were moved from ptrCommonContext to ptrInternalContext structure

User experience improvement

Updated the description of the Cy_CapSense_RunSelfTest() function

Defect fixing

Specified measurement units in the following function descriptions:

Defect fixing

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