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.

The functions that contain CSD or CSX in the name are specified for that sensing method appropriately and should be used only with dedicated widgets having that mode. All other 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_status	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_status	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...
cy_status	Cy_CapSense_CSDCalibrateWidget (uint32_t widgetId, uint32_t target, cy_stc_capsense_context_t *context)
	Executes the IDAC calibration for all the sensors in the widget specified in the input. More...
void	Cy_CapSense_CSDSetupWidget (uint32_t widgetId, cy_stc_capsense_context_t *context)
	Performs the initialization required to scan the specified CSD widget. More...
void	Cy_CapSense_CSDSetupWidgetExt (uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context)
	Performs extended initialization required to scan a specified sensor in a widget using CSD sensing method. More...
void	Cy_CapSense_CSDScan (cy_stc_capsense_context_t *context)
	This function initiates a scan for the sensors of the widget initialized by the Cy_CapSense_CSDSetupWidget() function. More...
void	Cy_CapSense_CSDScanExt (cy_stc_capsense_context_t *context)
	Starts the CSD conversion on the preconfigured sensor. More...
void	Cy_CapSense_CSDConnectSns (const cy_stc_capsense_pin_config_t *snsAddrPtr, cy_stc_capsense_context_t *context)
	Connects port pin to the CSD HW block using AMUX bus. More...
void	Cy_CapSense_CSDDisconnectSns (const cy_stc_capsense_pin_config_t *snsAddrPtr, const cy_stc_capsense_context_t *context)
	Disconnects port pin from the CSD HW block by disconnecting it from AMUX bus. More...
cy_status	Cy_CapSense_CSXCalibrateWidget (uint32_t widgetId, uint32_t target, cy_stc_capsense_context_t *context)
	Executes the IDAC calibration for all the sensors in the widget specified in the input. More...
void	Cy_CapSense_CSXSetupWidget (uint32_t widgetId, cy_stc_capsense_context_t *context)
	Performs the initialization required to scan the specified CSX widget. More...
void	Cy_CapSense_CSXSetupWidgetExt (uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context)
	Performs extended initialization required to scan a specified sensor in a widget using CSX sensing method. More...
void	Cy_CapSense_CSXScan (cy_stc_capsense_context_t *context)
	This function initiates a scan for the sensors of the widget initialized by the Cy_CapSense_CSXSetupWidget() function. More...
void	Cy_CapSense_CSXScanExt (cy_stc_capsense_context_t *context)
	Starts the CSD conversion on the preconfigured sensor. More...
void	Cy_CapSense_CSXConnectRx (const cy_stc_capsense_pin_config_t *rxPtr, cy_stc_capsense_context_t *context)
	Connects port pin (an Rx electrode) to the CSD HW block using AMUX bus. More...
void	Cy_CapSense_CSXConnectTx (const cy_stc_capsense_pin_config_t *txPtr, cy_stc_capsense_context_t *context)
	Connects port pin (a Tx electrode) to the CSD HW block. More...
void	Cy_CapSense_CSXDisconnectRx (const cy_stc_capsense_pin_config_t *rxPtr, cy_stc_capsense_context_t *context)
	Disconnects port pin (an Rx electrode) from the CSD HW block by disconnecting it from the AMUX bus. More...
void	Cy_CapSense_CSXDisconnectTx (const cy_stc_capsense_pin_config_t *txPtr, cy_stc_capsense_context_t *context)
	Disconnects port pin (a Tx electrode) from the CSD HW block. 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_status	Cy_CapSense_UpdateAllBaselines (const cy_stc_capsense_context_t *context)
	Updates the baseline for all the sensors in all the widgets. More...
cy_status	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_status	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_status	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_status	Cy_CapSense_ScanExt (cy_stc_capsense_context_t *context)
	Starts a conversion on the pre-configured sensor. More...
cy_status	Cy_CapSense_CalibrateWidget (uint32_t widgetId, cy_stc_capsense_context_t *context)
	Executes the IDAC calibration for all the sensors in the specified widget to the default target value. More...
cy_status	Cy_CapSense_CalibrateAllWidgets (cy_stc_capsense_context_t *context)
	Executes the IDAC calibration for all the sensors in all widgets in the middleware to default target value. More...
cy_status	Cy_CapSense_CalibrateAllCsdWidgets (cy_stc_capsense_context_t *context)
	Executes the IDAC calibration for all the sensors in CSD widgets to the default target value. More...
cy_status	Cy_CapSense_CalibrateAllCsxWidgets (cy_stc_capsense_context_t *context)
	Executes the IDAC calibration for all the sensors in CSX widgets to the default target value. More...
cy_status	Cy_CapSense_SetPinState (uint32_t widgetId, uint32_t sensorElement, uint32_t state, cy_stc_capsense_context_t *context)
	Sets the state (drive mode and HSIOM state) of the GPIO used by a sensor. More...

Function Documentation

Cy_CapSense_ProcessWidgetExt()

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

Performs customized data processing on the selected widget.

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

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

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

For more details, refer to function usage example below.

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
mode	Specifies the type of widget processing to be executed for the specified widget: Bits [31..6] - Reserved. Bits [5..0] - CY_CAPSENSE_PROCESS_ALL - Execute all of the below tasks. Bit [5] - CY_CAPSENSE_PROCESS_STATUS - Update the status (on/off, centroid position). Bit [4] - CY_CAPSENSE_PROCESS_THRESHOLDS - Update the thresholds (only in CSD auto-tuning mode). Bit [3] - CY_CAPSENSE_PROCESS_CALC_NOISE - Calculate the noise (only in CSD auto-tuning mode). Bit [2] - CY_CAPSENSE_PROCESS_DIFFCOUNTS - Update the difference counts of each sensor. Bit [1] - CY_CAPSENSE_PROCESS_BASELINE - Update the baselines for all sensor. Bit [0] - CY_CAPSENSE_PROCESS_FILTER - Run the firmware filters on sensor rawcounts.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the widget processing operation:

• CY_RET_SUCCESS - The processing is successfully performed.
• CY_RET_BAD_PARAM - The input parameter is invalid.
• CY_RET_BAD_DATA - The processing failed.

Function Usage

An example of customized data processing, changed processing order:

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

Cy_CapSense_ProcessSensorExt()

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

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
sensorId	Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.
mode	Specifies the type of the sensor processing that must be executed for the specified sensor: Bits [31..5] - Reserved Bits [4..0] - CY_CAPSENSE_PROCESS_ALL - Executes all the tasks Bit [4] - CY_CAPSENSE_PROCESS_THRESHOLDS - Updates the thresholds (only in auto-tuning mode) Bit [3] - CY_CAPSENSE_PROCESS_CALC_NOISE - Calculates the noise (only in auto-tuning mode) Bit [2] - CY_CAPSENSE_PROCESS_DIFFCOUNTS - Updates the diff count Bit [1] - CY_CAPSENSE_PROCESS_BASELINE - Updates the baseline Bit [0] - CY_CAPSENSE_PROCESS_FILTER - Runs the firmware filters
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the sensor process operation:

• CY_RET_SUCCESS - The processing is successfully performed.
• CY_RET_BAD_PARAM - The input parameter is invalid.
• CY_RET_BAD_DATA - The processing failed.

Function Usage

An example demonstrates pipeline implementation of sensor scanning and processing:

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

    /* Trigger scanning */
    Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, snsIndex, &cy_capsense_context);
    Cy_CapSense_ScanExt(&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)
            {
                /* Trigger the next sensor scanning and process previous sensor */
                Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, snsIndex, &cy_capsense_context);
                Cy_CapSense_ScanExt(&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_CSDCalibrateWidget()

cy_status Cy_CapSense_CSDCalibrateWidget	(	uint32_t	widgetId,
		uint32_t	target,
		cy_stc_capsense_context_t *	context
	)

Executes the IDAC calibration for all the sensors in the widget specified in the input.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_CalibrateWidget() function should be used instead.

Performs a successive approximation search algorithm to find appropriate modulator and compensation IDAC (if enabled) values for all sensors in the specified widget that provide the raw count to the level specified by the target parameter.

Calibration returns CYRET_BAD_DATA if the achieved raw count is outside of the range specified by the target and acceptable calibration deviation parameters.

This function could be used when the CSD Enable IDAC auto-calibration parameter is enabled. Do not use this function when the SmartSense auto-tuning mode is configured.

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
target	Specifies the calibration target in percentages of the maximum raw count.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the specified widget calibration:

• CYRET_SUCCESS - The operation is successfully completed.
• CYRET_BAD_PARAM - The input parameter is invalid.
• CYRET_BAD_DATA - The calibration failed and CapSense may not operate as expected.
• CYRET_INVALID_STATE - The previous scanning is not completed, and the CapSense middleware is busy.

Cy_CapSense_CSDSetupWidget()

void Cy_CapSense_CSDSetupWidget	(	uint32_t	widgetId,
		cy_stc_capsense_context_t *	context
	)

Performs the initialization required to scan the specified CSD widget.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_SetupWidget() function should be used instead.

This function prepares the middleware to scan all the sensors in the specified CSD widget by executing the following tasks:

1. Configure the CSD HW block if it is not configured to perform the CSD sensing method used by the specified widget.
2. Initialize the CSD HW block with specific sensing configuration (e.g. sensor clock, scan resolution) used by the widget.
3. Disconnect all previously connected electrodes, if the electrodes connected by the Cy_CapSense_CSDSetupWidgetExt(), Cy_CapSense_CSXSetupWidgetExt() functions are not disconnected.

This function does not start sensor scanning. The Cy_CapSense_CSDScan() function must be called to start the scan sensors in the widget. If this function is called more than once, it does not break the middleware operation, but only the last initialized widget is in effect. 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 example faster execution).

The status of a sensor scan must be checked using the Cy_CapSense_IsBusy() function prior to starting a next scan or setting up another widget.

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CSDSetupWidgetExt()

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

Performs extended initialization required to scan a specified sensor in a widget using CSD sensing method.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_SetupWidgetExt() function should be used instead.

This function performs the same tasks of Cy_CapSense_CSDSetupWidget() and also connects and configures specified sensor for scan. Hence this function, along with Cy_CapSense_CSDScanExt() function, can be used to scan a specific sensor in the widget.

This function should be called for widget that is configured to use CSD sensing method, using this function on a non-CSD sensing widget would cause unexpected result.

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

Calling this function directly from the application layer is not recommended. This function is used to implement only the user's specific use cases (for example faster execution).

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
sensorId	Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CSDScan()

void Cy_CapSense_CSDScan

(

cy_stc_capsense_context_t *

context

)

This function initiates a scan for the sensors of the widget initialized by the Cy_CapSense_CSDSetupWidget() function.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_Scan() function should be used instead.

This function does the following tasks:

1. Connects the first sensor of the widget.
2. Configures the IDAC value.
3. Starts scanning for the first sensor in the widget.

This function is called by the Cy_CapSense_Scan() if the given widget uses the CSD sensing method.

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 example faster execution).

This function is called when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status and the widget must be preconfigured using the Cy_CapSense_CSDSetupWidget() function prior to calling this function.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CSDScanExt()

void Cy_CapSense_CSDScanExt

(

cy_stc_capsense_context_t *

context

)

Starts the CSD conversion on the preconfigured sensor.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_ScanExt() function should be used instead.

This function performs scanning of a specific sensor in the widget previously initialized using the Cy_CapSense_CSDSetupWidgetExt() function.

This function is called when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status and the widget must be preconfigured using Cy_CapSense_CSDSetupWidgetExt() function prior to calling this 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 example faster execution).

This function does not disconnect sensor GPIOs from CSD HW block at the end of a scan, therefore making subsequent scan of the same sensor is faster. If sensor needs to be disconnected after the scan, Cy_CapSense_CSDDisconnectSns() function can be used.

Calling Cy_CapSense_SetupWidget(), Cy_CapSense_CSDSetupWidget(), Cy_CapSense_ScanAllWidgets(), or if Cy_CapSense_RunTuner() returns CY_CAPSENSE_STATUS_RESTART_DONE status invalidated initialization made by this function.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CSDConnectSns()

void Cy_CapSense_CSDConnectSns	(	const cy_stc_capsense_pin_config_t *	snsAddrPtr,
		cy_stc_capsense_context_t *	context
	)

Connects port pin to the CSD HW block using AMUX bus.

This function can be used to customize the default sensor connection by connecting one or more pins to an existing sensor prior to initiating scan of the sensor.

The function ignores whether the sensor is a ganged sensor and connects only a specified port pin to the CSD HW block. This function can only use GPIOs that are already assigned to CapSense middleware.

The functions that perform a setup and scan of a sensor/widget do not take into account changes in the design made by the Cy_CapSense_CSDConnectSns() function, hence all GPIOs connected using this function must be disconnected using the Cy_CapSense_CSDDisconnectSns() function prior to initializing new widgets. Use this function in StartSample callback (see the Callbacks section for details) or with low-level functions that perform a single-sensor scanning.

Scanning should be completed before calling this function.

Parameters

snsAddrPtr	Specifies the pointer to the cy_stc_capsense_pin_config_t object belonging to a sensor that is to be connected to the CSD HW block.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Function Usage

An example of using the function to perform port pin re-connection:

    /*...*/
    Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 0u, &cy_capsense_context);

    /* Connects a desired port pin as a sensor */
    Cy_CapSense_CSDConnectSns(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD0_SNS1_ID]), &cy_capsense_context);

    Cy_CapSense_ScanExt(&cy_capsense_context);
    while (CY_CAPSENSE_NOT_BUSY != Cy_CapSense_IsBusy(&cy_capsense_context)){}

    /* Disconnects a desired port pin */
    Cy_CapSense_CSDDisconnectSns(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD0_SNS1_ID]), &cy_capsense_context);
    /*...*/

Cy_CapSense_CSDDisconnectSns()

void Cy_CapSense_CSDDisconnectSns	(	const cy_stc_capsense_pin_config_t *	snsAddrPtr,
		const cy_stc_capsense_context_t *	context
	)

Disconnects port pin from the CSD HW block by disconnecting it from AMUX bus.

This function can be used to disconnect a sensor connected using the Cy_CapSense_CSDConnectSns() function. In addition, this function can be used to customize a default sensor connection by disconnecting one or more already connected sensors prior to initiating a scan of the sensor.

This function works identically to the Cy_CapSense_CSDConnectSns() function except it disconnects the specified port pin used by the sensor.

Scanning should be completed before calling this function.

Parameters

snsAddrPtr	Specifies the pointer to the cy_stc_capsense_pin_config_t object belonging to a sensor that should be disconnected from the CSD HW block.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Function Usage

An example of using the function to perform port pin re-connection:

    /*...*/
    Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 0u, &cy_capsense_context);

    /* Connects a desired port pin as a sensor */
    Cy_CapSense_CSDConnectSns(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD0_SNS1_ID]), &cy_capsense_context);

    Cy_CapSense_ScanExt(&cy_capsense_context);
    while (CY_CAPSENSE_NOT_BUSY != Cy_CapSense_IsBusy(&cy_capsense_context)){}

    /* Disconnects a desired port pin */
    Cy_CapSense_CSDDisconnectSns(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD0_SNS1_ID]), &cy_capsense_context);
    /*...*/

Cy_CapSense_CSXCalibrateWidget()

cy_status Cy_CapSense_CSXCalibrateWidget	(	uint32_t	widgetId,
		uint32_t	target,
		cy_stc_capsense_context_t *	context
	)

Executes the IDAC calibration for all the sensors in the widget specified in the input.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_CalibrateWidget() function should be used instead.

Performs a successive approximation search algorithm to find appropriate IDAC values for all sensors in the specified widget that provide the raw count to the level specified by the target parameter.

Calibration returns CYRET_BAD_DATA if the achieved raw count is outside of the range specified by the target and acceptable calibration deviation parameters.

This function could be used when the CSX Enable IDAC auto-calibration parameter is enabled.

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
target	Specifies the calibration target in percentages of the maximum raw count.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the specified widget calibration:

• CYRET_SUCCESS - The operation is successfully completed.
• CYRET_BAD_PARAM - The input parameter is invalid.
• CYRET_BAD_DATA - The calibration failed and CapSense may not operate as expected.
• CYRET_INVALID_STATE - The previous scanning is not completed, and the CapSense middleware is busy.

Cy_CapSense_CSXSetupWidget()

void Cy_CapSense_CSXSetupWidget	(	uint32_t	widgetId,
		cy_stc_capsense_context_t *	context
	)

Performs the initialization required to scan the specified CSX widget.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_SetupWidget() function should be used instead.

This function prepares the middleware to scan all the sensors in the specified CSX widget by executing the following tasks:

1. Configure the CSD HW block if it is not configured to perform the CSX sensing method used by the specified widget.
2. Initialize the CSD HW block with specific sensing configuration (e.g. sensor clock, scan resolution) used by the widget.
3. Disconnect all previously connected electrodes, if the electrodes connected by the Cy_CapSense_CSDSetupWidgetExt(), Cy_CapSense_CSXSetupWidgetExt() functions are not disconnected.

This function does not start sensor scanning. The Cy_CapSense_CSXScan() function must be called to start the scan sensors in the widget. If this function is called more than once, it does not break the middleware operation, but only the last initialized widget is in effect. 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 example faster execution).

The status of a sensor scan must be checked using the Cy_CapSense_IsBusy() function prior to starting a next scan or setting up another widget.

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CSXSetupWidgetExt()

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

Performs extended initialization required to scan a specified sensor in a widget using CSX sensing method.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_SetupWidgetExt() function should be used instead.

This function performs the same tasks of Cy_CapSense_CSXSetupWidget() and also connects and configures specified sensor for scan. Hence this function, along with Cy_CapSense_CSXScanExt() function, can be used to scan a specific sensor in the widget.

This function should be called for a widget that is configured to use CSX sensing method. Using this function on a non-CSX sensing widget would cause an unexpected result.

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

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 example faster execution).

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
sensorId	Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CSXScan()

void Cy_CapSense_CSXScan

(

cy_stc_capsense_context_t *

context

)

This function initiates a scan for the sensors of the widget initialized by the Cy_CapSense_CSXSetupWidget() function.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_Scan() function should be used instead.

This function does the following tasks:

1. Connects the first sensor of the widget.
2. Configures the IDAC value.
3. Starts scanning for the first sensor in the widget.

This function is called by the Cy_CapSense_Scan() if the given widget uses the CSX sensing method.

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 example faster execution).

This function is called when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status and the widget must be preconfigured using the Cy_CapSense_CSXSetupWidget() function prior to calling this function.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CSXScanExt()

void Cy_CapSense_CSXScanExt

(

cy_stc_capsense_context_t *

context

)

Starts the CSD conversion on the preconfigured sensor.

Note

This function is obsolete and kept for backward compatibility only. The Cy_CapSense_ScanExt() function should be used instead.

This function performs scanning of a specific sensor in the widget previously initialized using the Cy_CapSense_CSXSetupWidgetExt() function.

This function is called when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status and the widget must be preconfigured using Cy_CapSense_CSXSetupWidgetExt() function prior to calling this 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 example faster execution).

This function does not disconnect sensor GPIOs from CSD HW block at the end of a scan, therefore making subsequent scan of the same sensor is faster. If sensor must be disconnected after the scan, the Cy_CapSense_CSXDisconnectTx() or Cy_CapSense_CSXDisconnectRx() functions can be used.

Calling Cy_CapSense_SetupWidget(), Cy_CapSense_CSXSetupWidget(), Cy_CapSense_ScanAllWidgets(), or if Cy_CapSense_RunTuner() returns CY_CAPSENSE_STATUS_RESTART_DONE status invalidated initialization made by this function.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CSXConnectRx()

void Cy_CapSense_CSXConnectRx	(	const cy_stc_capsense_pin_config_t *	rxPtr,
		cy_stc_capsense_context_t *	context
	)

Connects port pin (an Rx electrode) to the CSD HW block using AMUX bus.

This function can be used to customize the default sensor connection by connecting one or more pins to an existing sensor as an Rx electrode prior to initiating scan of the sensor.

The function ignores whether the sensor is a ganged sensor and connects only a specified port pin to the CSD HW block. This function can only use GPIOs that is already assigned to CapSense middleware.

The functions that perform a setup and scan of a sensor/widget do not take into account changes in the design made by the Cy_CapSense_CSXConnectRx() function. Hence all GPIOs connected using this function must be disconnected using the Cy_CapSense_CSXDisconnectRx() function prior to initializing new widgets. Use this function in StartSample callback (see the Callbacks section for details) or with low-level functions that perform a single-sensor scanning.

Scanning should be completed before calling this function.

Parameters

rxPtr	Specifies the pointer to the cy_stc_capsense_pin_config_t object belonging to a sensor which to be connected to the CSD HW block as an Rx electrode.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Function Usage

An example of using the function to perform port pin re-connection:

    /*...*/
    Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 0u, &cy_capsense_context);

    /* Connects a desired port pin as an extra Tx electrode */
    Cy_CapSense_CSXConnectTx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_TX1_ID]), &cy_capsense_context);
    /* Connects a desired port pin as an extra Tx electrode */
    Cy_CapSense_CSXConnectRx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_RX1_ID]), &cy_capsense_context);

    Cy_CapSense_ScanExt(&cy_capsense_context);
    while (CY_CAPSENSE_NOT_BUSY != Cy_CapSense_IsBusy(&cy_capsense_context)){}

    /* Restore the port pins states */
    Cy_CapSense_CSXDisconnectTx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_TX1_ID]), &cy_capsense_context);
    Cy_CapSense_CSXDisconnectRx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_RX1_ID]), &cy_capsense_context);
    /*...*/

Cy_CapSense_CSXConnectTx()

void Cy_CapSense_CSXConnectTx	(	const cy_stc_capsense_pin_config_t *	txPtr,
		cy_stc_capsense_context_t *	context
	)

Connects port pin (a Tx electrode) to the CSD HW block.

This function can be used to customize the default sensor connection by connecting one or more pins to an existing sensor as a Tx electrode prior to initiating scan of the sensor.

The function ignores whether the sensor is a ganged sensor and connects only a specified port pin to the CSD HW block. This function can only use GPIOs that is already assigned to CapSense middleware.

The functions that perform a setup and scan of a sensor/widget do not take into account changes in the design made by the Cy_CapSense_CSXConnectTx() function. Hence all GPIOs connected using this function must be disconnected using the Cy_CapSense_CSXDisconnectTx() function prior to initializing new widgets. Use this function in StartSample callback (see the Callbacks section for details) or with low-level functions that perform a single-sensor scanning.

Scanning should be completed before calling this function.

Parameters

txPtr	Specifies the pointer to the cy_stc_capsense_pin_config_t object belonging to a sensor which to be connected to the CSD HW block as a Tx electrode.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Function Usage

An example of using the function to perform port pin re-connection:

    /*...*/
    Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 0u, &cy_capsense_context);

    /* Connects a desired port pin as an extra Tx electrode */
    Cy_CapSense_CSXConnectTx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_TX1_ID]), &cy_capsense_context);
    /* Connects a desired port pin as an extra Tx electrode */
    Cy_CapSense_CSXConnectRx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_RX1_ID]), &cy_capsense_context);

    Cy_CapSense_ScanExt(&cy_capsense_context);
    while (CY_CAPSENSE_NOT_BUSY != Cy_CapSense_IsBusy(&cy_capsense_context)){}

    /* Restore the port pins states */
    Cy_CapSense_CSXDisconnectTx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_TX1_ID]), &cy_capsense_context);
    Cy_CapSense_CSXDisconnectRx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_RX1_ID]), &cy_capsense_context);
    /*...*/

Cy_CapSense_CSXDisconnectRx()

void Cy_CapSense_CSXDisconnectRx	(	const cy_stc_capsense_pin_config_t *	rxPtr,
		cy_stc_capsense_context_t *	context
	)

Disconnects port pin (an Rx electrode) from the CSD HW block by disconnecting it from the AMUX bus.

This function can be used to disconnect a sensor connected using the Cy_CapSense_CSXConnectRx() function. In addition, this function can be used to customize default sensor connection by disconnecting one or more already connected sensors prior to initiating scan of the sensor.

This function works identically to the Cy_CapSense_CSDConnectRx() function except it disconnects the specified port pin used by the sensor.

Scanning should be completed before calling this function.

Parameters

rxPtr	Specifies the pointer to the cy_stc_capsense_pin_config_t object belonging to an Rx pin sensor to be disconnected from the CSD HW block.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Function Usage

An example of using the function to perform port pin re-connection:

    /*...*/
    Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 0u, &cy_capsense_context);

    /* Connects a desired port pin as an extra Tx electrode */
    Cy_CapSense_CSXConnectTx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_TX1_ID]), &cy_capsense_context);
    /* Connects a desired port pin as an extra Tx electrode */
    Cy_CapSense_CSXConnectRx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_RX1_ID]), &cy_capsense_context);

    Cy_CapSense_ScanExt(&cy_capsense_context);
    while (CY_CAPSENSE_NOT_BUSY != Cy_CapSense_IsBusy(&cy_capsense_context)){}

    /* Restore the port pins states */
    Cy_CapSense_CSXDisconnectTx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_TX1_ID]), &cy_capsense_context);
    Cy_CapSense_CSXDisconnectRx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_RX1_ID]), &cy_capsense_context);
    /*...*/

Cy_CapSense_CSXDisconnectTx()

void Cy_CapSense_CSXDisconnectTx	(	const cy_stc_capsense_pin_config_t *	txPtr,
		cy_stc_capsense_context_t *	context
	)

Disconnects port pin (a Tx electrode) from the CSD HW block.

This function can be used to disconnect a sensor connected using the Cy_CapSense_CSXConnectTx() function. In addition, this function can be used to customize default sensor connection by disconnecting one or more already connected sensors prior to initiating scan of the sensor.

This function works identically to the Cy_CapSense_CSDConnectTx() function except it disconnects the specified port pin used by the sensor.

Scanning should be completed before calling this function.

Parameters

txPtr	Specifies the pointer to the cy_stc_capsense_pin_config_t object belonging to a Tx pin sensor to be disconnected from the CSD HW block.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Function Usage

An example of using the function to perform port pin re-connection:

    /*...*/
    Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 0u, &cy_capsense_context);

    /* Connects a desired port pin as an extra Tx electrode */
    Cy_CapSense_CSXConnectTx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_TX1_ID]), &cy_capsense_context);
    /* Connects a desired port pin as an extra Tx electrode */
    Cy_CapSense_CSXConnectRx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_RX1_ID]), &cy_capsense_context);

    Cy_CapSense_ScanExt(&cy_capsense_context);
    while (CY_CAPSENSE_NOT_BUSY != Cy_CapSense_IsBusy(&cy_capsense_context)){}

    /* Restore the port pins states */
    Cy_CapSense_CSXDisconnectTx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_TX1_ID]), &cy_capsense_context);
    Cy_CapSense_CSXDisconnectRx(&(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD1_WDGT_ID].ptrEltdConfig->ptrPin[CY_CAPSENSE_TOUCHPAD1_RX1_ID]), &cy_capsense_context);
    /*...*/

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:

• Cy_CapSense_InitializeAllStatuses()
• Cy_CapSense_InitializeAllFilters()

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

Parameters

context

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

• Cy_CapSense_InitializeWidgetStatus()
• Cy_CapSense_InitializeWidgetFilter()

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

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

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

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
sensorId	Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_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

• Cy_CapSense_InitializeAllStatuses()
• Cy_CapSense_InitializeAllBaselines()

Parameters

context

The 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

• Cy_CapSense_InitializeWidgetStatus().
• Cy_CapSense_InitializeWidgetBaseline().

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_UpdateAllBaselines()

cy_status 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

context

The 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_RET_SUCCESS - The operation is successfully completed.
• CY_RET_BAD_DATA - The baseline processing failed.

Cy_CapSense_UpdateWidgetBaseline()

cy_status 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

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the specified widget update baseline operation:

• CY_RET_SUCCESS - The operation is successfully completed.
• CY_RET_BAD_DATA - The baseline processing failed.

Cy_CapSense_UpdateSensorBaseline()

cy_status 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

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
sensorId	Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the specified sensor update baseline operation:

• CY_RET_SUCCESS - The operation is successfully completed.
• CY_RET_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

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_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

• Cy_CapSense_InitializeAllBaselines().
• Cy_CapSense_InitializeAllFilters().

Parameters

context

The 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

• Cy_CapSense_InitializeWidgetBaseline().
• Cy_CapSense_InitializeWidgetFilter().

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_SetupWidgetExt()

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

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
sensorId	Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_ScanExt()

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

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Cy_CapSense_CalibrateWidget()

cy_status Cy_CapSense_CalibrateWidget	(	uint32_t	widgetId,
		cy_stc_capsense_context_t *	context
	)

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

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the specified widget calibration:

• CY_RET_SUCCESS - The operation is successfully completed.
• CY_RET_BAD_PARAM - The input parameter is invalid.
• CY_RET_BAD_DATA - The calibration failed and the middleware may not operate as expected.

Cy_CapSense_CalibrateAllWidgets()

cy_status Cy_CapSense_CalibrateAllWidgets

(

cy_stc_capsense_context_t *

context

)

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

Calibration returns CYRET_BAD_DATA if resulted raw count is outside the limits.

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

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the calibration process:

• CY_RET_SUCCESS - The operation is successfully completed.
• CY_RET_BAD_DATA - The calibration failed and the middleware may not operate as expected.

Cy_CapSense_CalibrateAllCsdWidgets()

cy_status Cy_CapSense_CalibrateAllCsdWidgets

(

cy_stc_capsense_context_t *

context

)

Executes the IDAC calibration for all the sensors in CSD widgets to the default target value.

This function performs exact same tasks of Cy_CapSense_CalibrateAllWidgets(), but only for CSD widgets.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the operation:

• Zero - All the widgets are calibrated successfully.
• Non-zero - Calibration failed for at least one widget.

Cy_CapSense_CalibrateAllCsxWidgets()

cy_status Cy_CapSense_CalibrateAllCsxWidgets

(

cy_stc_capsense_context_t *

context

)

Executes the IDAC calibration for all the sensors in CSX widgets to the default target value.

This function performs the exact same tasks of Cy_CapSense_CalibrateAllWidgets(), but only for CSX widgets.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the operation:

• Zero - All the widgets are calibrated successfully.
• Non-zero - Calibration failed for at least one widget.

Cy_CapSense_SetPinState()

cy_status Cy_CapSense_SetPinState	(	uint32_t	widgetId,
		uint32_t	sensorElement,
		uint32_t	state,
		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, Rx, and Sensor. If the sensor specified in the input parameter is a ganged sensor, then the state of all GPIOs associated with the ganged sensor is updated.

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

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

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

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

Parameters

widgetId	Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID.
sensorElement	Specifies the ID of the sensor element within the widget to change its pin state. For the CSD widgets use the sensor ID. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID. For the CSX widgets use either Rx ID or Tx ID. The first Rx in a widget corresponds to sensorElement = 0; the second Rx in a widget corresponds to sensorElement = 1, and so on. The last Tx in a widget corresponds to sensorElement = (RxNum + TxNum - 1). A macro for the Rx ID or Tx ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_<TX/RX><TX/RX_NUMBER>_ID.
state	Specifies the state of the sensor to be set: CY_CAPSENSE_GROUND - The pin is connected to the ground. CY_CAPSENSE_HIGHZ - The drive mode of the pin is set to High-Z Analog. CY_CAPSENSE_SHIELD - The shield signal is routed to the pin (available only if CSD sensing method with shield electrode is enabled). CY_CAPSENSE_SENSOR - The pin is connected to the scanning bus (available only if CSD sensing method is enabled). CY_CAPSENSE_TX_PIN - The Tx signal is routed to the sensor (available only if CSX sensing method is enabled). CY_CAPSENSE_RX_PIN - The pin is connected to the scanning bus (available only if CSX sensing method is enabled).
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

status Returns the operation status:

• CY_RET_SUCCESS - Indicates the successful electrode setting.
• CY_RET_BAD_PARAM - 1) widgetID or sensorElement 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 or CY_CAPSENSE_RX_PIN states.

Function Usage

An example of using the Cy_CapSense_SetPinState() function to perform sensor state re-configuration:

    /*...*/
    Cy_CapSense_SetupWidgetExt(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 0u, &cy_capsense_context);

    /* This call changes state of the second sensor from GROUND to HIGH-Z */
    Cy_CapSense_SetPinState(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 1u, CY_CAPSENSE_HIGHZ, &cy_capsense_context);

    Cy_CapSense_ScanExt(&cy_capsense_context);
    while (CY_CAPSENSE_NOT_BUSY != Cy_CapSense_IsBusy(&cy_capsense_context)){}

    /* This call restores the sensor state to GROUND */
    Cy_CapSense_SetPinState(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, 1u, CY_CAPSENSE_GROUND, &cy_capsense_context);
    /*...*/