 |
CAPSENSE™ Middleware Library 5.0
|
|
CAPSENSE™ Middleware Library 5.0
|
The Low-level functions represent the lower layer of abstraction in support of High-level Functions.
These functions also enable implementation of special case designs requiring performance optimization and non-typical functionalities.
All functions are general to all sensing methods. Some of the functions detect the sensing method used by the widget and execute tasks as appropriate.
Functions | |
| cy_capsense_status_t | Cy_CapSense_ProcessWidgetExt (uint32_t widgetId, uint32_t mode, cy_stc_capsense_context_t *context) |
| Performs customized data processing on the selected widget. More... | |
| cy_capsense_status_t | Cy_CapSense_ProcessSensorExt (uint32_t widgetId, uint32_t sensorId, uint32_t mode, const cy_stc_capsense_context_t *context) |
| Performs customized data processing on the selected sensor. More... | |
| void | Cy_CapSense_InitializeAllBaselines (cy_stc_capsense_context_t *context) |
| Initializes the baselines of all the sensors of all the widgets. More... | |
| void | Cy_CapSense_InitializeWidgetBaseline (uint32_t widgetId, cy_stc_capsense_context_t *context) |
| Initializes the baselines of all the sensors in a specific widget. More... | |
| void | Cy_CapSense_InitializeSensorBaseline (uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context) |
| Initializes the baseline of a sensor in a widget specified by the input parameters. More... | |
| void | Cy_CapSense_InitializeAllFilters (const cy_stc_capsense_context_t *context) |
| Initializes (or re-initializes) all the firmware filter history, except the baseline. More... | |
| void | Cy_CapSense_InitializeWidgetFilter (uint32_t widgetId, const cy_stc_capsense_context_t *context) |
| Initializes (or re-initializes) the raw count filter history of all the sensors in a widget specified by the input parameter. More... | |
| cy_capsense_status_t | Cy_CapSense_UpdateAllBaselines (const cy_stc_capsense_context_t *context) |
| Updates the baseline for all the sensors in all the widgets. More... | |
| cy_capsense_status_t | Cy_CapSense_UpdateWidgetBaseline (uint32_t widgetId, const cy_stc_capsense_context_t *context) |
| Updates the baselines for all the sensors in a widget specified by the input parameter. More... | |
| cy_capsense_status_t | Cy_CapSense_UpdateSensorBaseline (uint32_t widgetId, uint32_t sensorId, const cy_stc_capsense_context_t *context) |
| Updates the baseline for a sensor in a widget specified by the input parameters. More... | |
| void | Cy_CapSense_InitializeWidgetGestures (uint32_t widgetId, const cy_stc_capsense_context_t *context) |
| Performs initialization of all gestures for the specified widget. More... | |
| void | Cy_CapSense_InitializeAllStatuses (const cy_stc_capsense_context_t *context) |
| Performs initialization of all statuses and related modules including debounce counters and touch positions of all the widgets. More... | |
| void | Cy_CapSense_InitializeWidgetStatus (uint32_t widgetId, const cy_stc_capsense_context_t *context) |
| Performs initialization of all statuses, debounce counters, and touch positions of the specified widget. More... | |
| cy_capsense_status_t | Cy_CapSense_ProcessWidgetMpDeconvolution (uint32_t widgetId, cy_stc_capsense_context_t *context) |
| Performs raw count deconvolution for the specified widget: More... | |
| void | Cy_CapSense_PreProcessSensor (uint32_t widgetId, uint32_t sensorId, const cy_stc_capsense_context_t *context) |
| Executes the pre-processing of scan raw data for specified sensor. More... | |
| void | Cy_CapSense_PreProcessWidget (uint32_t widgetId, const cy_stc_capsense_context_t *context) |
| Executes the pre-processing of scan raw data for specified widgets. More... | |
| cy_capsense_status_t | Cy_CapSense_RunMfsMedian (uint32_t widgetId, const cy_stc_capsense_context_t *context) |
| Applies the median filter to the specified multi-frequency widget and updates the specified widget diff counts. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_CheckCRCWidget (uint32_t widgetId, cy_stc_capsense_context_t *context) |
| Checks the stored CRC of the cy_stc_capsense_widget_context_t data structure of the specified widget. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_CheckIntegritySensorRawcount (uint32_t widgetId, uint32_t sensorId, uint16_t rawcountHighLimit, uint16_t rawcountLowLimit, cy_stc_capsense_context_t *context) |
| Checks the raw count of the specified widget/sensor is within the specified range. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_CheckIntegritySensorBaseline (uint32_t widgetId, uint32_t sensorId, uint16_t baselineHighLimit, uint16_t baselineLowLimit, cy_stc_capsense_context_t *context) |
| Checks if the baseline of the specified sensor is not corrupted by comparing it with its inverse copy and checks if the baseline is within the specified range. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_CheckIntegritySensorPins (uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context) |
| Checks the specified widget/sensor for shorts to GND, VDD or other sensors. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_MeasureCapacitanceCap (cy_en_capsense_bist_external_cap_id_t integrationCapId, uint32_t *ptrValue, uint32_t maxCapacitance, cy_stc_capsense_context_t *context) |
| Measures the capacitance in picofarads of the specified CAPSENSE™ integration (external) capacitor. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_MeasureVdda (uint32_t *ptrValue, cy_stc_capsense_context_t *context) |
| Measures a VDDA voltage, returns the measured voltage in millivolts through the ptrValue argument and stores it to the .vddaVoltage field of the cy_stc_capsense_bist_context_t structure. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_MeasureCapacitanceSensorElectrode (uint32_t widgetId, uint32_t eltdId, cy_stc_capsense_context_t *context) |
| Measures the specified CSD sensor / CSX electrode capacitance in femtofarads. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_MeasureCapacitanceSlotSensors (uint32_t slotId, uint32_t skipChMask, cy_stc_capsense_context_t *context) |
| Measures the specified slot sensor capacitance in femtofarads. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_MeasureCapacitanceShieldElectrode (uint32_t skipChMask, cy_stc_capsense_context_t *context) |
| Measures shield electrode capacitances in femtofarads. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_MeasureCapacitanceLpSlotSensors (uint32_t slotId, cy_stc_capsense_context_t *context) |
| Measures the specified low power slot sensor capacitance in femtofarads. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_MeasureCapacitanceSensor (uint32_t widgetId, uint32_t sensorId, uint32_t *ptrValue, cy_stc_capsense_context_t *context) |
| Measures the specified CSD sensor / CSX electrode capacitance in femtofarads. More... | |
| cy_en_capsense_bist_status_t | Cy_CapSense_MeasureCapacitanceShield (uint32_t *ptrValue, cy_stc_capsense_context_t *context) |
| Measures shield electrode capacitance in femtofarads. More... | |
| cy_capsense_status_t | Cy_CapSense_CalibrateAllWidgets (cy_stc_capsense_context_t *context) |
| Executes CapDAC/IDAC auto-calibration for all the sensors in all widgets of some sensing groups (CSD, CSX, or ISX) if calibration is enabled for such group of widgets. More... | |
| cy_capsense_status_t | Cy_CapSense_CalibrateAllSlots (cy_stc_capsense_context_t *context) |
| Executes CapDAC/IDAC auto-calibration for all the sensors in all widgets of some sensing groups (CSD, CSX, or ISX) if calibration is enabled for such group of widgets. More... | |
| cy_capsense_status_t | Cy_CapSense_SetCalibrationTarget (uint32_t calibrTarget, uint32_t snsMethod, cy_stc_capsense_context_t *context) |
| Sets the CapDAC auto-calibration raw count target for CSD, CSX or ISX widgets. More... | |
| cy_capsense_status_t | Cy_CapSense_CalibrateWidget (uint32_t widgetId, cy_stc_capsense_context_t *context) |
| Executes the CapDAC/IDAC calibration for all the sensors in the specified widget to the default target value. More... | |
| cy_capsense_status_t | Cy_CapSense_ScanSensor (uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context) |
| Initiates the scanning of the selected sensor in the widget. More... | |
| cy_capsense_status_t | Cy_CapSense_SetPinState (uint32_t widgetId, uint32_t sensorElement, uint32_t state, const cy_stc_capsense_context_t *context) |
| Sets the state (drive mode and HSIOM state) of the GPIO used by a sensor. More... | |
| cy_capsense_status_t | Cy_CapSense_SlotPinState (uint32_t slotId, const cy_stc_capsense_electrode_config_t *ptrEltdCfg, uint32_t pinState, cy_stc_capsense_context_t *context) |
| Configures the specified electrode to the desired state in the specified slot (Active slot for fifth-generation low power CAPSENSE™) by updating the CAPSENSE™ configuration. More... | |
| cy_capsense_status_t | Cy_CapSense_SetInactiveElectrodeState (uint32_t inactiveState, uint32_t sensingGroup, cy_stc_capsense_context_t *context) |
| Sets a desired state for all inactive CAPSENSE™-related electrodes for CSD, CSX, ISX scans, or BIST measurement scans. More... | |
| cy_capsense_status_t | Cy_CapSense_ScanAbort (cy_stc_capsense_context_t *context) |
| This function sets the sequencer to the idle state by resetting the hardware, it can be used to abort current scan. More... | |
| cy_capsense_status_t | Cy_CapSense_LpSlotPinState (uint32_t lpSlotId, const cy_stc_capsense_electrode_config_t *ptrEltdCfg, uint32_t pinState, cy_stc_capsense_context_t *context) |
| Configures the specified electrode to the desired state in the specified Low Power slot by updating the CAPSENSE™ configuration. More... | |
| cy_capsense_status_t | Cy_CapSense_CalibrateAllLpWidgets (cy_stc_capsense_context_t *context) |
| Executes CapDAC auto-calibration for all relevant low power widgets if enabled. More... | |
| cy_capsense_status_t | Cy_CapSense_CalibrateAllLpSlots (cy_stc_capsense_context_t *context) |
| Calibrates CapDACs for all Low power widgets. More... | |
| cy_capsense_status_t | Cy_CapSense_ScanInitializeHwIirAllSlots (cy_stc_capsense_context_t *context) |
| Initializes (or re-initializes) the hardware IIR filter for all slots. More... | |
| cy_capsense_status_t | Cy_CapSense_ScanInitializeHwIirSlots (uint32_t startSlotId, uint32_t numberSlots, cy_stc_capsense_context_t *context) |
| Initializes (or re-initializes) the hardware IIR filter for specified slots. More... | |
| cy_capsense_status_t | Cy_CapSense_SetupWidgetExt (uint32_t widgetId, uint32_t sensorId, cy_stc_capsense_context_t *context) |
| Performs extended initialization for the specified widget and also performs initialization required for a specific sensor in the widget. More... | |
| cy_capsense_status_t | Cy_CapSense_ScanExt (cy_stc_capsense_context_t *context) |
| Starts a conversion on the pre-configured sensor. More... | |
| cy_capsense_status_t | Cy_CapSense_GetParam (uint32_t paramId, uint32_t *value, const void *ptrTuner, const cy_stc_capsense_context_t *context) |
| Gets a value of the specified parameter from the cy_capsense_tuner structure. More... | |
| cy_capsense_status_t | Cy_CapSense_SetParam (uint32_t paramId, uint32_t value, void *ptrTuner, cy_stc_capsense_context_t *context) |
| Sets a new value for the specified parameter in cy_capsense_tuner structure. More... | |
| uint16_t | Cy_CapSense_GetCRC (const uint8_t *ptrData, uint32_t len) |
| Calculates CRC for the specified buffer and length. More... | |
| cy_capsense_status_t | Cy_CapSense_SetWidgetStatus (uint32_t widgetId, uint32_t mode, uint32_t value, cy_stc_capsense_context_t *context) |
| Performs configuring of the selected widget. More... | |
| uint32_t | Cy_CapSense_IsWidgetEnabled (uint32_t widgetId, const cy_stc_capsense_context_t *context) |
| Returns widget enable/working status. More... | |
| uint32_t | Cy_CapSense_IsSlotEnabled (uint32_t slotId, const cy_stc_capsense_context_t *context) |
| Returns slot enable/working status. More... | |
| cy_capsense_status_t Cy_CapSense_ProcessWidgetExt | ( | uint32_t | widgetId, |
| uint32_t | mode, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Performs customized data processing on the selected widget.
This function performs customized data processing specified by the mode parameter on a widget. This function can be used with any of the available scan functions. This function should be called only after all the sensors in the specified widget are scanned. Calling this function multiple times with the same mode without new sensor scan causes unexpected behavior. This function ignores the widget statuses like disabled and/or non-working and performs processing in any case.
The CY_CAPSENSE_PROCESS_CALC_NOISE and CY_CAPSENSE_PROCESS_THRESHOLDS masks for mode parameter are supported only when smart sensing algorithm is enabled for CSD widgets.
The execution order of processing tasks starts from LSB to MSB of the mode parameter. To implement a different order of execution, call this function multiple times with the required mode parameter.
For more details, refer to function usage example below.
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID. |
| mode | Specifies the type of widget processing to be executed for the specified widget:
|
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
An example of customized data processing, changed processing order:
| cy_capsense_status_t Cy_CapSense_ProcessSensorExt | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| uint32_t | mode, | ||
| const cy_stc_capsense_context_t * | context | ||
| ) |
Performs customized data processing on the selected sensor.
This function performs customized data processing specified by the mode parameter on a sensor. This function performs the exact same task of the Cy_CapSense_ProcessWidgetExt() function but only on the specified sensor instead of all sensors in the widget.
The pipeline scan method (i.e. during scanning of a sensor, processing of a previously scanned sensor is performed) can be implemented using this function and it may reduce the total scan/process time, increase the refresh rate, and decrease the power consumption. For more details, refer to function usage example below.
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID. |
| sensorId | Specifies the ID number of the sensor within the widget. A macro for the sensor ID within a specified widget can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_SNS<SENSOR_NUMBER>_ID. |
| mode | Specifies the type of the sensor processing that must be executed for the specified sensor:
|
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
An example demonstrates pipeline implementation of sensor scanning and processing:
| void Cy_CapSense_InitializeAllBaselines | ( | cy_stc_capsense_context_t * | context | ) |
Initializes the baselines of all the sensors of all the widgets.
This function initializes baselines for all sensors and widgets in the project. It can also be used to re-initialize baselines at any time, however, note that all sensor data history information and sensor status shall be reset along with re-initialization of baseline.
Following functions to initialize sensor and widgets and filter history should be called after initializing baseline for proper operation of the CAPSENSE™ middleware:
These functions are called by the CapSense_Enable() function, hence it is not required to use this function if above function is used.
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| void Cy_CapSense_InitializeWidgetBaseline | ( | uint32_t | widgetId, |
| cy_stc_capsense_context_t * | context | ||
| ) |
Initializes the baselines of all the sensors in a specific widget.
This function initializes baselines for all sensors in a specific widget in the project. It can also be used to re-initialize baselines at any time, however, note that all sensor data history information and sensor status should be reset along with re-initialization of baseline.
The following functions to initialize sensor and widgets and filter history should be called after initializing baselines for proper operation of middleware.
These functions are called by CapSense_Enable() function, hence it is not required to use this function is above function is used.
| 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_InitializeSensorBaseline | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Initializes the baseline of a sensor in a widget specified by the input parameters.
| 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. |
| void Cy_CapSense_InitializeAllFilters | ( | const cy_stc_capsense_context_t * | context | ) |
Initializes (or re-initializes) all the firmware filter history, except the baseline.
Calling this function is accompanied by
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| void Cy_CapSense_InitializeWidgetFilter | ( | uint32_t | widgetId, |
| const cy_stc_capsense_context_t * | context | ||
| ) |
Initializes (or re-initializes) the raw count filter history of all the sensors in a widget specified by the input parameter.
Calling this function is accompanied by
| 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_UpdateAllBaselines | ( | const cy_stc_capsense_context_t * | context | ) |
Updates the baseline for all the sensors in all the widgets.
Baselines must be updated after sensor scan to ignore low frequency changes in the sensor data caused by environment changes such as temperature from sensor status decision.
This function ignores the widget enable bit in the widget status register. Calling this function multiple times without a new sensor scan leads to unexpected behavior and should be avoided.
This function is called by Cy_CapSense_ProcessAllWidgets() and Cy_CapSense_ProcessWidget(), hence the application program need not use this function if any of the above functions is already used. This function can be used for custom application implementation.
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_UpdateWidgetBaseline | ( | uint32_t | widgetId, |
| const cy_stc_capsense_context_t * | context | ||
| ) |
Updates the baselines for all the sensors in a widget specified by the input parameter.
This function performs exactly the same tasks as Cy_CapSense_UpdateAllBaselines() but only for a specified widget.
Calling this function multiple times without a new sensor scan leads to unexpected behavior and should be avoided. The application program need not use this function if the Cy_CapSense_UpdateAllBaselines(), Cy_CapSense_ProcessAllWidgets() or Cy_CapSense_ProcessWidget() functions are already used.
| 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_UpdateSensorBaseline | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| const cy_stc_capsense_context_t * | context | ||
| ) |
Updates the baseline for a sensor in a widget specified by the input parameters.
This function performs exactly the same tasks as Cy_CapSense_UpdateAllBaselines() and Cy_CapSense_UpdateWidgetBaseline() but only for a specified sensor.
Calling this function multiple times without a new sensor scan leads to unexpected behavior and should be avoided. The application need not use this function if the Cy_CapSense_UpdateWidgetBaseline (), Cy_CapSense_UpdateAllBaselines (), Cy_CapSense_ProcessAllWidgets(), or Cy_CapSense_ProcessWidget() functions are already used.
| 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. |
| void Cy_CapSense_InitializeWidgetGestures | ( | uint32_t | widgetId, |
| const cy_stc_capsense_context_t * | context | ||
| ) |
Performs initialization of all gestures for the specified widget.
| 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_InitializeAllStatuses | ( | const cy_stc_capsense_context_t * | context | ) |
Performs initialization of all statuses and related modules including debounce counters and touch positions of all the widgets.
The initialization includes the following tasks:
Calling this function is accompanied by
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| void Cy_CapSense_InitializeWidgetStatus | ( | uint32_t | widgetId, |
| const cy_stc_capsense_context_t * | context | ||
| ) |
Performs initialization of all statuses, debounce counters, and touch positions of the specified widget.
The initialization includes:
The Button and Matrix Button widgets have individual debounce counters per sensor for the CSD widgets and per node for the CSX and ISX widgets.
The Slider and Touchpad widgets have a single debounce counter per widget.
The Proximity widget has two debounce counters per sensor. One is for the proximity event and the second is for the touch event.
All debounce counters during initialization are set to the value of the onDebounce widget parameter.
Calling this function is accompanied by
| 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_ProcessWidgetMpDeconvolution | ( | uint32_t | widgetId, |
| cy_stc_capsense_context_t * | context | ||
| ) |
Performs raw count deconvolution for the specified widget:
This function decodes raw counts received after scanning into normal view by performing deconvolution algorithm. If the function is called for a widget with disabled multi-phase, the function returns CY_CAPSENSE_STATUS_BAD_DATA.
No need to call this function from application layer since the Cy_CapSense_ProcessAllWidgets() and Cy_CapSense_ProcessWidget() functions calls deconvolution automatically.
DAC auto-calibration when enabled performs sensor auto-calibration without performing deconvolution. For the CSX widgets, the deconvolution algorithm for even number of TX electrodes decreases raw count level twice (keeping the signal on the same level).
If specific processing is implemented using the Cy_CapSense_ProcessWidgetExt() and Cy_CapSense_ProcessSensorExt() function then a call of this function is required prior doing the specific processing.
| widgetId | Specifies the ID number of the widget. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| void Cy_CapSense_PreProcessSensor | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| const cy_stc_capsense_context_t * | context | ||
| ) |
Executes the pre-processing of scan raw data for specified sensor.
This function is called prior any other processing function for the fifth CAPSENSE™ and fifth low power HW generation. The pre-processing routine implements the following operations:
No need to call this function from application layer since the Cy_CapSense_ProcessAllWidgets() and Cy_CapSense_ProcessWidget() functions calls it automatically.
If specific processing is implemented using the Cy_CapSense_ProcessWidgetExt() and Cy_CapSense_ProcessSensorExt() function then a call of this function is required prior doing the specific processing. If Multi-phase is enabled then deconvolution should be executed after pre-processing of all sensors of the specified widget using the Cy_CapSense_ProcessWidgetMpDeconvolution() function.
| widgetId | The widget ID, for which the pre-processing should be executed. |
| sensorId | The sensor ID, for which the pre-processing should be executed. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| void Cy_CapSense_PreProcessWidget | ( | uint32_t | widgetId, |
| const cy_stc_capsense_context_t * | context | ||
| ) |
Executes the pre-processing of scan raw data for specified widgets.
This function is called prior any other processing function for the fifth CAPSENSE™ and fifth low power CAPSENSE™ HW generation. The pre-processing routine implements the following operations:
No need to call this function from application layer since the Cy_CapSense_ProcessAllWidgets() and Cy_CapSense_ProcessWidget() functions calls it automatically.
If specific processing is implemented using the Cy_CapSense_ProcessWidgetExt() and Cy_CapSense_ProcessSensorExt() function then a call of this function is required prior doing the specific processing. If Multi-phase is enabled then deconvolution should be executed after call of this function using the Cy_CapSense_ProcessWidgetMpDeconvolution() function.
| widgetId | The widget ID, for which the pre-processing should be executed. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_RunMfsMedian | ( | uint32_t | widgetId, |
| const cy_stc_capsense_context_t * | context | ||
| ) |
Applies the median filter to the specified multi-frequency widget and updates the specified widget diff counts.
This function is a low-level function and is called automatically by high-level processing functions like Cy_CapSense_ProcessWidget() and Cy_CapSense_ProcessAllWidgets().
It is not recommended to use this function directly on application level.
The function applies the median filter to diff count of each sensor of the specified widget (with enabled multi-frequency feature) and update the diff count of the specified main widget.
This function is needed to implement customer-specific use cases.
| 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_CheckCRCWidget | ( | uint32_t | widgetId, |
| cy_stc_capsense_context_t * | context | ||
| ) |
Checks the stored CRC of the cy_stc_capsense_widget_context_t data structure of the specified widget.
This function validates the data integrity of the cy_stc_capsense_widget_context_t data structure of the specified widget by calculating the CRC and comparing it with the stored CRC value of the specified widget.
Initially, after the device power up, the Cy_CapSense_Enable() function calculates CRC for each widget and stores them in the .ptrWdgtCrc[] array of the cy_stc_capsense_bist_context_t structure. The test execution compares this stored CRC value with the newly calculated and if the stored and calculated CRC values differ:
The function never clears the CY_CAPSENSE_BIST_CRC_WDGT_MASK bit. If the CY_CAPSENSE_BIST_CRC_WDGT_MASK bit is set, the wdgtCrcCalc and .crcWdgtId fields are not updated.
It is recommended to use the Cy_CapSense_SetParam() function to change the value of the cy_stc_capsense_widget_context_t data structure elements as the CRC is updated by Cy_CapSense_SetParam() function.
You can initiate this test by the Cy_CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_CRC_WDGT_MASK mask as an input.
The function clears the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure if the calculated CRC value differs to the stored CRC value. Those non-working widgets are skipped by the high-level scanning and processing functions. Restoring a widget to its working state should be done by the application level.
For details of the used CRC algorithm, refer to the Cy_CapSense_GetCRC() function.
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorRawcount | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| uint16_t | rawcountHighLimit, | ||
| uint16_t | rawcountLowLimit, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Checks the raw count of the specified widget/sensor is within the specified range.
The raw count is within a specific range (based on the calibration target) for good units. The function checks whether or not the raw count is within the user-defined limits in the ranges function arguments. If the raw count is out of limits, this function sets the CY_CAPSENSE_BIST_RAW_INTEGRITY_MASK bit in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.
This function does not update the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure and is not available in the Cy_CapSense_RunSelfTest() function.
Use this function to verify the uniformity of sensors, for example, at mass-production or during an operation phase together with the Cy_CapSense_CheckIntegritySensorBaseline() function.
The function should be called after sensors scanning and processing. Do not call the function before processing since processing changes sensor raw counts.
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID. |
| sensorId | Specifies the ID number of the sensor within the widget. A macro for the sensor ID within the specified widget can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID. |
| rawcountHighLimit | Specifies the upper limit for the widget/sensor raw count. |
| rawcountLowLimit | Specifies the lower limit for the widget/sensor raw count. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorBaseline | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| uint16_t | baselineHighLimit, | ||
| uint16_t | baselineLowLimit, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Checks if the baseline of the specified sensor is not corrupted by comparing it with its inverse copy and checks if the baseline is within the specified range.
The function checks whether or not the baseline binary inverted to its inverse copy is saved to the self-test baseline-inverse structure and is within the user-defined limits. If the baseline does not match its inverse copy or if the baseline is out of the user-defined limits, the function sets the CY_CAPSENSE_BIST_BSLN_INTEGRITY_MASK bit in the .testResultMask field of the cy_stc_capsense_bist_context_t structure.
The test is integrated into the CAPSENSE™ Middleware. All CAPSENSE™ processing functions like Cy_CapSense_ProcessAllWidgets() or Cy_CapSense_UpdateSensorBaseline() automatically verify the baseline value before using it and update its inverse copy after processing. If a baseline update fails, a CY_CAPSENSE_STATUS_BAD_DATA result is returned. The baseline initialization functions do not verify the baseline and update the baseline inverse copy.
This function does not update the CY_CAPSENSE_WD_WORKING_MASK bit of the .status field in cy_stc_capsense_widget_context_t structure and is not available in the Cy_CapSense_RunSelfTest() function.
Use this function to verify the uniformity of sensors, for example, at mass-production or during an operation phase together with the Cy_CapSense_CheckIntegritySensorRawcount() function.
The function should be called after sensors scanning and processing. Do not call the function before processing since processing changes sensor baselines.
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID. |
| sensorId | Specifies the ID number of the sensor within the widget. A macro for the sensor ID within the specified widget can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID. |
| baselineHighLimit | Specifies the upper limit for a baseline. |
| baselineLowLimit | Specifies the lower limit for a baseline. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_CheckIntegritySensorPins | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Checks the specified widget/sensor for shorts to GND, VDD or other sensors.
This function performs several sub-tests to verify the specified sensor is not electrically shorted and is in a good condition to reliably detect user interactions.
This function performs tests to check if the specified sensor is shorted to:
The absolute resistance of an electrical short must be less than 1500 Ohm including all series resistors on a sensor for a short to be detected to GND, VDD or GPIOs. For example, if a series resistor on a sensor is 560 Ohm (as recommended) and the sensor is shorted with another sensor, the function can detect a short with a short resistance up to 380 Ohm as there are two 560 ohm resistors between the shorted sensor GPIOs.
The function executes the following flow to detect a short:
Due to the sensor parasitic capacitance and internal pull-up/down resistance, logic high-to-low (and vice versa) transitions require a settling time before checking the sensor status. A 2us delay is used as a settling time and can be changed using the .snsIntgShortSettlingTime field of the cy_stc_capsense_bist_context_t structure.
If a short is detected this function updates the following statuses:
To check all the project sensors at once, use the Cy_CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_SNS_INTEGRITY_MASK mask.
To detect an electrical short or fault condition with resistance higher than 1500 ohm, the Cy_CapSense_MeasureCapacitanceSensor() (4th Generation) or Cy_CapSense_MeasureCapacitanceSensorElectrode() (5th Generation) function can be used as the fault condition affects the measured sensor capacitance.
This test can be executed only if the CAPSENSE™ Middleware is in the IDLE state. This function must not be called while CAPSENSE™ Middleware is busy.
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID. |
| sensorId | Specifies the ID of the sensor (electrode for CSX widgets) within the widget to be tested. |
For the CSD widgets, a macro for the sensor ID within the specified widget can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.
For the CSX widgets, sensorId is an electrode ID and is defined as Rx ID or Tx ID. The first Rx in a widget corresponds to electrodeId = 0, the second Rx in a widget corresponds to electrodeId = 1, and so on. The last Tx in a widget corresponds to electrodeId = (RxNum + TxNum - 1). Macros for Rx and Tx IDs can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as:
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceCap | ( | cy_en_capsense_bist_external_cap_id_t | integrationCapId, |
| uint32_t * | ptrValue, | ||
| uint32_t | maxCapacitance, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Measures the capacitance in picofarads of the specified CAPSENSE™ integration (external) capacitor.
The function measures the capacitance of the specified external capacitor such as Cmod and returns the result through ptrValue, alternatively the measurement result is stored in the corresponding field of the cy_stc_capsense_bist_context_t structure (either .cModCap, .cIntACap, .cIntBCap, or .cShieldCap for the fourth-generation, and .cMod01Cap or .cMod02Cap the fifth-generation low power CAPSENSE™ HW blocks).
The maximum measurement capacitance is 25nF. The measurement accuracy is up to 15% for the fourth-generation and up to 30% for the fifth-generation low power CAPSENSE™ HW blocks. The measurement resolution is 10 bit which corresponds to the maximum capacitance specified by the maxCapacitance parameter. The bigger specified maximum capacitance is, the bigger capacitance value is for one measured count. It is recommended to specify the maximum capacitance twice bigger as the nominal capacitor capacitance. For example, if the nominal Cmod value is 2.2nF, the maxCapacitance parameter is set to 4nF-5nF.
The function configures all CAPSENSE™ pins to Strong-drive-low mode that allows detecting a short of the measured capacitor to other pins.
To measure all the available capacitors, the Cy_CapSense_RunSelfTest() function can be used with the CY_CAPSENSE_BIST_EXTERNAL_CAP_MASK mask. The measured results are stored in the corresponding field of the cy_stc_capsense_bist_context_t structure.
Measurement can be done only if the CAPSENSE™ Middleware is in the IDLE state. This function must not be called while the CAPSENSE™ Middleware is busy. The function is blocking, i.e. waits for the measurement to be completed prior to returning to the caller.
| integrationCapId | Indexes of external capacitors to measure their capacitance. There are the enumeration list /ref cy_en_capsense_bist_external_cap_id_t for each of them. Their values could be for the fourth-generation CAPSENSE™ HW blocks:
|
| ptrValue | The pointer to the result of the measurement. The result is calculated as a specified capacitor capacitance value in picofarads. The user declares a variable of the uint32_t type and passes the pointer to this variable as the function parameter. If the ptrValue parameter is NULL then the capacitance value is not returned through the parameter but stored to the corresponding field of the cy_stc_capsense_bist_context_t structure. |
| maxCapacitance | An expected by the user maximum value of the measured capacitance in nanofarads in the range from 1 to 25 nF. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_MeasureVdda | ( | uint32_t * | ptrValue, |
| cy_stc_capsense_context_t * | context | ||
| ) |
Measures a VDDA voltage, returns the measured voltage in millivolts through the ptrValue argument and stores it to the .vddaVoltage field of the cy_stc_capsense_bist_context_t structure.
This function measures the device analog supply voltage (VDDA) without need of explicitly connecting VDDA to any additional GPIO input. This capability can be used in variate cases, for example to monitor the battery voltage.
A measurement can be done only if the CAPSENSE™ middleware is in the IDLE state. This function must not be called while the CAPSENSE™ middleware is busy. The function is blocking, i.e. waits for the conversion to be completed prior to returning to the caller.
| ptrValue | The pointer to the uint32_t to store measured VDDA voltage value. If the ptrValue parameter is NULL then VDDA voltage value is not returned through the parameter and is stored in the .vddaVoltage field of the cy_stc_capsense_bist_context_t structure. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSensorElectrode | ( | uint32_t | widgetId, |
| uint32_t | eltdId, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Measures the specified CSD sensor / CSX electrode capacitance in femtofarads.
This function measures the sensor capacitance for CSD widgets or the electrode capacitance for CSX widgets and returns the measurement status. For a CSX sensor, the measurement is done on either Rx or Tx electrode. For a CSD sensor, measurement is done on a sensor (refer to the eltdId parameter description). If the specified sensor (electrode) is a ganged sensor, the capacitance is measured for all the pins ganged together that belong to this sensor (electrode).
The measured capacitance is stored in the .eltdCap[] array. The .ptrEltdCapacitance field of the cy_stc_capsense_widget_config_t structure contains a pointer to the first widget sensor (electrode) element within the .eltdCap[] array.
In addition to the measuring sensor (electrode) capacitance, this function is used to identify various fault conditions with sensors such as electrically-opened or -shorted sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns changed capacitance which can be compared against predetermined capacitance for the sensor to detect a fault condition.
The sensor capacitance is measured independently of the sensor scan configuration. For the capacitance measurement, the CSD sensing method is used. The default scanning parameters are the following:
The raw count is converted into capacitance using the following equation:
Cs = Rawcount * RefCDAC capacitance / NumConv
where:
The minimum measurable input by this function is 1pF and the maximum is either 200pF or limited by the RC time constant (Cs < 1 / (2*5*SnsClk*R), where R is the total sensor series resistance that includes on-chip GPIO resistance ~500 Ohm and external series resistance). The measurement accuracy is about 30% and is defined by the RefCDAC tolerance.
By default, all CAPSENSE™ sensors (electrodes) that are not being are set to a corresponding Inactive sensor connection parameter matching configuration used for a specified sensing method. Shield electrodes are also matching the CSD Inactive sensor connection parameter. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function.
By default, the both Cmod1 and Cmod2 capacitors are used for the measurement.
The sensor measurement can be done on all the electrodes using the Cy_CapSense_RunSelfTest() function along with the CY_CAPSENSE_BIST_ELTD_CAP_MASK mask.
This function must not be called while the CAPSENSE™ MW is busy by another scan.
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID. |
| eltdId | Specifies the ID of the electrode within the widget (sensorID for CSD widgets and Rx or Tx electrode ID for CSX widgets). |
For the CSD widgets, a macro for the sensor ID within the specified widget can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.
For the CSX widgets, eltdId is an electrode ID and is defined as Rx ID or Tx ID. The first Rx in a widget corresponds to eltdId = 0, the second Rx in a widget corresponds to eltdId = 1, and so on. The last Tx in a widget corresponds to eltdId = (RxNum + TxNum - 1). Macros for Rx and Tx IDs can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as:
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSlotSensors | ( | uint32_t | slotId, |
| uint32_t | skipChMask, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Measures the specified slot sensor capacitance in femtofarads.
The function measures the Cp capacitance for CSD widgets and the Cm capacitance for CSX widgets.
This function performs BIST slot scan with predefined parameters, back-calculates the slot sensor capacitances (Cp for CSD and Cm for CSX) by using the raw-count equation, stores the calculated capacitances to the sensor context structure, and returns the measurement status. If the specified slot has a ganged sensor, the capacitance is measured for all the pins ganged together that belong to this sensor.
Besides the sensor capacitance measuring, this function could be used to identify various fault conditions with sensors such as electrically-opened or -shorted sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, the function returns changed capacitance which can be compared against predetermined capacitance for the sensor to detect a fault condition.
The sensor capacitance is measured independently of the sensor regular scan configuration. For the capacitance measurement, the BIST specific scan parameters are used. They can be found in the Electrode capacitance measurement macros group. The CDAC code for the CSD sensors is 100u and that provides about 0.886 pF of the CDAC value and for CSX sensors the CDAC code is 50u (0.443 pF). Compensation CDAC is disabled during the BIST scan. Another default scanning parameters are the following:
The raw count is converted into capacitance using the following equation:
Cs = Rawcount * CDAC / 2 / NumConv / 2
where:
The minimum measurable input by this function is 0.5 pF and the maximum is either 200pF or limited by the RC time constant (Cs < 1 / (2*10*SnsClk*R), where R is the total sensor series resistance that includes on-chip pin resistance ~500 Ohm and external series resistance). The measurement accuracy is about 30%.
By default, all CAPSENSE™ sensors (electrodes) that are not being are set to a corresponding Inactive sensor connection parameter matching configuration used for a specified sensing method. Shield electrodes are also matching the CSD Inactive sensor connection parameter. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function.
By default, the both Cmod1 and Cmod2 capacitors are used for the measurement.
Measured capacitance values (Cp for CSD widgets and Cm for CSX widgets) are stored in the ptrSnsCapacitance sensor capacitance array field and in the ptrEltdCapacitance electrode capacitance array of the cy_stc_capsense_widget_config_t structure.
The all sensor measurement can be done on all the sensors using the Cy_CapSense_RunSelfTest() function along with the CY_CAPSENSE_BIST_SNS_CAP_MASK mask.
This function must not be called while the CAPSENSE™ MW is busy by another scan.
| slotId | Specifies the ID number of the slot to measure sensor capacitance. The slot ID should be in the admissible range. |
| skipChMask | Specifies the mask to skip some channels during the slot sensor capacitance measurement. If the bit N in the skipChMask is set to 1, the channel N will be excluded from measuring and all its pins will be set to the inactive sensor connection state (see the .eltdCapCsdISC field of the cy_stc_capsense_bist_context_t structure for CSD widgets and the .eltdCapCsxISC field respectively for CSX widgets). For fifth-generation low power CAPSENSE™ this argument is kept for uniformity and backward compatibility and is not used. The function can be called with value 0u. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceShieldElectrode | ( | uint32_t | skipChMask, |
| cy_stc_capsense_context_t * | context | ||
| ) |
Measures shield electrode capacitances in femtofarads.
This function measures the capacitances of all shield electrodes for all enabled MSCv3 channels and returns a status of this measurement. The function checks if there is any CSD widget in the project and if the shield is enabled. The measurement results in femtofarads are stored in the chShieldCap[CY_MSC_ENABLED_CH_NUMBER] array. The pointer to the array is in the .ptrChShieldCap field of the cy_stc_capsense_bist_context_t structure, the CY_MSC_ENABLED_CH_NUMBER define is in the cycfg_peripherals.h file. If the any channel shield consists of several electrodes, the total capacitance of all the shield electrodes is measured.
This function uses an algorithm identical to the electrode capacitance measurement. Refer to the Cy_CapSense_MeasureCapacitanceSensorElectrode() function for more details.
In addition to measuring shield capacitance, this function is used to identify various fault conditions with shield electrodes such as an electrically-open or -short shield electrodes, e.g. the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns changed capacitance that can be compared against pre-determined capacitance for the shield electrode to detect a hardware fault.
By default, all CAPSENSE™ sensors (electrodes) that are not being measured are set to the GND state. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function. When the inactive sensor (electrode) connection is set to the CY_CAPSENSE_SNS_CONNECTION_SHIELD state, all the CAPSENSE™ electrodes are connected to the shield and the total capacitance are measured.
By default, the both Cmod1 and Cmod2 capacitors are used for the measurement.
This test can be executed using the CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_SHIELD_CAP_MASK mask.
| skipChMask | Specifies the mask to skip some channels during the shield electrode capacitance measurement. If the bit N in the skipChMask is set to 1, the channel N will be excluded from measuring and all its shield pins will be set to the shield inactive sensor connection state (see the .shieldCapISC field of the cy_stc_capsense_bist_context_t structure). For fifth-generation low power CAPSENSE™ this argument is kept for uniformity and backward compatibility and is not used. The function can be called with value 0u. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceLpSlotSensors | ( | uint32_t | slotId, |
| cy_stc_capsense_context_t * | context | ||
| ) |
Measures the specified low power slot sensor capacitance in femtofarads.
The function measures the Cp capacitance for CSD widgets and the Cm capacitance for CSX widgets.
This function performs BIST slot scan with predefined parameters, back-calculates the slot sensor capacitances (Cp for CSD and Cm for CSX) by using the raw-count equation, stores the calculated capacitances to the sensor context structure, and returns the measurement status. If the specified slot has a ganged sensor, the capacitance is measured for all the pins ganged together that belong to this sensor.
Besides the sensor capacitance measuring, this function could be used to identify various fault conditions with sensors such as electrically-opened or -shorted sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, the function returns changed capacitance which can be compared against predetermined capacitance for the sensor to detect a fault condition.
The sensor capacitance is measured independently of the sensor regular scan configuration. For the capacitance measurement, the BIST specific scan parameters are used. They can be found in the Electrode capacitance measurement macros group. The CDAC code for the CSD sensors is 100u and that provides about 0.886 pF of the CDAC value and for CSX sensors the CDAC code is 50u (0.443 pF). Compensation CDAC is disabled during the BIST scan. Another default scanning parameters are the following:
The raw count is converted into capacitance using the following equation:
Cs = Rawcount * CDAC / 2 / NumConv / 2
where:
The minimum measurable input by this function is 0.5 pF and the maximum is either 200pF or limited by the RC time constant (Cs < 1 / (2*10*SnsClk*R), where R is the total sensor series resistance that includes on-chip pin resistance ~500 Ohm and external series resistance). The measurement accuracy is about 30%.
By default, all CAPSENSE™ sensors (electrodes) that are not being are set to a corresponding Inactive sensor connection parameter matching configuration used for a specified sensing method. Shield electrodes are also matching the CSD Inactive sensor connection parameter. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function.
By default, the both Cmod1 and Cmod2 capacitors are used for the measurement.
Measured capacitance values (Cp for CSD widgets and Cm for CSX widgets) are stored in the ptrSnsCapacitance sensor capacitance array field and in the ptrEltdCapacitance electrode capacitance array of the cy_stc_capsense_widget_config_t structure.
The all sensor measurement can be done on all the sensors using the Cy_CapSense_RunSelfTest() function along with the CY_CAPSENSE_BIST_SNS_CAP_MASK mask.
This function must not be called while the CAPSENSE™ MW is busy by another scan.
| slotId | Specifies the ID number of the slot to measure sensor capacitance. The slot ID should be in the admissible range. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceSensor | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| uint32_t * | ptrValue, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Measures the specified CSD sensor / CSX electrode capacitance in femtofarads.
This function measures the capacitance of the sensor (electrode for CSX widgets) and returns the measurement status. For a CSX sensor, the measurement is done on either Rx or Tx electrode. For a CSD sensor, measurement is done on a sensor (refer to the sensorId parameter description). If the specified sensor (electrode) is a ganged sensor, the capacitance is measured for all the pins ganged together that belong to this sensor (electrode).
The measured capacitance is stored in the .eltdCap[] array. The .ptrEltdCapacitance field of the cy_stc_capsense_widget_config_t structure contains a pointer to the first widget sensor (electrode) element within the .eltdCap[] array.
In addition to the measuring sensor (electrode) capacitance, this function is used to identify various fault conditions with sensors such as electrically-opened or -shorted sensors. For example, the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns changed capacitance which can be compared against predetermined capacitance for the sensor to detect a fault condition.
The sensor capacitance is measured independently of the sensor scan configuration. For the capacitance measurement, the CSD sensing method is used. The measurements consists of up to four scans with different IDAC current. The IDAC current of the first measurement is 6 uA and each next measurement the IDAC current increase by four times. The default scanning parameters are the following:
If the scanning raw count is within 7.5% to 45% range of a maximum raw count the raw count is converted into capacitance using the following equation:
Cs = Rawcount * I / ((2^Res - 1) * Vref * SnsClk)
where:
If the raw count is less than 7.5% of the maximum limit (2^Res - 1), the function stops scanning the sequence and returns the CY_CAPSENSE_BIST_LOW_LIMIT_E status.
If the raw count is between 7.5% and 45% of the maximum, the function calculates the sensor capacitance, updates the register map and returns CY_CAPSENSE_BIST_SUCCESS_E status.
If the raw count is above 45% of the maximum, the function repeats scanning with a 4x increased IDAC current (up to four scans in total).
The minimum measurable input by this function is 1pF and the maximum is either 384pF or limited by the RC time constant (Cs < 1 / (2*5*SnsClk*R), where R is the total sensor series resistance that includes on-chip GPIO resistance ~500 Ohm and external series resistance). The measurement accuracy is about 15%.
By default, all CAPSENSE™ sensors (electrodes) that are not being are set to a corresponding Inactive sensor connection parameter matching configuration used for a specified sensing method. Shield electrodes are also matching the CSD Inactive sensor connection parameter. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function.
By default, the Cmod capacitor is used for the measurement. If a dedicated Cmod is not available (e.g. the design has CSX widgets only), CintA and CintB capacitors are combined together by the firmware to form a single integration capacitor for the measurement.
The sensor measurement can be done on all the sensors using the Cy_CapSense_RunSelfTest() function along with the CY_CAPSENSE_BIST_SNS_CAP_MASK mask.
This function must not be called while the CSD HW block is busy by another state.
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_WDGT_ID. |
| sensorId | Specifies the ID of the sensor (electrode for CSX widgets) within the widget to be measured. |
For the CSD widgets, a macro for the sensor ID within the specified widget can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as CY_CAPSENSE_<WidgetName>_SNS<SensorNumber>_ID.
For the CSX widgets, sensorId is an electrode ID and is defined as Rx ID or Tx ID. The first Rx in a widget corresponds to electrodeId = 0, the second Rx in a widget corresponds to electrodeId = 1, and so on. The last Tx in a widget corresponds to electrodeId = (RxNum + TxNum - 1). Macros for Rx and Tx IDs can be found in the CAPSENSE™ Configuration header file (cycfg_capsense.h) defined as:
| ptrValue | The pointer to the measured capacitance in femtofarads. The user declares a variable of the uint32_t type and passes the variable pointer as the function parameter. If the ptrValue parameter is NULL, the capacitance value is not returned through the parameter but still stored in the corresponding field of the data structure. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_en_capsense_bist_status_t Cy_CapSense_MeasureCapacitanceShield | ( | uint32_t * | ptrValue, |
| cy_stc_capsense_context_t * | context | ||
| ) |
Measures shield electrode capacitance in femtofarads.
This function measures the capacitance of the shield electrode and returns a status of this measurement. The measurement result in femtofarads is stored in the .shieldCap field of the cy_stc_capsense_bist_context_t structure. If the shield consists of several electrodes, the total capacitance of all shield electrodes is reported.
This function uses an algorithm identical to the sensor capacitance measurement. Refer to the Cy_CapSense_MeasureCapacitanceSensor() function for more details.
In addition to measuring shield capacitance, this function is used to identify various fault conditions with a shield electrode such as an electrically-open or -short shield electrode, e.g. the PCB track is broken or shorted to other nodes in the system - in all of these conditions, this function returns changed capacitance that can be compared against pre-determined capacitance for the shield electrode to detect a fault condition.
By default, all CAPSENSE™ sensors (electrodes) that are not being measured are set to the GND state. The inactive state can be changed in run-time by using the Cy_CapSense_SetInactiveElectrodeState() function. When the inactive sensor (electrode) connection is set to the CY_CAPSENSE_SNS_CONNECTION_SHIELD state, all the CAPSENSE™ electrodes are connected to the shield and the total capacitance are measured.
By default, the Cmod capacitor is used for the measurement. If a dedicated Cmod is not available (e.g. the design has CSX widgets only), CintA and CintB capacitors are combined together by the firmware to form a single integration capacitor which is used for measurement.
This test can be executed using the CapSense_RunSelfTest() function with the CY_CAPSENSE_BIST_SHIELD_CAP_MASK mask.
| ptrValue | The pointer to the variable the measured capacitance is stored. The user should declare a variable of uint32_t type and pass the variable pointer as the function parameter. If the ptrValue parameter is NULL then the shield capacitance value is not returned through the parameter but is still stored in the .shieldCap field of the cy_stc_capsense_bist_context_t structure. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_CalibrateAllWidgets | ( | cy_stc_capsense_context_t * | context | ) |
Executes CapDAC/IDAC auto-calibration for all the sensors in all widgets of some sensing groups (CSD, CSX, or ISX) if calibration is enabled for such group of widgets.
The auto-calibration finds CapDAC/IDAC values to have raw counts close to configured target values. Use sensing and processing functions after auto-calibration to update all baselines and configured filters.
Having enabled the CDAC auto-calibration algorithm is the most common use case. It helps to tune your system considering board-to-board variation, temperature drift, etc. CDAC auto-calibration is enabled by default.
The default auto-calibration target values are defined as:
For fifth-generation low power CAPSENSE™ the function calibrates only Active widgets. For Low Power widgets use the Cy_CapSense_CalibrateAllLpWidgets() function.
This function detects the sensing method used by each widget and performs a successive approximation search algorithm to find the appropriate Reference and Compensation CapDAC (if enabled) values for all sensors for the fifth-generation CAPSENSE™ and for all Active sensors for the fifth-generation low power CAPSENSE™. For the fifth-generation low power CAPSENSE™ if during the calibration process it is reached the Reference CapDAC value lower than /ref CY_CAPSENSE_CAL_REF_CDAC_MIN_CODE and Fine CapDAC usage is enabled in CAPSENSE™ Configurator then the FineCDAC calibration is performed with the reference CDAC value set to 0.
For the the forth-generation CAPSENSE™ the function finds appropriate modulator and compensation IDAC (if enabled) values for all sensors in CSD widgets and/or IDAC values for all sensors in CSX widgets to make sensor raw count to the default value level.
This function could be used only if Enable auto-calibration parameter is enabled for CSD and/or CSX (and/or ISX for fifth-generation low power CAPSENSE™) widgets.
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_CalibrateAllSlots | ( | cy_stc_capsense_context_t * | context | ) |
Executes CapDAC/IDAC auto-calibration for all the sensors in all widgets of some sensing groups (CSD, CSX, or ISX) if calibration is enabled for such group of widgets.
The auto-calibration finds CapDAC/IDAC values to have raw counts close to configured target values. Use sensing and processing functions after auto-calibration to update all baselines and configured filters.
Having enabled the CDAC auto-calibration algorithm is the most common use case. It helps to tune your system considering board-to-board variation, temperature drift, etc. CDAC auto-calibration is enabled by default.
For fifth-generation low power CAPSENSE™ the function calibrates only Active widgets. For Low Power widgets use the Cy_CapSense_CalibrateAllLpWidgets() function.
The function performs searching of Reference CDAC code, Compensation CDAC code Compensation Divider (whichever is enabled) by using a successive approximation method to make the sensor's raw count closest to the defined targets. The auto-calibration target values are defined (by default) as:
For the fifth-generation low power CAPSENSE™ if during the calibration process it is reached the Reference CapDAC value lower than /ref CY_CAPSENSE_CAL_REF_CDAC_MIN_CODE and Fine CapDAC usage is enabled in CAPSENSE™ Configurator then the FineCDAC calibration is performed with the reference CDAC value set to 0.
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_SetCalibrationTarget | ( | uint32_t | calibrTarget, |
| uint32_t | snsMethod, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Sets the CapDAC auto-calibration raw count target for CSD, CSX or ISX widgets.
The function only updates the target value, use Cy_CapSense_CalibrateWidget() / Cy_CapSense_CalibrateAllWidgets() / Cy_CapSense_CalibrateAllLpWidgets() / Cy_CapSense_CalibrateAllSlots() to change raw counts according to the updated target.
The function sets the specified raw count targets if CSD, CSX and/or ISX widgets are in the project and the auto-calibration is enabled for them. These targets will be used instead the configured ones by Cy_CapSense_CalibrateAllSlots(), Cy_CapSense_CalibrateAllWidgets() and Cy_CapSense_CalibrateWidget() functions.
| calibrTarget | The raw counts target in percentage for the specified sensing method. It should be in range [1..99]. If the specified target is outside the range, then it will not be updated and the CY_CAPSENSE_STATUS_BAD_PARAM status will be returned. |
| snsMethod | Desired sensing method the calibration target should be updated for:
|
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_CalibrateWidget | ( | uint32_t | widgetId, |
| cy_stc_capsense_context_t * | context | ||
| ) |
Executes the CapDAC/IDAC calibration for all the sensors in the specified widget to the default target value.
This function performs exactly the same tasks as Cy_CapSense_CalibrateAllWidgets(), but only for a specified widget. Use sensing and processing functions after auto-calibration to update all baselines and configured filters.
| 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.
If the middleware is busy, do not initiate a new scan or set up widgets. Use the Cy_CapSense_IsBusy() function to check HW busyness at a particular moment. Use the Cy_CapSense_MwState() function to verify if MW executes any firmware tasks related to initialization, scanning, and processing at a particular moment.
| 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_SetPinState | ( | uint32_t | widgetId, |
| uint32_t | sensorElement, | ||
| uint32_t | state, | ||
| const cy_stc_capsense_context_t * | context | ||
| ) |
Sets the state (drive mode and HSIOM state) of the GPIO used by a sensor.
The possible states are GND, Shield, High-Z, Tx, Negative Tx, Rx, and Sensor. If the sensor specified in the input parameter is a ganged sensor, then the state of all GPIOs associated with the ganged sensor is updated.
To access a sensor of CSD of button or slider widgets, use the sensor ID. To access a sensor of CSD matrix button or touchpad widgets, use either row ID or column ID as appropriate. To access sensor CSX widgets, use either Rx ID or Tx ID as appropriate.
This function accepts the CY_CAPSENSE_SHIELD and CY_CAPSENSE_SENSOR states as an input only if there is at least one CSD widget in the project. Similarly, this function accepts the CY_CAPSENSE_TX_PIN and CY_CAPSENSE_RX_PIN states as an input only if there is at least one CSX widget in the project.
This function must not be called while the middleware is in the busy state. Calling this function directly from the application program is not recommended. This function is used to implement only the custom-specific use cases.
Functions that perform a setup and scan of a sensor/widget automatically set the required pin states for a sensor as required and overwrite changes made by this function to a sensor that are going to be scanned. Therefore the Cy_CapSense_SetPinState() function should be called in StartSample callback (see the Callbacks section for details) or with low-level functions that perform a single-sensor scanning.
The function is available for the fourth-generation and fifth-generation (only for CY_CAPSENSE_AMUX_SENSOR_CONNECTION_METHOD) CAPSENSE™. For fifth-generation CAPSENSE&trade with CY_CAPSENSE_CTRLMUX_SENSOR_CONNECTION_METHOD and for fifth- generation low power CAPSENSE&trade use Cy_CapSense_SlotPinState().
| widgetId | Specifies the ID number of the widget. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID. |
| sensorElement | Specifies the ID of the sensor element within the widget to change its pin state.
|
| state | Specifies the state of the sensor to be set:
|
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_SlotPinState | ( | uint32_t | slotId, |
| const cy_stc_capsense_electrode_config_t * | ptrEltdCfg, | ||
| uint32_t | pinState, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Configures the specified electrode to the desired state in the specified slot (Active slot for fifth-generation low power CAPSENSE™) by updating the CAPSENSE™ configuration.
This function changes / overwrites configuration of an electrode (several pins in case the electrode is ganged to more pins) with a state specified by the pinState parameter. The function does this only for the specified slot ID (Active slotID for fifth-generation low power CAPSENSE™). If the electrode should have the desired state during scans in another slots, the function should be called multiple times for each desired slot (Active slot for fifth-generation low power CAPSENSE™).
The function call changes the pin states permanently and all further scans of the slot will have the electrode state as specified by the pinState parameter. Call the function again to change the electrode state to a new desired one or reinitialize CAPSENSE™ middleware by using the Cy_CapSense_Enable() function.
The re-configuration is available only when parameter Sensor connection method = CTRLMUX. If parameter Sensor connection method = AMUXBUS, then the Cy_CapSense_SetPinState() function should be used.
The function changes the configuration of an electrode without storing the previous state. A user is responsible to keep the previous state to revert to the default settings if needed. Also, the default settings can be configured again by calling Cy_CapSense_Enable() function that leads to repeating CAPSENSE™ Data Structure initialization, DAC auto-calibration, and baseline initialization.
Using the function is recommended only for advanced users for specific use cases. For instance, to change the CAPSENSE™ default electrode configuration, the function could be called by using a CAPSENSE™ Data Structure Initialization callback ptrEODsInitCallback. For details of how to register the callback see the Callbacks section. That avoids repeating of DAC auto-calibration and baseline initialization since the callback is called after CAPSENSE™ Data Structure initialization but before the first initialization scan.
You can also use this function to change the shield electrode state - call the function and pass the pointer to the shield electrode configuration as an input parameter.
| slotId | The desired slot ID (Active slot ID for fifth-generation low power CAPSENSE™). |
| ptrEltdCfg | The pointer to an electrode the all pins states of which will be configured as pinState parameter. |
| pinState | The desired pins state for CSX widget electrodes could be:
|
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_SetInactiveElectrodeState | ( | uint32_t | inactiveState, |
| uint32_t | sensingGroup, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Sets a desired state for all inactive CAPSENSE™-related electrodes for CSD, CSX, ISX scans, or BIST measurement scans.
Use the function to set/change the desired state of all CAPSENSE™-related electrodes which are not scanned during regular scans or BIST capacitance measurements. There are separate states for the CSD sensing method group, the CSX sensing method group, the ISX sensing method group, the BIST CSD sensor (electrode) capacitance measurement, the BIST CSX sensor (electrode) capacitance measurement, and the BIST shield electrode capacitance measurement. For instance, it can be configured the GND state for all inactive sensors for CSX scanning and the High-Z state for CSD scanning and the Shield state for BIST CSD sensor (electrode) capacitance measurement. The function updates some corresponding parameters in the CAPSENSE™ Data Structure to provide the desired state and not changes pin state immediately. The desired state will be applied to all inactive electrodes during the CSD, CSX, ISX scans or BIST capacitance measurements. It is not recommended to update the Data Structure registers directly. Additionally (only for fifth-generation CAPSENSE™), the function recalculates sensor frames in a case of the CTRLMUX sensor connection method. For fifth-generation low power CAPSENSE™, the function always recalculates all sensor frames including low-power sensors.
| inactiveState | Specifies the inactive CAPSENSE™ electrode state:
|
| sensingGroup | Specifies the sensing group:
|
| 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.
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_LpSlotPinState | ( | uint32_t | lpSlotId, |
| const cy_stc_capsense_electrode_config_t * | ptrEltdCfg, | ||
| uint32_t | pinState, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Configures the specified electrode to the desired state in the specified Low Power slot by updating the CAPSENSE™ configuration.
This function changes / overwrites configuration of an electrode (several pins in case the electrode is ganged to more pins) with a state specified by the pinState parameter. The function does this only for the specified Low Power slot ID. If the electrode should have the desired state during scans in another Low Power slots, the function should be called multiple times for each desired Low Power slot.
The function call changes the pin states permanently and all further scans of the slot will have the electrode state as specified by the pinState parameter. Call the function again to change the electrode state to a new desired one or reinitialize CAPSENSE™ middleware by using the Cy_CapSense_Enable() function.
The function changes the configuration of an electrode without storing the previous state. A user is responsible to keep the previous state to revert to the default settings if needed. Also, the default settings can be configured again by calling Cy_CapSense_Enable() function that leads to repeating CAPSENSE™ Data Structure initialization, DAC auto-calibration, and baseline initialization.
Using the function is recommended only for advanced users for specific use cases. For instance, to change the CAPSENSE™ default electrode configuration, the function could be called by using a CAPSENSE™ Data Structure Initialization callback ptrEODsInitCallback. For details of how to register the callback see the Callbacks section. That avoids repeating of DAC auto-calibration and baseline initialization since the callback is called after CAPSENSE™ Data Structure initialization but before the first initialization scan.
The function is a low-level function and does not perform an input parameter verification (like Low Power slot ID, pointers, etc.). For example, the CY_CAPSENSE_CTRLMUX_PIN_STATE_SHIELD pin state is not available if a shield is not configured in the project, but the function will set the pin state and the HW block behavior is unpredictable.
| lpSlotId | The desired Low Power slot ID. |
| ptrEltdCfg | The pointer to an electrode the all pins states of which will be configured as pinState parameter. |
| pinState | The desired pins state for CSX widget electrodes could be:
|
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_CalibrateAllLpWidgets | ( | cy_stc_capsense_context_t * | context | ) |
Executes CapDAC auto-calibration for all relevant low power widgets if enabled.
Having enabled the CDAC auto-calibration algorithm is the most common use case. It helps to tune your system considering board-to-board variation, temperature drift, etc. CDAC auto-calibration is enabled by default.
The function performs searching of Reference CDAC code, Compensation CDAC code, Compensation Divider (whichever is enabled) by using a successive approximation method to make the sensor's raw count closest to the defined targets. The auto-calibration target values are defined (by default) as:
To change calibration targets use the Cy_CapSense_SetCalibrationTarget() function.
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_CalibrateAllLpSlots | ( | cy_stc_capsense_context_t * | context | ) |
Calibrates CapDACs for all Low power widgets.
The function is the wrapper for the Cy_CapSense_CalibrateAllLpWidgets() function to provide the backward compatibility.
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_ScanInitializeHwIirAllSlots | ( | cy_stc_capsense_context_t * | context | ) |
Initializes (or re-initializes) the hardware IIR filter for all slots.
This function initiates the blocking scan of all slots to initialize the hardware IIR filter. This should be done before firmware filters and baselines initialization.
Calling this function is accompanied by
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_ScanInitializeHwIirSlots | ( | uint32_t | startSlotId, |
| uint32_t | numberSlots, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Initializes (or re-initializes) the hardware IIR filter for specified slots.
This function initiates the blocking scan of specified slots to initialize the hardware IIR filter. This should be done before firmware filters and baselines initialization.
Calling this function is accompanied by
| startSlotId | The slot ID initialization will be started from. |
| numberSlots | The number of slots will be initialized. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_SetupWidgetExt | ( | uint32_t | widgetId, |
| uint32_t | sensorId, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Performs extended initialization for the specified widget and also performs initialization required for a specific sensor in the widget.
This function requires using the Cy_CapSense_ScanExt() function to initiate a scan.
This function does the same as Cy_CapSense_SetupWidget() and also does the following tasks:
Once this function is called to initialize a widget and a sensor, the Cy_CapSense_ScanExt() function is called to scan the sensor.
This function is called when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status.
Calling this function directly from the application program is not recommended. This function is used to implement only the user's specific use cases (for faster execution time or pipeline scanning, for example).
| 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_ScanExt | ( | cy_stc_capsense_context_t * | context | ) |
Starts a conversion on the pre-configured sensor.
This function requires using the Cy_CapSense_SetupWidgetExt() function to set up the a widget.
This function performs single scanning of one sensor in the widget configured by the Cy_CapSense_SetupWidgetExt() function.
Calling this function directly from the application program is not recommended. This function is used to implement only the user's specific use cases (for faster execution time or pipeline scanning, for example). This function is called when no scanning is in progress. I.e. Cy_CapSense_IsBusy() returns a non-busy status.
The sensor must be pre-configured by using the Cy_CapSense_SetupWidgetExt() prior to calling this function. The sensor remains ready for the next scan if a previous scan was triggered by using the Cy_CapSense_ScanExt() function. In this case, calling Cy_CapSense_SetupWidgetExt() is not required every time before the Cy_CapSense_ScanExt() function. If a previous scan was triggered in any other way - Cy_CapSense_Scan(), Cy_CapSense_ScanAllWidgets(), or Cy_CapSense_RunTuner() - (see the Cy_CapSense_RunTuner() function description for more details), the sensor must be pre-configured again by using the Cy_CapSense_SetupWidgetExt() prior to calling the Cy_CapSense_ScanExt() function.
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_GetParam | ( | uint32_t | paramId, |
| uint32_t * | value, | ||
| const void * | ptrTuner, | ||
| const cy_stc_capsense_context_t * | context | ||
| ) |
Gets a value of the specified parameter from the cy_capsense_tuner structure.
This function gets the value of the specified parameter by the paramId argument. The paramId for each register of cy_capsense_tuner is available in the cycfg_capsense.h file as CY_CAPSENSE_<ParameterName>_PARAM_ID. The paramId is a special enumerated value generated by the CAPSENSE™ Configurator tool. The format of paramId is as follows:
| paramId | Specifies the ID of parameter to get its value. A macro for the parameter ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<ParameterName>_PARAM_ID. |
| value | The pointer to a variable to be updated with the obtained value. |
| ptrTuner | The pointer to the cy_capsense_tuner variable of cy_stc_capsense_tuner_t. The cy_capsense_tuner is declared in CAPSENSE™ Configurator tool generated files:
|
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| cy_capsense_status_t Cy_CapSense_SetParam | ( | uint32_t | paramId, |
| uint32_t | value, | ||
| void * | ptrTuner, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Sets a new value for the specified parameter in cy_capsense_tuner structure.
This function sets the value of the specified parameter by the paramId argument. The paramId for each register of cy_capsense_tuner is available in the cycfg_capsense.h file as CY_CAPSENSE_<ParameterName>_PARAM_ID. The paramId is a special enumerated value generated by the CAPSENSE™ Configurator tool. The format of paramId is as follows:
This function writes specified value into the desired register without other registers update. It is application layer responsibility to keep all the data structure registers aligned. Repeated call of Cy_CapSense_Enable() function helps aligning dependent register values.
This function updates also the widget CRC field if Built-in Self-test is enabled and paramId requires that.
| paramId | Specifies the ID of parameter to set its value. A macro for the parameter ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<ParameterName>_PARAM_ID. |
| value | Specifies the new parameter's value. |
| ptrTuner | The pointer to the cy_capsense_tuner variable of cy_stc_capsense_tuner_t. The cy_capsense_tuner is declared in CAPSENSE™ Configurator tool generated files:
|
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| uint16_t Cy_CapSense_GetCRC | ( | const uint8_t * | ptrData, |
| uint32_t | len | ||
| ) |
Calculates CRC for the specified buffer and length.
This API is used for the CRC protection of a packet received from the CAPSENSE™ Tuner tool and for BIST operations. CRC polynomial is 0xAC9A. It has a Hamming distance 5 for data words up to 241 bits.
Reference: "P. Koopman, T. Chakravarthy, "Cyclic Redundancy Code (CRC) Polynomial Selection for Embedded Networks", The International Conference on Dependable Systems and Networks, DSN-2004"
| ptrData | The pointer to the data. |
| len | The length of the data in bytes. |
| cy_capsense_status_t Cy_CapSense_SetWidgetStatus | ( | uint32_t | widgetId, |
| uint32_t | mode, | ||
| uint32_t | mask, | ||
| cy_stc_capsense_context_t * | context | ||
| ) |
Performs configuring of the selected widget.
This function performs customized widget status configuration by the mode parameter. There are two general use cases for this function:
Although other statuses can be changed by this function, this is not recommended to avoid impact on CAPSENSE™ operation and is needed to implement only specific use cases.
By default, all widgets are enabled and working during CAPSENSE™ initialization. All disabled or non-working widgets are excluded from scanning and processing.
Excluding a widget from a scanning flow happens immediately by re-generation a new scanning frame. This function does it for optimization, which means that scanning functions save CPU time by checking if any widget status was changed.
Excluding from processing flow happens inside the process functions since they perform processing by widgets and not by slots. Therefore, changing the widget status should happen before a new scan and/or after processing.
The Cy_CapSense_ProcessWidgetExt() and Cy_CapSense_ProcessSensorExt() functions ignore widget disable and non-working statuses and perform processing based on specified mode provided to those functions.
The function also checks if there is at least one enabled and working widget. If no valid widgets are left for scanning, the function returns CY_CAPSENSE_STATUS_BAD_CONFIG separately for active and low-power widgets due to these groups' independent scanning frames.
| widgetId | Specifies the widget ID number. A macro for the widget ID can be found in the cycfg_capsense.h file defined as CY_CAPSENSE_<WIDGET_NAME>_WDGT_ID. |
| mode | Specifies the bit mask of widget status to be configured. It is allowed to configure several bits simultaneously.
|
| mask | Specifies the value of widget status field to be configured. All bit values not set by the mask passed as the mode parameter are ignored. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |
| uint32_t Cy_CapSense_IsWidgetEnabled | ( | uint32_t | widgetId, |
| const cy_stc_capsense_context_t * | context | ||
| ) |
Returns widget enable/working status.
| widgetId | Specifies the widget ID number. 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_IsSlotEnabled | ( | uint32_t | slotId, |
| const cy_stc_capsense_context_t * | context | ||
| ) |
Returns slot enable/working status.
| slotId | Specifies the slot ID number. |
| context | The pointer to the CAPSENSE™ context structure cy_stc_capsense_context_t. |