 |
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:
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:
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.
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:
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.
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.
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.
This quick start guide assumes that the environment is configured:
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:
and call the resource initialization functions in main() at the beginning:
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:
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:
To operate in custom environments with Arm Compiler 6, apply the above mentioned build options.
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:
You might need to re-generate the configuration structures for either the device initialization code or the middleware initialization code.
The CAPSENSE™ middleware Flash and RAM memory consumption varies:
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: | Mode | Sensor Connection Type | Memory Type | Configuration 1 | Configuration 2 | Configuration 3 | Configuration 4 | Configuration 5 | Configuration 6 | Configuration 7 | Configuration 8 | Configuration 9 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4th Gen | IntDrv | AMUX | Flash: | < 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 Gen | IntDrv | AMUX | Flash: | < 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_MUX | Flash: | Flash memory consumption 1000 bytes higher then CTRL_MUX - DMA | ||||||||||
| SRAM: | SRAM memory consumption is the same as in CTRL_MUX - DMA | |||||||||||
| DMA | CTRL_MUX | Flash: | < 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 Button | 3(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 | enabled | enabled | ||||||||||
| SmartSense | enabled | |||||||||||
| CSD auto-calibration | ||||||||||||
| CSX auto-calibration | enabled | |||||||||||
| Self-test | enabled | |||||||||||
| Raw Count Filters | ||||||||||||
| IIR | enabled | enabled | enabled | |||||||||
| Median | enabled | |||||||||||
| Average | enabled | |||||||||||
| Position Filters | ||||||||||||
| IIR | enabled | |||||||||||
| Median | enabled | |||||||||||
| Average | enabled | |||||||||||
| Adaptive IIR | enabled | |||||||||||
| Jitter | enabled | |||||||||||
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.
| 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. |
| 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. |
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. 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:
|
| Version | Changes | Reason 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:
| 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:
| 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:
| 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:
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 | |
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: