High-level Functions

General Description

High-level functions represent the highest abstraction layer of the CAPSENSE™ middleware.

These functions perform tasks such as scanning, data processing, data reporting and tuning interfaces. When performing a task, different initialization is required based on a sensing method or type of widgets is automatically handled by these functions. Therefore, these functions are sensing methods, features, and widget type agnostics. The only exception is the functions for low power widget scanning, they are available only for the fifth-generation low power CAPSENSE™.

All the tasks required to implement a sensing system can be fulfilled by the high-level functions. But, there is a set of Low-level Functions that provides access to lower level and specific tasks. If a design requires access to low-level tasks, these functions can be used. The functions related to a given sensing methods are not available if the corresponding method is disabled.

Functions
cy_capsense_status_t	Cy_CapSense_Init (cy_stc_capsense_context_t *context)
	Captures HW blocks (one or more) for CAPSENSE™ operations and configures them to the default state. More...
cy_capsense_status_t	Cy_CapSense_DeInit (cy_stc_capsense_context_t *context)
	Stops the middleware operation and releases the CAPSENSE™ captured HW blocks. More...
cy_capsense_status_t	Cy_CapSense_Enable (cy_stc_capsense_context_t *context)
	Initializes the CAPSENSE™ firmware modules. More...
cy_capsense_status_t	Cy_CapSense_Save (cy_stc_capsense_context_t *context)
	Saves the state of CAPSENSE™ so the functionality can be restored using the Cy_CapSense_Restore() function. More...
cy_capsense_status_t	Cy_CapSense_Restore (cy_stc_capsense_context_t *context)
	Resumes the middleware operation if the Cy_CapSense_Save() function was called previously. More...
cy_capsense_status_t	Cy_CapSense_ProcessAllWidgets (cy_stc_capsense_context_t *context)
	Performs full data processing of all enabled widgets. More...
cy_capsense_status_t	Cy_CapSense_ProcessWidget (uint32_t widgetId, cy_stc_capsense_context_t *context)
	Performs full data processing of the specified widget if it is enabled. More...
void	Cy_CapSense_IncrementGestureTimestamp (cy_stc_capsense_context_t *context)
	Increments the timestamp register for the predefined timestamp interval. More...
void	Cy_CapSense_SetGestureTimestamp (uint32_t value, cy_stc_capsense_context_t *context)
	Rewrites the timestamp register by the specified value. More...
void	Cy_CapSense_Wakeup (const cy_stc_capsense_context_t *context)
	Resumes the middleware after System Deep Sleep. More...
cy_en_syspm_status_t	Cy_CapSense_DeepSleepCallback (cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)
	Handles CPU active to System Deep Sleep power mode transition for the CAPSENSE™ middleware. More...
cy_capsense_status_t	Cy_CapSense_RegisterCallback (cy_en_capsense_callback_event_t callbackType, cy_capsense_callback_t callbackFunction, cy_stc_capsense_context_t *context)
	Registers a ures's callback function. More...
cy_capsense_status_t	Cy_CapSense_UnRegisterCallback (cy_en_capsense_callback_event_t callbackType, cy_stc_capsense_context_t *context)
	This function unregisters a previously registered user's callback function in the CAPSENSE™ middleware. More...
uint32_t	Cy_CapSense_DecodeWidgetGestures (uint32_t widgetId, const cy_stc_capsense_context_t *context)
	Performs decoding of all gestures for the specified widget. More...
cy_en_capsense_bist_status_t	Cy_CapSense_RunSelfTest (uint32_t testEnMask, cy_stc_capsense_context_t *context)
	Runs built-in self-tests specified by the test enable mask. More...
cy_capsense_status_t	Cy_CapSense_ScanAllSlots (cy_stc_capsense_context_t *context)
	Initiates the non-blocking scan of all Active slots and then exits. More...
cy_capsense_status_t	Cy_CapSense_ScanSlots (uint32_t startSlotId, uint32_t numberSlots, cy_stc_capsense_context_t *context)
	Initiates the non-blocking scan of a specified regular slots set named "frame" and then exits. More...
cy_capsense_mw_state_t	Cy_CapSense_MwState (const cy_stc_capsense_context_t *context)
	Returns a detailed state of the CAPSENSE™ middleware and MSC and MSCLP HW blocks in Single- or Multi-channel mode. More...
cy_capsense_status_t	Cy_CapSense_ScanAllWidgets (cy_stc_capsense_context_t *context)
	Initiates scanning of all enabled widgets (and sensors) in the project. More...
cy_capsense_status_t	Cy_CapSense_ScanWidget (uint32_t widgetId, cy_stc_capsense_context_t *context)
	Performs the initialization required to scan the specified widget and triggers the scanning of all sensors in the widget. More...
uint32_t	Cy_CapSense_IsBusy (const cy_stc_capsense_context_t *context)
	This function returns a status whether MW executes HW scanning at a particular moment. More...
void	Cy_CapSense_InterruptHandler (void *base, cy_stc_capsense_context_t *context)
	Implements interrupt service routine for CAPSENSE™ middleware. More...
cy_capsense_status_t	Cy_CapSense_ScanLpSlots (uint32_t startLpSlotId, uint32_t numberLpSlots, cy_stc_capsense_context_t *context)
	Initiates a non-blocking scan for specified low power slots and exits. More...
cy_capsense_status_t	Cy_CapSense_ScanAllLpSlots (cy_stc_capsense_context_t *context)
	Initiates a non-blocking scan of all low power slots and then exits. More...
cy_capsense_status_t	Cy_CapSense_ScanAllLpWidgets (cy_stc_capsense_context_t *context)
	Initiates a non-blocking scan for all low power widgets/sensors. More...
cy_capsense_status_t	Cy_CapSense_ConfigureMsclpWotTimer (uint32_t wakeupTimer, cy_stc_capsense_context_t *context)
	Configures the wakeup timer value for Wake-On-Touch mode. More...
cy_capsense_status_t	Cy_CapSense_ConfigureMsclpTimer (uint32_t wakeupTimer, cy_stc_capsense_context_t *context)
	Configures the wakeup timer value for Active mode. More...
cy_capsense_status_t	Cy_CapSense_IloCompensate (cy_stc_capsense_context_t *context)
	Measures the actual ILO frequency and calculates the compensation factor for MSCLP Active and Wake-On-Touch mode timers. More...
cy_capsense_status_t	Cy_CapSense_SetupWidget (uint32_t widgetId, cy_stc_capsense_context_t *context)
	Performs the initialization required to scan the specified widget. More...
cy_capsense_status_t	Cy_CapSense_Scan (cy_stc_capsense_context_t *context)
	Initiates scanning of all the sensors in the widget initialized by Cy_CapSense_SetupWidget(), if no scan is in progress. More...
uint32_t	Cy_CapSense_IsAnyWidgetActive (const cy_stc_capsense_context_t *context)
	Reports whether any widget has detected touch. More...
uint32_t	Cy_CapSense_IsAnyLpWidgetActive (const cy_stc_capsense_context_t *context)
	Reports whether any low power widget has detected a touch at the previous low power scan. More...
uint32_t	Cy_CapSense_IsWidgetActive (uint32_t widgetId, const cy_stc_capsense_context_t *context)
	Reports whether the specified widget detected touch on any of its sensors. More...
uint32_t	Cy_CapSense_IsSensorActive (uint32_t widgetId, uint32_t sensorId, const cy_stc_capsense_context_t *context)
	Reports whether the specified sensor in the widget is sensor detects a touch. More...
uint32_t	Cy_CapSense_IsProximitySensorActive (uint32_t widgetId, uint32_t sensorId, const cy_stc_capsense_context_t *context)
	Reports the status of the specified proximity widget/sensor. More...
cy_stc_capsense_touch_t *	Cy_CapSense_GetTouchInfo (uint32_t widgetId, const cy_stc_capsense_context_t *context)
	Reports the details of touch position detected on the specified touchpad, matrix buttons or slider widgets. More...
uint32_t	Cy_CapSense_RunTuner (cy_stc_capsense_context_t *context)
	Establishes synchronized operation between the CAPSENSE™ Middleware and the CAPSENSE™ Tuner tool. More...
uint32_t	Cy_CapSense_CheckTunerCmdIntegrity (const uint8_t *commandPacket)
	Checks command format, header, tail, CRC, etc. More...

Function Documentation

Cy_CapSense_Init()

cy_capsense_status_t Cy_CapSense_Init

(

cy_stc_capsense_context_t *

context

)

Captures HW blocks (one or more) for CAPSENSE™ operations and configures them to the default state.

Call this function with the application program prior to calling any other function of the middleware.

The following tasks are executed:

1. Capturing not used HW blocks. If any of HW blocks are already in use, then the function returns the fail status, and the application program should perform corresponding actions. For example, releasing the HW block captured by another middleware.
2. If the HW block has been captured successfully, this function configures it to the default state.

After the middleware is configured using the Cy_CapSense_Init() function, the application program configures and enables the HW block interrupt(s), and then call of the Cy_CapSense_Enable() function to complete the middleware initialization process. See the function usage example below for more details.

When the middleware operation is stopped by the Cy_CapSense_DeInit() function, subsequent call of the Cy_CapSense_Init() function repeats initialization process and it is not needed to call the Cy_CapSense_Enable() function second time. However, to implement time-multiplexed mode (sharing the HW block(s) between multiple middleware) the Cy_CapSense_Save() and Cy_CapSense_Restore() functions should be used instead of the Cy_CapSense_DeInit() and Cy_CapSense_Init() functions for further compatibility.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t generated by the CAPSENSE™ Configurator tool. The structure contains both, CAPSENSE™ configuration and internal data and it is used during whole CAPSENSE™ operation.

Returns

Returns the status of the initialization process. If CY_CAPSENSE_STATUS_SUCCESS is not received, some of the initialization fails, the middleware may not operate as expected, and repeating of initialization is required.

Function Usage

    /* Capture the HW block and initialize it to the default state. */
    Cy_CapSense_Init(&cy_capsense_context);

    /* Initialize interrupt */
    Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
    NVIC_ClearPendingIRQ(CapSense_ISR_cfg.intrSrc);
    NVIC_EnableIRQ(CapSense_ISR_cfg.intrSrc);

    /* Initialize the firmware modules. */
    Cy_CapSense_Enable(&cy_capsense_context);

The 'cy_capsense_context' variable that is used as the parameter of the Cy_CapSense_Init() and Cy_CapSense_Enable() functions is declared in the cycfg_capsense.h file.

The CapSense_ISR_cfg variable should be declared by the application program according to the examples below:
For PSoC™ 4 CPU or for PSoC™ 6 CM0+ core:

    #if (CY_CAPSENSE_PSOC4_FOURTH_GEN)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #elif (CY_CAPSENSE_PSOC4_FIFTH_GEN)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msc_0_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,               /* Interrupt priority is 3 */
        };
    #elif (CY_CAPSENSE_PSOC4_FIFTH_GEN_LP)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msclp_interrupt_lp_IRQn, /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,                 /* Interrupt priority is 3 */
        };
    #endif

Note

MSCLP HW contains two interrupt sources. The CAPSENSE™ Middleware supports only the msclp_interrupt_lp_IRQn vector and therefore it should be used.

For CM4 core:

        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn, /* Interrupt source is the CSD interrupt */
            .intrPriority = 7u,            /* Interrupt priority is 7 */
        };

The CAPSENSE™ interrupt handler should be declared by the application program according to the example below:

void CapSense_InterruptHandler(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

The CapSense_HW is the pointer to the base register address of the CAPSENSE™ HW block. A macro for the pointer is in the cycfg_peripherals.h file defined as <Personality_Name>_HW. If no name is specified, the following default names are used:

• csd_<Block_Number>_csd_<Block_Number>_HW - for forth-generation CAPSENSE™ HW.
• msc_<Block_Number>_msc_<Block_Number>_HW - for fifth-generation CAPSENSE™ HW.
• msclp_<Block_Number>_msclp_<Block_Number>_HW - for fifth-generation low power CAPSENSE™ HW.

Cy_CapSense_DeInit()

cy_capsense_status_t Cy_CapSense_DeInit

(

cy_stc_capsense_context_t *

context

)

Stops the middleware operation and releases the CAPSENSE™ captured HW blocks.

No sensor scanning can be executed when the middleware is stopped. This function should be called only when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status.

After the middleware stops, the CAPSENSE™ HW block(s) may be reconfigured with the application program or other middleware for any other usage.

When the middleware operation is stopped by the Cy_CapSense_DeInit() function, subsequent call of the Cy_CapSense_Init() function repeats the initialization process, so a subsequent call of the Cy_CapSense_Enable() function is not required. However, to implement Time-multiplexed mode (sharing the CAPSENSE™ HW block(s) between multiple middleware) the Cy_CapSense_Save() and Cy_CapSense_Restore() functions should be used instead of the Cy_CapSense_DeInit() and Cy_CapSense_Init() functions for further compatibility.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the stop process. If CY_CAPSENSE_STATUS_SUCCESS is not received, the stop process fails and retries may be required.

Cy_CapSense_Enable()

cy_capsense_status_t Cy_CapSense_Enable

(

cy_stc_capsense_context_t *

context

)

Initializes the CAPSENSE™ firmware modules.

Call the Cy_CapSense_Init() function and configure CAPSENSE™ HW block interrupts prior to calling this function. See the function usage example below for details on usage.

The following are executed as part of the function:

1. Check CAPSENSE™ configuration integrity.
2. Pre-calculate of internal register values to speed up operation.
3. Configure the CAPSENSE™ HW block to perform capacitive sensing operation.
4. If the smart sensing algorithm is selected for the CSD Tuning mode in the Basic tab, the auto-tuning functionality is executed to set the optimal values for the CAPSENSE™ HW block parameters of the widgets/sensors.
5. Calibrate the sensors and find the optimal values for DACs of each widget/sensor, if the auto-calibration is enabled in the CSD Settings, CSX Settings or ISX Settings tabs.
6. Perform scanning for all the sensors and initialize the baseline history.
7. If the firmware filters are enabled in the Advanced General tab, the filter histories are also initialized.

Any subsequent call of this function repeats the initialization process. Therefore, it is possible to change the middleware configuration from the application program by writing registers to the data structure and calling this function again.

The repeated call of this function is also done inside the Cy_CapSense_RunTuner() function when a restart command is received.

The function calls the Cy_CapSense_ScanAllWidgets() function to proper baseline setup.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the initialization process. If CY_CAPSENSE_STATUS_SUCCESS is not received, some of the initialization fails.

Function Usage

    /* Capture the HW block and initialize it to the default state. */
    Cy_CapSense_Init(&cy_capsense_context);

    /* Initialize interrupt */
    Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
    NVIC_ClearPendingIRQ(CapSense_ISR_cfg.intrSrc);
    NVIC_EnableIRQ(CapSense_ISR_cfg.intrSrc);

    /* Initialize the firmware modules. */
    Cy_CapSense_Enable(&cy_capsense_context);

The 'cy_capsense_context' variable that is used as the parameter of the Cy_CapSense_Init() and Cy_CapSense_Enable() functions is declared in the cycfg_capsense.h file.

The CapSense_ISR_cfg variable should be declared by the application program according to the examples below:
For CM0+ core:

    #if (CY_CAPSENSE_PSOC4_FOURTH_GEN)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #elif (CY_CAPSENSE_PSOC4_FIFTH_GEN)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msc_0_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,               /* Interrupt priority is 3 */
        };
    #elif (CY_CAPSENSE_PSOC4_FIFTH_GEN_LP)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msclp_interrupt_lp_IRQn, /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,                 /* Interrupt priority is 3 */
        };
    #endif

Note

MSCLP HW contains two interrupt sources. The CAPSENSE™ Middleware supports only the msclp_interrupt_lp_IRQn vector and therefore it should be used.

For CM4 core:

        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn, /* Interrupt source is the CSD interrupt */
            .intrPriority = 7u,            /* Interrupt priority is 7 */
        };

The CAPSENSE™ interrupt handler should be declared by the application program according to the example below:

void CapSense_InterruptHandler(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

The CapSense_HW is the pointer to the base register address of the CAPSENSE™ HW block. A macro for the pointer is in the cycfg_peripherals.h file defined as <Personality_Name>_HW. If no name is specified, the following default names are used:

• csd_<Block_Number>_csd_<Block_Number>_HW - for forth-generation CAPSENSE™ HW.
• msc_<Block_Number>_msc_<Block_Number>_HW - for fifth-generation CAPSENSE™ HW.
• msclp_<Block_Number>_msclp_<Block_Number>_HW - for fifth-generation low power CAPSENSE™ HW.

Cy_CapSense_Save()

cy_capsense_status_t Cy_CapSense_Save

(

cy_stc_capsense_context_t *

context

)

Saves the state of CAPSENSE™ so the functionality can be restored using the Cy_CapSense_Restore() function.

This function, along with the Cy_CapSense_Restore() function, is specifically designed for ease of use and supports time multiplexing of the CAPSENSE™ HW block among multiple middleware. When the CAPSENSE™ HW block is shared by multiple middleware, this function can be used to save the current state of the CAPSENSE™ HW block and CAPSENSE™ Middleware prior to releasing the CAPSENSE™ HW block for use by other middleware. See the function usage example below for details on usage.

This function performs the same tasks as the Cy_CapSense_DeInit() function and is kept for API consistency among middlewares. It is recommended to use Cy_CapSense_Save() and Cy_CapSense_Restore() functions to implement Time-multiplexed mode instead of Cy_CapSense_DeInit() and Cy_CapSense_Init() functions for further compatibility.

This function performs the following operations:

• Releases the CAPSENSE™ HW block.
• Configures sensor pins to the default state and disconnects them from analog buses.
• Disconnects external capacitors from analog buses.
• Sets the middleware state to default.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the process. If CY_CAPSENSE_STATUS_SUCCESS is not received, the save process fails and retries may be required.

Function Usage

An example of sharing the CAPSENSE™ HW block by the CAPSENSE™ and CSDADC middleware.
Declares the CapSense_ISR_cfg variable:

        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn, /* Interrupt source is the CSD interrupt */
            .intrPriority = 7u,            /* Interrupt priority is 7 */
        };

Declares the CSDADC_ISR_cfg variable:

        const cy_stc_sysint_t CSDADC_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn, /* Interrupt source is the CSD interrupt */
            .intrPriority = 7u,            /* Interrupt priority is 7 */
        };

Defines the CapSense interrupt handler:

void CapSense_InterruptHandler(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

Defines the CSDADC interrupt handler:

    static void CSDADC_Interrupt(void)
    {
        Cy_CSDADC_InterruptHandler(CSD0, &cy_csd_0_context);
    }

The part of the main.c FW flow:

        /* ... */

        /* Initialize CAPSENSE MW */
        Cy_CapSense_Init(&cy_capsense_context);
        Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
        NVIC_ClearPendingIRQ(CapSense_ISR_cfg.intrSrc);
        NVIC_EnableIRQ(CapSense_ISR_cfg.intrSrc);
        Cy_CapSense_Enable(&cy_capsense_context);
        Cy_CapSense_Save(&cy_capsense_context);

        /* Initialize CSDADC MW */
        Cy_CSDADC_Init(&CapSense_csdadc_config, &cy_csdadc_context);
        Cy_SysInt_Init(&CSDADC_ISR_cfg, &CSDADC_Interrupt);
        NVIC_ClearPendingIRQ(CSDADC_ISR_cfg.intrSrc);
        NVIC_EnableIRQ(CSDADC_ISR_cfg.intrSrc);
        Cy_CSDADC_Enable(&cy_csdadc_context);
        Cy_CSDADC_Save(&cy_csdadc_context);

        for (;;)
        {
            /* Switch to CAPSENSE MW */
            Cy_CapSense_Restore(&cy_capsense_context);
            Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
                /* Perform sensing operation */
            Cy_CapSense_Save(&cy_capsense_context);

            /* Switch to CSDADC MW */
            Cy_CSDADC_Restore(&cy_csdadc_context);
            Cy_SysInt_Init(&CSDADC_ISR_cfg, &CSDADC_Interrupt);
                /* Do CSDADC measurement operation */
            Cy_CSDADC_Save(&cy_csdadc_context);
        }

        /* ... */

Cy_CapSense_Restore()

cy_capsense_status_t Cy_CapSense_Restore

(

cy_stc_capsense_context_t *

context

)

Resumes the middleware operation if the Cy_CapSense_Save() function was called previously.

This function, along with the Cy_CapSense_Save() function is specifically designed for ease of use and supports time multiplexing of the CAPSENSE™ HW block among multiple middleware. When the CAPSENSE™ HW blocks are shared by multiple middleware, this function can be used to restore the previous state of the CAPSENSE™ HW block(s) and CAPSENSE™ Middleware is saved using the Cy_CapSense_Save() function. See the function usage example below for details on usage.

This function performs the same tasks as Cy_CapSense_Init() function and is kept for API consistency among middlewares. It is recommended to use Cy_CapSense_Save() and Cy_CapSense_Restore() functions to implement time-multiplexed mode instead of Cy_CapSense_DeInit() and Cy_CapSense_Init() functions for further compatibility.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the resume process. If CY_CAPSENSE_STATUS_SUCCESS is not received, the resume process fails and retries may be required.

Function Usage

An example of sharing the CAPSENSE™ HW block by CAPSENSE™ and CSDADC middleware:

        /* ... */

        /* Initialize CAPSENSE MW */
        Cy_CapSense_Init(&cy_capsense_context);
        Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
        NVIC_ClearPendingIRQ(CapSense_ISR_cfg.intrSrc);
        NVIC_EnableIRQ(CapSense_ISR_cfg.intrSrc);
        Cy_CapSense_Enable(&cy_capsense_context);
        Cy_CapSense_Save(&cy_capsense_context);

        /* Initialize CSDADC MW */
        Cy_CSDADC_Init(&CapSense_csdadc_config, &cy_csdadc_context);
        Cy_SysInt_Init(&CSDADC_ISR_cfg, &CSDADC_Interrupt);
        NVIC_ClearPendingIRQ(CSDADC_ISR_cfg.intrSrc);
        NVIC_EnableIRQ(CSDADC_ISR_cfg.intrSrc);
        Cy_CSDADC_Enable(&cy_csdadc_context);
        Cy_CSDADC_Save(&cy_csdadc_context);

        for (;;)
        {
            /* Switch to CAPSENSE MW */
            Cy_CapSense_Restore(&cy_capsense_context);
            Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
                /* Perform sensing operation */
            Cy_CapSense_Save(&cy_capsense_context);

            /* Switch to CSDADC MW */
            Cy_CSDADC_Restore(&cy_csdadc_context);
            Cy_SysInt_Init(&CSDADC_ISR_cfg, &CSDADC_Interrupt);
                /* Do CSDADC measurement operation */
            Cy_CSDADC_Save(&cy_csdadc_context);
        }

        /* ... */

Cy_CapSense_ProcessAllWidgets()

cy_capsense_status_t Cy_CapSense_ProcessAllWidgets

(

cy_stc_capsense_context_t *

context

)

Performs full data processing of all enabled widgets.

This function performs all data processes for all enabled widgets and sensors in the middleware to produce meaningful status output from widgets and sensors. The following tasks are executed as part of processing all the widgets:

1. Apply raw count filters to the raw counts, if they are enabled.
2. Update the thresholds if the smart sensing algorithm Full Auto-Tuning is enabled.
3. Update the baselines and difference counts for all the sensors.
4. Update the sensor and widget output status. Updates on/off status for buttons and proximity widgets, centroid/position for the sliders and the X/Y position for the touchpads.

This function is called by the application program only after all the enabled widgets (and sensors) in the middleware are scanned. Calling this function multiple times without sensor scanning causes unexpected behavior.

Disabled and/or non-working widgets are not processed by this function.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the processing operation. If CY_CAPSENSE_STATUS_SUCCESS is not received, the processing fails and retries may be required.

Cy_CapSense_ProcessWidget()

cy_capsense_status_t Cy_CapSense_ProcessWidget	(	uint32_t	widgetId,
		cy_stc_capsense_context_t *	context
	)

Performs full data processing of the specified widget if it is enabled.

This function performs exactly the same tasks as Cy_CapSense_ProcessAllWidgets(), but only for a specified widget. This function can be used along with the Cy_CapSense_ScanWidget() function (4th Generation) to scan and process data for a specific widget or with the Cy_CapSense_ScanSlots() function (5th Generation). This function is called only after all the sensors in the widgets are scanned.

The disabled and/or non-working widgets are not processed by this function.

The pipeline scan method, which during scanning a current widget (N), performs the processing of the previously scanned widget (N-1)) can be implemented using this function and it may reduce the total execution time, increase the refresh rate, and decrease the average power consumption. See the function usage example below for details on usage.

For the Fifth generation CAPSENSE™ if the specified widget has the enabled multi-frequency scan feature then the function does the following:

• If the specified widget ID refers to main (base) frequency then the function processes raw count processing of all three widgets (main and two sub-widgets) and then status processing of the main widget only.
• If the specified widget ID refers to sub-widgets (1st or 2nd frequency channels) then the function returns CY_CAPSENSE_STATUS_BAD_PARAM. To perform customized processing use the Cy_CapSense_ProcessWidgetExt() function.

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.

Note

For the fifth-generation low power CAPSENSE™ widgets of the CY_CAPSENSE_WD_LOW_POWER_E type are not processed and CY_CAPSENSE_STATUS_BAD_PARAM is returned if a widget of this type is passed.

Parameters

context

The 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
• CY_CAPSENSE_STATUS_INVALID_STATE - The specified widget is disabled
• CY_CAPSENSE_STATUS_BAD_DATA - The processing is failed

Function Usage

An example of pipeline implementation:

    /*...*/
    currentWidgetIndex = 0u;

    /* The first widget scan start */
    #if (CY_CAPSENSE_PLATFORM_BLOCK_FIFTH_GEN || CY_CAPSENSE_PLATFORM_BLOCK_FIFTH_GEN_LP)
        if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ScanSlots(
                                            cy_capsense_context.ptrWdConfig[currentWidgetIndex].firstSlotId,
                                            cy_capsense_context.ptrWdConfig[currentWidgetIndex].numSlots,
                                            &cy_capsense_context))
        {
            /* Insert the error handle code here, for instance as below */
            CY_ASSERT(0u);
        }
    #else  /* CY_CAPSENSE_PLATFORM_BLOCK_FOURTH_GEN */
        if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ScanWidget(currentWidgetIndex, &cy_capsense_context))
        {
            /* Insert the error handle code here, for instance as below */
            CY_ASSERT(0u);
        }
    #endif

    for (;;)
    {
        if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
        {
            /* Store the current widget index */
            previousWidgetIndex = currentWidgetIndex;

            /* Go to the next widget */
            currentWidgetIndex++;
            if (currentWidgetIndex == CY_CAPSENSE_WIDGET_COUNT)
            {
                /* Reset the current widget index to start scan from the first one */
                currentWidgetIndex = 0u;
            }

            /* The next widget scan start */
            #if (CY_CAPSENSE_PLATFORM_BLOCK_FIFTH_GEN || CY_CAPSENSE_PLATFORM_BLOCK_FIFTH_GEN_LP)
                if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ScanSlots(
                                                    cy_capsense_context.ptrWdConfig[currentWidgetIndex].firstSlotId,
                                                    cy_capsense_context.ptrWdConfig[currentWidgetIndex].numSlots,
                                                    &cy_capsense_context))
                {
                    /* Insert the error handle code here, for instance as below */
                    CY_ASSERT(0u);
                }
            #else  /* CY_CAPSENSE_PLATFORM_BLOCK_FOURTH_GEN */
                if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ScanWidget(currentWidgetIndex, &cy_capsense_context))
                {
                    /* Insert the error handle code here, for instance as below */
                    CY_ASSERT(0u);
                }
            #endif

            /* Process the previous widget while scanning the next one */
            if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ProcessWidget(previousWidgetIndex, &cy_capsense_context))
            {
                /* Insert the error handle code here, for instance as below */
                CY_ASSERT(0u);
            }
        }
    }
    /*...*/

Cy_CapSense_IncrementGestureTimestamp()

void Cy_CapSense_IncrementGestureTimestamp

(

cy_stc_capsense_context_t *

context

)

Increments the timestamp register for the predefined timestamp interval.

A timestamp is required for the operation of the Gesture and Ballistic multiplier feature. Hence, this function and timestamp are required only if the Gesture detection or Ballistic multiplier feature is enabled.

This function increments the timestamp by the interval specified in the context->ptrCommonContext->timestampInterval register. The unit for the timestamp and timestamp interval is milliseconds and the default value of the interval is 1.

The application program must periodically call this function or register a periodic callback to this function to keep the timestamp updated and operational for the operation of the Gesture and Ballistic multiplier feature.

The timestamp can be updated in one of the three methods:

1. Register a periodic callback for the Cy_CapSense_IncrementGestureTimestamp() function.
2. Periodically call the Cy_CapSense_IncrementGestureTimestamp() function from the application program.
3. Directly modify the timestamp using the Cy_CapSense_SetGestureTimestamp() function.

See the function usage example below for more details.

The interval at which this function is called should match with interval defined in context->ptrCommonContext->timestampInterval register. Either the register value can be updated to match the callback interval or the callback can be made to be set in the register at an interval.

If a timestamp is available from another source, the application program may choose to periodically update the timestamp by using the Cy_CapSense_SetGestureTimestamp() function instead of registering a callback.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Function Usage

An example of timestamp updating:

    /* If previous scan complete, process widget data and trigger the next scan */
    if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
    {
        /* Increment timestamp: Option 2 */
        Cy_CapSense_IncrementGestureTimestamp(&cy_capsense_context);
        /* Increment timestamp: Option 3 */
        cy_capsense_context.ptrCommonContext->timestamp = newTimestamp;

        Cy_CapSense_ProcessWidget(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);
        Cy_CapSense_DecodeWidgetGestures(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);

        Cy_CapSense_ScanWidget(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);
    }

Cy_CapSense_SetGestureTimestamp()

void Cy_CapSense_SetGestureTimestamp	(	uint32_t	value,
		cy_stc_capsense_context_t *	context
	)

Rewrites the timestamp register by the specified value.

This function writes the specified value into the middleware timestamp context->ptrCommonContext->timestamp register.

If a timestamp is available from another source, the application program may choose to periodically update the timestamp by using this function instead of registering a callback.

Do not modify the timestamp arbitrarily or simultaneously use with the Cy_CapSense_IncrementGestureTimestamp() function, which may result in unexpected result.

Parameters

value	Specifies the timestamp value (in ms).
context	The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Cy_CapSense_Wakeup()

void Cy_CapSense_Wakeup

(

const cy_stc_capsense_context_t *

context

)

Resumes the middleware after System Deep Sleep.

This function is used to resume the middleware operation after exiting System Deep Sleep. After the CAPSENSE™ HW block is powered on, an extra delay is required to establish the correct operation of the CAPSENSE™ HW block. No need for the Cy_CapSense_Wakeup() function call for the fifth-generation low power CAPSENSE™ because all needed delays are managed automatically in scan start functions.

This function is called by the Cy_CapSense_DeepSleepCallback() function after exiting System Deep Sleep if the CAPSENSE™ Deep Sleep callback is registered.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Cy_CapSense_DeepSleepCallback()

cy_en_syspm_status_t Cy_CapSense_DeepSleepCallback	(	cy_stc_syspm_callback_params_t *	callbackParams,
		cy_en_syspm_callback_mode_t	mode
	)

Handles CPU active to System Deep Sleep power mode transition for the CAPSENSE™ middleware.

Calling this function directly from the application program is not recommended. Instead, Cy_SysPm_CpuEnterDeepSleep() should be used for the CPU active to System Deep Sleep power mode transition of the device.

Note

After the CPU Deep Sleep transition, the device automatically goes to System Deep Sleep if all conditions are fulfilled: another core is in CPU Deep Sleep, all the peripherals are ready to System Deep Sleep, etc. (see details in the device TRM).

For proper operation of the CAPSENSE™ middleware during the CPU active to System Deep Sleep mode transition, a callback to this function should be registered using the Cy_SysPm_RegisterCallback() function with CY_SYSPM_DEEPSLEEP type. After the callback is registered, this function is called by the Cy_SysPm_CpuEnterDeepSleep() function to prepare the middleware to the device power mode transition.

When this function is called with CY_SYSPM_CHECK_READY as an input, this function returns CY_SYSPM_SUCCESS if no scanning is in progress or not a single HW block is captured by the CAPSENSE™ middleware. Otherwise CY_SYSPM_FAIL is returned. If CY_SYSPM_FAIL status is returned, a device cannot change the power mode without completing the current scan as a transition to System Deep Sleep during the scan can disrupt the middleware operation.

When this function is called with CY_SYSPM_AFTER_TRANSITION as an input, then the Cy_CapSense_Wakeup() function is called to resume the middleware operation after exiting System Deep Sleep. If there are no CAPSENSE™ captured HW blocks, no need for the Cy_CapSense_Wakeup() function call and restoring CAPSENSE™ immediately after Deep Sleep without the wake-up delay can lead to unpredictable behavior.

For details of SysPm types and macros refer to the SysPm section of the PDL documentation.

Note

For the fifth-generation low power CAPSENSE™ this function does nothing. The device can easily go to and out of System Deep Sleep power mode. So there is no need to register it into the SysPm driver. Also the function should not be called from any interrupt handler for any device generation.

Parameters

callbackParams	Refer to the description of the cy_stc_syspm_callback_params_t type in the Peripheral Driver Library documentation.
mode	Specifies mode cy_en_syspm_callback_mode_t.

Returns

Returns the status cy_en_syspm_status_t of the operation requested by the mode parameter:

• CY_SYSPM_SUCCESS - System Deep Sleep power mode can be entered.
• CY_SYSPM_FAIL - System Deep Sleep power mode cannot be entered.

Cy_CapSense_RegisterCallback()

cy_capsense_status_t Cy_CapSense_RegisterCallback	(	cy_en_capsense_callback_event_t	callbackType,
		cy_capsense_callback_t	callbackFunction,
		cy_stc_capsense_context_t *	context
	)

Registers a ures's callback function.

The registered function will be called by the CAPSENSE™ middleware when the specified event cy_en_capsense_callback_event_t has occurred in the CAPSENSE™ middleware.

Parameters

callbackType	The event on which the registered user's function is called by the CAPSENSE™ middleware. Refer to cy_en_capsense_callback_event_t for the list of supported events.
callbackFunction	The pointer to the user's callback function to be called by the middleware.
context	The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the callback registration:

• CY_CAPSENSE_STATUS_SUCCESS - The action performed successfully.
• CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.

Cy_CapSense_UnRegisterCallback()

cy_capsense_status_t Cy_CapSense_UnRegisterCallback	(	cy_en_capsense_callback_event_t	callbackType,
		cy_stc_capsense_context_t *	context
	)

This function unregisters a previously registered user's callback function in the CAPSENSE™ middleware.

Parameters

callbackType	The event on which the callback function should be unregistered. Refer to cy_en_capsense_callback_event_t for the list of supported events.
context	The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the callback deregistration:

• CY_CAPSENSE_STATUS_SUCCESS - The action performed successfully.
• CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.

Cy_CapSense_DecodeWidgetGestures()

uint32_t Cy_CapSense_DecodeWidgetGestures	(	uint32_t	widgetId,
		const cy_stc_capsense_context_t *	context
	)

Performs decoding of all gestures for the specified widget.

This function should be called by application program only after all sensors are scanned and all data processing is executed using Cy_CapSense_ProcessAllWidgets() or Cy_CapSense_ProcessWidget() functions for the widget. Calling this function multiple times without a new sensor scan and process causes unexpected behavior.

Note

The function (Gesture detection functionality) requires a timestamp for its operation. The timestamp should be initialized and maintained in the application program prior to calling this function. See the descriptions of the Cy_CapSense_SetGestureTimestamp() and Cy_CapSense_IncrementGestureTimestamp() functions for details.

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 detected Gesture mask and direction of detected gestures. The same information is stored in ptrWdContext->gestureDetected and ptrWdContext->gestureDirection registers. Corresponding macros could be found Gesture Macros.

• bit[0..15] - detected gesture masks gesture
  • bit[0] - one-finger single click gesture
  • bit[1] - one-finger double click gesture
  • bit[2] - one-finger click and drag gesture
  • bit[3] - two-finger single click gesture
  • bit[4] - one-finger scroll gesture
  • bit[5] - two-finger scroll gesture
  • bit[6] - one-finger edge swipe
  • bit[7] - one-finger flick
  • bit[8] - one-finger rotate
  • bit[9] - two-finger zoom
  • bit[10] - one-finger long press
  • bit[13] - touchdown event
  • bit[14] - liftoff event
• bit[16..31] - gesture direction if detected
  • bit[0..1] - direction of one-finger scroll gesture
  • bit[2..3] - direction of two-finger scroll gesture
  • bit[4..5] - direction of one-finger edge swipe gesture
  • bit[6] - direction of one-finger rotate gesture
  • bit[7] - direction of two-finger zoom gesture
  • bit[8..10] - direction of one-finger flick gesture

Function Usage

An example of gesture decoding:

    /* If previous scan complete, process widget data and trigger the next scan */
    if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
    {
        /* Increment timestamp before widget data processing if ballistic multiplier is enabled */
        Cy_CapSense_IncrementGestureTimestamp(&cy_capsense_context);

        /* Process widget data: Calculate diff counts, status, position, etc. */
        Cy_CapSense_ProcessWidget(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);

        /* Process gesture for the widget */
        gestureStatus = Cy_CapSense_DecodeWidgetGestures(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);

        /* The same gestureStatus can be read from the following registers */
        gestureStatus = cy_capsense_context.ptrWdContext[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].gestureDetected |
                    ((uint32_t)cy_capsense_context.ptrWdContext[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].gestureDirection << CY_CAPSENSE_GESTURE_DIRECTION_OFFSET);

        #if (CY_CAPSENSE_PLATFORM_BLOCK_FIFTH_GEN || CY_CAPSENSE_PLATFORM_BLOCK_FIFTH_GEN_LP)
            Cy_CapSense_ScanSlots(cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].firstSlotId,
                        cy_capsense_context.ptrWdConfig[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].numSlots, &cy_capsense_context);
        #else /* CY_CAPSENSE_PLATFORM_BLOCK_FOURTH_GEN */
            Cy_CapSense_ScanWidget(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);
        #endif
    }

An example of gesture status parsing:

    /* If Two-finger Scroll gesture is detected */
    if (CY_CAPSENSE_GESTURE_NO_GESTURE != (gestureStatus & CY_CAPSENSE_GESTURE_TWO_FNGR_SCROLL_MASK))
    {
        /* Get gesture direction */
        direction = (gestureStatus >> CY_CAPSENSE_GESTURE_DIRECTION_OFFSET) & CY_CAPSENSE_GESTURE_DIRECTION_MASK_TWO_SCROLL;
        switch (direction >> CY_CAPSENSE_GESTURE_DIRECTION_OFFSET_TWO_SCROLL)
        {
            case CY_CAPSENSE_GESTURE_DIRECTION_UP:
                /* UP is detected */
                break;
            case CY_CAPSENSE_GESTURE_DIRECTION_DOWN:
                /* DOWN is detected */
                break;
            case CY_CAPSENSE_GESTURE_DIRECTION_LEFT:
                /* LEFT is detected */
                break;
            case CY_CAPSENSE_GESTURE_DIRECTION_RIGHT:
                /* RIGHT is detected */
                break;
        }
    }

Cy_CapSense_RunSelfTest()

cy_en_capsense_bist_status_t Cy_CapSense_RunSelfTest	(	uint32_t	testEnMask,
		cy_stc_capsense_context_t *	context
	)

Runs built-in self-tests specified by the test enable mask.

The function performs various self-tests on all the enabled widgets and sensors in the project. Select the required set of tests using the bit-mask in testEnMask parameter.

Use CY_CAPSENSE_BIST_RUN_AVAILABLE_SELF_TEST_MASK to execute all the self-tests or any combination of the masks (defined in testEnMask parameter) to specify the desired test list.

This function does not execute two tests: sensor raw count and baseline integrity.

To execute a single-element test (i.e. for one widget or one sensor), the following low-level functions are available:

For the fourth-generation CAPSENSE™:

• Cy_CapSense_CheckCRCWidget()
• Cy_CapSense_CheckIntegritySensorRawcount()
• Cy_CapSense_CheckIntegritySensorBaseline()
• Cy_CapSense_CheckIntegritySensorPins()
• Cy_CapSense_MeasureCapacitanceSensor()
• Cy_CapSense_MeasureCapacitanceShield()
• Cy_CapSense_MeasureCapacitanceCap()
• Cy_CapSense_MeasureVdda()

For the fifth-generation CAPSENSE™:

• Cy_CapSense_CheckCRCWidget()
• Cy_CapSense_CheckIntegritySensorRawcount()
• Cy_CapSense_CheckIntegritySensorBaseline()
• Cy_CapSense_CheckIntegritySensorPins()
• Cy_CapSense_MeasureCapacitanceSensorElectrode()
• Cy_CapSense_MeasureCapacitanceSlotSensors()
• Cy_CapSense_MeasureCapacitanceShieldElectrode()

For the fifth-generation low power CAPSENSE™:

• Cy_CapSense_CheckCRCWidget()
• Cy_CapSense_CheckIntegritySensorRawcount()
• Cy_CapSense_CheckIntegritySensorBaseline()
• Cy_CapSense_CheckIntegritySensorPins()
• Cy_CapSense_MeasureCapacitanceSensorElectrode()
• Cy_CapSense_MeasureCapacitanceSlotSensors()
• Cy_CapSense_MeasureCapacitanceShieldElectrode()
• Cy_CapSense_MeasureCapacitanceCap()
• Cy_CapSense_MeasureVdda()

Refer to these functions descriptions for detail information on the corresponding test.

Parameters

testEnMask

Specifies the tests to be executed. Each bit corresponds to one test. It is possible to launch the function with any combination of the available tests. CY_CAPSENSE_BIST_CRC_WDGT_MASK - Verifies the RAM widget structure CRC for all the widgets. CY_CAPSENSE_BIST_SNS_INTEGRITY_MASK - Checks all the sensor pins for a short to GND / VDD / other sensors. CY_CAPSENSE_BIST_SNS_CAP_MASK - Measures all the sensors capacitance. CY_CAPSENSE_BIST_ELTD_CAP_MASK - Measures all the electrodes capacitance (only for the fifth-generation CAPSENSE™). CY_CAPSENSE_BIST_SHIELD_CAP_MASK - Measures the shield capacitance. CY_CAPSENSE_BIST_EXTERNAL_CAP_MASK - Measures the capacitance of the available external capacitors (only for the fourth-generation CAPSENSE™). CY_CAPSENSE_BIST_VDDA_MASK - Measures the VDDA voltage (only for the fourth-generation CAPSENSE™). CY_CAPSENSE_BIST_RUN_AVAILABLE_SELF_TEST_MASK - Executes all available tests.

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns a bit-mask with a status of execution of the specified tests:

• CY_CAPSENSE_BIST_SUCCESS_E - All the tests passed successfully.
• CY_CAPSENSE_BIST_BAD_PARAM_E - A non-defined test was requested in the testEnMask parameter or the context is a NULL pointer. The function was not performed.
• CY_CAPSENSE_BIST_HW_BUSY_E - The CAPSENSE™ HW block is busy with a previous operation. The function was not performed.
• CY_CAPSENSE_BIST_ERROR_E - An unexpected fault occurred during the measurement, you may need to repeat the measurement.
• CY_CAPSENSE_BIST_FAIL_E - Any of tests specified by the testEnMask parameters has faulted.

Cy_CapSense_ScanAllSlots()

cy_capsense_status_t Cy_CapSense_ScanAllSlots

(

cy_stc_capsense_context_t *

context

)

Initiates the non-blocking scan of all Active slots and then exits.

Scanning is initiated only if no scan is in progress. To initiate all Low Power slot scan use the Cy_CapSense_ScanAllLpSlots() function.

• For fifth-generation low power CAPSENSE™ This function loads slots configurations into the internal buffer of the CAPSENSE™ hardware block and triggers scanning. If the scan frame doesn`t fit into the internal buffer it will be processed as the sequence of sub-frames. Next sub-frame will be loaded by the interrupt service routine(part of middleware) once scan of previous sub-frame is complete. The scanning process duration consists of a some pre-configured interval and a frame scan duration. The first slot scan starts after the pre-configured interval. The default duration of the interval is 1 ILO cycle. The interval duration can be changed by the Cy_CapSense_ConfigureMsclpTimer() function. If the "Enable external frame start" option is disabled in the CAPSENSE™ Configurator, the scanning process will be triggered immediately. If the "Enable external frame start" option is enabled in the CAPSENSE™ Configurator, the scanning process will be triggered by the first external synchronization signal after a function call. The number of slots in frame in this case should not exceed the maximum possible slot number to fit into the internal buffer of the CAPSENSE™ hardware block. The External synchronization signal parameters should meet the following constraints:
  • - the interval between the return of the function and the rising edge of an external synchronization signal must not be less than 2 ILO cycles;
  • - the pulse duration of an external synchronization signal (if the signal is in High level) must not be less than 2 ILO cycles and more than the full scanning process duration. The full scanning process duration is the time between the rising edge of the external synchronization pulse and clearing of BUSY flag. The Cy_CapSense_IsBusy() function can be used to check BUSY flag;
  • - the interval between sub-sequent pulses should not be less than full scanning process duration. Disregarding the "Enable external frame start" option, the transition into system DEEP SLEEP mode is allowed after the scan process is started by the function. To decrease the start scan time when it is intended to scan the same frame, i.e. startSlotId and numberSlots parameters are the same, then the scan is performed without the MSC HW block reconfiguration. In this case, the number of slots in the frame shall not exceed the maximum possible slot number to fit into the internal buffer of the CAPSENSE™ hardware block.

• For fifth-generation CAPSENSE™ this function initiates a scan for the first slot for all channels and then exits. Scans for the remaining slots in the Interrupt-driven scan mode are initiated in the interrupt service routine (part of middleware) triggered at the end of each scan completed for each channel. If the syncMode field in the cy_stc_capsense_common_config_t structure is set to CY_CAPSENSE_SYNC_MODE_OFF, then the next slot scan for the channel with the fired interrupt, will start regardless of the another channel readiness for the next scan. If the syncMode field is set to CY_CAPSENSE_SYNC_INTERNAL (for single-chip projects) or to CY_CAPSENSE_SYNC_EXTERNAL (for multi-chip projects), then the next slot scan for the channel with the fired interrupt, will start in lockstep with another channels after they all are ready for the next scan (the next scan configuration is loaded into the channel MSC HW block). Scans for the remaining slots in CS-DMA scan mode are initiated by DMAC triggered at the end of each scan completed for each channel. The channel scan synchronization is performed as in Interrupt-driven scan mode. After all slots are scanned, the FRAME interrupt is fired and the interrupt service routine (part of middleware) updates the busy status. The transition into system DEEP SLEEP mode is allowed only when all scans are finished.

If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment.

Note

This function is available for the fifth-generation and fifth-generation low power CAPSENSE™.

Parameters

context

The 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_HW_BUSY - The HW is busy with the previous scan.

Cy_CapSense_ScanSlots()

cy_capsense_status_t Cy_CapSense_ScanSlots	(	uint32_t	startSlotId,
		uint32_t	numberSlots,
		cy_stc_capsense_context_t *	context
	)

Initiates the non-blocking scan of a specified regular slots set named "frame" and then exits.

Scanning is initiated only if no scan is in progress. Check the status of the current scan using the Cy_CapSense_IsBusy() function. The application program should wait until the current frame scan is finished prior to start a next scan by using the function.

• For fifth-generation low power CAPSENSE™ The function loads the frame configuration into the internal buffer of the CAPSENSE™ hardware block and triggers the scanning process. If the frame configuration does not fit into the internal buffer its scan will be processed as a sequence of sub-frame scans. A next sub-frame will be loaded by the interrupt service routine (part of the middleware) after the previous sub-frame scan is complete. The scanning process duration consists of a some pre-configured interval and a frame scan duration. The first slot scan starts after the pre-configured interval. The default duration of the interval is 1 ILO cycle. The interval duration can be changed by the Cy_CapSense_ConfigureMsclpTimer() function. If the "Enable external frame start" option is disabled in the CAPSENSE™ Configurator, the scanning process will be triggered immediately. If the "Enable external frame start" option is enabled in the CAPSENSE™ Configurator, the scanning process will be triggered by the first external synchronization signal after a function call. In this case, the number of slots in the frame shall not exceed the maximum possible slot number to fit into the internal buffer of the CAPSENSE™ hardware block. The External synchronization signal parameters should meet the following constraints:
  • - the interval between the return of the function and the rising edge of an external synchronization signal must not be less than 2 ILO cycles;
  • - the pulse duration of an external synchronization signal (if the signal is in High level) must not be less than 2 ILO cycles and more than the full scanning process duration. The full scanning process duration is the time between the rising edge of the external synchronization pulse and clearing of BUSY flag. The Cy_CapSense_IsBusy() function can be used to check BUSY flag;
  • - the interval between sub-sequent pulses should not be less than full scanning process duration. Disregarding the "Enable external frame start" option, the transition into a system DEEP SLEEP mode is allowed after the scan process is started by the function. To decrease the start scan time when it is intended to scan the same frame, i.e. startSlotId and numberSlots parameters are the same, then the scan is performed without the MSC HW block reconfiguration. In this case, the number of slots in the frame shall not exceed the maximum possible slot number to fit into the internal buffer of the CAPSENSE™ hardware block.

• For fifth-generation CAPSENSE™ this function initiates a scan for the first slot for all channels and then exits. Scans for the remaining slots in the Interrupt-driven scan mode are initiated in the interrupt service routine (part of middleware) triggered at the end of each scan completed for each channel. If the syncMode field in the cy_stc_capsense_common_config_t structure is set to CY_CAPSENSE_SYNC_MODE_OFF, then the next slot scan for the channel with the fired interrupt, will start regardless of the another channel readiness for the next scan. If the syncMode field is set to CY_CAPSENSE_SYNC_INTERNAL (for single-chip projects) or to CY_CAPSENSE_SYNC_EXTERNAL (for multi-chip projects), then the next slot scan for the channel with the fired interrupt, will start in lockstep with another channels after they all are ready for the next scan. The scan for the remaining slots in CS-DMA scan mode are initiated by DMAC triggered at the end of each scan completion for each channel. The channel scan synchronization is performed as in Interrupt-driven scan mode. After all specified slots are scanned, the FRAME interrupt is fired and the interrupt service routine (part of middleware) updates the busy status. The transition into a system DEEP SLEEP mode is allowed only when all specified scans are finished. To decrease the start scan time when it is intended to scan the same slot, i.e. the startSlotId parameter is the same and numberSlots = 1u, then the scan is performed without the MSC HW block reconfiguration. Also, in the legacy AMUX mode sensors are not disconnected.

If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment.

Note

This function is available for the fifth-generation and fifth-generation low power CAPSENSE™.

Parameters

startSlotId	The slot ID the scan of the specified frame will be started from.
numberSlots	The number of slots in the specified frame will be scanned.
context	The 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_HW_BUSY - The HW is busy with the previous scan.

Cy_CapSense_MwState()

cy_capsense_mw_state_t Cy_CapSense_MwState

(

const cy_stc_capsense_context_t *

context

)

Returns a detailed state of the CAPSENSE™ middleware and MSC and MSCLP HW blocks in Single- or Multi-channel mode.

This feature is useful in multi-thread applications or in ISR. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment. If the middleware is busy, a new scan, setup widgets, any kind of reconfiguration, or parameter change should not be initiated.

Note

This function is available for the fifth-generation and fifth-generation low power CAPSENSE™.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the state of the middleware as a sum of the state and status masks:

• CY_CAPSENSE_BUSY_CH_MASK - The set [x] bit of the result means that the previously initiated scan for the [x] channel is in progress. The next scan frame cannot be started.
• CY_CAPSENSE_MW_STATE_ACTIVE_WD_SCAN_MASK - The last or currently scanned widget type is Active widget.

  Note

  This field is available only for the fifth-generation low power CAPSENSE™.

• CY_CAPSENSE_MW_STATE_LP_WD_SCAN_MASK - The last or currently scanned widget type is Low Power widget.

  Note

  This field is available only for the fifth-generation low power CAPSENSE™.

• CY_CAPSENSE_BUSY - The previously initiated scan is in progress.
• CY_CAPSENSE_MW_STATE_BIST_MASK - The BIST is in progress. The next scan frame cannot be started.
• CY_CAPSENSE_MW_STATE_CALIBRATION_MASK - The auto-calibration is in progress. The next scan frame cannot be started.
• CY_CAPSENSE_MW_STATE_SMARTSENSE_MASK - The smart sensing algorithm is in progress. The next scan frame cannot be started.
• CY_CAPSENSE_MW_STATE_INITIALIZATION_MASK - Middleware initialization is in progress and the next scan frame cannot be initiated.
• CY_CAPSENSE_MW_STATE_SCAN_SLOT_MASK[x] - The set [x] number of the result means that the previously initiated scan for the [x] slot is completed or in progress. In CS-DMA mode, this field is set only for the first scanned slot.

Cy_CapSense_ScanAllWidgets()

cy_capsense_status_t Cy_CapSense_ScanAllWidgets

(

cy_stc_capsense_context_t *

context

)

Initiates scanning of all enabled widgets (and sensors) in the project.

For fifth-generation low power CAPSENSE™ the function initiates only Active widget scans. The initiation of a Low Power widget scan uses the Cy_CapSense_ScanAllLpWidgets() function.

This function initiates a scan only for the first sensor in the first widget for the fourth-generation CAPSENSE™ or a scan for the first slot for the fifth-generation CAPSENSE™ and fifth-generation low power CAPSENSE™ and then exits the function. The scan for the remaining sensors(slots) are initiated in the interrupt-driven mode in the interrupt service routine (part of middleware) triggered at the end of each scan completion or by DMA controllers in the DMA mode for the fifth-generation CAPSENSE™. For the fifth-generation low power CAPSENSE™ the remaining sensor scans depend on the ACTIVE sensor quantity, for details see the Cy_CapSense_ScanAllSlots() function description.

If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment. The application program should wait until the current frame scan is finished prior to start a next scan by using the function.

To get widget enable/working status the Cy_CapSense_IsWidgetEnabled() and Cy_CapSense_IsSlotEnabled() functions should be used. This status can be configured with Cy_CapSense_SetWidgetStatus() function.

Note

For the fifth-generation CAPSENSE™ and fifth-generation low power CAPSENSE™ it is recommended to use the Cy_CapSense_ScanAllSlots() function instead for compatibility with further CAPSENSE™ middleware versions.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the operation cy_capsense_status_t.

Cy_CapSense_ScanWidget()

cy_capsense_status_t Cy_CapSense_ScanWidget	(	uint32_t	widgetId,
		cy_stc_capsense_context_t *	context
	)

Performs the initialization required to scan the specified widget and triggers the scanning of all sensors in the widget.

If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment.

For fifth-generation low power CAPSENSE™ the function initiates only Active widget scans. To initiate Low Power widget scan use the Cy_CapSense_ScanLpWidget() function.

Note

For the fourth-generation this function is also available and it should be used instead of Cy_CapSense_SetupWidget() and Cy_CapSense_Scan() functions. The specified widget will remain set up after scanning completes. If this function is called multiple times on the same widget, the set up is only done the first time but a scan will be done each time the function is called. For the fifth-generation CAPSENSE™ this function is available in single-channel solution only. It is recommended to use the Cy_CapSense_ScanSlots() function instead for compatibility with further CAPSENSE™ middleware versions.

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 operation cy_capsense_status_t.

Cy_CapSense_IsBusy()

uint32_t Cy_CapSense_IsBusy

(

const cy_stc_capsense_context_t *

context

)

This function returns a status whether MW executes HW scanning at a particular moment.

If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment. If the middleware is busy, a new scan, setup widgets, any kind of reconfiguration, or parameter change should not be initiated.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the middleware as a sum of the masks.

• CY_CAPSENSE_NOT_BUSY - No scan is in progress and a next scan can be initiated.
• CY_CAPSENSE_BUSY - The previously initiated scan is in progress.

Cy_CapSense_InterruptHandler()

void Cy_CapSense_InterruptHandler	(	void *	base,
		cy_stc_capsense_context_t *	context
	)

Implements interrupt service routine for CAPSENSE™ middleware.

The CAPSENSE™ middleware uses this interrupt to implement a non-blocking sensor scan method, in which only the first sensor scan is initiated by the application program. Subsequent sensor scans are initiated in the interrupt service routine as soon as the current scan or current sub-frame is completed.

The CAPSENSE™ middleware does not initialize or modify the priority of interrupts. For the proper middleware operation, the application program must configure CAPSENSE™ block interrupt and assign the interrupt vector to the Cy_CapSense_InterruptHandler() function. Refer to function usage example for details.

The calls of the Start Sample and End Of Scan callbacks (see the Callbacks section for details) are the part of the Cy_CapSense_InterruptHandler() routine and they lengthen its execution. These callbacks should not lengthen the ISR execution too much to prevent different interrupt overlaps.

Parameters

base	The pointer to the base register address of the CAPSENSE™ HW block. This argument is kept for uniformity and backward compatibility and is not used. The function can be called with value NULL.
context	The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Function Usage

An example of the ISR initialization:

The CapSense_ISR_cfg variable should be declared by the application program according to the examples below:
For Core CM0+:

    #if (CY_CAPSENSE_PSOC4_FOURTH_GEN)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #elif (CY_CAPSENSE_PSOC4_FIFTH_GEN)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msc_0_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,               /* Interrupt priority is 3 */
        };
    #elif (CY_CAPSENSE_PSOC4_FIFTH_GEN_LP)
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msclp_interrupt_lp_IRQn, /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,                 /* Interrupt priority is 3 */
        };
    #endif

Note

MSCLP HW contains two interrupt sources. The CAPSENSE™ Middleware supports only the msclp_interrupt_lp_IRQn vector and therefore it should be used.

For Core CM4:

        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn, /* Interrupt source is the CSD interrupt */
            .intrPriority = 7u,            /* Interrupt priority is 7 */
        };

The CAPSENSE™ interrupt handler should be defined by the application program according to the example below:

void CapSense_InterruptHandler(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

Then, the application program should configure and enable the CSD block interrupt between calls of the Cy_CapSense_Init() and Cy_CapSense_Enable() functions:

    /* Capture the HW block and initialize it to the default state. */
    Cy_CapSense_Init(&cy_capsense_context);

    /* Initialize interrupt */
    Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
    NVIC_ClearPendingIRQ(CapSense_ISR_cfg.intrSrc);
    NVIC_EnableIRQ(CapSense_ISR_cfg.intrSrc);

    /* Initialize the firmware modules. */
    Cy_CapSense_Enable(&cy_capsense_context);

The CapSense_HW is the pointer to the base register address of the CAPSENSE™ HW block. A macro for the pointer is in the cycfg_peripherals.h file defined as <Personality_Name>_HW. If no name is specified, the following default names are used:

• csd_<Block_Number>_csd_<Block_Number>_HW - for forth-generation CAPSENSE™ HW.
• msc_<Block_Number>_msc_<Block_Number>_HW - for fifth-generation CAPSENSE™ HW.
• msclp_<Block_Number>_msclp_<Block_Number>_HW - for fifth-generation low power CAPSENSE™ HW.

An example of sharing the CSD HW block (fourth-generation CAPSENSE™) by the CAPSENSE™ middleware and CSDADC middleware.
Declares the CapSense_ISR_cfg variable:

        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn, /* Interrupt source is the CSD interrupt */
            .intrPriority = 7u,            /* Interrupt priority is 7 */
        };

Declares the CSDADC_ISR_cfg variable:

        const cy_stc_sysint_t CSDADC_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn, /* Interrupt source is the CSD interrupt */
            .intrPriority = 7u,            /* Interrupt priority is 7 */
        };

Defines the CAPSENSE™ interrupt handler:

void CapSense_InterruptHandler(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

Defines the CSDADC interrupt handler:

    static void CSDADC_Interrupt(void)
    {
        Cy_CSDADC_InterruptHandler(CSD0, &cy_csd_0_context);
    }

The part of the main.c FW flow:

        /* ... */

        /* Initialize CAPSENSE MW */
        Cy_CapSense_Init(&cy_capsense_context);
        Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
        NVIC_ClearPendingIRQ(CapSense_ISR_cfg.intrSrc);
        NVIC_EnableIRQ(CapSense_ISR_cfg.intrSrc);
        Cy_CapSense_Enable(&cy_capsense_context);
        Cy_CapSense_Save(&cy_capsense_context);

        /* Initialize CSDADC MW */
        Cy_CSDADC_Init(&CapSense_csdadc_config, &cy_csdadc_context);
        Cy_SysInt_Init(&CSDADC_ISR_cfg, &CSDADC_Interrupt);
        NVIC_ClearPendingIRQ(CSDADC_ISR_cfg.intrSrc);
        NVIC_EnableIRQ(CSDADC_ISR_cfg.intrSrc);
        Cy_CSDADC_Enable(&cy_csdadc_context);
        Cy_CSDADC_Save(&cy_csdadc_context);

        for (;;)
        {
            /* Switch to CAPSENSE MW */
            Cy_CapSense_Restore(&cy_capsense_context);
            Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_InterruptHandler);
                /* Perform sensing operation */
            Cy_CapSense_Save(&cy_capsense_context);

            /* Switch to CSDADC MW */
            Cy_CSDADC_Restore(&cy_csdadc_context);
            Cy_SysInt_Init(&CSDADC_ISR_cfg, &CSDADC_Interrupt);
                /* Do CSDADC measurement operation */
            Cy_CSDADC_Save(&cy_csdadc_context);
        }

        /* ... */

Cy_CapSense_ScanLpSlots()

cy_capsense_status_t Cy_CapSense_ScanLpSlots	(	uint32_t	startLpSlotId,
		uint32_t	numberLpSlots,
		cy_stc_capsense_context_t *	context
	)

Initiates a non-blocking scan for specified low power slots and exits.

Scanning is initiated only if no scan is in progress. Scans initiated by this function can be performed in different system power modes such as Active, Sleep or Deep Sleep. After all specified number of frames are scanned or if a touch is detected during the scan, the interrupt is fired, the CPU switches Power mode to Active and the interrupt service routine (part of middleware) transfers the last frame raw counts and clears the busy status. If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment. The function clears the CY_CAPSENSE_MW_STATE_LP_ACTIVE_MASK status bit. It is set when a touch detection occurs during the low power slot scans and will remain set until the next Cy_CapSense_ScanLpSlots() function call.

Note

This function is available only for the fifth-generation low power CAPSENSE™.

Parameters

startLpSlotId	The slot ID to start a scan from.
numberLpSlots	The number of slots to be scanned.
context	The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the operation:

• CY_CAPSENSE_STATUS_SUCCESS - The operation completed successfully.
• CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.
• CY_CAPSENSE_STATUS_HW_BUSY - The hardware is busy with the previous scan.

Cy_CapSense_ScanAllLpSlots()

cy_capsense_status_t Cy_CapSense_ScanAllLpSlots

(

cy_stc_capsense_context_t *

context

)

Initiates a non-blocking scan of all low power slots and then exits.

Scanning is initiated only if no scan is in progress. A scan initiated by this function can be performed in different power modes such as Active, Sleep or Deep Sleep. After all specified number of frames are scanned or if a touch is detected during the scan, the interrupt is fired, the CPU switches Power mode to Active and the interrupt service routine (part of middleware) updates the busy status. If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment.

Note

This function is available only for the fifth-generation low power CAPSENSE™.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the operation:

• CY_CAPSENSE_STATUS_SUCCESS - The operation completed successfully.
• CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.
• CY_CAPSENSE_STATUS_HW_BUSY - The hardware is busy with the previous scan.

Function Usage

    /* 
    * Scenario: Configure the hardware to perform scanning
    * in Autonomous mode (Wake On Touch), while the device is in Deep Sleep power mode.
    */

    /*
    * Option: Configure the number of scans performed in Autonomous mode.
    * The number of scans performed in Autonomous mode can be configured by
    * writing to the wotTimeout field. The default value is 100 scans.
    */
    cy_capsense_context.ptrInternalContext->wotTimeout = 60u;

    /*
    * Option: Configure the interval between low-power frames.
    * The interval between scans in Autonomous mode can be configured by using
    * Cy_CapSense_ConfigureMsclpWotTimer() function. This interval is inserted
    * before each scan, so the first scan starts only after the first interval
    * passes. The default value is 100000 us.
    */
    Cy_CapSense_ConfigureMsclpWotTimer(80000u, &cy_capsense_context);

    for (;;)
    {
        /*
        * This call starts scanning all low-power widgets. The scan is performed autonomously,
        * so the Deep Sleep transition is allowed.
        */
        Cy_CapSense_ScanAllLpSlots(&cy_capsense_context);

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

        if (0u != Cy_CapSense_IsAnyLpWidgetActive(&cy_capsense_context))
        {
            /* A touch is detected on a low-power widget, so switch the state machine to activate the widgets scan */
        }
        else
        {
            /* No activity, so run the LP scan again or perform a single active widget scan for the baseline update (to compensate temperature drift, etc.) */
        }
    }

Cy_CapSense_ScanAllLpWidgets()

cy_capsense_status_t Cy_CapSense_ScanAllLpWidgets

(

cy_stc_capsense_context_t *

context

)

Initiates a non-blocking scan for all low power widgets/sensors.

If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment.

The function is the wrapper for the Cy_CapSense_ScanAllLpSlots() function.

Note

This function is available only for the fifth-generation low power CAPSENSE™.

Parameters

context

The 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_HW_BUSY - The hardware is busy with the previous scan.

Cy_CapSense_ConfigureMsclpWotTimer()

cy_capsense_status_t Cy_CapSense_ConfigureMsclpWotTimer	(	uint32_t	wakeupTimer,
		cy_stc_capsense_context_t *	context
	)

Configures the wakeup timer value for Wake-On-Touch mode.

The wakeup time is introduced before each scan frame.

The minimum wakeup time value is corresponding to one ILO cycle (25us for 40KHz ILO). The maximum wakeup time value depends on actual ILO frequency and can be set to a value, corresponding to 2^16 ILO cycles (1638400us for 40KHz ILO). If the timer value exceeds 2^16 ILO cycles, it would be set to the maximum possible value. The real wakeup time interval depends on ILO frequency which have a big tolerance (above +/- 50 %), see device datasheets. In order to improve the timer accuracy, use Cy_CapSense_IloCompensate() function.

Note

This function is available only for the fifth-generation low power CAPSENSE™.

Parameters

wakeupTimer	The desired wakeup timer value in microseconds.
context	The 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.

Function Usage

    /* 
    * Scenario: Configure the hardware to perform scanning
    * in Autonomous mode (Wake On Touch), while the device is in Deep Sleep power mode.
    */

    /*
    * Option: Configure the number of scans performed in Autonomous mode.
    * The number of scans performed in Autonomous mode can be configured by
    * writing to the wotTimeout field. The default value is 100 scans.
    */
    cy_capsense_context.ptrInternalContext->wotTimeout = 60u;

    /*
    * Option: Configure the interval between low-power frames.
    * The interval between scans in Autonomous mode can be configured by using
    * Cy_CapSense_ConfigureMsclpWotTimer() function. This interval is inserted
    * before each scan, so the first scan starts only after the first interval
    * passes. The default value is 100000 us.
    */
    Cy_CapSense_ConfigureMsclpWotTimer(80000u, &cy_capsense_context);

    for (;;)
    {
        /*
        * This call starts scanning all low-power widgets. The scan is performed autonomously,
        * so the Deep Sleep transition is allowed.
        */
        Cy_CapSense_ScanAllLpSlots(&cy_capsense_context);

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

        if (0u != Cy_CapSense_IsAnyLpWidgetActive(&cy_capsense_context))
        {
            /* A touch is detected on a low-power widget, so switch the state machine to activate the widgets scan */
        }
        else
        {
            /* No activity, so run the LP scan again or perform a single active widget scan for the baseline update (to compensate temperature drift, etc.) */
        }
    }

Cy_CapSense_ConfigureMsclpTimer()

cy_capsense_status_t Cy_CapSense_ConfigureMsclpTimer	(	uint32_t	wakeupTimer,
		cy_stc_capsense_context_t *	context
	)

Configures the wakeup timer value for Active mode.

The wakeup timer interval is introduced before each scan frame start. Use the function to implement different Active scan refresh rates (for instance an Active mode with the 128 Hz refresh rate and an Active Low Refresh Rate mode with the 32 Hz refresh rate).

The minimum wakeup time value is corresponding to one ILO cycle (25us for 40KHz ILO). The maximum wakeup time value depends on actual ILO frequency and can be set to a value, corresponding to 2^16 ILO cycles (1638400us for 40KHz ILO). If the timer value exceeds 2^16 ILO cycles, it would be set to the maximum possible value. The real wakeup time interval depends on ILO frequency which have a big tolerance (above +/- 50 %), see device datasheets. In order to improve the timer accuracy, use Cy_CapSense_IloCompensate() function.

Note

This function is available only for the fifth-generation low power CAPSENSE™.

Parameters

wakeupTimer	The desired wakeup timer value in microseconds.
context	The 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.

Function Usage

    /*
    * Scenario: Scan all Active widgets in Low Refresh mode at 30 Hz (30 samples per second).
    * This saves power due to entering Deep Sleep power mode during scanning.
    * The timer value can be calculated as follows: ((1000 / refresh rate) - frame scan duration).
    * To achieve the desired refresh rate, configure the wake-up timer to insert the 32-ms delay
    * before scanning, given the frame scan duration equals 1ms.
    */

    /* Define the 32-ms delay for the wake-up timer **/
    #define ALR_INTERVAL_US    (32000u)

    /* Configure the hardware wake-up timer */
    Cy_CapSense_ConfigureMsclpTimer(ALR_INTERVAL_US, &cy_capsense_context);

    for (;;)
    {
        /*
        * This call starts scanning with a delay inserted before scanning.
        * Scanning will be performed autonomously after a delay is inserted by the internal wake-up timer.
        */
        Cy_CapSense_ScanAllSlots(&cy_capsense_context);

        /* To save power, move the device to Deep Sleep */
        while (CY_CAPSENSE_NOT_BUSY != Cy_CapSense_IsBusy(&cy_capsense_context))
        {
            Cy_SysPm_CpuEnterDeepSleep ();
        }

        Cy_CapSense_ProcessAllWidgets(&cy_capsense_context);

        if (0u != Cy_CapSense_IsAnyWidgetActive(&cy_capsense_context))
        {
            /* Touch on widget is detected */
        }
    }

Cy_CapSense_IloCompensate()

cy_capsense_status_t Cy_CapSense_IloCompensate

(

cy_stc_capsense_context_t *

context

)

Measures the actual ILO frequency and calculates the compensation factor for MSCLP Active and Wake-On-Touch mode timers.

In order to keep timer intervals accurate, call this function periodically. To set Active and Wake-On-Touch mode timers, use Cy_CapSense_ConfigureMsclpTimer() and Cy_CapSense_ConfigureMsclpWotTimer() functions correspondingly.

Note

SysClk should be clocked by IMO, otherwise the Cy_CapSense_IloCompensate() function can work incorrectly.

If the System clock frequency is changed in runtime, the mtb-pdl-cat2 SystemCoreClockUpdate() function should be called before calling Cy_CapSense_IloCompensate().

This function is blocking, function execution time is ~1ms, regardless of IMO frequency.

This function is available only for the fifth-generation low power CAPSENSE™.

Parameters

context

The 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_SetupWidget()

cy_capsense_status_t Cy_CapSense_SetupWidget	(	uint32_t	widgetId,
		cy_stc_capsense_context_t *	context
	)

Performs the initialization required to scan the specified widget.

Attention

This function is deprecated, it will become obsolete in upcoming major version of middleware. It is kept for backward compatibility only. The Cy_CapSense_ScanWidget() function should be used instead.

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

1. Configure the CSD HW block if it is not configured to perform the sensing method used by the specified widget. This happens only if the CSD and CSX methods are used in a user's project.
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.

This function does not start sensor scanning. The Cy_CapSense_Scan() 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.

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.

Note

This function is available only for the fourth-generation CAPSENSE™.

Parameters

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

Returns

Returns the status of the widget setting up operation:

• CY_CAPSENSE_STATUS_SUCCESS - The operation is successfully completed.
• CY_CAPSENSE_STATUS_BAD_PARAM - The widget is invalid or if the specified widget is disabled.
• CY_CAPSENSE_STATUS_INVALID_STATE - The previous scanning is not completed and the CSD HW block is busy.
• CY_CAPSENSE_STATUS_UNKNOWN - An unknown sensing method is used by the widget or any other spurious error occurred.

Cy_CapSense_Scan()

cy_capsense_status_t Cy_CapSense_Scan

(

cy_stc_capsense_context_t *

context

)

Initiates scanning of all the sensors in the widget initialized by Cy_CapSense_SetupWidget(), if no scan is in progress.

Attention

This function is deprecated, it will become obsolete in upcoming major version of middleware. It is kept for backward compatibility only. The Cy_CapSense_ScanWidget() function should be used instead without additional call of Cy_CapSense_SetupWidget().

Prior to calling this function to scan sensors, the widget required to be scanned must be initialized using Cy_CapSense_SetupWidget() function.

This function initiates scan only for the first sensor in the widget and then exits the function. The scan for the remaining sensors in the widget is initiated in the interrupt service routine (part of middleware) triggered at the end of each scan completion. Hence, check the status of the current scan using the Cy_CapSense_IsBusy() function and wait until all scans in the current widget are finished prior to starting the next scan or initializing another widget.

Note

This function is available only for the fourth-generation CAPSENSE™.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the status of the scan initiation operation:

• CY_CAPSENSE_STATUS_SUCCESS - Scanning is successfully started.
• CY_CAPSENSE_STATUS_INVALID_STATE - The previous scan is not completed and the CSD HW block is busy.
• CY_CAPSENSE_STATUS_UNKNOWN - An unknown sensing method is used by the widget.

Cy_CapSense_IsAnyWidgetActive()

uint32_t Cy_CapSense_IsAnyWidgetActive

(

const cy_stc_capsense_context_t *

context

)

Reports whether any widget has detected touch.

This function reports whether any widget has detected a touch by extracting information from the widget status registers. This function does not process widget data but extracts previously processed results from the Structures.

Note

For the fifth-generation low power CAPSENSE™ widgets of the CY_CAPSENSE_WD_LOW_POWER_E type are not processed, its status is not taken into account.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the touch detection status of all the widgets:

• Zero - No touch is detected in any of the widgets or sensors.
• Non-zero - At least one widget or sensor has detected a touch.

Cy_CapSense_IsAnyLpWidgetActive()

uint32_t Cy_CapSense_IsAnyLpWidgetActive

(

const cy_stc_capsense_context_t *

context

)

Reports whether any low power widget has detected a touch at the previous low power scan.

This function reports whether any low power widget has detected a touch by extracting information from the common status register. The function does not process the widget data but extracts the result obtained at the previous low power widget scan. The result remains set up to the next low power widget scan and is reset with the low power scan start.

Note

This function is available only for the fifth-generation low power CAPSENSE™.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the touch detection status of all the widgets:

• Zero - No touch is detected in any of the low power widgets or sensors
• CY_CAPSENSE_MW_STATE_LP_ACTIVE_MASK - At least one low power widget or sensor has detected a touch at the previous scan

Cy_CapSense_IsWidgetActive()

uint32_t Cy_CapSense_IsWidgetActive	(	uint32_t	widgetId,
		const cy_stc_capsense_context_t *	context
	)

Reports whether the specified widget detected touch on any of its sensors.

This function reports whether the specified widget has detected a touch by extracting information from the widget status register. This function does not process widget data but extracts previously processed results from the Structures.

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.

Note

For the fifth-generation low power CAPSENSE™ widgets of the CY_CAPSENSE_WD_LOW_POWER_E type are not processed and a zero is returned.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

Returns the touch detection status of the specified widgets:

• Zero - No touch is detected in the specified widget or a wrong widgetId is specified.
• Non-zero if at least one sensor of the specified widget is active, i.e. a touch is detected.

Cy_CapSense_IsSensorActive()

uint32_t Cy_CapSense_IsSensorActive	(	uint32_t	widgetId,
		uint32_t	sensorId,
		const cy_stc_capsense_context_t *	context
	)

Reports whether the specified sensor in the widget is sensor detects a touch.

This function reports whether the specified sensor in the widget has detected a touch by extracting information from the widget status register. This function does not process widget or sensor data but extracts previously processed results from the Structures.

For proximity sensors, this function returns the proximity detection status. To get the touch status of proximity sensors, use the Cy_CapSense_IsProximitySensorActive() function.

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.

Note

For the fifth-generation low power CAPSENSE™ widgets of the CY_CAPSENSE_WD_LOW_POWER_E type are not processed and a zero is returned.

Parameters

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 touch detection status of the specified sensor/widget:

• Zero if no touch is detected in the specified sensor/widget or a wrong widget ID/sensor ID is specified.
• Non-zero if the specified sensor is active, i.e. touch is detected. If the specific sensor belongs to a proximity widget, the proximity detection status is returned.

Cy_CapSense_IsProximitySensorActive()

uint32_t Cy_CapSense_IsProximitySensorActive	(	uint32_t	widgetId,
		uint32_t	sensorId,
		const cy_stc_capsense_context_t *	context
	)

Reports the status of the specified proximity widget/sensor.

This function reports whether the specified proximity sensor has detected a touch or proximity event by extracting information from the widget status register. This function is used only with proximity widgets. This function does not process widget data but extracts previously processed results from the Structures.

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 of the proximity widget. Zero indicates that no touch is detected in the specified sensor/widget or a wrong widgetId/proxId is specified.

• Bits [31..2] are reserved.
• Bit [1] indicates that a touch is detected.
• Bit [0] indicates that a proximity is detected.

Cy_CapSense_GetTouchInfo()

cy_stc_capsense_touch_t* Cy_CapSense_GetTouchInfo	(	uint32_t	widgetId,
		const cy_stc_capsense_context_t *	context
	)

Reports the details of touch position detected on the specified touchpad, matrix buttons or slider widgets.

This function does not process widget data but extracts previously processed results from the Structures.

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 pointer to widget cy_stc_capsense_touch_t structure that contains number of positions and data about each position.

Cy_CapSense_RunTuner()

uint32_t Cy_CapSense_RunTuner

(

cy_stc_capsense_context_t *

context

)

Establishes synchronized operation between the CAPSENSE™ Middleware and the CAPSENSE™ Tuner tool.

This function is called periodically in the application program. It serves the CAPSENSE™ Tuner tool requests and commands to synchronize the operation. Mostly, the best place to call this function is between processing and next scanning. If the user changes some parameters in the Tuner tool, the middleware is re-started - the Tuner issues a restart command to be executed by this function.

The Tuner interface supports two communication protocol: EZI2C and UART.

To use an EZI2C-based tuner interface, only initialization of the EZI2C driver and interface is required in the application program. Refer to the I2C driver documentation for details of the protocol implementation and data package format by the EZI2C interface.

To use a UART-based tuner interface, the user must:

• Initialize the UART driver and interface
• Use a callback function to facilitate data transmission and reception using the UART driver.

The application program must:

• Form a transmission data packet
• Validate the data package on receiver implementation prior to passing to the CAPSENSE™ Middleware.

The transmission packet includes a CAPSENSE™ context structure sandwiched between a header (0x0D0A) and a tail (0x00FFFF), hence the package size is dependent on CAPSENSE™ context information. The receiver packet is 16-byte (fixed length) data explained under the Cy_CapSense_CheckTunerCmdIntegrity() function. The Cy_CapSense_CheckTunerCmdIntegrity() function is used to validate the received data package prior to passing it to the CAPSENSE™ middleware.

Periodical calling the Cy_CapSense_RunTuner() function is:

• mandatory for operation of a UART-based tuner interface. The middleware operation is always synchronous to the Tuner tool.
• optional for EZI2C based interface.

If the Cy_CapSense_RunTuner() function is not periodically called by the application program, the middleware operation is asynchronous to the Tuner tool and the following disadvantages are applicable:

• The raw counts displayed in the CAPSENSE™ Tuner tool may be filtered and/or non-filtered. Result - noise and SNR measurements are not accurate.
• The CAPSENSE™ Tuner tool can read sensor data (such as raw counts) from a scan multiply. Result - noise and SNR measurement are not accurate.
• The CAPSENSE™ Tuner tool and Host controller should not change the parameters via the Tuner interface - in async mode this leads to abnormal behaviour.
• Displaying detected gestures may be missed.
• The raw counts of CSX and/or ISX sensors may be non-inverted.

Warning

This function executes received commands. Two commands CY_CAPSENSE_TU_CMD_ONE_SCAN_E and CY_CAPSENSE_TU_CMD_SUSPEND_E change the FW tuner module state to suspend. In this state, the function waits until CY_CAPSENSE_TU_CMD_RESUME_E is received. Use a callback mechanism of command receiving to avoid FW hanging. Refer to the Function Usage section for examples.

Parameters

context

The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t.

Returns

The return parameter indicates whether a middleware re-start was executed by this function or not:

• CY_CAPSENSE_STATUS_RESTART_DONE - Based on a received command, the CAPSENSE™ was re-initialized.
• CY_CAPSENSE_STATUS_RESTART_NONE - Re-start was not executed by this function.

Function Usage

An example of synchronization with the Tuner tool using EzI2C interface:

1. In the Device Configurator, enable the SCB resource in the EzI2C mode with the "EZI2C" name. Configure interface parameters, assign required clock source and pins. Note that in the CapSense Tuner tool, I2C interface settings should match device EzI2C configuration.
2. Declare EzI2C interface context:

   cy_stc_scb_ezi2c_context_t EZI2C_context;

3. Setup EzI2C interrupt handler:

   static void EZI2C_Interrupt(void)
   {
       Cy_SCB_EZI2C_Interrupt(EZI2C_HW, &EZI2C_context);
   }

4. Configure EzI2C buffer and use EzI2C as the tuner interface:

   
       /* EZI2C Initialization and assignment of communication buffer to cy_capsense_tuner */
       Cy_SCB_EZI2C_Init(EZI2C_HW, &EZI2C_config, &EZI2C_context);
       Cy_SysInt_Init(&EZI2C_ISR_cfg, &EZI2C_Interrupt);
       NVIC_EnableIRQ(EZI2C_ISR_cfg.intrSrc);
       Cy_SCB_EZI2C_SetBuffer1(EZI2C_HW, (uint8_t *)&cy_capsense_tuner, sizeof(cy_capsense_tuner), sizeof(cy_capsense_tuner), &EZI2C_context);
       Cy_SCB_EZI2C_Enable(EZI2C_HW);
   
       /* Initialize the firmware modules. */
       if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_Enable(&cy_capsense_context))
       {
           /* Insert the error handle code here, for instance as below */
           CY_ASSERT(0u);
       }
   
       for (;;)
       {
           if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
           {
               if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ProcessAllWidgets(&cy_capsense_context))
               {
                   /* Insert the error handle code here, for instance as below */
                   CY_ASSERT(0u);
               }
   
               (void)Cy_CapSense_RunTuner(&cy_capsense_context);
   
               if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ScanAllWidgets(&cy_capsense_context))
               {
                   /* Insert the error handle code here, for instance as below */
                   CY_ASSERT(0u);
               }
           }
       }
   

An example of synchronization with the Tuner tool using UART interface:

1. In the Device Configurator, enable the SCB resource in the UART mode with the "UART" name. Configure interface parameters, assign required clock source and pins. Note that in the CapSense Tuner tool, UART interface settings should match device UART configuration.
2. Declare UART interface context:

   cy_stc_scb_uart_context_t UART_context;

3. Setup UART interrupt handler:

   void UART_Interrupt(void)
   {
       Cy_SCB_UART_Interrupt(UART_HW, &UART_context);
   }

4. Add Send callback implementation:

   void TunerSend(void * context)
   {
       uint8_t uartTxHeader[] = {0x0Du, 0x0Au};
       uint8_t uartTxTail[] = {0x00u, 0xFFu, 0xFFu};
   
       (void)context;
   
       Cy_SCB_UART_PutArrayBlocking(UART_HW, &(uartTxHeader[0u]), sizeof(uartTxHeader));
       Cy_SCB_UART_PutArrayBlocking(UART_HW, (uint8_t *)&cy_capsense_tuner, sizeof(cy_capsense_tuner));
       Cy_SCB_UART_PutArrayBlocking(UART_HW, &(uartTxTail[0u]), sizeof(uartTxTail));
   
       /* Blocking wait for transfer completion */
       while (!Cy_SCB_UART_IsTxComplete(UART_HW))
       {
       }
   }

5. Add Receive callback implementation:

   void TunerReceive(uint8_t ** packet, uint8_t ** tunerPacket, void * context)
   {
       uint32_t i;
       (void)context;
       static uint32_t dataIndex = 0u;
       static uint8_t commandPacket[CY_CAPSENSE_COMMAND_PACKET_SIZE] = {0u};
       uint32_t numBytes;
   
       while(0u != Cy_SCB_UART_GetNumInRingBuffer(UART_HW, &UART_context))
       {
           numBytes = Cy_SCB_UART_GetNumInRingBuffer(UART_HW, &UART_context);
   
           /* Calculate number of bytes to read from ring buffer */
           if ((CY_CAPSENSE_COMMAND_PACKET_SIZE - dataIndex) < numBytes)
           {
               numBytes = CY_CAPSENSE_COMMAND_PACKET_SIZE - dataIndex;
           }
   
           /* Add received data to the end of commandPacket */
           Cy_SCB_UART_Receive(UART_HW, &commandPacket[dataIndex], numBytes, &UART_context);
           dataIndex += numBytes;
   
           if (CY_CAPSENSE_COMMAND_PACKET_SIZE <= dataIndex)
           {
               if (CY_CAPSENSE_COMMAND_OK == Cy_CapSense_CheckTunerCmdIntegrity(&commandPacket[0u]))
               {
                   /* Found a correct command, reset data index and assign pointers to buffers */
                   dataIndex = 0u;
                   *tunerPacket = (uint8_t *)&cy_capsense_tuner;
                   *packet = &commandPacket[0u];
                   break;
               }
               else
               {
                   /* Command is not correct, remove the first byte in commandPacket buffer */
                   dataIndex--;
                   for (i = 0u; i < (CY_CAPSENSE_COMMAND_PACKET_SIZE - 1u); i++)
                   {
                       commandPacket[i] = commandPacket[i + 1u];
                   }
               }
           }
       }
   }

6. Configure UART RX ring buffer and register Send and Receive callbacks as a part of the main.c FW flow:

       /*...*/
   
       /* Define UART ring buffer size to hold extra tuner command packets.
       *  Additional byte is required by the UART ring buffer implementation.
       */
       #define UART_RINGBUFFER_SIZE (CY_CAPSENSE_COMMAND_PACKET_SIZE * 2u + 1u)
   
       static uint8_t uartRingBuffer[UART_RINGBUFFER_SIZE];
   
       const cy_stc_sysint_t uart_intr_config =
       {
           .intrSrc = UART_IRQ,
           .intrPriority = 2u,
       };
   
       /* Register communication callbacks */
       cy_capsense_context.ptrInternalContext->ptrTunerSendCallback = TunerSend;
       cy_capsense_context.ptrInternalContext->ptrTunerReceiveCallback = TunerReceive;
   
       /* Configure and enable UART communication */
       Cy_SCB_UART_Init(UART_HW, &UART_config, &UART_context);
       Cy_SysInt_Init(&uart_intr_config, UART_Interrupt);
       NVIC_EnableIRQ(uart_intr_config.intrSrc);
       Cy_SCB_UART_StartRingBuffer(UART_HW, uartRingBuffer, UART_RINGBUFFER_SIZE, &UART_context);
       Cy_SCB_UART_Enable(UART_HW);
   
       /* Initialize the firmware modules. */
       if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_Enable(&cy_capsense_context))
       {
           /* Insert the error handle code here, for instance as below */
           CY_ASSERT(0u);
       }
   
       for (;;)
       {
           if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
           {
               if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ProcessAllWidgets(&cy_capsense_context))
               {
                   /* Insert the error handle code here, for instance as below */
                   CY_ASSERT(0u);
               }
               /*
               * Cy_CapSense_RunTuner() calls periodically communication callbacks
               * for hence the Tuner tool are able to monitor sensor signals/statuses
               * and change the parameters for easy tuning.
               */
               (void)Cy_CapSense_RunTuner(&cy_capsense_context);
   
               if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_ScanAllWidgets(&cy_capsense_context))
               {
                   /* Insert the error handle code here, for instance as below */
                   CY_ASSERT(0u);
               }
           }
       }
       /*...*/
   

   Refer to the Callbacks section for details.

Note

For the fifth-generation Low Power CAPSENSE™ you may encounter issue with the Tuner tool connection establishment for both EZI2C and UART interfaces. This may happen due to usage of the Sleep or Deep Sleep power modes during the scan operation. Depending on the project configuration, scan length may exceed the Tuner tool connection timeout. Since the Tuner tool resets the device during the connection establishment, you can add following code to your application after the communication interface initialization and before the main loop to eliminate the issue:

    /* Communication interface initialization */

    /*...*/

    /* Initialize the firmware modules. */
    if (CY_CAPSENSE_STATUS_SUCCESS != Cy_CapSense_Enable(&cy_capsense_context))
    {
        /* Insert the error handle code here, for instance as below */
        CY_ASSERT(0u);
    }

    /* Delay to allow the device to receive the command from the Tuner Tool.
    *  The delay time depends on the configuration and the device initialization time.
    */
    Cy_SysLib_Delay(100u);

    /* Process first received command, if available */
    (void)Cy_CapSense_RunTuner(&cy_capsense_context);

    for (;;)
    {
        /*...*/

Cy_CapSense_CheckTunerCmdIntegrity()

uint32_t Cy_CapSense_CheckTunerCmdIntegrity

(

const uint8_t *

commandPacket

)

Checks command format, header, tail, CRC, etc.

This function checks whether the specified packet with the size CY_CAPSENSE_COMMAND_PACKET_SIZE could be represented as a command received from the CAPSENSE™ Tuner tool. The verification includes the following items:

• Header
• Tail
• CRC
• Command code

Command format is the following:

• Byte 0: Header 0 = 0x0D
• Byte 1: Header 1 = 0x0A
• Byte 2: Command code = cy_en_capsense_tuner_cmd_t
• Byte 3: Command counter
• Byte 4: Size = either 1, 2 or 4
• Byte 5: Offset MSB
• Byte 6: Offset LSB
• Byte 7: Data MSB
• Byte 8: Data
• Byte 9: Data
• Byte 10: Data LSB
• Byte 11: 16-bit CRC MSB
• Byte 12: 16-bit CRC LSB
• Byte 13: Tail 0 = 0x00
• Byte 14: Tail 1 = 0xFF
• Byte 15: Tail 2 = 0xFF

Parameters

commandPacket

The pointer to the data packet that should be verified.

Returns

Returns the result of the command verification:

• CY_CAPSENSE_COMMAND_OK - Command is correct.
• CY_CAPSENSE_WRONG_HEADER - Wrong header.
• CY_CAPSENSE_WRONG_TAIL - Wrong tail.
• CY_CAPSENSE_WRONG_CRC - Wrong CRC.
• CY_CAPSENSE_WRONG_CODE - Wrong Command code.