CAPSENSE™ Middleware Library 3.0
Low-level Functions

General Description

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. More...
 
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. More...
 
void Cy_CapSense_InitializeAllBaselines (cy_stc_capsense_context_t *context)
 Initializes the baselines of all the sensors of all the widgets. More...
 
void Cy_CapSense_InitializeWidgetBaseline (uint32_t widgetId, cy_stc_capsense_context_t *context)
 Initializes the baselines of all the sensors in a specific widget. More...
 
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. More...
 
void Cy_CapSense_InitializeAllFilters (const cy_stc_capsense_context_t *context)
 Initializes (or re-initializes) all the firmware filter history, except the baseline. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void Cy_CapSense_InitializeWidgetGestures (uint32_t widgetId, const cy_stc_capsense_context_t *context)
 Performs initialization of all gestures for the specified widget. More...
 
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. More...
 
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. More...
 
cy_capsense_status_t Cy_CapSense_ProcessWidgetMptxDeconvolution (uint32_t widgetId, cy_stc_capsense_context_t *context)
 Performs raw count deconvolution for the specified CSX widget when Multi-phase Tx is enabled. More...
 
void Cy_CapSense_PreProcessWidget (uint32_t widgetId, const cy_stc_capsense_context_t *context)
 Executes the pre-processing of scan raw data for specified widgets. More...
 
void Cy_CapSense_PreProcessSensor (uint32_t widgetId, uint32_t sensorId, const cy_stc_capsense_context_t *context)
 Executes the pre-processing of scan raw data for specified sensor. More...
 
cy_capsense_status_t Cy_CapSense_RunMfsMedian (uint32_t widgetId, const cy_stc_capsense_context_t *context)
 Applies the median filter to the specified multi-frequency widget and updates the specified widget diff counts. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceShield (uint32_t *ptrValue, cy_stc_capsense_context_t *context)
 Measures shield electrode capacitance in femtofarads. More...
 
cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSensorElectrode (uint32_t widgetId, uint32_t eltdId, cy_stc_capsense_context_t *context)
 Measures the specified CSD sensor / CSX electrode capacitance in femtofarads. More...
 
cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSlotSensors (uint32_t slotId, uint32_t skipChMask, cy_stc_capsense_context_t *context)
 Measures the specified slot sensor capacitance in femtofarads. More...
 
cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceShieldElectrode (uint32_t skipChMask, cy_stc_capsense_context_t *context)
 Measures shield electrode capacitances in femtofarads. More...
 
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. More...
 
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. More...
 
cy_capsense_status_t Cy_CapSense_ScanSensor (uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context)
 Initiates the scanning of the selected sensor in the widget. More...
 
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. More...
 
cy_capsense_status_t Cy_CapSense_SetInactiveElectrodeState (uint32_t inactiveState, uint32_t sensingGroup, cy_stc_capsense_context_t *context)
 Sets a desired state for all inactive CAPSENSE™-related electrodes for CSD or CSX scans. More...
 
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. More...
 
cy_capsense_status_t Cy_CapSense_ScanExt (cy_stc_capsense_context_t *context)
 Starts a conversion on the pre-configured sensor. More...
 
cy_capsense_status_t Cy_CapSense_CalibrateAllSlots (cy_stc_capsense_context_t *context)
 Executes CapDAC auto-calibration for all relevant widgets if enabled. More...
 
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. More...
 
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. More...
 
cy_capsense_status_t Cy_CapSense_ScanAbort (cy_stc_capsense_context_t *context)
 This function sets the sequencer to the idle state by resetting the hardware, it can be used to abort current scan. More...
 
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. More...
 
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. More...
 
uint16_t Cy_CapSense_GetCRC (const uint8_t *ptrData, uint32_t len)
 Calculates CRC for the specified buffer and length. More...
 

Function Documentation

◆ Cy_CapSense_ProcessWidgetExt()

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 smart sensing algorithm 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.

Note
For the the fifth-generation CAPSENSE™ an extra processing should be performed prior a call of this function:
Parameters
widgetIdSpecifies 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.
modeSpecifies the type of widget processing to be executed for the specified widget:
  1. Bits [31..7] - Reserved.
  2. Bits [6..0] - CY_CAPSENSE_PROCESS_ALL - Execute all of the below tasks.
  3. Bit [6] - CY_CAPSENSE_PROCESS_MFS_FILTER - Run the firmware filters for MFS on sensor rawcounts (applicable only for fifth-generation CAPSENSE™).
  4. Bit [5] - CY_CAPSENSE_PROCESS_STATUS - Update the status (on/off, centroid position).
  5. Bit [4] - CY_CAPSENSE_PROCESS_THRESHOLDS - Update the thresholds (only in CSD auto-tuning mode).
  6. Bit [3] - CY_CAPSENSE_PROCESS_CALC_NOISE - Calculate the noise (only in CSD auto-tuning mode).
  7. Bit [2] - CY_CAPSENSE_PROCESS_DIFFCOUNTS - Update the difference counts of each sensor.
  8. Bit [1] - CY_CAPSENSE_PROCESS_BASELINE - Update the baselines for all sensor.
  9. Bit [0] - CY_CAPSENSE_PROCESS_FILTER - Run the firmware filters on sensor rawcounts.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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

An example of customized data processing, changed processing order:

/*...*/
/* Standard execution order (smart sensing algorithm 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_ProcessWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID,
&cy_capsense_context);
Cy_CapSense_ProcessWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID,
&cy_capsense_context);
/*...*/

◆ Cy_CapSense_ProcessSensorExt()

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
For the the fifth CAPSENSE™ HW generation an extra processing should be performed prior a call of this function:
Parameters
widgetIdSpecifies 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.
sensorIdSpecifies 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.
modeSpecifies 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
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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

An example demonstrates pipeline implementation of sensor scanning and processing:

/*...*/
snsIndex = 0u;
Cy_CapSense_ScanSensor(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, snsIndex, &cy_capsense_context);
for(;;)
{
if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
{
snsIndex++;
if (snsIndex < cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].numSns)
{
Cy_CapSense_ScanSensor(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, snsIndex, &cy_capsense_context);
Cy_CapSense_ProcessSensorExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, snsIndex, CY_CAPSENSE_PROCESS_ALL, &cy_capsense_context);
}
else
{
/* The last sensor is scanned already */
Cy_CapSense_ProcessSensorExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, snsIndex, CY_CAPSENSE_PROCESS_ALL, &cy_capsense_context);
/* All sensors processed, therefore process only widget-related task */
Cy_CapSense_ProcessWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, CY_CAPSENSE_PROCESS_STATUS, &cy_capsense_context);
/* Reset sensor index to start from the first sensor */
snsIndex = 0u;
}
}
}
/*...*/

◆ Cy_CapSense_InitializeAllBaselines()

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
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_InitializeWidgetBaseline()

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
widgetIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_InitializeSensorBaseline()

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
widgetIdSpecifies 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.
sensorIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_InitializeAllFilters()

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
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_InitializeWidgetFilter()

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
widgetIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_UpdateAllBaselines()

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.

Parameters
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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.

◆ Cy_CapSense_UpdateWidgetBaseline()

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.

Parameters
widgetIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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.

◆ Cy_CapSense_UpdateSensorBaseline()

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.

Parameters
widgetIdSpecifies 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.
sensorIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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.

◆ Cy_CapSense_InitializeWidgetGestures()

void Cy_CapSense_InitializeWidgetGestures ( uint32_t  widgetId,
const cy_stc_capsense_context_t context 
)

Performs initialization of all gestures for the specified widget.

Parameters
widgetIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_InitializeAllStatuses()

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
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_InitializeWidgetStatus()

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
widgetIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_ProcessWidgetMptxDeconvolution()

cy_capsense_status_t Cy_CapSense_ProcessWidgetMptxDeconvolution ( uint32_t  widgetId,
cy_stc_capsense_context_t context 
)

Performs raw count deconvolution for the specified CSX widget when Multi-phase Tx is enabled.

This function decodes raw counts received after scanning into normal view by performing deconvolution algorithm. If the function is called for a widget with disabled Multi-phase Tx, the function returns CY_CAPSENSE_STATUS_BAD_DATA.

No need to call this function from application layer since the Cy_CapSense_ProcessAllWidgets() and Cy_CapSense_ProcessWidget() functions calls deconvolution automatically.

DAC auto-calibration when enabled performs sensor auto-calibration without performing deconvolution. The deconvolution algorithm for even number of TX electrodes decreases raw count level twice (keeping the signal on the same level).

If specific processing is implemented using the Cy_CapSense_ProcessWidgetExt() and Cy_CapSense_ProcessSensorExt() function then a call of this function is required prior doing the specific processing.

Parameters
widgetIdSpecifies the ID number of the widget.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
Returns the status of the processing operation.

◆ Cy_CapSense_PreProcessWidget()

void Cy_CapSense_PreProcessWidget ( uint32_t  widgetId,
const cy_stc_capsense_context_t context 
)

Executes the pre-processing of scan raw data for specified widgets.

This function is called prior any other processing function for the fifth CAPSENSE™ HW generation. The pre-processing routine implements the following operations:

  • Executes the CIC2 pre-processing if the filter mode is set to CIC2.
  • Limits raw count to maximum value.
  • Executes the raw data inversion for the CSX sensors.

No need to call this function from application layer since the Cy_CapSense_ProcessAllWidgets() and Cy_CapSense_ProcessWidget() functions calls it automatically.

If specific processing is implemented using the Cy_CapSense_ProcessWidgetExt() and Cy_CapSense_ProcessSensorExt() function then a call of this function is required prior doing the specific processing. If Multi-phase TX is enabled then deconvolution should be executed after call of this function using the Cy_CapSense_ProcessWidgetMptxDeconvolution() function.

Parameters
widgetIdThe widget ID, for which the pre-processing should be executed.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_PreProcessSensor()

void Cy_CapSense_PreProcessSensor ( uint32_t  widgetId,
uint32_t  sensorId,
const cy_stc_capsense_context_t context 
)

Executes the pre-processing of scan raw data for specified sensor.

This function is called prior any other processing function for the fifth CAPSENSE™ HW generation. The pre-processing routine implements the following operations:

  • Executes the CIC2 pre-processing if the filter mode is set to CIC2.
  • Limits raw count to maximum value.
  • Executes the raw data inversion for the CSX sensors.

No need to call this function from application layer since the Cy_CapSense_ProcessAllWidgets() and Cy_CapSense_ProcessWidget() functions calls it automatically.

If specific processing is implemented using the Cy_CapSense_ProcessWidgetExt() and Cy_CapSense_ProcessSensorExt() function then a call of this function is required prior doing the specific processing. If Multi-phase TX is enabled then deconvolution should be executed after pre-processing of all sensors of the specified widget using the Cy_CapSense_ProcessWidgetMptxDeconvolution() function.

Parameters
widgetIdThe widget ID, for which the pre-processing should be executed.
sensorIdThe sensor ID, for which the pre-processing should be executed.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_RunMfsMedian()

cy_capsense_status_t Cy_CapSense_RunMfsMedian ( uint32_t  widgetId,
const cy_stc_capsense_context_t context 
)

Applies the median filter to the specified multi-frequency widget and updates the specified widget diff counts.

This function is a low-level function and is called automatically by high-level processing functions like Cy_CapSense_ProcessWidget() and Cy_CapSense_ProcessAllWidgets().

It is not recommended to use this function directly on application level.

The function applies the median filter to diff count of each sensor of the specified widget (with enabled multi-frequency feature) and update the diff count of the specified main widget.

This function is needed to implement customer-specific use cases.

Note
This function is available only for the fifth-generation CAPSENSE™.
Parameters
widgetIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
Returns the status of the widget processing:
  • CY_CAPSENSE_STATUS_SUCCESS - The operation is successfully completed
  • CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid either widgetId is not valid or multi-frequency is not enabled for this widget or the specified widgetId is derivative of the main widget.

◆ Cy_CapSense_CheckCRCWidget()

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_MASK bit is set in the .testResultMask field.

The function never clears the CY_CAPSENSE_BIST_CRC_WDGT_MASK bit. If the CY_CAPSENSE_BIST_CRC_WDGT_MASK 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 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.

Parameters
widgetIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_CheckIntegritySensorRawcount()

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

Parameters
widgetIdSpecifies 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.
sensorIdSpecifies 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.
rawcountHighLimitSpecifies the upper limit for the widget/sensor raw count.
rawcountLowLimitSpecifies the lower limit for the widget/sensor raw count.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_CheckIntegritySensorBaseline()

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

Parameters
widgetIdSpecifies 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.
sensorIdSpecifies 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.
baselineHighLimitSpecifies the upper limit for a baseline.
baselineLowLimitSpecifies the lower limit for a baseline.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_CheckIntegritySensorPins()

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_INTEGRITY_MASK bit is set in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.
  • If CY_CAPSENSE_BIST_SNS_INTEGRITY_MASK 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_INTEGRITY_MASK 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_INTEGRITY_MASK mask.

To detect an electrical short or fault condition with resistance higher than 1500 ohm, the Cy_CapSense_MeasureCapacitanceSensor() (4th Generation) or Cy_CapSense_MeasureCapacitanceSensorElectrode() (5th Generation) 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.

Parameters
widgetIdSpecifies 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.
sensorIdSpecifies the ID of the sensor (electrode for CSX widgets) within the widget to be tested.

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.

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.
Parameters
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_MeasureCapacitanceCap()

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_EXTERNAL_CAP_MASK 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™.
Parameters
integrationCapIdIndexes 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
ptrValueThe 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.
maxCapacitanceAn expected by the user maximum value of the measured capacitance in nanofarads in the range from 1 to 25 nF.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_MeasureVdda()

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™.
Parameters
ptrValueThe 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_MeasureCapacitanceSensor()

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 or -shorted sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns changed 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 set to the GND state for CSD measured electrodes (sensors) and to the HIGH-Z state for CSX measured electrodes (Rx and Tx). Shield electrodes are also configured to the GND state. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function.

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 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™.
Parameters
widgetIdSpecifies 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.
sensorIdSpecifies the ID of the sensor (electrode for CSX widgets) within the widget to be measured.

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.

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.
Parameters
ptrValueThe 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_MeasureCapacitanceShield()

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 or -short 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 changed capacitance that can be compared against pre-determined capacitance for the shield electrode to detect a fault condition.

By default, all CAPSENSE™ sensors (electrodes) that are not being measured are set to the GND state. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function. When the inactive sensor (electrode) connection is set to the CY_CAPSENSE_SNS_CONNECTION_SHIELD state, all the CAPSENSE™ electrodes are connected to the shield and the total capacitance are measured.

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

Note
This function is available only for the fourth-generation CAPSENSE™.
Parameters
ptrValueThe 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_MeasureCapacitanceSensorElectrode()

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSensorElectrode ( uint32_t  widgetId,
uint32_t  eltdId,
cy_stc_capsense_context_t context 
)

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

This function measures the sensor capacitance for CSD widgets or the electrode capacitance 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 eltdId 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 or -shorted sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns changed 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 default scanning parameters are the following:

  • SnsClk divider (256) is the divider for the sensor clock frequency.
  • NumConv (100) is the number of sub-conversions.
  • The reference CDAC capacitance (886 fF) is equivalent to CDAC Code of 100u.
  • The compensation CDAC is disabled.
  • The CIC2 filter is disabled.
  • The dithering is disabled.
  • The chopping is disabled.

The raw count is converted into capacitance using the following equation:

Cs = Rawcount * RefCDAC capacitance / NumConv

where:

  • Cs is the sensor capacitance.
  • Rawcount is the measured raw count value.

The minimum measurable input by this function is 1pF and the maximum is either 200pF 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 30% and is defined by the RefCDAC tolerance.

By default, all CAPSENSE™ sensors (electrodes) that are not being measured are set to the GND state for CSD measured electrodes (sensors) and to the HIGH-Z state for CSX measured electrodes (Rx and Tx). Shield electrodes are also configured to the GND state. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function.

By default, the both Cmod1 and Cmod2 capacitors are used for the measurement.

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

This function must not be called while the CAPSENSE™ MW is busy by another scan.

Note
This function is available only for the fifth-generation CAPSENSE™.
Parameters
widgetIdSpecifies 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.
eltdIdSpecifies the ID of the electrode within the widget (sensorID for CSD widgets and Rx or Tx electrode ID for CSX widgets).

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.

For the CSX widgets, eltdId is an electrode ID and is defined as Rx ID or Tx ID. The first Rx in a widget corresponds to eltdId = 0, the second Rx in a widget corresponds to eltdId = 1, and so on. The last Tx in a widget corresponds to eltdId = (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.
Parameters
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_MeasureCapacitanceSlotSensors()

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSlotSensors ( uint32_t  slotId,
uint32_t  skipChMask,
cy_stc_capsense_context_t context 
)

Measures the specified slot sensor capacitance in femtofarads.

The function measures the Cp capacitance for CSD widgets and the Cm capacitance for CSX widgets.

This function performs BIST slot scan with predefined parameters, back-calculates the slot sensor capacitances (Cp for CSD and Cm for CSX) by using the raw-count equation, stores the calculated capacitances to the sensor context structure, and returns the measurement status. If the specified slot has a ganged sensor, the capacitance is measured for all the pins ganged together that belong to this sensor.

Besides the sensor capacitance measuring, this function could be used to identify various fault conditions with sensors such as electrically-opened or -shorted sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, the function returns changed 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 regular scan configuration. For the capacitance measurement, the BIST specific scan parameters are used. They can be found in the Electrode capacitance measurement macros group. The CDAC code for the CSD sensors is 100u and that provides about 0.886 pF of the CDAC value and for CSX sensors the CDAC code is 50u (0.443 pF). Compensation CDAC is disabled during the BIST scan. Another default scanning parameters are the following:

  • NumConv (100) is the number of sub-conversions.
  • SnsClk divider (256) is the divider for the sensor clock frequency.

The raw count is converted into capacitance using the following equation:

Cs = Rawcount * CDAC / 2 / NumConv / 2

where:

  • Cs is the sensor capacitance.
  • Rawcount is the measured raw count value.
  • The first divider of 2 is determined by the divided ref_clk frequency usage.
  • The second divider of 2 is used only for CSX sensors.

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

By default, all CAPSENSE™ sensors (electrodes) that are not being measured are set to the GND state for CSD measured electrodes (sensors) and to the HIGH-Z state for CSX measured electrodes (Rx and Tx). Shield electrodes are also configured to the GND state. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function.

By default, the both Cmod1 and Cmod2 capacitors are used for the measurement.

Measured capacitance values (Cp for CSD widgets and Cm for CSX widgets) are stored in the .snsCap field of the cy_stc_capsense_sensor_context_t structure.

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

This function must not be called while the CAPSENSE™ MW is busy by another scan.

Note
This function is available only for the fifth-generation CAPSENSE™.
Parameters
slotIdSpecifies the ID number of the slot to measure sensor capacitance. The slot ID should be in the admissible range.
skipChMaskSpecifies the mask to skip some channels during the slot sensor capacitance measurement. If the bit N in the skipChMask is set to 1, the channel N will be excluded from measuring and all its pins will be set to the inactive sensor connection state (see the .eltdCapCsdISC field of the cy_stc_capsense_bist_context_t structure for CSD widgets and the .eltdCapCsxISC field respectively for CSX widgets).
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_ERROR_E - An unexpected fault occurred during the measurement.

◆ Cy_CapSense_MeasureCapacitanceShieldElectrode()

cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceShieldElectrode ( uint32_t  skipChMask,
cy_stc_capsense_context_t context 
)

Measures shield electrode capacitances in femtofarads.

This function measures the capacitances of all shield electrodes for all enabled MSCv3 channels and returns a status of this measurement. The function checks if there is any CSD widget in the project and if the shield is enabled. The measurement results in femtofarads are stored in the chShieldCap[CY_MSC_ENABLED_CH_NUMBER] array. The pointer to the array is in the .ptrChShieldCap field of the cy_stc_capsense_bist_context_t structure, the CY_MSC_ENABLED_CH_NUMBER define is in the cycfg_peripherals.h file. If the any channel shield consists of several electrodes, the total capacitance of all the shield electrodes is measured.

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

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

By default, all CAPSENSE™ sensors (electrodes) that are not being measured are set to the GND state. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function. When the inactive sensor (electrode) connection is set to the CY_CAPSENSE_SNS_CONNECTION_SHIELD state, all the CAPSENSE™ electrodes are connected to the shield and the total capacitance are measured.

By default, the both Cmod1 and Cmod2 capacitors are used for the measurement.

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

Note
This function is available only for the fifth-generation CAPSENSE™.
Parameters
skipChMaskSpecifies the mask to skip some channels during the shield electrode capacitance measurement. If the bit N in the skipChMask is set to 1, the channel N will be excluded from measuring and all its shield pins will be set to the shield inactive sensor connection state (see the .shieldCapISC field of the cy_stc_capsense_bist_context_t structure).
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_BAD_CONFIG_E - The shield is disabled.

◆ Cy_CapSense_CalibrateAllWidgets()

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.

Note
For the fifth-generation CAPSENSE™ this function is available in single-channel solution. It is recommended to use the Cy_CapSense_CalibrateAllSlots() function instead for compatibility with further CAPSENSE™ middleware versions.
Parameters
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
Returns the status of the operation cy_capsense_status_t.

◆ Cy_CapSense_CalibrateWidget()

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.

Note
For the fifth-generation CAPSENSE™ this function is available in single-channel solution. It is recommended to use the Cy_CapSense_CalibrateAllSlots() function instead for compatibility with further CAPSENSE™ middleware versions.
Parameters
widgetIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
Returns the status of the operation cy_capsense_status_t.

◆ Cy_CapSense_ScanSensor()

cy_capsense_status_t Cy_CapSense_ScanSensor ( uint32_t  widgetId,
uint32_t  sensorId,
cy_stc_capsense_context_t context 
)

Initiates the scanning of the selected sensor in the widget.

Scanning is initiated only if no scan is in progress. Scan finishing can be checked by the Cy_CapSense_IsBusy() function.

Note
For the fifth-generation CAPSENSE™ this function is available in single-channel solution. It is recommended to use the Cy_CapSense_ScanSlots() function instead for compatibility with further CAPSENSE™ middleware versions.
Parameters
widgetIdSpecifies 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.
sensorIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
Returns the status of the operation cy_capsense_status_t.

◆ Cy_CapSense_SetPinState()

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 should be called in StartSample callback (see the Callbacks section for details) or with low-level functions that perform a single-sensor scanning.

Parameters
widgetIdSpecifies 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.
sensorElementSpecifies 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.
stateSpecifies 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).
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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.

◆ Cy_CapSense_SetInactiveElectrodeState()

cy_capsense_status_t Cy_CapSense_SetInactiveElectrodeState ( uint32_t  inactiveState,
uint32_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 during regular scans or BIST capacitance measurements. There are separate states for the CSX sensing method group, the CSD sensing method group, the BIST CSD sensor (electrode) capacitance measurement, the BIST CSX sensor (electrode) capacitance measurement, and the BIST shield electrode capacitance measurement. For instance, it can be configured the GND state for all inactive sensors for CSX scanning and the High-Z state for CSD scanning and the Shield state for BIST CSD sensor (electrode) capacitance measurement. The function updates some corresponding parameters in the CAPSENSE™ Data Structure to provide the desired state and not changes pin state immediately. The desired state will be applied to all inactive electrodes during the CSD or CSX scans or BIST capacitance measurements. 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.

Parameters
inactiveStateSpecifies the inactive CAPSENSE™ electrode state:
  • CY_CAPSENSE_SNS_CONNECTION_HIGHZ
  • CY_CAPSENSE_SNS_CONNECTION_SHIELD (only for CSD scan)
  • CY_CAPSENSE_SNS_CONNECTION_GROUND
sensingGroupSpecifies the sensing group:
  • CY_CAPSENSE_CSD_GROUP
  • CY_CAPSENSE_CSX_GROUP
  • CY_CAPSENSE_BIST_CSD_GROUP
  • CY_CAPSENSE_BIST_CSX_GROUP
  • CY_CAPSENSE_BIST_SHIELD_GROUP
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
Returns the status of the operation cy_capsense_status_t.

◆ Cy_CapSense_SetupWidgetExt()

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
widgetIdSpecifies 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.
sensorIdSpecifies 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_ScanExt()

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
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

◆ Cy_CapSense_CalibrateAllSlots()

cy_capsense_status_t Cy_CapSense_CalibrateAllSlots ( cy_stc_capsense_context_t context)

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

Having enabled the CDAC auto-calibration algorithm is the most common use case. It helps to tune your system considering board-to-board variation, temperature drift, etc. CDAC auto-calibration is enabled by default.

The function performs searching of Reference CDAC code, Compensation CDAC code Compensation Divider (whichever is enabled) by using a successive approximation method to make the sensor's raw count closest to the defined targets. The auto-calibration target values are defined (by default) as:

  • 85% of the maximum raw count for CSD widgets
  • 40% of the maximum raw count for CSX widgets.

To change calibration targets use the Cy_CapSense_SetCalibrTarget() function.

Note
This function is available only for the fifth-generation CAPSENSE™.
Parameters
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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_CALIBRATION_FAIL - The calibration is failed due to the issues with scanning (either watchdog timer, interrupt breaking, etc.).
  • CY_CAPSENSE_STATUS_CALIBRATION_CHECK_FAIL - The calibration is failed because of rawcount is out of the defined range.

◆ Cy_CapSense_SetCalibrationTargets()

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.

Note
This function is available only for the fifth-generation CAPSENSE™.
Parameters
csdCalibrTargetThe 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.
csxCalibrTargetThe 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.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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.

◆ Cy_CapSense_SlotPinState()

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_PIN_STATE_SHIELD is not available if shield is not configured in the project.

Parameters
slotIdThe desired slot ID.
ptrEltdCfgThe pointer to an electrode the all pins states of which will be configured as pinState parameter.
pinStateThe desired pins state for CSX widget electrodes:
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_RX - Rx electrode.
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_TX - Tx electrode.
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_GND - Grounded.
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_TX_NEGATIVE - Negative Tx electrode (for multi-phase TX method).
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_HIGH_Z - Unconnected (high-z).
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_VDDA2 - Connected to VDDA/2. The desired pins state for CSD widget electrodes:
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_SNS - Self-cap sensor.
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_HIGH_Z - Unconnected (high-z).
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_GND - Grounded.
  • CY_CAPSENSE_CTRLMUX_PIN_STATE_SHIELD - Shield is routed to the pin.
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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.

◆ Cy_CapSense_ScanAbort()

cy_capsense_status_t Cy_CapSense_ScanAbort ( cy_stc_capsense_context_t context)

This function sets the sequencer to the idle state by resetting the hardware, it can be used to abort current scan.

Note
This function is available only for the fifth-generation CAPSENSE™.
If this function is called from ISR during initialization or auto-calibration the operation of these functions will be corrupted.
Parameters
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
Returns the status of the operation cy_capsense_status_t.

◆ Cy_CapSense_GetParam()

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
Parameters
paramIdSpecifies the ID of parameter to get its value. A macro for the parameter ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<ParameterName>_PARAM_ID.
valueThe pointer to a variable to be updated with the obtained value.
ptrTunerThe 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
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
Returns the status of the operation. If CY_CAPSENSE_STATUS_SUCCESS is not received, either paramId is invalid or ptrTuner is null.

◆ Cy_CapSense_SetParam()

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.

Parameters
paramIdSpecifies the ID of parameter to set its value. A macro for the parameter ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<ParameterName>_PARAM_ID.
valueSpecifies the new parameter's value.
ptrTunerThe 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
contextThe pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.
Returns
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.

◆ Cy_CapSense_GetCRC()

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"

Parameters
ptrDataThe pointer to the data.
lenThe length of the data in bytes.
Returns
Returns a calculated CRC-16 value.