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.

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_status	Cy_CapSense_Init (cy_stc_capsense_context_t *context)
	Captures the CSD HW block and configures it to the default state. More...
cy_status	Cy_CapSense_DeInit (cy_stc_capsense_context_t *context)
	Stops the middleware operation and releases the CSD HW block. More...
cy_status	Cy_CapSense_Enable (cy_stc_capsense_context_t *context)
	Initializes the CapSense firmware modules. More...
cy_status	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_status	Cy_CapSense_Restore (cy_stc_capsense_context_t *context)
	Resumes the middleware operation if the Cy_CapSense_Save() function was called previously. More...
cy_status	Cy_CapSense_ProcessAllWidgets (cy_stc_capsense_context_t *context)
	Performs full data processing of all enabled widgets. More...
cy_status	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 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 Active to Deep Sleep power mode transition for the CapSense middleware. More...
cy_status	Cy_CapSense_RegisterCallback (cy_en_capsense_callback_event_t callbackType, cy_capsense_callback_t callbackFunction, cy_stc_capsense_context_t *context)
	Registers a callback function. More...
cy_status	Cy_CapSense_UnRegisterCallback (cy_en_capsense_callback_event_t callbackType, cy_stc_capsense_context_t *context)
	This function unregisters a previously registered callback function in the CapSense middleware. More...
uint32_t	Cy_CapSense_DecodeWidgetGestures (uint32_t widgetId, const cy_stc_capsense_context_t *context)
	Performs processing of all gestures for the specified widget. More...
cy_status	Cy_CapSense_SetupWidget (uint32_t widgetId, cy_stc_capsense_context_t *context)
	Performs the initialization required to scan the specified widget. More...
cy_status	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...
cy_status	Cy_CapSense_ScanAllWidgets (cy_stc_capsense_context_t *context)
	Initiates scanning of all enabled widgets (and sensors) in the project. More...
uint32_t	Cy_CapSense_IsBusy (const cy_stc_capsense_context_t *context)
	This function returns a status of the CapSense middleware whether a scan is currently in progress or not. More...
void	Cy_CapSense_InterruptHandler (const CSD_Type *base, cy_stc_capsense_context_t *context)
	Implements interrupt service routine for CapSense Middleware. 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_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 detected 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_CheckCommandIntegrity (const uint8_t *commandPacket)
	Checks command format, header, tail, CRC, etc. More...

Function Documentation

Cy_CapSense_Init()

cy_status Cy_CapSense_Init

(

cy_stc_capsense_context_t *

context

)

Captures the CSD HW block and configures it to the default state.

This function is called by the application program prior to calling any other function of the middleware.

The following tasks are executed:

1. Capturing the CSD HW block if it is not in use. If the CSD HW block is already in use, then the function returns fail status. In this case, the application program should perform corresponding actions like releasing the CSD HW block captured by other middleware.
2. If the CSD HW block was captured this function configures it to the default state.

After the middleware is configured using Cy_CapSense_Init() function, application program should configure and enable the CSD block interrupt, 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 CSD HW Block 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_RET_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 CSD HW block and initialize it to the default state. */
    Cy_CapSense_Init(&cy_capsense_context);

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

    /* Initialize the CapSense 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:

const cy_stc_sysint_t CapSense_ISR_cfg =
{
    .intrSrc = NvicMux2_IRQn,       /* CM0+ interrupt is NVIC #2 */
    .cm0pSrc = csd_interrupt_IRQn,  /* Source of NVIC #2 is the CSD interrupt */
    .intrPriority = 3u,             /* Interrupt priority is 3 */
};

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 snippet_Cy_CapSense_IntHandler(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

The CapSense_HW is the pointer to the base register address of the CSD HW block. A macro for the pointer can be found in cycfg_peripherals.h file defined as <Csd_Personality_Name>_HW. If no name specified then the default name is used csd_<Block_Number>_csd_<Block_Number>_HW.

Cy_CapSense_DeInit()

cy_status Cy_CapSense_DeInit

(

cy_stc_capsense_context_t *

context

)

Stops the middleware operation and releases the CSD HW block.

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 it is stopped, the CSD HW block may be reconfigured by 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 initialization process and it is not needed to call the Cy_CapSense_Enable() function second time. However, to implement time-multiplexed mode (sharing the CSD HW Block 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_RET_SUCCESS is not received, the stop process fails and retries may be required.

Cy_CapSense_Enable()

cy_status Cy_CapSense_Enable

(

cy_stc_capsense_context_t *

context

)

Initializes the CapSense firmware modules.

This function requires the Cy_CapSense_Init() function is called and the CSD HW block interrupt to be configured 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 CSD HW block to perform capacitive sensing operation.
4. If SmartSense Auto-tuning is selected for the CSD Tuning mode in the Basic tab, the auto-tuning algorithm is executed to set the optimal values for the CSD HW block parameters of the widgets/sensors.
5. Calibrate the sensors and find the optimal values for IDACs of each widget/sensor, if the Enable IDAC auto-calibration is enabled in the CSD Setting or CSX Setting tabs.

1. Perform scanning for all the sensors and initialize the baseline history.
2. If the firmware filters are enabled in the Advanced General tab, the filter histories are also initialized.

Any subsequent call of this function repeats 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.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

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

Function Usage

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

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

    /* Initialize the CapSense 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:

const cy_stc_sysint_t CapSense_ISR_cfg =
{
    .intrSrc = NvicMux2_IRQn,       /* CM0+ interrupt is NVIC #2 */
    .cm0pSrc = csd_interrupt_IRQn,  /* Source of NVIC #2 is the CSD interrupt */
    .intrPriority = 3u,             /* Interrupt priority is 3 */
};

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 snippet_Cy_CapSense_IntHandler(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

The CapSense_HW is the pointer to the base register address of the CSD HW block. A macro for the pointer can be found in cycfg_peripherals.h file defined as <Csd_Personality_Name>_HW. If no name is specified then the default name is used csd_<Block_Number>_csd_<Block_Number>_HW.

Cy_CapSense_Save()

cy_status 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 CSD HW block among multiple middlewares. When the CSD HW block is shared by two or more middlewares, this function can be used to save the current state of the CSD HW block and CapSense middleware prior to releasing the CSD 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:

• Release the CSD HW block.
• Configure sensor pins to the default state and disconnect them from analog buses.
• Disconnect external capacitors from analog buses.
• Set 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_RET_SUCCESS is not received, the save process fails and retries may be required.

Function Usage

An example of sharing the CSD 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:

static void CapSense_Interrupt(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

Defines the CSDADC interrupt handler:

static void CSDADC_Interrupt(void)
{
    Cy_CSDADC_InterruptHandler(&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_Interrupt);
    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_Interrupt);
            /* Do CapSense 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_status 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 CSD HW block among multiple middlewares. When the CSD HW block is shared by two or more middlewares, this function can be used to restore the previous state of the CSD HW block and CapSense middleware 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_RET_SUCCESS is not received, the resume process fails and retries may be required.

Function Usage

An example of sharing the CSD HW block by CapSense and CSDADC middleware:

    /* ... */

    /* Initialize CapSense MW */
    Cy_CapSense_Init(&cy_capsense_context);
    Cy_SysInt_Init(&CapSense_ISR_cfg, &CapSense_Interrupt);
    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_Interrupt);
            /* Do CapSense 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_status 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 SmartSense 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.

The disabled 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_RET_SUCCESS is not received, the processing fails and retries may be required.

Cy_CapSense_ProcessWidget()

cy_status 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_SetupWidget() and Cy_CapSense_Scan() functions to scan and process data for a specific widget. This function is called only after all the sensors in the widgets are scanned. A disabled widget is not processed by this function.

A pipeline scan method (i.e. during scanning of a widget performing processing of the previously scanned widget) can be implemented using this function and it may reduce the total execution time, increase the refresh rate and decrease the average power consumption.

A pipeline scan method (i.e. during scanning of a current widget (N), perform 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.

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 processing:

• CY_RET_SUCCESS - The operation is successfully completed
• CY_RET_BAD_PARAM - The input parameter is invalid
• CY_RET_INVALID_STATE - The specified widget is disabled
• CY_RET_BAD_DATA - The processing is failed

Function Usage

An example of pipeline implementation:

    /*...*/
    currentWidgetId = 0u;
    previousWidgetId = 0u;

    /* Trigger scanning */
    Cy_CapSense_SetupWidget(currentWidgetId, &cy_capsense_context);
    Cy_CapSense_Scan(&cy_capsense_context);

    for(;;)
    {
        if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
        {
            currentWidgetId = (currentWidgetId < (cy_capsense_context.ptrCommonConfig->numWd - 1u)) ? (currentWidgetId + 1u) : 0u;

            /* Trigger scanning of the next widget */
            Cy_CapSense_SetupWidget(currentWidgetId, &cy_capsense_context);
            Cy_CapSense_Scan(&cy_capsense_context);

            /* Process a previous widget during scanning of the current widget */
            Cy_CapSense_ProcessWidget(previousWidgetId, &cy_capsense_context);
            previousWidgetId = currentWidgetId;
        }
    }
    /*...*/

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 operation of the Gesture and Ballistic multiplier feature. Hence this function and timestamp is 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 at interval set in the register.

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);

        /* Trigger the next scan */
        Cy_CapSense_Scan(&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 Deep Sleep.

This function is used to resume the middleware operation after exiting Deep Sleep. In Deep Sleep power mode, the CSD HW block is powered off and an extra delay is required to establish correct operation of the CSD HW block.

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 Active to Deep Sleep power mode transition for the CapSense middleware.

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

For proper operation of the CapSense middleware during the Active to 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_DeepSleep() function to prepare the middleware to the device power mode transition.

When this function is called with CY_SYSPM_CHECK_READY as input, this function returns CY_SYSPM_SUCCESS if no scanning is in progress. 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 Deep Sleep during the scan can disrupt the middleware operation.

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 - Deep Sleep power mode can be entered.
• CY_SYSPM_FAIL - Deep Sleep power mode cannot be entered.

Cy_CapSense_RegisterCallback()

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

Registers a 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 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 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_RET_SUCCESS - The action performed successfully.
• CY_RET_BAD_PARAM - The input parameter is invalid.

Cy_CapSense_UnRegisterCallback()

cy_status Cy_CapSense_UnRegisterCallback	(	cy_en_capsense_callback_event_t	callbackType,
		cy_stc_capsense_context_t *	context
	)

This function unregisters a previously registered callback function in the CapSense middleware.

Parameters

callbackType	The event on which the 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_RET_SUCCESS - The action performed successfully.
• CY_RET_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 processing 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[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 |
                       (cy_capsense_context.ptrWdContext[CY_CAPSENSE_TOUCHPAD0_WDGT_ID].gestureDirection << CY_CAPSENSE_GESTURE_DIRECTION_OFFSET);

        /* Configure the widget if previously configured widget was not TOUCHPAD0 */
        Cy_CapSense_SetupWidget(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);

        /* Trigger the next scan */
        Cy_CapSense_Scan(&cy_capsense_context);
    }

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

cy_status Cy_CapSense_SetupWidget	(	uint32_t	widgetId,
		cy_stc_capsense_context_t *	context
	)

Performs the initialization required to scan the specified widget.

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, if the electrodes are connected by the Cy_CapSense_CSDSetupWidgetExt(), Cy_CapSense_CSXSetupWidgetExt(), or Cy_CapSense_CSDConnectSns() functions and are not disconnected.

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.

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_RET_SUCCESS - The operation is successfully completed.
• CY_RET_BAD_PARAM - The widget is invalid or if the specified widget is disabled.
• CY_RET_INVALID_STATE - The previous scanning is not completed and the CSD HW block is busy.
• CY_RET_UNKNOWN - An unknown sensing method is used by the widget or any other spurious error occurred.

Cy_CapSense_Scan()

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

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) trigged at the end of each scan completion. Hence, status of the current scan should be checked using the Cy_CapSense_IsBusy() and wait until all scans in the current widget are finished prior to starting the next scan or initializing another widget.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the scan initiation operation:

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

Cy_CapSense_ScanAllWidgets()

cy_status Cy_CapSense_ScanAllWidgets

(

cy_stc_capsense_context_t *

context

)

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

The tasks of both Cy_CapSense_SetupWidget() and Cy_CapSense_Scan() functions are executed by this function. The status of a sensor scan must be checked using the Cy_CapSense_IsBusy() prior to starting the next scan or setting up another widget.

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

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns the status of the operation:

• CY_RET_SUCCESS - Scanning is successfully started.
• CY_RET_BAD_PARAM - All the widgets are disabled.
• CY_RET_INVALID_STATE - The previous scanning is not completed and the CSD HW block is busy.
• CY_RET_UNKNOWN - There are unknown errors.

Cy_CapSense_IsBusy()

uint32_t Cy_CapSense_IsBusy

(

const cy_stc_capsense_context_t *

context

)

This function returns a status of the CapSense middleware whether a scan is currently in progress or not.

If the middleware is busy, a new scan or setup widgets 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:

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

Cy_CapSense_InterruptHandler()

void Cy_CapSense_InterruptHandler	(	const CSD_Type *	base,
		cy_stc_capsense_context_t *	context
	)

Implements interrupt service routine for CapSense Middleware.

The CSD HW block generates an interrupt at end of every sensor scan. 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 and subsequent sensor scans are initiated in the interrupt service routine as soon as the current scan is completed. The above stated interrupt service routine is implemented as a part of the CapSense middleware.

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

Parameters

base	The pointer to the base register address of the CSD HW block. A macro for the pointer can be found in cycfg_peripherals.h file defined as <Csd_Personality_Name>_HW. If no name is specified then the default name is used csd_<Block_Number>_csd_<Block_Number>_HW.
context	The pointer to the CapSense context structure cy_stc_capsense_context_t.

Note

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 will lengthen the CSD ISR execution in case of a direct call of the Cy_CapSense_InterruptHandler() function from a CSD ISR.

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+:

const cy_stc_sysint_t CapSense_ISR_cfg =
{
    .intrSrc = NvicMux2_IRQn,       /* CM0+ interrupt is NVIC #2 */
    .cm0pSrc = csd_interrupt_IRQn,  /* Source of NVIC #2 is the CSD interrupt */
    .intrPriority = 3u,             /* Interrupt priority is 3 */
};

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 snippet_Cy_CapSense_IntHandler(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 CSD HW block and initialize it to the default state. */
    Cy_CapSense_Init(&cy_capsense_context);

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

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

CapSense_HW is the pointer to the base register address of the CSD HW block. A macro for the pointer can be found in the cycfg_peripherals.h file defined as <Csd_Personality_Name>_HW. If no name specified, the default name is used csd_<Block_Number>_csd_<Block_Number>_HW.

An example of sharing the CSD 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:

static void CapSense_Interrupt(void)
{
    Cy_CapSense_InterruptHandler(CapSense_HW, &cy_capsense_context);
}

Defines the CSDADC interrupt handler:

static void CSDADC_Interrupt(void)
{
    Cy_CSDADC_InterruptHandler(&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_Interrupt);
    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_Interrupt);
            /* Do CapSense 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_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 CapSense Structures.

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_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 CapSense 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 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 detected 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 CapSense 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.
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 CapSense 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 CapSense 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 should be called periodically in the application program to serve the CapSense Tuner tool requests and commands to synchronize the operation, however there is no specific timing requirement for this function. In most cases, the best place to call this function is after processing and before next scanning.

If a user changes some parameters in the Tuner tool, a re-initialization of the middleware is required. In such cases, the tuner issues a re-initialize command and which is executed by this function.

If this function is not 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. As a result, noise and SNR measurements will not be accurate.
• The CapSense Tuner tool may read the sensor data such as raw counts from a scan multiple times. As a result, noise and SNR measurement will not be accurate.
• The CapSense Tuner tool and Host controller should not change the parameters via the tuner interface. Changing the parameters via the Tuner interface in the async mode will result in abnormal behavior.
• Displaying detected gestures may be missed.

Note

Calling this function is not mandatory and required only synchronizing the communication with the CapSense Tuner tool when the Tuner is used.

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. A callback mechanism of command receiving should be used to avoid FW hang.

Parameters

context

The pointer to the CapSense context structure cy_stc_capsense_context_t.

Returns

Returns a status of whether a re-initialization of the middleware 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 - No re-initialization was executed by this function.

Function Usage

An example of synchronization with the Tuner tool using EzI2C:

    /* 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 *)&cy_capsense_tuner, sizeof(cy_capsense_tuner), sizeof(cy_capsense_tuner), &EZI2C_context);
    Cy_SCB_EZI2C_Enable(EZI2C_HW);

    for(;;)
    {
        if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
        {
            Cy_CapSense_ProcessAllWidgets(&cy_capsense_context);
            Cy_CapSense_RunTuner(&cy_capsense_context);
            Cy_CapSense_ScanAllWidgets(&cy_capsense_context);
        }
    }

An example of synchronization with the Tuner tool using UART.
Tuner Send callback implementation: Transmitting data through UART interface:

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 *)&cy_capsense_tuner, sizeof(cy_capsense_tuner));
    Cy_SCB_UART_PutArrayBlocking(UART_HW, uartTxTail, sizeof(uartTxTail));
}

Tuner Receive callback implementation: Receiving data from UART interface:

void TunerReceive(uint8_t ** packet, uint8_t ** tunerPacket, void * context)
{
    uint32_t i;
    static uint32_t dataIndex = 0u;
    static uint8_t commandPacket[16u] = {0u};

    while(0 != Cy_SCB_UART_GetNumInRxFifo(UART_HW))
    {
        commandPacket[dataIndex++] = (uint8_t)Cy_SCB_UART_Get(UART_HW);

        if (CY_CAPSENSE_COMMAND_PACKET_SIZE <= dataIndex)
        {
            if (CY_CAPSENSE_COMMAND_OK == Cy_CapSense_CheckCommandIntegrity(&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 FIFO */
                dataIndex--;
                for(i = 0u; i < (CY_CAPSENSE_COMMAND_PACKET_SIZE - 1u); i++)
                {
                    commandPacket[i] = commandPacket[i + 1u];
                }
            }
        }
    }
}

A part of the main.c FW flow with registering callbacks:

    /*...*/

    /* Register communication callbacks */
    cy_capsense_context.ptrCommonContext->ptrTunerSendCallback = TunerSend;
    cy_capsense_context.ptrCommonContext->ptrTunerReceiveCallback = TunerReceive;

    Cy_SCB_UART_Init(UART_HW, &UART_config, &UART_context);
    Cy_SCB_UART_Enable(UART_HW);

    for(;;)
    {
        if (CY_CAPSENSE_NOT_BUSY == Cy_CapSense_IsBusy(&cy_capsense_context))
        {
            Cy_CapSense_ProcessAllWidgets(&cy_capsense_context);

            /*
            * Cy_CapSense_RunTuner() calls periodically communication callbacks
            * for hence the Tuner tool are able to monitor sensor signals/statuses
            * and change CapSense parameters for easy tuning.
            */
            Cy_CapSense_RunTuner(&cy_capsense_context);

            Cy_CapSense_ScanAllWidgets(&cy_capsense_context);
        }
    }
    /*...*/
    

Refer to the Callbacks section for details.

Cy_CapSense_CheckCommandIntegrity()

uint32_t Cy_CapSense_CheckCommandIntegrity

(

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 MSB = cy_en_capsense_tuner_cmd_t
• Byte 3: Command code LSB = cy_en_capsense_tuner_cmd_t
• Byte 4: Command counter
• Byte 5: Size = either 1, 2 or 4
• Byte 6: Offset MSB
• Byte 7: Offset LSB
• Byte 8: Data MSB
• Byte 9: Data
• Byte 10: Data
• Byte 11: Data LSB
• Byte 12: 8-bit CRC
• 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.