 |
CAPSENSE™ Middleware Library 5.0
|
|
CAPSENSE™ Middleware Library 5.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 CSD, CSX, and ISX 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, fifth-generation and fifth-generation LP of CAPSENSE™ HW. CAPSENSE™ HW enables the multiple sensing capabilities on PSoC™ devices including the Self-Capacitance (CSD) and Mutual-Capacitance (CSX) capacitive touch sensing solutions, inductive sensing (ISX), 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 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 Infineon 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 MSCLP/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 | 3.2 |
| - ModusToolbox™ Device Configurator tool | 4.20 |
| - ModusToolbox™ MSC Superblock Personality for PSoC™ 4 devices in the Device Configurator tool | 1.0 |
| - ModusToolbox™ MSC Personality for PSoC™ 4 devices in the Device Configurator tool | 1.1 |
| - ModusToolbox™ MSCLP Personality for PSoC™ 4 devices in the Device Configurator tool | 3.0 |
| - ModusToolbox™ CSD Personality for PSoC™ 4 devices in the Device Configurator tool | 2.0 |
| - ModusToolbox™ CSD Personality for PSoC™ 6 devices in the Device Configurator tool | 3.0 |
| - ModusToolbox™ CAPSENSE™ Configurator tool | 6.20 |
| - ModusToolbox™ CAPSENSE™ Tuner tool | 6.10 |
| CAT1 Peripheral Driver Library (PDL) | 3.3.1 |
| CAT2 Peripheral Driver Library (PDL) | 2.5.0 |
| GCC Compiler | 11.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: | < 6.0 kB | < 8.8 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.9 kB | < 0.8 kB | < 0.8 kB | < 1.1 kB | < 1.8 kB | < 0.7 kB | < 2.4 kB | |||
| 5th Gen | IntDrv | AMUX | Flash: | < 8.0 kB | < 10.4 kB | < 11.8 kB | < 7.9 kB | < 9.3 kB | < 10.1 kB | < 11.2 kB | < 12.0 kB | < 15.0 kB |
| SRAM: | < 1.1 kB | < 1.3 kB | < 1.4 kB | < 1.3 kB | < 1.3 kB | < 1.7 kB | < 2.4 kB | < 1.7 kB | < 3.3 kB | |||
| CTRL_MUX | Flash: | < 7.6 kB | < 10.7 kB | < 11.4 kB | < 7.4 kB | < 9.2 kB | < 9.8 kB | < 10.9 kB | < 11.9 kB | < 14.8 kB | ||
| SRAM: | < 1.1 kB | < 1.3 kB | < 1.4 kB | < 1.3 kB | < 1.3 kB | < 1.7 kB | < 2.4 kB | < 1.7 kB | < 3.3 kB | |||
| DMA | CTRL_MUX | Flash: | < 7.9 kB | < 11.3 kB | < 12.1 kB | < 8.0 kB | < 9.8 kB | < 10.4 kB | < 11.5 kB | < 12.0 kB | < 15.4 kB | |
| SRAM: | < 1.4 kB | < 1.6 kB | < 1.7 kB | < 2.2 kB | < 2.2 kB | < 2.7 kB | < 3.3 kB | < 2.1 kB | < 5.4 kB | |||
| 5th Gen Low Power | LP-AOS | AMUX | Flash: | < 7.5 kB | < 10.8 kB | < 11.3 kB | < 7.4 kB | < 9.2 kB | < 9.6 kB | < 11.1 kB | < 11.3 kB | < 14.4 kB |
| SRAM: | < 1.4 kB | < 1.6 kB | < 1.7 kB | < 2.1 kB | < 2.1 kB | < 2.6 kB | < 3.1 kB | < 1.8 kB | < 5.1 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.4 | A conversion should not be performed between a pointer to object and an integer type. | Advisory. There is an issue with a SYSCLK driver (IFXID-10550), due to which integer type is cast to an object pointer type. Code is manually checked and reviewed to be safe. |
| 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 |
|---|---|---|
| 5.0 | This version is not backward compatible with the previous version due to re-designed CDAC Auto-calibration. We tried to keep the established API, but your design may need to be updated to operate with CAPSENSE™ middleware v5.0. Also, if you use the CAPSENSE&trade middleware v5.0, you must use the CAPSENSE&trade Configurator v6.20 tool or later. This MW version is not compatible with the previous Configurator tool versions. | |
| Re-designed CDAC Auto-calibration algorithm for the fifth-generation LP devices | Feature enhancement | |
| Added auto selection mode of CIC2 decimation rate for the fifth-generation LP devices | Feature enhancement | |
| Added Auto-selection mode of CDAC Dither scale value for the fifth-generation and fifth-generation LP devices | Feature enhancement | |
| Added the HW IIR Filter initialization function Cy_CapSense_ScanInitializeHwIirAllSlots() and Cy_CapSense_ScanInitializeHwIirSlots() for fifth-generation LP devices | Feature enhancement | |
| Corrected the low power widget scanning flow by excluding waking up at a signal detection - only the end of the frame interrupt is kept. Condition: multiple low power sensors. This will avoid multiple interrupt generation and in some cases prevent the device from hanging. | Defect fixing | |
| Corrected description of the cy_stc_capsense_position_t structure | Defect fixing | |
| Removed Epilogue cycles from the maximum Raw Counts definition | Defect fixing | |
| Hidden a Multi-phase Self feature for fifth-generation LP devices | Defect fixing | |
| Disabled the External Frame Start in the Cy_CapSense_InitializeMaxRaw() function for the fifth-generation devices | Defect fixing | |
| Corrected description of the BIST measurement function | Defect fixing | |
| Corrected description of the cy_stc_capsense_touch_t structure | Defect fixing | |
| Updated description of the software watchdog time calculation for the fifth-generation devices | Defect fixing | |
| 4.0 | This version is not backward compatible with the previous version due to fifth-generation LP devices support implementation and defect fixes. We tried to keep the established API, but your design may need to be updated to operate with CAPSENSE™ middleware v4.0. | |
| Added CAPSENSE™ fifth-generation LP device support | Feature enhancement | |
| Added the Inductive sensing method support (ISX) | Feature enhancement | |
| Added the feature of enabling/disabling widgets and built-in self-test working/non-working widgets | Feature enhancement | |
| Added Multi-phase Self support for fifth-generation LP devices | Feature enhancement | |
| Updated the CIC2 functionality for the fifth-generation devices to be consistent with the fifth-generation LP devices. | Feature enhancement | |
| Added saturated scan during CAPSENSE™ initialization to measure maximum rawcounts precisely instead of using equations. | Feature enhancement | |
| Changed the meaning of bit[2] of the widget status register in the cy_stc_capsense_widget_context_t: logical 1 means the widget is enabled. Replaced CY_CAPSENSE_WD_DISABLE_MASK with CY_CAPSENSE_WD_ENABLE_MASK for consistency | Defect fixing | |
| Swapped the position of bit[0] and bit[1] of the sensor status register in the cy_stc_capsense_sensor_context_t: bit[0] reports the Proximity sensor status, bit[1] - the regular sensor status. Updated values of CY_CAPSENSE_SNS_PROX_STATUS_MASK and CY_CAPSENSE_SNS_TOUCH_STATUS_MASK macros. | Defect fixing | |
| Renamed cy_stc_active_scan_sns_t to cy_stc_capsense_active_scan_sns_t. | Following naming convention. Defect fixing | |
| Renamed cy_stc_msc_channel_config_t to cy_stc_capsense_channel_config_t, updated field names | Following naming convention. Updated for consistency between fifth-generation and fifth-generation LP devices | |
| Renamed Cy_CapSense_ProcessWidgetMptxDeconvolution() to Cy_CapSense_ProcessWidgetMpDeconvolution() | Updated function name to better reflect its purpose | |
| Renamed Cy_CapSense_SetCalibrationTargets() to Cy_CapSense_SetCalibrationTarget(), updated function interface and implementation to cover all sensing methods. | Feature enhancement. | |
| Fixed incorrect shield pins configuration for Cy_CapSense_MeasureCapacitanceSensor() function for fourth-generation devices | Defect fixing | |
| Updater measurement error handling for Cy_CapSense_MeasureCapacitanceShieldElectrode(), Cy_CapSense_MeasureCapacitanceSlotSensors() and Cy_CapSense_MeasureCapacitanceSensorElectrode() functions for fifth-generation devices | Defect fixing | |
| Optimized cy_stc_capsense_common_config_t structure (renamed fields, removed unused fields) | User experience improvement | |
| Added Long Press gesture | Feature enhancement | |
| 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. Infineon Technologies highly recommends starting with these documents. They can be found on the Infineon Technologies web site at www.infineon.com.
For more information, refer to the following documents: