High-level Functions

group group_capsense_high_level

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_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 block is 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.


    /* Capture the CapSense 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.
Return

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

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.

The CapSense_ISR_cfg variable should be declared by the application program according to the examples below:

For PSoC4 CPU or for PSoC6 CM0+ core:


    #if (!defined(CY_IP_M0S8MSCV3))
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #else
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msc_0_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #endif
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 CY_MSC<X>_HW is the pointer to the base register address of the MSC_X HW block. A macro for the pointer is in the cycfg_peripherals.h file defined as <Msc_Personality_Name>_HW. If no name is specified, the default msc_<Block_Number>_msc_<Block_Number>_HW is used.

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 MSC 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 initialization process and it is not needed to call the Cy_CapSense_Enable() function second time. However, to implement time-multiplexed mode (sharing the MSC 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.

Return

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

Parameters

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 MSC 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 MSC HW block(s) to perform capacitive sensing operation.

  4. Calibrate the sensors and find the optimal values for CDACs of each widget/sensor, if the Enable CDAC 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.


    /* Capture the CapSense 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.
Return

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

Function Usage

Parameters

The CapSense_ISR_cfg variable should be declared by the application program according to the examples below:

For CM0+ core:


    #if (!defined(CY_IP_M0S8MSCV3))
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #else
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msc_0_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #endif
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 CY_MSC<X>_HW is the pointer to the base register address of the MSC_X HW block. A macro for the pointer is in the cycfg_peripherals.h file defined as <Msc_Personality_Name>_HW. If no name is specified, the default msc_<Block_Number>_msc_<Block_Number>_HW is used.

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

Return

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

Parameters

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 MSC HW block among multiple middleware. When the MSC HW blocks are shared by multiple middleware, this function can be used to restore the previous state of the MSC 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.

Return

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

Parameters

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

Return

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

Parameters

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

An example of pipeline implementation:


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

    #if (CY_CAPSENSE_PLATFORM_BLOCK_MSCV3)
            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_ScanWidget(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);
    #endif

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

            #if (CY_CAPSENSE_PLATFORM_BLOCK_MSCV3)
                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_ScanWidget(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);
            #endif
            /* Process a previous widget during scanning of the current widget */
            Cy_CapSense_ProcessWidget(previousWidgetId, &cy_capsense_context);
            previousWidgetId = currentWidgetId;
        }
    }
    /*...*/
Return

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

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

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

void Cy_CapSense_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.

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

        #if (CY_CAPSENSE_PLATFORM_BLOCK_MSCV3)
            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_ScanWidget(CY_CAPSENSE_TOUCHPAD0_WDGT_ID, &cy_capsense_context);
        #endif
    }
Function Usage

Parameters

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.

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 MSC HW block is powered off, an extra delay is required to establish the correct operation of the MSC HW block.

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

Parameters

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 the Cy_CapSense_Wakeup() function calling is omitted 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.

Return

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.

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.

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.

Return

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.

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.

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.

Return

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.

Parameters

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.

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

        #if (CY_CAPSENSE_PLATFORM_BLOCK_MSCV3)
            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_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;
        }
    }
Return

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

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

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

cy_en_capsense_bist_status_t Cy_CapSense_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_TST_RUN_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.

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

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

note

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

Return

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_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The function was not performed.

  • 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 CSD 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.

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 - Verifies the RAM widget structure CRC for all the widgets.

    • CY_CAPSENSE_BIST_SNS_INTEGRITY - Checks all the sensors for a short to GND / VDD / other sensors.

    • CY_CAPSENSE_BIST_SNS_CAP - Measures all the sensors capacitance.

    • CY_CAPSENSE_BIST_SHIELD_CAP - Measures the shield capacitance.

    • CY_CAPSENSE_BIST_EXTERNAL_CAP - Measures the capacitance of the available external capacitors.

    • CY_CAPSENSE_BIST_VDDA - Measures the VDDA voltage.

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

cy_en_capsense_bist_status_t Cy_CapSense_RunSelfTest_V2(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_TST_RUN_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.

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

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

note

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

Return

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_FEATURE_DISABLED_E - The BIST feature is disabled in the configuration. The function was not performed.

  • 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 CSD 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.

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 - Verifies the RAM widget structure CRC for all the widgets.

    • CY_CAPSENSE_BIST_SNS_INTEGRITY - Checks all the sensors for a short to GND / VDD / other sensors.

    • CY_CAPSENSE_BIST_SNS_CAP - Measures all the sensors capacitance.

    • CY_CAPSENSE_BIST_SHIELD_CAP - Measures the shield capacitance.

    • CY_CAPSENSE_BIST_EXTERNAL_CAP - Measures the capacitance of the available external capacitors.

    • CY_CAPSENSE_BIST_VDDA - Measures the VDDA voltage.

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

cy_en_capsense_bist_status_t Cy_CapSense_RunSelfTest_V3(uint32_t testEnMask, cy_stc_capsense_context_t *context)

TBD.

Return

TBD

Parameters
  • testEnMask: TBD

  • context: TBD

cy_capsense_status_t Cy_CapSense_ScanWidget(uint32_t widgetId, cy_stc_capsense_context_t *context)

Initiates the scanning of all sensors in the widget.

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

note

For the fifth-generation CapSense this function is available in single-channel solution.

Return

Returns the status of the operation cy_capsense_status_t.

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

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

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

Initiates the scanning of the selected sensor in the widget.

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

note

For the fifth-generation CapSense this function is available in single-channel solution.

Return

Returns the status of the operation cy_capsense_status_t.

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

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

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

cy_capsense_status_t Cy_CapSense_ScanAllWidgets(cy_stc_capsense_context_t *context)

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

Scanning is initiated only if no scan is in progress.

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.

Return

Returns the status of the operation cy_capsense_status_t.

Parameters

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.

Return

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_BUSY_CALIBRATION - The auto-calibration is in progress. The next scan frame cannot be started.

  • CY_CAPSENSE_BUSY_VERIFY_CALIBRATION - The auto-calibration verification is in progress. The next scan frame cannot be started.

Parameters

void Cy_CapSense_InterruptHandler(void *base, cy_stc_capsense_context_t *context)

Implements interrupt service routine for CapSense Middleware.

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

An example of the ISR initialization:

Function Usage

Parameters
  • base: The pointer to the base register address of the CSD 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.

The CapSense_ISR_cfg variable should be declared by the application program according to the examples below:

For Core CM0+:


    #if (!defined(CY_IP_M0S8MSCV3))
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = csd_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #else
        const cy_stc_sysint_t CapSense_ISR_cfg =
        {
            .intrSrc = msc_0_interrupt_IRQn,  /* CM0+ interrupt is NVIC #2 */
            .intrPriority = 3u,             /* Interrupt priority is 3 */
        };
    #endif
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 CapSense 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(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_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_status_t 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.

note

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

Return

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.

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

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

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

note

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

Return

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.

Parameters

cy_capsense_status_t Cy_CapSense_ScanAllSlots(cy_stc_capsense_context_t *context)

Initiates the non-blocking scan of all slots.

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

This function initiates a scan only 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) trigged at the end of each scan completion 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 trigged at the end of each scan completion 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 status of the current scan should be checked using the Cy_CapSense_IsBusy() function, where there are separate busy bits for each channel and the application program waits until all scans are finished prior to starting a next scan by using this function.

note

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

Return

Returns the status of the operation:

  • CY_CAPSENSE_STATUS_SUCCESS - The operation is performed successfully.

  • CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.

  • CY_CAPSENSE_STATUS_HW_BUSY - The HW is busy with the previous scan.

Parameters

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 specified slots.

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

This function initiates a scan only for the first specified 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) trigged at the end of each scan completion 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 trigged at the end of each scan completion 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.

note

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

Return

Returns the status of the operation:

  • CY_CAPSENSE_STATUS_SUCCESS - The operation is performed successfully.

  • CY_CAPSENSE_STATUS_BAD_PARAM - The input parameter is invalid.

  • CY_CAPSENSE_STATUS_HW_BUSY - The HW is busy with the previous scan.

Parameters
  • startSlotId: The slot ID scan will be started from.

  • numberSlots: The number of slots will be scanned.

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

cy_capsense_status_t Cy_CapSense_ScanAbort(cy_stc_capsense_context_t *context)

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

note

If this function is called from ISR during initialization or auto-calibration the operation of these functions will be corrupted.

Return

Returns the status of the operation cy_capsense_status_t.

Parameters

cy_capsense_mw_state_t Cy_CapSense_MwState(const cy_stc_capsense_context_t *context)

This function returns a detailed state of the CapSense middleware and MSC hardware in Single- or Multi-channel mode.

This feature is useful in multi-thread applications or in ISR.

Return

Zero indicates that the CapSense middleware is currently not busy, otherwise returns the state of the middleware as a sum of the state masks cy_capsense_mw_state_t.

Parameters

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.

Return

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.

Parameters

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.

Return

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.

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.

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.

Return

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.

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.

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.

Return

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.

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

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

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

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

Return

Returns the pointer to widget cy_stc_capsense_touch_t structure that contains number of positions and data about each position.

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.

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 to periodically call Cy_CapSense_RunTuner() 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 behavior.

  • Displaying detected gestures may be missed.

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.

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

            #if (CY_CAPSENSE_PLATFORM_BLOCK_MSCV3)
                Cy_CapSense_ScanAllSlots(&cy_capsense_context);
            #else
                Cy_CapSense_ScanAllWidgets(&cy_capsense_context);
            #endif
        }
    }
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;
    (void) context;
    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_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 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.ptrInternalContext->ptrTunerSendCallback = TunerSend;
    cy_capsense_context.ptrInternalContext->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);

            #if (CY_CAPSENSE_PLATFORM_BLOCK_MSCV3)
                Cy_CapSense_ScanAllSlots(&cy_capsense_context);
            #else
                Cy_CapSense_ScanAllWidgets(&cy_capsense_context);
            #endif
        }
    }
    /*...*/
Refer to the Callbacks section for details.
Return

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

Parameters

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

Return

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.

Parameters
  • commandPacket: The pointer to the data packet that should be verified.