# Low-level Functions¶

group group_capsense_low_level

The Low-level functions represent the lower layer of abstraction in support of High-level Functions.

These functions also enable implementation of special case designs requiring performance optimization and non-typical functionalities.

All functions are general to all sensing methods. Some of the functions detect the sensing method used by the widget and execute tasks as appropriate.

Functions

cy_capsense_status_t Cy_CapSense_ProcessWidgetExt(uint32_t widgetId, uint32_t mode, cy_stc_capsense_context_t *context)

Performs customized data processing on the selected widget.

This function performs customized data processing specified by the mode parameter on a widget. This function can be used with any of the available scan functions. This function should be called only after all the sensors in the specified widget are scanned. Calling this function multiple times with the same mode without new sensor scan causes unexpected behavior. This function ignores the value of the wdgtEnable register.

The CY_CAPSENSE_PROCESS_CALC_NOISE and CY_CAPSENSE_PROCESS_THRESHOLDS masks for mode parameter are supported only when SmartSense is enabled for CSD widgets.

The execution order of processing tasks starts from LSB to MSB of the mode parameter. To implement a different order of execution, call this function multiple times with the required mode parameter.

For more details, refer to function usage example below.

An example of customized data processing, changed processing order:


/*...*/
/* Standard execution order (SmartSense is disabled):
* - Filtering
* - Baselining
* - Difference calculation
* - Status / Position calculation
*
* An example below makes a different order:
* - filtering is executed as a last task
*/
CY_CAPSENSE_PROCESS_BASELINE |
CY_CAPSENSE_PROCESS_DIFFCOUNTS |
CY_CAPSENSE_PROCESS_STATUS,
&cy_capsense_context);
CY_CAPSENSE_PROCESS_FILTER,
&cy_capsense_context);
/*...*/

Return

Returns the status of the widget processing operation:

• CY_CAPSENSE_STATUS_SUCCESS - The processing is successfully performed.

• CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.

• CY_CAPSENSE_STATUS_BAD_DATA - The processing failed.

Function Usage

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• mode: Specifies the type of widget processing to be executed for the specified widget:

1. Bits [31..6] - Reserved.

2. Bits [5..0] - CY_CAPSENSE_PROCESS_ALL - Execute all of the below tasks.

3. Bit [5] - CY_CAPSENSE_PROCESS_STATUS - Update the status (on/off, centroid position).

4. Bit [4] - CY_CAPSENSE_PROCESS_THRESHOLDS - Update the thresholds (only in CSD auto-tuning mode).

5. Bit [3] - CY_CAPSENSE_PROCESS_CALC_NOISE - Calculate the noise (only in CSD auto-tuning mode).

6. Bit [2] - CY_CAPSENSE_PROCESS_DIFFCOUNTS - Update the difference counts of each sensor.

7. Bit [1] - CY_CAPSENSE_PROCESS_BASELINE - Update the baselines for all sensor.

8. Bit [0] - CY_CAPSENSE_PROCESS_FILTER - Run the firmware filters on sensor rawcounts.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_ProcessSensorExt(uint32_t widgetId, uint32_t sensorId, uint32_t mode, const cy_stc_capsense_context_t *context)

Performs customized data processing on the selected sensor.

This function performs customized data processing specified by the mode parameter on a sensor. This function performs the exact same task of the Cy_CapSense_ProcessWidgetExt() function but only on the specified sensor instead of all sensors in the widget.

The pipeline scan method (i.e. during scanning of a sensor, processing of a previously scanned sensor is performed) can be implemented using this function and it may reduce the total scan/process time, increase the refresh rate, and decrease the power consumption. For more details, refer to function usage example below.

note

This function does not perform raw count deconvolition for widgets with multi-phase Tx. The Cy_CapSense_ProcessWidgetMptxDeconvolution() function must be called manually from application layer before data processing perfomed by this function.

An example demonstrates pipeline implementation of sensor scanning and processing:


/*...*/
snsIndex = 0u;

for(;;)
{
if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
{
snsIndex++;
{

}
else
{
/* The last sensor is scanned already */
/* All sensors processed, therefore process only widget-related task */
/* Reset sensor index to start from the first sensor */
snsIndex = 0u;
}
}
}
/*...*/

Return

Returns the status of the sensor process operation:

• CY_CAPSENSE_STATUS_SUCCESS - The processing is successfully performed.

• CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.

• CY_CAPSENSE_STATUS_BAD_DATA - The processing failed.

Function Usage

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• sensorId: Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.

• mode: Specifies the type of the sensor processing that must be executed for the specified sensor:

1. Bits [31..5] - Reserved

2. Bits [4..0] - CY_CAPSENSE_PROCESS_ALL - Executes all the tasks

3. Bit [4] - CY_CAPSENSE_PROCESS_THRESHOLDS - Updates the thresholds (only in auto-tuning mode)

4. Bit [3] - CY_CAPSENSE_PROCESS_CALC_NOISE - Calculates the noise (only in auto-tuning mode)

5. Bit [2] - CY_CAPSENSE_PROCESS_DIFFCOUNTS - Updates the diff count

6. Bit [1] - CY_CAPSENSE_PROCESS_BASELINE - Updates the baseline

7. Bit [0] - CY_CAPSENSE_PROCESS_FILTER - Runs the firmware filters

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

void Cy_CapSense_InitializeAllBaselines(cy_stc_capsense_context_t *context)

Initializes the baselines of all the sensors of all the widgets.

This function initializes baselines for all sensors and widgets in the project. It can also be used to re-initialize baselines at any time, however, note that all sensor data history information and sensor status shall be reset along with re-initialization of baseline.

Following functions to initialize sensor and widgets and filter history should be called after initializing baseline for proper operation of the CapSense middleware:

These functions are called by the CapSense_Enable() function, hence it is not required to use this function if above function is used.

Parameters

void Cy_CapSense_InitializeWidgetBaseline(uint32_t widgetId, cy_stc_capsense_context_t *context)

Initializes the baselines of all the sensors in a specific widget.

This function initializes baselines for all sensors in a specific widget in the project. It can also be used to re-initialize baselines at any time, however, note that all sensor data history information and sensor status should be reset along with re-initialization of baseline.

The following functions to initialize sensor and widgets and filter history should be called after initializing baselines for proper operation of middleware.

These functions are called by CapSense_Enable() function, hence it is not required to use this function is above function is used.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

void Cy_CapSense_InitializeSensorBaseline(uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context)

Initializes the baseline of a sensor in a widget specified by the input parameters.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• sensorId: Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

void Cy_CapSense_InitializeAllFilters(const cy_stc_capsense_context_t *context)

Initializes (or re-initializes) all the firmware filter history, except the baseline.

Calling this function is accompanied by

Parameters

void Cy_CapSense_InitializeWidgetFilter(uint32_t widgetId, const cy_stc_capsense_context_t *context)

Initializes (or re-initializes) the raw count filter history of all the sensors in a widget specified by the input parameter.

Calling this function is accompanied by

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_UpdateAllBaselines(const cy_stc_capsense_context_t *context)

Updates the baseline for all the sensors in all the widgets.

Baselines must be updated after sensor scan to ignore low frequency changes in the sensor data caused by environment changes such as temperature from sensor status decision.

This function ignores the widget enable bit in the widget status register. Calling this function multiple times without a new sensor scan leads to unexpected behavior and should be avoided.

This function is called by Cy_CapSense_ProcessAllWidgets() and Cy_CapSense_ProcessWidget(), hence the application program need not use this function if any of the above functions is already used. This function can be used for custom application implementation.

Return

Returns the status of the update baseline operation of all the widgets:

• CY_CAPSENSE_STATUS_SUCCESS - The operation is successfully completed.

• CY_CAPSENSE_STATUS_BAD_DATA - The baseline processing failed.

Parameters

cy_capsense_status_t Cy_CapSense_UpdateWidgetBaseline(uint32_t widgetId, const cy_stc_capsense_context_t *context)

Updates the baselines for all the sensors in a widget specified by the input parameter.

This function performs exactly the same tasks as Cy_CapSense_UpdateAllBaselines() but only for a specified widget.

Calling this function multiple times without a new sensor scan leads to unexpected behavior and should be avoided. The application program need not use this function if the Cy_CapSense_UpdateAllBaselines(), Cy_CapSense_ProcessAllWidgets() or Cy_CapSense_ProcessWidget() functions are already used.

Return

Returns the status of the specified widget update baseline operation:

• CY_CAPSENSE_STATUS_SUCCESS - The operation is successfully completed.

• CY_CAPSENSE_STATUS_BAD_DATA - The baseline processing failed.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_UpdateSensorBaseline(uint32_t widgetId, uint32_t sensorId, const cy_stc_capsense_context_t *context)

Updates the baseline for a sensor in a widget specified by the input parameters.

This function performs exactly the same tasks as Cy_CapSense_UpdateAllBaselines() and Cy_CapSense_UpdateWidgetBaseline() but only for a specified sensor.

Calling this function multiple times without a new sensor scan leads to unexpected behavior and should be avoided. The application need not use this function if the Cy_CapSense_UpdateWidgetBaseline (), Cy_CapSense_UpdateAllBaselines (), Cy_CapSense_ProcessAllWidgets(), or Cy_CapSense_ProcessWidget() functions are already used.

Return

Returns the status of the specified sensor update baseline operation:

• CY_CAPSENSE_STATUS_SUCCESS - The operation is successfully completed.

• CY_CAPSENSE_STATUS_BAD_DATA - The baseline processing failed.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• sensorId: Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

void Cy_CapSense_InitializeWidgetGestures(uint32_t widgetId, const cy_stc_capsense_context_t *context)

Performs initialization of all gestures for the specified widget.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

void Cy_CapSense_InitializeAllStatuses(const cy_stc_capsense_context_t *context)

Performs initialization of all statuses and related modules including debounce counters and touch positions of all the widgets.

The initialization includes the following tasks:

• Reset the debounce counters of all the widgets.

• Reset the number of touches.

• Reset the position filter history for slider and touchpad widgets.

• Clear all status of widgets and sensors.

• Enable all the widgets.

Calling this function is accompanied by

Parameters

void Cy_CapSense_InitializeWidgetStatus(uint32_t widgetId, const cy_stc_capsense_context_t *context)

Performs initialization of all statuses, debounce counters, and touch positions of the specified widget.

The initialization includes:

• Resets the debounce counter of the widget.

• Resets the number of touches.

• Resets the position filter history for slider and touchpad widgets.

• Clears widget and sensor statuses.

• Enables the widget.

The Button and Matrix Button widgets have individual debounce counters per sensor for the CSD widgets and per node for the CSX widgets.

The Slider and Touchpad widgets have a single debounce counter per widget.

The Proximity widget has two debounce counters per sensor. One is for the proximity event and the second is for the touch event.

All debounce counters during initialization are set to the value of the onDebounce widget parameter.

Calling this function is accompanied by

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckCRCWidget(uint32_t widgetId, cy_stc_capsense_context_t *context)

Checks the stored CRC of the cy_stc_capsense_widget_context_t data structure of the specified widget.

This function validates the data integrity of the cy_stc_capsense_widget_context_t data structure of the specified widget by calculating the CRC and comparing it with the stored CRC value of the specified widget.

Initially, after the device power up, the Cy_CapSense_Enable() function calculates CRC for each widget and stores them in the .ptrWdgtCrc[] array of the cy_stc_capsense_bist_context_t structure. The test execution compares this stored CRC value with the newly calculated and if the stored and calculated CRC values differ:

1. The calculated CRC is stored to the .wdgtCrcCalc field of the cy_stc_capsense_bist_context_t data structure.

2. The widget ID is stored to the .crcWdgtId field.

3. The CY_CAPSENSE_BIST_CRC_WDGT bit is set in the .testResultMask field.

The function never clears the CY_CAPSENSE_BIST_CRC_WDGT bit. If the CY_CAPSENSE_BIST_CRC_WDGT bit is set, the wdgtCrcCalc and .crcWdgtId fields are not updated.

It is recommended to use the Cy_CapSense_SetParam() function to change the value of the cy_stc_capsense_widget_context_t data structure elements as the CRC is updated by Cy_CapSense_SetParam() function.

You can initiate this test by the Cy_CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_CRC_WDGT mask as an input.

The function clears the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure if the calculated CRC value differs to the stored CRC value. Those non-working widgets are skipped by the high-level scanning and processing functions. Restoring a widget to its working state should be done by the application level.

For details of the used CRC algorithm, refer to the Cy_CapSense_GetCRC() function.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The stored CRC matches the calculated CRC.

• CY_CAPSENSE_BIST_FAIL_E - The widget CRC differs to the stored CRC.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameters are invalid. The test was not executed.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The test was not executed.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorRawcount(uint32_t widgetId, uint32_t sensorId, uint16_t rawcountHighLimit, uint16_t rawcountLowLimit, cy_stc_capsense_context_t *context)

Checks the raw count of the specified widget/sensor is within the specified range.

The raw count is within a specific range (based on the calibration target) for good units. The function checks whether or not the raw count is within the user-defined limits in the ranges function arguments. If the raw count is out of limits, this function sets the CY_CAPSENSE_BIST_RAW_INTEGRITY bit in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.

This function does not update the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure and is not available in the Cy_CapSense_RunSelfTest() function.

Use this function to verify the uniformity of sensors, for example, at mass-production or during an operation phase together with the Cy_CapSense_CheckIntegritySensorBaseline() function.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The raw count is within the specified range.

• CY_CAPSENSE_BIST_FAIL_E - The test failed and raw count is out of the specified limits.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The test was not executed.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The test was not executed.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• sensorId: Specifies the ID number of the sensor within the widget. A macro for the sensor ID within the specified widget can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.

• rawcountHighLimit: Specifies the upper limit for the widget/sensor raw count.

• rawcountLowLimit: Specifies the lower limit for the widget/sensor raw count.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorBaseline(uint32_t widgetId, uint32_t sensorId, uint16_t baselineHighLimit, uint16_t baselineLowLimit, cy_stc_capsense_context_t *context)

Checks if the baseline of the specified sensor is not corrupted by comparing it with its inverse copy and checks if the baseline is within the specified range.

The function checks whether or not the baseline binary inverted to its inverse copy is saved to the self-test baseline-inverse structure and is within the user-defined limits. If the baseline does not match its inverse copy or if the baseline is out of the user-defined limits, the function sets the CY_CAPSENSE_BIST_BSLN_INTEGRITY bit in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.

The test is integrated into the CapSense Middleware. All CapSense processing functions like Cy_CapSense_ProcessAllWidgets() or Cy_CapSense_UpdateSensorBaseline() automatically verify the baseline value before using it and update its inverse copy after processing. If a baseline update fails, a CY_CAPSENSE_STATUS_BAD_DATA result is returned. The baseline initialization functions do not verify the baseline and update the baseline inverse copy.

This function does not update the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure and is not available in the Cy_CapSense_RunSelfTest() function.

Use this function to verify the uniformity of sensors, for example, at mass-production or during an operation phase together with the Cy_CapSense_CheckIntegritySensorRawcount() function.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The baseline is within the specified range.

• CY_CAPSENSE_BIST_FAIL_E - The test failed and the baseline is not binary inverted to its inverse copy or is out of the specified limits.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The test was not executed.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The test was not executed.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• sensorId: Specifies the ID number of the sensor within the widget. A macro for the sensor ID within the specified widget can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.

• baselineHighLimit: Specifies the upper limit for a baseline.

• baselineLowLimit: Specifies the lower limit for a baseline.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorPins(uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context)

Checks the specified widget/sensor for shorts to GND, VDD or other sensors.

This function performs several sub-tests to verify the specified sensor is not electrically shorted and is in a good condition to reliably detect user interactions.

This function performs tests to check if the specified sensor is shorted to:

• GND

• VDD

• Other GPIOs used by CapSense (such as sensors, Tx, Rx, shield electrodes, and external capacitors)

• Other non-CapSense GPIOs (only if they are configured in a strong high or low state during the test execution).

The absolute resistance of an electrical short must be less than 1500 Ohm including all series resistors on a sensor for a short to be detected to GND, VDD or GPIOs. For example, if a series resistor on a sensor is 560 Ohm (as recommended) and the sensor is shorted with another sensor, the function can detect a short with a short resistance up to 380 Ohm as there are two 560 ohm resistors between the shorted sensor GPIOs.

The function executes the following flow to detect a short:

• Configures all CapSense controlled GPIOs to strong-drive-high, and the specified sensor GPIO to resistive pull down mode.

• Waits for a delay (defined by .snsIntgShortSettlingTime field of the cy_stc_capsense_bist_context_t structure) to get established all transient processes.

• Checks the status of the specified sensor for the expected state (logic low).

• Configures all CapSense controlled GPIOs to strong-drive-low, and the specified sensor GPIO to resistive pull up mode.

• Waits for the above mentioned delay.

• Checks the status of the specified sensor for the expected state (logic high).

• Stores the test result in the CapSense Data Structure. A short is reported only when the sensor status check returns an unexpected state.

Due to the sensor parasitic capacitance and internal pull-up/down resistance, logic high-to-low (and vice versa) transitions require a settling time before checking the sensor status. A 2us delay is used as a settling time and can be changed using the .snsIntgShortSettlingTime field of the cy_stc_capsense_bist_context_t structure.

If a short is detected this function updates the following statuses:

• The widget ID is stored to the .shortedWdId field of the cy_stc_capsense_bist_context_t structure.

• The sensor ID is stored to the .shortedSnsId field of the cy_stc_capsense_bist_context_t structure.

• The CY_CAPSENSE_BIST_SNS_SHORT bit is set in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.

• If CY_CAPSENSE_BIST_SNS_SHORT is already set due to a previously detected fault on any of the sensor, this function does not update the .shortedWdId and .shortedSnsId fields. For this reason, clear the CY_CAPSENSE_BIST_SNS_SHORT bit prior calling this function.

• The widget is disabled by clearing the CY_CAPSENSE_WD_WORKING_MASK bit in the .status field of the cy_stc_capsense_widget_context_t structure of the specified widget. The disabled widget is ignored by high-level functions of scanning / data processing. To restore the widget operation the application layer should manually set the CY_CAPSENSE_WD_WORKING_MASK bit.

To check all the project sensors at once, use the Cy_CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_SNS_SHORT mask.

To detect an electrical short or fault condition with resistance higher than 1500 ohm, the Cy_CapSense_GetSensorCapacitance() function can be used as the fault condition affects the measured sensor capacitance.

This test can be executed only if the CapSense Middleware is in the IDLE state. This function must not be called while CapSense Middleware is busy.

note

This function is available only for the fourth-generation CapSense.

For the CSD widgets, a macro for the sensor ID within the specified widget can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• sensorId: Specifies the ID of the sensor (electrode for CSX widgets) within the widget to be tested.

For the CSX widgets, sensorId is an electrode ID and is defined as Rx ID or Tx ID. The first Rx in a widget corresponds to electrodeId = 0, the second Rx in a widget corresponds to electrodeId = 1, and so on. The last Tx in a widget corresponds to electrodeId = (RxNum + TxNum - 1). Macros for Rx and Tx IDs can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as:

• CapSense_<WidgetName>_RX<RXNumber>_ID

• CapSense_<WidgetName>_TX<TXNumber>_ID.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The sensor pin(s) are valid for CapSense operations.

• CY_CAPSENSE_BIST_FAIL_E - A short is detected on the specified sensor.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The test was not executed.

• CY_CAPSENSE_BIST_HW_BUSY_E - The CSD HW block is busy with a previous operation. The function was not executed.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The test was not executed.

Parameters

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSensor(uint32_t widgetId, uint32_t sensorId, uint32_t *ptrValue, cy_stc_capsense_context_t *context)

Measures the specified CSD sensor / CSX electrode capacitance in femtofarads.

This function measures the capacitance of the sensor (electrode for CSX widgets) and returns the measurement status. For a CSX sensor, the measurement is done on either Rx or Tx electrode. For a CSD sensor, measurement is done on a sensor (refer to the sensorId parameter description). If the specified sensor (electrode) is a ganged sensor, the capacitance is measured for all the pins ganged together that belong to this sensor (electrode).

The measured capacitance is stored in the .eltdCap[] array. The .ptrEltdCapacitance field of the cy_stc_capsense_widget_config_t structure contains a pointer to the first widget sensor (electrode) element within the .eltdCap[] array.

In addition to the measuring sensor (electrode) capacitance, this function is used to identify various fault conditions with sensors such as electrically-opened sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns elevated capacitance which can be compared against predetermined capacitance for the sensor to detect a fault condition.

The sensor capacitance is measured independently of the sensor scan configuration. For the capacitance measurement, the CSD sensing method is used. The measurements consists of up to four scans with different IDAC current. The IDAC current of the first measurement is 6 uA and each next measurement the IDAC current increase by four times. The default scanning parameters are the following:

• I (6 uA) is the current equal to IDAC Gain * IDAC Code (Compensation IDAC is disabled).

• Res (12 bits) is the scanning resolution.

• Vref (1.2 V) is the reference voltage.

• SnsClk (375 kHz) is the sensor clock frequency.

If the scanning raw count is within 7.5% to 45% range of a maximum raw count the raw count is converted into capacitance using the following equation:

Cs = Rawcount * I / ((2^Res - 1) * Vref * SnsClk)

where:

• Cs is the sensor capacitance.

• Rawcount is the measured raw count value.

If the raw count is less than 7.5% of the maximum limit (2^Res - 1), the function stops scanning the sequence and returns the CY_CAPSENSE_BIST_LOW_LIMIT_E status.

If the raw count is between 7.5% and 45% of the maximum, the function calculates the sensor capacitance, updates the register map and returns CY_CAPSENSE_BIST_SUCCESS_E status.

If the raw count is above 45% of the maximum, the function repeats scanning with a 4x increased IDAC current (up to four scans in total).

The minimum measurable input by this function is 1pF and the maximum is either 384pF or limited by the RC time constant (Cs < 1 / (2*5*SnsClk*R), where R is the total sensor series resistance that includes on-chip GPIO resistance ~500 Ohm and external series resistance). The measurement accuracy is about 15%.

By default, all CapSense sensors (electrodes) that are not being measured are configured to the strong-drive-low state. The shield electrode is also configured to the strong-drive-low state.

By default, the Cmod capacitor is used for the measurement. If a dedicated Cmod is not available (e.g. the design has CSX widgets only), CintA and CintB capacitors are combined together by the firmware to form a single integration capacitor for the measurement.

The sensor measurement can be done on all the sensors using the Cy_CapSense_RunSelfTest() function along with the CY_CAPSENSE_BIST_SNS_CAP mask.

This function must not be called while the CSD HW block is busy by another state.

note

This function is available only for the fourth-generation CapSense.

For the CSD widgets, a macro for the sensor ID within the specified widget can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• sensorId: Specifies the ID of the sensor (electrode for CSX widgets) within the widget to be measured.

For the CSX widgets, sensorId is an electrode ID and is defined as Rx ID or Tx ID. The first Rx in a widget corresponds to electrodeId = 0, the second Rx in a widget corresponds to electrodeId = 1, and so on. The last Tx in a widget corresponds to electrodeId = (RxNum + TxNum - 1). Macros for Rx and Tx IDs can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as:

• CapSense_<WidgetName>_RX<RXNumber>_ID

• CapSense_<WidgetName>_TX<TXNumber>_ID.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The measurement completes successfully, the result is valid.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The measurement was not executed.

• CY_CAPSENSE_BIST_HW_BUSY_E - The CSD HW block is busy with a previous operation. The measurement was not executed.

• CY_CAPSENSE_BIST_LOW_LIMIT_E - The measurement was executed and the scanning result is below the minimum possible value. The measurement result could be invalid. The sensor might be shorted to VDD or a sensor PCB track was broken (open sensor).

• CY_CAPSENSE_BIST_HIGH_LIMIT_E - The measurement was executed and the scanning result is above the maximum possible value. The measurement result could be invalid. The sensor might be shorted to GND.

• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The measurement was not executed.

Parameters
• ptrValue: The pointer to the measured capacitance in femtofarads. The user declares a variable of the uint32_t type and passes the variable pointer as the function parameter. If the ptrValue parameter is NULL, the capacitance value is not returned through the parameter but still stored in the corresponding field of the data structure.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceShield(uint32_t *ptrValue, cy_stc_capsense_context_t *context)

Measures shield electrode capacitance in femtofarads.

This function measures the capacitance of the shield electrode and returns a status of this measurement. The measurement result in femtofarads is stored in the .shieldCap field of the cy_stc_capsense_bist_context_t structure. If the shield consists of several electrodes, the total capacitance of all shield electrodes is reported.

This function uses an algorithm identical to the sensor capacitance measurement. Refer to the Cy_CapSense_MeasureCapacitanceSensor() function for more details.

In addition to measuring shield capacitance, this function is used to identify various fault conditions with a shield electrode such as an electrically open shield electrode, e.g. the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns elevated capacitance that can be compared against pre-determined capacitance for the shield electrode to detect a fault condition.

By default, all CapSense sensors (electrodes) are configured to the strong-drive-low state.

By default, the Cmod capacitor is used for the measurement. If a dedicated Cmod is not available (e.g. the design has CSX widgets only), CintA and CintB capacitors are combined together by the firmware to form a single integration capacitor which is used for measurement.

This test can be executed using the CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_SHIELD_CAP mask.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The measurement completes successfully, the result is valid.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The measurement was not executed.

• CY_CAPSENSE_BIST_HW_BUSY_E - The CSD HW block is busy with a previous operation. The measurement was not executed.

• CY_CAPSENSE_BIST_LOW_LIMIT_E - The measurement was executed but the measured raw count is below the minimum possible value. The measurement result could be invalid. The shield might be shorted to VDD or a shield PCB track is broken (the open shield electrode).

• CY_CAPSENSE_BIST_HIGH_LIMIT_E - The measurement was executed but the measured raw count is above the maximum possible value. The measurement result is invalid. The sensor might be shorted to GND.

• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The measurement was not executed.

Parameters
• ptrValue: The pointer to the variable the measured capacitance is stored. The user should declare a variable of uint32_t type and pass the variable pointer as the function parameter. If the ptrValue parameter is NULL then the shield capacitance value is not returned through the parameter but is still stored in the .shieldCap field of the cy_stc_capsense_bist_context_t structure.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceCap(cy_en_capsense_bist_external_cap_id_t integrationCapId, uint32_t *ptrValue, uint32_t maxCapacitance, cy_stc_capsense_context_t *context)

Measures the capacitance in picofarads of the specified CapSense integration (external) capacitor.

The function measures the capacitance of the specified external capacitor such as Cmod and returns the result through ptrValue, alternatively the measurement result is stored in the corresponding field of the cy_stc_capsense_bist_context_t structure (either .cModCap, .cIntACap, .cIntBCap, or .cShieldCap).

The maximum measurement capacitance is 25nF. The measurement accuracy is up to 15%. The measurement resolution is 10 bit which corresponds to the maximum capacitance specified by the maxCapacitance parameter. The bigger specified maximum capacitance is, the bigger capacitance value is for one measured count. It is recommended to specify the maximum capacitance twice bigger as the nominal capacitor capacitance. For example, if the nominal Cmod value is 2.2nF, the maxCapacitance parameter is set to 4nF-5nF.

The function configures all CapSense pins to Strong-drive-low mode that allows detecting a short of the measured capacitor to other pins.

To measure all the available capacitors, the Cy_CapSense_RunSelfTest() function can be used with the CY_CAPSENSE_BIST_SNS_SHORT mask. The measured results are stored in the corresponding field of the cy_stc_capsense_bist_context_t structure.

Measurement can be done only if the CapSense Middleware is in the IDLE state. This function must not be called while the CapSense Middleware is busy. The function is blocking, i.e. waits for the measurement to be completed prior to returning to the caller.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The measurement completes successfully, the result is valid.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The measurement was not executed.

• CY_CAPSENSE_BIST_HW_BUSY_E - The CSD HW block is busy with a previous operation. The measurement was not executed.

• CY_CAPSENSE_BIST_LOW_LIMIT_E - The measurement was performed but the scanning result is below the minimum possible value. The measurement result could be invalid. The capacitor might be shorted to VDD or a PCB track is broken (open capacitor).

• CY_CAPSENSE_BIST_HIGH_LIMIT_E - The measurement was performed but the scanning result is above the maximum possible value. The measurement result could be invalid. The capacitor might be shorted to GND.

• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The measurement was not executed.

Parameters
• integrationCapId: Indexes of external capacitors to measure their capacitance. There are macros for each of them, namely:

• CY_CAPSENSE_BIST_CMOD_ID for the CSD method Cmod capacitor

• CY_CAPSENSE_BIST_CINTA_ID for the CSX method CintA capacitor

• CY_CAPSENSE_BIST_CINTB_ID for the CSX method CintB capacitor

• CY_CAPSENSE_BIST_CSH_ID for the CSD method Csh capacitor

• ptrValue: The pointer to the result of the measurement. The result is calculated as a specified capacitor capacitance value in picofarads. The user declares a variable of the uint32_t type and passes the pointer to this variable as the function parameter. If the ptrValue parameter is NULL then the capacitance value is not returned through the parameter but stored to the corresponding field of the cy_stc_capsense_bist_context_t structure.

• maxCapacitance: An expected by the user maximum value of the measured capacitance in nanofarads in the range from 1 to 25 nF.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_MeasureVdda(uint32_t *ptrValue, cy_stc_capsense_context_t *context)

Measures a VDDA voltage, returns the measured voltage in millivolts through the ptrValue argument and stores it to the .vddaVoltage field of the cy_stc_capsense_bist_context_t structure.

This function measures the device analog supply voltage (VDDA) without need of explicitly connecting VDDA to any additional GPIO input. This capability can be used in variate cases, for example to monitor the battery voltage.

A measurement can be done only if the CapSense middleware is in the IDLE state. This function must not be called while the CapSense middleware is busy. The function is blocking, i.e. waits for the conversion to be completed prior to returning to the caller.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The measurement executed successfully.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The measurement was not executed.

• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The measurement was not executed.

Parameters
• ptrValue: The pointer to the uint32_t to store measured VDDA voltage value. If the ptrValue parameter is NULL then VDDA voltage value is not returned through the parameter and is stored in the .vddaVoltage field of the cy_stc_capsense_bist_context_t structure.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckCRCWidget_V2(uint32_t widgetId, cy_stc_capsense_context_t *context)

Checks the stored CRC of the cy_stc_capsense_widget_context_t data structure of the specified widget.

This function validates the data integrity of the cy_stc_capsense_widget_context_t data structure of the specified widget by calculating the CRC and comparing it with the stored CRC value of the specified widget.

Initially, after the device power up, the Cy_CapSense_Enable() function calculates CRC for each widget and stores them in the .ptrWdgtCrc[] array of the cy_stc_capsense_bist_context_t structure. The test execution compares this stored CRC value with the newly calculated and if the stored and calculated CRC values differ:

1. The calculated CRC is stored to the .wdgtCrcCalc field of the cy_stc_capsense_bist_context_t data structure.

2. The widget ID is stored to the .crcWdgtId field.

3. The CY_CAPSENSE_BIST_CRC_WDGT bit is set in the .testResultMask field.

The function never clears the CY_CAPSENSE_BIST_CRC_WDGT bit. If the CY_CAPSENSE_BIST_CRC_WDGT bit is set, the wdgtCrcCalc and .crcWdgtId fields are not updated.

It is recommended to use the Cy_CapSense_SetParam() function to change the value of the cy_stc_capsense_widget_context_t data structure elements as the CRC is updated by Cy_CapSense_SetParam() function.

You can initiate this test by the Cy_CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_CRC_WDGT mask as an input.

The function clears the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure if the calculated CRC value differs to the stored CRC value. Those non-working widgets are skipped by the high-level scanning and processing functions. Restoring a widget to its working state should be done by the application level.

For details of the used CRC algorithm, refer to the Cy_CapSense_GetCRC() function.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The stored CRC matches the calculated CRC.

• CY_CAPSENSE_BIST_FAIL_E - The widget CRC differs to the stored CRC.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameters are invalid. The test was not executed.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The test was not executed.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorRawcount_V2(uint32_t widgetId, uint32_t sensorId, uint16_t rawcountHighLimit, uint16_t rawcountLowLimit, cy_stc_capsense_context_t *context)

Checks the raw count of the specified widget/sensor is within the specified range.

The raw count is within a specific range (based on the calibration target) for good units. The function checks whether or not the raw count is within the user-defined limits in the ranges function arguments. If the raw count is out of limits, this function sets the CY_CAPSENSE_BIST_RAW_INTEGRITY bit in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.

This function does not update the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure and is not available in the Cy_CapSense_RunSelfTest() function.

Use this function to verify the uniformity of sensors, for example, at mass-production or during an operation phase together with the Cy_CapSense_CheckIntegritySensorBaseline() function.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The raw count is within the specified range.

• CY_CAPSENSE_BIST_FAIL_E - The test failed and raw count is out of the specified limits.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The test was not executed.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The test was not executed.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• sensorId: Specifies the ID number of the sensor within the widget. A macro for the sensor ID within the specified widget can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.

• rawcountHighLimit: Specifies the upper limit for the widget/sensor raw count.

• rawcountLowLimit: Specifies the lower limit for the widget/sensor raw count.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorBaseline_V2(uint32_t widgetId, uint32_t sensorId, uint16_t baselineHighLimit, uint16_t baselineLowLimit, cy_stc_capsense_context_t *context)

Checks if the baseline of the specified sensor is not corrupted by comparing it with its inverse copy and checks if the baseline is within the specified range.

The function checks whether or not the baseline binary inverted to its inverse copy is saved to the self-test baseline-inverse structure and is within the user-defined limits. If the baseline does not match its inverse copy or if the baseline is out of the user-defined limits, the function sets the CY_CAPSENSE_BIST_BSLN_INTEGRITY bit in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.

The test is integrated into the CapSense Middleware. All CapSense processing functions like Cy_CapSense_ProcessAllWidgets() or Cy_CapSense_UpdateSensorBaseline() automatically verify the baseline value before using it and update its inverse copy after processing. If a baseline update fails, a CY_CAPSENSE_STATUS_BAD_DATA result is returned. The baseline initialization functions do not verify the baseline and update the baseline inverse copy.

This function does not update the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure and is not available in the Cy_CapSense_RunSelfTest() function.

Use this function to verify the uniformity of sensors, for example, at mass-production or during an operation phase together with the Cy_CapSense_CheckIntegritySensorRawcount() function.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The baseline is within the specified range.

• CY_CAPSENSE_BIST_FAIL_E - The test failed and the baseline is not binary inverted to its inverse copy or is out of the specified limits.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The test was not executed.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The test was not executed.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• sensorId: Specifies the ID number of the sensor within the widget. A macro for the sensor ID within the specified widget can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.

• baselineHighLimit: Specifies the upper limit for a baseline.

• baselineLowLimit: Specifies the lower limit for a baseline.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorPins_V2(uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context)

Checks the specified widget/sensor for shorts to GND, VDD or other sensors.

This function performs several sub-tests to verify the specified sensor is not electrically shorted and is in a good condition to reliably detect user interactions.

This function performs tests to check if the specified sensor is shorted to:

• GND

• VDD

• Other GPIOs used by CapSense (such as sensors, Tx, Rx, shield electrodes, and external capacitors)

• Other non-CapSense GPIOs (only if they are configured in a strong high or low state during the test execution).

The absolute resistance of an electrical short must be less than 1500 Ohm including all series resistors on a sensor for a short to be detected to GND, VDD or GPIOs. For example, if a series resistor on a sensor is 560 Ohm (as recommended) and the sensor is shorted with another sensor, the function can detect a short with a short resistance up to 380 Ohm as there are two 560 ohm resistors between the shorted sensor GPIOs.

The function executes the following flow to detect a short:

• Configures all CapSense controlled GPIOs to strong-drive-high, and the specified sensor GPIO to resistive pull down mode.

• Waits for a delay (defined by .snsIntgShortSettlingTime field of the cy_stc_capsense_bist_context_t structure) to get established all transient processes.

• Checks the status of the specified sensor for the expected state (logic low).

• Configures all CapSense controlled GPIOs to strong-drive-low, and the specified sensor GPIO to resistive pull up mode.

• Waits for the above mentioned delay.

• Checks the status of the specified sensor for the expected state (logic high).

• Stores the test result in the CapSense Data Structure. A short is reported only when the sensor status check returns an unexpected state.

Due to the sensor parasitic capacitance and internal pull-up/down resistance, logic high-to-low (and vice versa) transitions require a settling time before checking the sensor status. A 2us delay is used as a settling time and can be changed using the .snsIntgShortSettlingTime field of the cy_stc_capsense_bist_context_t structure.

If a short is detected this function updates the following statuses:

• The widget ID is stored to the .shortedWdId field of the cy_stc_capsense_bist_context_t structure.

• The sensor ID is stored to the .shortedSnsId field of the cy_stc_capsense_bist_context_t structure.

• The CY_CAPSENSE_BIST_SNS_SHORT bit is set in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.

• If CY_CAPSENSE_BIST_SNS_SHORT is already set due to a previously detected fault on any of the sensor, this function does not update the .shortedWdId and .shortedSnsId fields. For this reason, clear the CY_CAPSENSE_BIST_SNS_SHORT bit prior calling this function.

• The widget is disabled by clearing the CY_CAPSENSE_WD_WORKING_MASK bit in the .status field of the cy_stc_capsense_widget_context_t structure of the specified widget. The disabled widget is ignored by high-level functions of scanning / data processing. To restore the widget operation the application layer should manually set the CY_CAPSENSE_WD_WORKING_MASK bit.

To check all the project sensors at once, use the Cy_CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_SNS_SHORT mask.

To detect an electrical short or fault condition with resistance higher than 1500 ohm, the Cy_CapSense_GetSensorCapacitance() function can be used as the fault condition affects the measured sensor capacitance.

This test can be executed only if the CapSense Middleware is in the IDLE state. This function must not be called while CapSense Middleware is busy.

note

This function is available only for the fourth-generation CapSense.

For the CSD widgets, a macro for the sensor ID within the specified widget can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• sensorId: Specifies the ID of the sensor (electrode for CSX widgets) within the widget to be tested.

For the CSX widgets, sensorId is an electrode ID and is defined as Rx ID or Tx ID. The first Rx in a widget corresponds to electrodeId = 0, the second Rx in a widget corresponds to electrodeId = 1, and so on. The last Tx in a widget corresponds to electrodeId = (RxNum + TxNum - 1). Macros for Rx and Tx IDs can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as:

• CapSense_<WidgetName>_RX<RXNumber>_ID

• CapSense_<WidgetName>_TX<TXNumber>_ID.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The sensor pin(s) are valid for CapSense operations.

• CY_CAPSENSE_BIST_FAIL_E - A short is detected on the specified sensor.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The test was not executed.

• CY_CAPSENSE_BIST_HW_BUSY_E - The CSD HW block is busy with a previous operation. The function was not executed.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The test was not executed.

Parameters

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSensor_V2(uint32_t widgetId, uint32_t sensorId, uint32_t *ptrValue, cy_stc_capsense_context_t *context)

Measures the specified CSD sensor / CSX electrode capacitance in femtofarads.

This function measures the capacitance of the sensor (electrode for CSX widgets) and returns the measurement status. For a CSX sensor, the measurement is done on either Rx or Tx electrode. For a CSD sensor, measurement is done on a sensor (refer to the sensorId parameter description). If the specified sensor (electrode) is a ganged sensor, the capacitance is measured for all the pins ganged together that belong to this sensor (electrode).

The measured capacitance is stored in the .eltdCap[] array. The .ptrEltdCapacitance field of the cy_stc_capsense_widget_config_t structure contains a pointer to the first widget sensor (electrode) element within the .eltdCap[] array.

In addition to the measuring sensor (electrode) capacitance, this function is used to identify various fault conditions with sensors such as electrically-opened sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns elevated capacitance which can be compared against predetermined capacitance for the sensor to detect a fault condition.

The sensor capacitance is measured independently of the sensor scan configuration. For the capacitance measurement, the CSD sensing method is used. The measurements consists of up to four scans with different IDAC current. The IDAC current of the first measurement is 6 uA and each next measurement the IDAC current increase by four times. The default scanning parameters are the following:

• I (6 uA) is the current equal to IDAC Gain * IDAC Code (Compensation IDAC is disabled).

• Res (12 bits) is the scanning resolution.

• Vref (1.2 V) is the reference voltage.

• SnsClk (375 kHz) is the sensor clock frequency.

If the scanning raw count is within 7.5% to 45% range of a maximum raw count the raw count is converted into capacitance using the following equation:

Cs = Rawcount * I / ((2^Res - 1) * Vref * SnsClk)

where:

• Cs is the sensor capacitance.

• Rawcount is the measured raw count value.

If the raw count is less than 7.5% of the maximum limit (2^Res - 1), the function stops scanning the sequence and returns the CY_CAPSENSE_BIST_LOW_LIMIT_E status.

If the raw count is between 7.5% and 45% of the maximum, the function calculates the sensor capacitance, updates the register map and returns CY_CAPSENSE_BIST_SUCCESS_E status.

If the raw count is above 45% of the maximum, the function repeats scanning with a 4x increased IDAC current (up to four scans in total).

The minimum measurable input by this function is 1pF and the maximum is either 384pF or limited by the RC time constant (Cs < 1 / (2*5*SnsClk*R), where R is the total sensor series resistance that includes on-chip GPIO resistance ~500 Ohm and external series resistance). The measurement accuracy is about 15%.

By default, all CapSense sensors (electrodes) that are not being measured are configured to the strong-drive-low state. The shield electrode is also configured to the strong-drive-low state.

By default, the Cmod capacitor is used for the measurement. If a dedicated Cmod is not available (e.g. the design has CSX widgets only), CintA and CintB capacitors are combined together by the firmware to form a single integration capacitor for the measurement.

The sensor measurement can be done on all the sensors using the Cy_CapSense_RunSelfTest() function along with the CY_CAPSENSE_BIST_SNS_CAP mask.

This function must not be called while the CSD HW block is busy by another state.

note

This function is available only for the fourth-generation CapSense.

For the CSD widgets, a macro for the sensor ID within the specified widget can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID.

• sensorId: Specifies the ID of the sensor (electrode for CSX widgets) within the widget to be measured.

For the CSX widgets, sensorId is an electrode ID and is defined as Rx ID or Tx ID. The first Rx in a widget corresponds to electrodeId = 0, the second Rx in a widget corresponds to electrodeId = 1, and so on. The last Tx in a widget corresponds to electrodeId = (RxNum + TxNum - 1). Macros for Rx and Tx IDs can be found in the CapSense Configuration header file (cycfg_capsense.h) defined as:

• CapSense_<WidgetName>_RX<RXNumber>_ID

• CapSense_<WidgetName>_TX<TXNumber>_ID.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The measurement completes successfully, the result is valid.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The measurement was not executed.

• CY_CAPSENSE_BIST_HW_BUSY_E - The CSD HW block is busy with a previous operation. The measurement was not executed.

• CY_CAPSENSE_BIST_LOW_LIMIT_E - The measurement was executed and the scanning result is below the minimum possible value. The measurement result could be invalid. The sensor might be shorted to VDD or a sensor PCB track was broken (open sensor).

• CY_CAPSENSE_BIST_HIGH_LIMIT_E - The measurement was executed and the scanning result is above the maximum possible value. The measurement result could be invalid. The sensor might be shorted to GND.

• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The measurement was not executed.

Parameters
• ptrValue: The pointer to the measured capacitance in femtofarads. The user declares a variable of the uint32_t type and passes the variable pointer as the function parameter. If the ptrValue parameter is NULL, the capacitance value is not returned through the parameter but still stored in the corresponding field of the data structure.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceShield_V2(uint32_t *ptrValue, cy_stc_capsense_context_t *context)

Measures shield electrode capacitance in femtofarads.

This function measures the capacitance of the shield electrode and returns a status of this measurement. The measurement result in femtofarads is stored in the .shieldCap field of the cy_stc_capsense_bist_context_t structure. If the shield consists of several electrodes, the total capacitance of all shield electrodes is reported.

This function uses an algorithm identical to the sensor capacitance measurement. Refer to the Cy_CapSense_MeasureCapacitanceSensor_V2() function for more details.

In addition to measuring shield capacitance, this function is used to identify various fault conditions with a shield electrode such as an electrically open shield electrode, e.g. the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns elevated capacitance that can be compared against pre-determined capacitance for the shield electrode to detect a fault condition.

By default, all CapSense sensors (electrodes) are configured to the strong-drive-low state.

By default, the Cmod capacitor is used for the measurement. If a dedicated Cmod is not available (e.g. the design has CSX widgets only), CintA and CintB capacitors are combined together by the firmware to form a single integration capacitor which is used for measurement.

This test can be executed using the CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_SHIELD_CAP mask.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The measurement completes successfully, the result is valid.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The measurement was not executed.

• CY_CAPSENSE_BIST_HW_BUSY_E - The CSD HW block is busy with a previous operation. The measurement was not executed.

• CY_CAPSENSE_BIST_LOW_LIMIT_E - The measurement was executed but the measured raw count is below the minimum possible value. The measurement result could be invalid. The shield might be shorted to VDD or a shield PCB track is broken (the open shield electrode).

• CY_CAPSENSE_BIST_HIGH_LIMIT_E - The measurement was executed but the measured raw count is above the maximum possible value. The measurement result is invalid. The sensor might be shorted to GND.

• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The measurement was not executed.

Parameters
• ptrValue: The pointer to the variable the measured capacitance is stored. The user should declare a variable of uint32_t type and pass the variable pointer as the function parameter. If the ptrValue parameter is NULL then the shield capacitance value is not returned through the parameter but is still stored in the .shieldCap field of the cy_stc_capsense_bist_context_t structure.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceCap_V2(cy_en_capsense_bist_external_cap_id_t integrationCapId, uint32_t *ptrValue, uint32_t maxCapacitance, cy_stc_capsense_context_t *context)

Measures the capacitance in picofarads of the specified CapSense integration (external) capacitor.

The function measures the capacitance of the specified external capacitor such as Cmod and returns the result through ptrValue, alternatively the measurement result is stored in the corresponding field of the cy_stc_capsense_bist_context_t structure (either .cModCap, .cIntACap, .cIntBCap, or .cShieldCap).

The maximum measurement capacitance is 25nF. The measurement accuracy is up to 15%. The measurement resolution is 10 bit which corresponds to the maximum capacitance specified by the maxCapacitance parameter. The bigger specified maximum capacitance is, the bigger capacitance value is for one measured count. It is recommended to specify the maximum capacitance twice bigger as the nominal capacitor capacitance. For example, if the nominal Cmod value is 2.2nF, the maxCapacitance parameter is set to 4nF-5nF.

The function configures all CapSense pins to Strong-drive-low mode that allows detecting a short of the measured capacitor to other pins.

To measure all the available capacitors, the Cy_CapSense_RunSelfTest() function can be used with the CY_CAPSENSE_BIST_SNS_SHORT mask. The measured results are stored in the corresponding field of the cy_stc_capsense_bist_context_t structure.

Measurement can be done only if the CapSense Middleware is in the IDLE state. This function must not be called while the CapSense Middleware is busy. The function is blocking, i.e. waits for the measurement to be completed prior to returning to the caller.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The measurement completes successfully, the result is valid.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The measurement was not executed.

• CY_CAPSENSE_BIST_HW_BUSY_E - The CSD HW block is busy with a previous operation. The measurement was not executed.

• CY_CAPSENSE_BIST_LOW_LIMIT_E - The measurement was performed but the scanning result is below the minimum possible value. The measurement result could be invalid. The capacitor might be shorted to VDD or a PCB track is broken (open capacitor).

• CY_CAPSENSE_BIST_HIGH_LIMIT_E - The measurement was performed but the scanning result is above the maximum possible value. The measurement result could be invalid. The capacitor might be shorted to GND.

• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The measurement was not executed.

Parameters
• integrationCapId: Indexes of external capacitors to measure their capacitance. There are macros for each of them, namely:

• CY_CAPSENSE_BIST_CMOD_ID for the CSD method Cmod capacitor

• CY_CAPSENSE_BIST_CINTA_ID for the CSX method CintA capacitor

• CY_CAPSENSE_BIST_CINTB_ID for the CSX method CintB capacitor

• CY_CAPSENSE_BIST_CSH_ID for the CSD method Csh capacitor

• ptrValue: The pointer to the result of the measurement. The result is calculated as a specified capacitor capacitance value in picofarads. The user declares a variable of the uint32_t type and passes the pointer to this variable as the function parameter. If the ptrValue parameter is NULL then the capacitance value is not returned through the parameter but stored to the corresponding field of the cy_stc_capsense_bist_context_t structure.

• maxCapacitance: An expected by the user maximum value of the measured capacitance in nanofarads in the range from 1 to 25 nF.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_MeasureVdda_V2(uint32_t *ptrValue, cy_stc_capsense_context_t *context)

Measures a VDDA voltage, returns the measured voltage in millivolts through the ptrValue argument and stores it to the .vddaVoltage field of the cy_stc_capsense_bist_context_t structure.

This function measures the device analog supply voltage (VDDA) without need of explicitly connecting VDDA to any additional GPIO input. This capability can be used in variate cases, for example to monitor the battery voltage.

A measurement can be done only if the CapSense middleware is in the IDLE state. This function must not be called while the CapSense middleware is busy. The function is blocking, i.e. waits for the conversion to be completed prior to returning to the caller.

note

This function is available only for the fourth-generation CapSense.

Return

Returns a status of the test execution:

• CY_CAPSENSE_BIST_SUCCESS_E - The measurement executed successfully.

• CY_CAPSENSE_BIST_BAD_PARAM_E - The input parameter is invalid. The measurement was not executed.

• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement.

• CY_CAPSENSE_BIST_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The measurement was not executed.

Parameters
• ptrValue: The pointer to the uint32_t to store measured VDDA voltage value. If the ptrValue parameter is NULL then VDDA voltage value is not returned through the parameter and is stored in the .vddaVoltage field of the cy_stc_capsense_bist_context_t structure.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_en_capsense_bist_status_t Cy_CapSense_CheckCRCWidget_V3(uint32_t widgetId, cy_stc_capsense_context_t *context)

TBD.

Return

TBD

Parameters
• widgetId: TBD

• context: TBD

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorRawcount_V3(uint32_t widgetId, uint32_t sensorId, uint16_t rawcountHighLimit, uint16_t rawcountLowLimit, cy_stc_capsense_context_t *context)

TBD.

Return

TBD

Parameters
• widgetId: TBD

• sensorId: TBD

• rawcountHighLimit: TBD

• rawcountLowLimit: TBD

• context: TBD

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorBaseline_V3(uint32_t widgetId, uint32_t sensorId, uint16_t baselineHighLimit, uint16_t baselineLowLimit, cy_stc_capsense_context_t *context)

TBD.

Return

TBD

Parameters
• widgetId: TBD

• sensorId: TBD

• baselineHighLimit: TBD

• baselineLowLimit: TBD

• context: TBD

cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorPins_V3(uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context)

TBD.

Return

TBD

Parameters
• widgetId: TBD

• sensorId: TBD

• context: TBD

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSensor_V3(uint32_t widgetId, uint32_t sensorId, uint32_t *ptrValue, cy_stc_capsense_context_t *context)

TBD.

Return

TBD

Parameters
• widgetId: TBD

• sensorId: TBD

• ptrValue: TBD

• context: TBD

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceShield_V3(uint32_t *ptrValue, cy_stc_capsense_context_t *context)

TBD.

Return

TBD

Parameters
• ptrValue: TBD

• context: TBD

cy_capsense_status_t Cy_CapSense_CalibrateAllWidgets(cy_stc_capsense_context_t *context)

Executes the CapDAC/IDAC calibration for all the sensors in all widgets in the middleware to default target value.

This function detects the sensing method used by each widget and performs a successive approximation search algorithm to find the appropriate modulator and compensation CapDAC/IDAC (if enabled) values for all sensors in CSD widgets and/or IDAC values for all sensors in CSX widgets to make sensor raw count to the default value level.

This function could be used only if Enable auto-calibration parameter is enabled for CSD and/or CSX widgets.

Return

Returns the status of the operation cy_capsense_status_t.

Parameters

cy_capsense_status_t Cy_CapSense_CalibrateWidget(uint32_t widgetId, cy_stc_capsense_context_t *context)

Executes the CapDAC/IDAC calibration for all the sensors in the specified widget to the default target value.

This function performs exactly the same tasks as Cy_CapSense_CalibrateAllWidgets(), but only for a specified widget.

Return

Returns the status of the operation cy_capsense_status_t.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_SetPinState(uint32_t widgetId, uint32_t sensorElement, uint32_t state, const cy_stc_capsense_context_t *context)

Sets the state (drive mode and HSIOM state) of the GPIO used by a sensor.

The possible states are GND, Shield, High-Z, Tx, Negative Tx, Rx, and Sensor. If the sensor specified in the input parameter is a ganged sensor, then the state of all GPIOs associated with the ganged sensor is updated.

To access a sensor of CSD of button or slider widgets, use the sensor ID. To access a sensor of CSD matrix button or touchpad widgets, use either row ID or column ID as appropriate. To access sensor CSX widgets, use either Rx ID or Tx ID as appropriate.

This function accepts the CY_CAPSENSE_SHIELD and CY_CAPSENSE_SENSOR states as an input only if there is at least one CSD widget in the project. Similarly, this function accepts the CY_CAPSENSE_TX_PIN and CY_CAPSENSE_RX_PIN states as an input only if there is at least one CSX widget in the project.

This function must not be called while the middleware is in the busy state. Calling this function directly from the application program is not recommended. This function is used to implement only the custom-specific use cases.

Functions that perform a setup and scan of a sensor/widget automatically set the required pin states for a sensor as required and overwrite changes made by this function to a sensor that are going to be scanned. Therefore the Cy_CapSense_SetPinState() function could be called in StartSample callback (see the Callbacks section for details) or with low-level functions that perform a single-sensor scanning.

note

This function is available only for the fifth-generation CapSense.

Return

status Returns the operation status:

• CY_CAPSENSE_STATUS_SUCCESS - Indicates the successful electrode setting.

• CY_CAPSENSE_STATUS_BAD_PARAM - 1) widgetID, sensorElement or state are not valid; 2) the CSD sensing method is disabled for desired CY_CAPSENSE_SHIELD or CY_CAPSENSE_SENSOR states; 3) the CSX sensing method is disabled for desired CY_CAPSENSE_TX_PIN, CY_CAPSENSE_NEGATIVE_TX_PIN or CY_CAPSENSE_RX_PIN states.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• sensorElement: Specifies the ID of the sensor element within the widget to change its pin state.

• For the CSD widgets use the sensor ID. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.

• For the CSX widgets use either Rx ID or Tx ID. The first Rx in a widget corresponds to sensorElement = 0; the second Rx in a widget corresponds to sensorElement = 1, and so on. The last Tx in a widget corresponds to sensorElement = (RxNum + TxNum - 1). A macro for the Rx ID or Tx ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_<TX/RX><TX/RX_NUMBER>_ID.

• state: Specifies the state of the sensor to be set:

1. CY_CAPSENSE_GROUND - The pin is connected to the ground.

2. CY_CAPSENSE_HIGHZ - The drive mode of the pin is set to High-Z Analog.

3. CY_CAPSENSE_SHIELD - The shield signal is routed to the pin (available only if CSD sensing method with shield electrode is enabled).

4. CY_CAPSENSE_SENSOR - The pin is connected to the scanning bus (available only if CSD sensing method is enabled).

5. CY_CAPSENSE_TX_PIN - The Tx signal is routed to the sensor (available only if CSX sensing method is enabled).

6. CY_CAPSENSE_RX_PIN - The pin is connected to the scanning bus (available only if CSX sensing method is enabled).

7. CY_CAPSENSE_NEGATIVE_TX_PIN - The Negative Tx signal is routed to the sensor (available only if CSD sensing method is enabled).

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_SetInactiveElectrodeState(uint8_t inactiveState, uint8_t sensingGroup, cy_stc_capsense_context_t *context)

Sets a desired state for all inactive CapSense-related electrodes for CSD or CSX scans.

Use the function to set/change the desired state of all CapSense-related electrodes which are not scanned. There are separate states for the CSX sensing method group and CSD sensing method group. For instance, it can be configured the GND state for all inactive sensors for CSX scanning and the High-Z state for CSD scanning. The function updates some corresponding parameters in the CapSense Data Structure to provide the desired state. It is not recommended to update the Data Structure registers directly. Additionally (only for fifth-generation CapSense), the function recalculates sensor frames in a case of the CTRLMUX sensor connection method.

Return

Returns the status of the operation cy_capsense_status_t.

Parameters
• inactiveState: Specifies the inactive CapSense electrode state:

• CY_CAPSENSE_SNS_CONNECTION_HIGHZ

• CY_CAPSENSE_SNS_CONNECTION_SHIELD (only for CSD scan)

• CY_CAPSENSE_SNS_CONNECTION_GROUND

• sensingGroup: Specifies the sensing group:

• CY_CAPSENSE_CSD_GROUP

• CY_CAPSENSE_CSX_GROUP

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_SetupWidgetExt(uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context)

Performs extended initialization for the specified widget and also performs initialization required for a specific sensor in the widget.

This function requires using the Cy_CapSense_ScanExt() function to initiate a scan.

This function does the same as Cy_CapSense_SetupWidget() and also does the following tasks:

1. Connects the specified sensor of the widget.

2. Configures the CSD HW block to perform a scan of the specified sensor.

Once this function is called to initialize a widget and a sensor, the Cy_CapSense_ScanExt() function is called to scan the sensor.

This function is called when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status.

Calling this function directly from the application program is not recommended. This function is used to implement only the user’s specific use cases (for faster execution time or pipeline scanning, for example).

note

This function is available only for the fourth-generation CapSense.

Parameters
• widgetId: Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.

• sensorId: Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_ScanExt(cy_stc_capsense_context_t *context)

Starts a conversion on the pre-configured sensor.

This function requires using the Cy_CapSense_SetupWidgetExt() function to set up the a widget.

This function performs single scanning of one sensor in the widget configured by the Cy_CapSense_SetupWidgetExt() function.

Calling this function directly from the application program is not recommended. This function is used to implement only the user’s specific use cases (for faster execution time or pipeline scanning, for example). This function is called when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status.

The sensor must be pre-configured by using the Cy_CapSense_SetupWidgetExt() prior to calling this function. The sensor remains ready for the next scan if a previous scan was triggered by using the Cy_CapSense_ScanExt() function. In this case, calling Cy_CapSense_SetupWidgetExt() is not required every time before the Cy_CapSense_ScanExt() function. If a previous scan was triggered in any other way - Cy_CapSense_Scan(), Cy_CapSense_ScanAllWidgets(), or Cy_CapSense_RunTuner() - (see the Cy_CapSense_RunTuner() function description for more details), the sensor must be pre-configured again by using the Cy_CapSense_SetupWidgetExt() prior to calling the Cy_CapSense_ScanExt() function.

note

This function is available only for the fourth-generation CapSense.

Parameters

cy_capsense_status_t Cy_CapSense_CalibrateAllSlots(cy_stc_capsense_context_t *context)

Executes CapDAC auto-calibration for all relevant widgets/sensors if enabled.

The function performs the CapDAC parameter search (reference and compensation CDAC codes or both and compensation CDAC divider as well whether is enabled) by using a successive approximation method for all relevant widgets/sensors to make sensor raw counts closest to defined targets.

The auto-calibration target values are defined as CSD/CSX raw count calibration level parameters on the Parameter View of the CSD and CSX Setting tabs for CSD and CSX widgets respectively. The function Cy_CapSense_SetCalibrTarget() should be used to change configured target values to the user defined.

This function detects the sensing method used by each widget and performs the following steps to find the appropriate values for:

• 1) the reference CDAC code, if the Reference CDAC parameter is set to Auto in the Configurator for such a sensor group CSD or CSX. If the parameter is set to Manual, this step is skipped and configured reference CDAC value is used to provide the demanded scan sensitivity. The search is performed by using a successive approximation method.

• 2) the compensation CapDAC divider, if the compensation CDAC is enabled and the Compensation CDAC divider parameter is set to Auto in the Configurator for such a sensor group CSD or CSX. If the parameter is set to Manual, this step is skipped and configured compensation CDAC divider is used. The automatic CDAC divider adjusting provide the covering of the wide sensor capacities range (up to 200 pF). The divider adjusting is performed by sequential scans with the defined on the previous step reference CDAC value and the maximum compensation CDAC value starting from CompDivider = SnsClkDivider (i.e. Kcomp = 1) by descending CompDivider to 1, if raw counts are bigger than a target. The only those CompDivider values are used which provide the Kcomp being integer. 3) the compensation CapDAC code, if the compensation CDAC is enabled in the Configurator for such a sensor group CSD or CSX. If the parameter is not enabled, this step is skipped and compensation CDAC is not used. The search is performed by using a successive approximation method for all sensors to make sensor raw counts closest to defined targets.

note

This function is available only for the fifth-generation CapSense.

Return

Returns the status of the operation:

• CY_CAPSENSE_STATUS_SUCCESS - The operation is performed successfully.

• CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.

• CY_CAPSENSE_STATUS_BAD_CONFIG - The configuration parameter is invalid.

• CY_CAPSENSE_STATUS_CALIBRATION_FAIL - The calibration failed if software watchdog timeout occurred during any calibration scan, the scan was not completed, or resulted raw counts are outside the limits.

Parameters

cy_capsense_status_t Cy_CapSense_SetCalibrationTargets(uint32_t csdCalibrTarget, uint32_t csxCalibrTarget, cy_stc_capsense_context_t *context)

Sets the CapDAC auto-calibration raw count targets for CSD and/or CSX widgets.

The function sets the specified raw count targets if CSD and/or CSX widgets are in the project and the auto-calibration is enabled for them. These targets will be used instead the configured ones by Cy_CapSense_CalibrateAllSlots(), Cy_CapSense_CalibrateAllWidgets() and Cy_CapSense_CalibrateWidget() functions.

Return

Returns the status of the operation:

• CY_CAPSENSE_STATUS_SUCCESS - The operation is performed successfully.

• CY_CAPSENSE_STATUS_BAD_PARAM - At least one of the input parameter is invalid.

• CY_CAPSENSE_STATUS_BAD_CONFIG - The configuration parameter is invalid.

Parameters
• csdCalibrTarget: The specified raw counts target for CSD widgets in percentage. It should be more than 0u and less than 100u. If the specified target is outside the range, then the configured target value will be used for the auto-calibration.

• csxCalibrTarget: The specified raw counts target for CSX widgets in percentage. It should be more than 0u and less than 100u. If the specified target is outside the range, then the configured target value will be used for the auto-calibration.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_Capsense_SlotPinState(uint32_t slotId, const cy_stc_capsense_electrode_config_t *ptrEltdCfg, uint32_t pinState, cy_stc_capsense_context_t *context)

Configures the desired electrode to the specified state by updating the CapSense configuration.

This function changes / overwrites configuration of an electrode (several pins in case the electrode is ganged to more pins) with a state provided by pinState parameter. The function does this only for the mentioned slot ID. If a pin should have the desired state during several scans, the function should be called multiple times for the each desired slot.

The re-configuration is possible when parameter Sensor connection method = CTRLMUX. If parameter Sensor connection method = AMUXBUS, then the function returns CY_CAPSENSE_STATUS_BAD_CONFIG. In next releases the Cy_CapSense_SetPinState() function will be provided for the AMUXBUS configuration.

The function changes the configuration of an electrode without storing the default state. A user is responsible to keep the default state to revert to the default settings if needed. Also, the default settings can be configured again by calling Cy_CapSense_Enable() function that leads to repeating CapSense Data Structure initialization, repeating DAC auto-calibration and repeating base-lining.

Using this function is not recommended. This function is used to implement only the user’s specific use cases (as changing the CapSense default configuration).

Call this function from CapSense Data Structure Initialization Callback ptrEODsInitCallback. For details of how to register callback see the Callbacks section. That avoids repeating of DAC auto-calibration and base-lining since the callback is called after CapSense Data Structure initialization but before the first initialization scan.

The function is a low-level function and does not perform verification of input parameters (like slot ID, pointers, etc.). For example, CY_CAPSENSE_CTRLMUX_STATE_SHIELD is not available if shield is not configured in the project.

Return

Returns the status of the operation:

• CY_CAPSENSE_STATUS_SUCCESS - The operation is performed successfully.

• CY_CAPSENSE_STATUS_BAD_CONFIG - The function does not suppose to be called with the current CapSense configuration.

Parameters
• slotId: The desired slot ID.

• ptrEltdCfg: The pointer to an electrode the all pins states of which will be configured as pinState parameter.

• pinState: The desired pins state for CSX widget electrodes:

• CY_CAPSENSE_CTRLMUX_STATE_RX - Rx electrode.

• CY_CAPSENSE_CTRLMUX_STATE_TX - Tx electrode.

• CY_CAPSENSE_CTRLMUX_STATE_GND - Grounded.

• CY_CAPSENSE_CTRLMUX_STATE_TX_NEGATIVE - Negative Tx electrode (for multi-phase TX method). The desired pins state for CSD widget electrodes:

• CY_CAPSENSE_CTRLMUX_STATE_SNS - Self-cap sensor.

• CY_CAPSENSE_CTRLMUX_STATE_HIGH_Z - Unconnected (high-z).

• CY_CAPSENSE_CTRLMUX_STATE_GND - Grounded.

• CY_CAPSENSE_CTRLMUX_STATE_SHIELD - Shield is routed to the pin.

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_GetParam(uint32_t paramId, uint32_t *value, const void *ptrTuner, const cy_stc_capsense_context_t *context)

Gets a value of the specified parameter from the cy_capsense_tuner structure.

This function gets the value of the specified parameter by the paramId argument. The paramId for each register of cy_capsense_tuner is available in the cycfg_capsense.h file as CY_CAPSENSE_<ParameterName>_PARAM_ID. The paramId is a special enumerated value generated by the CapSense Configurator. The format of paramId is as follows:

1. [ byte 3 byte 2 byte 1 byte 0 ]

2. [ RRRRRUTT IIIIIIII MMMMMMMM LLLLLLLL ]

3. U - indicates if the parameter affects the RAM Widget Object CRC.

4. T - encodes the parameter type:

• 01b: uint8_t

• 10b: uint16_t

• 11b: uint32_t

5. I - specifies that the widgetId parameter belongs to.

6. M,L - the parameter offset MSB and LSB accordingly in cy_capsense_tuner.

7. R - reserved

Return

Returns the status of the operation. If CY_CAPSENSE_STATUS_SUCCESS is not received, either paramId is invalid or ptrTuner is null.

Parameters
• paramId: Specifies the ID of parameter to get its value. A macro for the parameter ID can be found in the cycsg_capsense.h file defined as CY_CAPSENSE_<ParameterName>_PARAM_ID.

• value: The pointer to a variable to be updated with the obtained value.

• ptrTuner: The pointer to the cy_capsense_tuner variable of cy_stc_capsense_tuner_t. The cy_capsense_tuner is declared in CapSense Configurator generated files:

• cycfg_capsense.c/h

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

cy_capsense_status_t Cy_CapSense_SetParam(uint32_t paramId, uint32_t value, void *ptrTuner, cy_stc_capsense_context_t *context)

Sets a new value for the specified parameter in cy_capsense_tuner structure.

This function sets the value of the specified parameter by the paramId argument. The paramId for each register of cy_capsense_tuner is available in the cycfg_capsense.h file as CY_CAPSENSE_<ParameterName>_PARAM_ID. The paramId is a special enumerated value generated by the CapSense Configurator. The format of paramId is as follows:

1. [ byte 3 byte 2 byte 1 byte 0 ]

2. [ RRRRRUTT IIIIIIII MMMMMMMM LLLLLLLL ]

3. U - indicates if the parameter affects the RAM Widget Object CRC.

4. T - encodes the parameter type:

• 01b: uint8_t

• 10b: uint16_t

• 11b: uint32_t

5. I - specifies that the widgetId parameter belongs to

6. M,L - the parameter offset MSB and LSB accordingly in cy_capsense_tuner.

7. R - reserved

This function writes specified value into the desired register without other registers update. It is application layer responsibility to keep all the data structure registers aligned. Repeated call of Cy_CapSense_Enable() function helps aligning dependent register values.

This function updates also the widget CRC field if Built-in Self-test is enabled and paramId requires that.

Return

Returns the status of the operation. If CY_CAPSENSE_STATUS_SUCCESS is not received, the parameter was not updated with the new value, either paramId is invalid or ptrTuner is null.

Parameters
• paramId: Specifies the ID of parameter to set its value. A macro for the parameter ID can be found in the cycsg_capsense.h file defined as CY_CAPSENSE_<ParameterName>_PARAM_ID.

• value: Specifies the new parameter’s value.

• ptrTuner: The pointer to the cy_capsense_tuner variable of cy_stc_capsense_tuner_t. The cy_capsense_tuner is declared in CapSense Configurator generated files:

• cycfg_capsense.c/h

• context: The pointer to the CapSense context structure cy_stc_capsense_context_t.

uint16_t Cy_CapSense_GetCRC(const uint8_t *ptrData, uint32_t len)

Calculates CRC for the specified buffer and length.

This API is used for the CRC protection of a packet received from the CapSense Tuner tool and for BIST operations. CRC polynomial is 0xAC9A. It has a Hamming distance 5 for data words up to 241 bits.

Reference: “P. Koopman, T. Chakravarthy,

”Cyclic Redundancy Code (CRC) Polynomial Selection for Embedded Networks”,

The International Conference on Dependable Systems and Networks, DSN-2004”

Return

Returns a calculated CRC-16 value.

Parameters
• ptrData: The pointer to the data.

• len: The length of the data in bytes.