MSP430™CapTIvateSoftwareLibraryAPIGuide
1_83_00_05
|
Low-level sensor update module. More...
Functions | |
void | CAPT_blockOnFlag (volatile bool *pFlag, uint8_t ui8LPM) |
void | CAPT_loadCycle (tSensor *pSensor, uint8_t ui8Cycle, uint8_t ui8Freq, bool bFSM) |
void | CAPT_unloadCycle (tSensor *pSensor, uint8_t ui8Cycle, uint8_t ui8Index, bool bFSM) |
void | CAPT_startConversion (volatile bool *pbEndOfConversionFlag) |
void | CAPT_cleanupAfterConversion (void) |
void | CAPT_startConversionAndWaitUntilDone (volatile bool *pbEndOfConversionFlag, uint8_t ui8LPM) |
void | CAPT_initSensor (tSensor *pSensor) |
void | CAPT_updateSensor (tSensor *pSensor, uint8_t ui8LPM) |
void | CAPT_updateSensorRawCount (tSensor *pSensor, tRawConversionStyle conversion, tOversamplingStyle oversampling, uint8_t ui8LPM) |
void | CAPT_startWakeOnProxMode (tSensor *pSensor, uint8_t ui8Cycle, uint16_t ui16WakeupInterval) |
void | CAPT_startWakeOnProxModeWithEMCAuto (tSensor *pSensor, uint8_t ui8Cycle, uint16_t ui16WakeupInterval) |
void | CAPT_stopWakeOnProxMode (tSensor *pSensor, uint8_t ui8Cycle) |
void | CAPT_stopWakeOnProxModeWithEMCAuto (tSensor *pSensor, uint8_t ui8Cycle) |
void | CAPT_processFSMCycle (tSensor *pSensor, tCycle *pCycle) |
void | CAPT_processSensor (tSensor *pSensor) |
bool | CAPT_testForRecalibration (tSensor *pSensor) |
bool | CAPT_testForMaxCountRecalibration (tSensor *pSensor) |
bool | CAPT_testForNegativeTouchRecalibration (tSensor *pSensor) |
void | CAPT_flagAllElementsForReseed (tSensor *pSensor) |
void | CAPT_updateSensorTimeout (tSensor *pSensor) |
void | CAPT_updateSensorNoise (tSensor *pSensor) |
uint8_t | CAPT_convertAbsToRel (uint16_t ui16Ref, uint16_t ui16Abs) |
uint16_t | CAPT_convertRelToAbs (uint16_t ui16Ref, uint8_t ui8Rel) |
uint64_t | CAPT_getElementStateBitField (tSensor *pSensor, tElementStatusType status) |
Get a bit field of the requested state of all elements in the sensor. More... | |
void | CAPT_registerCallback (tSensor *pSensor, void(*user_callback)(tSensor *pSensor)) |
void | CAPT_registerTrackPadSensorProcessing (tSensor *pSensor, void(*user_function)(tSensor *)) |
void | CAPT_registerTrackPadGestureProcessing (tSensor *pSensor, void(*user_function)(tSensor *)) |
void | CAPT_clearSensorProxTouch (tSensor *pSensor) |
IQ16_t | CAPT_computeIIRFilter (IQ16_t *pRaw, IQ16_t *pFiltered, uint8_t ui8Beta) |
uint32_t | CAPT_computeIIRFilter32 (IQ16_t *pRaw, IQ16_t *pFiltered, uint8_t ui8Beta) |
IQ16_t | CAPT_computeIIRFilterFast (IQ16_t *pRaw, IQ16_t *pFiltered, uint8_t ui8Beta) |
uint32_t | CAPT_computeIIRFilterFast32 (IQ16_t *pRaw, IQ16_t *pFiltered, uint8_t ui8Beta) |
void | CAPT_reseedFilterAll (tSensor *pSensor, tFilterOption WhatToFilter) |
void | CAPT_reseedFilter (IQ16_t *pFilter, uint16_t ui16ReseedValue) |
bool | CAPT_updateProx (tSensor *pSensor, tElement *pElement) |
bool | CAPT_updateTouch (tSensor *pSensor, tElement *pElement) |
void | CAPT_updateLTA (tSensor *pSensor, tElement *pElement) |
void | CAPT_updateFSMProx (tSensor *pSensor, tElement *pElement) |
void | CAPT_updateFSMTouch (tSensor *pSensor, tElement *pElement) |
void | CAPT_updateSensorProxTouch (tSensor *pSensor) |
void | CAPT_updateSensorWithEMC (tSensor *pSensor, uint8_t ui8LPM) |
void | CAPT_updateSensorWithEMCAuto (tSensor *pSensor, uint8_t ui8LPM) |
void | CAPT_processCycleWithEMC (tSensor *pSensor, const tCycle *pCycle) |
void | CAPT_updateElementFilteredValuesWithEMC (tSensor *pSensor, tElement *pElement) |
bool | CAPT_updateSelfElementProxTouchWithEMC (tSensor *pSensor, tElement *pElement) |
bool | CAPT_updateProjElementProxTouchWithEMC (tSensor *pSensor, tElement *pElement) |
Low-level sensor update module.
This module APIs for sensor initialization, measurement, filtering, auto calibration, threshold detection, and debounce for proximity and touch. A fast IIR filter API and a performance IIR filter API are made available to higher level processing functions as well.
void CAPT_blockOnFlag | ( | volatile bool * | pFlag, |
uint8_t | ui8LPM | ||
) |
Use CAPT_blockOnFlag to safely stall the running program in the specified LPM mode until a boolean flag is set to true and the CPU is awakened.
pFlag | is a pointer to the boolean flag to pend on |
ui8LPM | indicates the low power mode to use while waiting |
void CAPT_loadCycle | ( | tSensor * | pSensor, |
uint8_t | ui8Cycle, | ||
uint8_t | ui8Freq, | ||
bool | bFSM | ||
) |
Use CAPT_loadCycle before CAPT_startConversion() or CAPT_startConversionAndWaitUntilDone() to load a cycle for measurement. This function sets up the IO for the cycle, applies the gain and offset, for each element in the cycle, and configures the FSM if requested.
pSensor | is a pointer to the parent sensor |
ui8Cycle | is the cycle to load in the sensor |
ui8Freq | is the oscillator frequency index to load values from |
bFSM | specifies whether to load and enable the FSM. |
void CAPT_unloadCycle | ( | tSensor * | pSensor, |
uint8_t | ui8Cycle, | ||
uint8_t | ui8Index, | ||
bool | bFSM | ||
) |
Use CAPT_unloadCycle after CAPT_startConversion() or CAPT_startConversionAndWaitUntilDone() to unload a cycle after measurement. This function clears up the IO for the cycle, saves the raw results, and saves the filtered count / LTA if the FSM parameter is true.
pSensor | is a pointer to the parent sensor |
ui8Cycle | is the cycle to load in the sensor |
ui8Index | is the raw count index to save the results to |
bFSM | specifies whether to save filtered count and LTA data from the FSM. |
void CAPT_startConversion | ( | volatile bool * | pbEndOfConversionFlag | ) |
Use CAPT_startConversion to immediately kickoff a conversion that has been set up. This function returns immediately and does not wait for the conversion to complete.
none |
void CAPT_cleanupAfterConversion | ( | void | ) |
Use CAPT_cleanupAfterConversion to cleanup the peripheral after CAPT_startConversion has been called and the conversion has completed.
none |
void CAPT_startConversionAndWaitUntilDone | ( | volatile bool * | pbEndOfConversionFlag, |
uint8_t | ui8LPM | ||
) |
Use CAPT_startConversionAndWaitUntilDone to kickoff a conversion that has been setup and wait in the specified low power mode until the conversion has completed, at which time the peripheral will be cleaned up.
ui8LPM | is the low power mode to enter during the conversion |
void CAPT_initSensor | ( | tSensor * | pSensor | ) |
Initialize Sensor
Clear all status flags in the sensor and elements.
pSensor | is a pointer to a generic sensor type |
Referenced by CAPT_initUI().
void CAPT_updateSensor | ( | tSensor * | pSensor, |
uint8_t | ui8LPM | ||
) |
Refresh all data for the specified sensor
This function samples the sensor and processes the data, upating all of the sensor and element values with the current data. Upon completion of the update, the sensor callback function will be called, if it exists.
pSensor | is a pointer to the sensor to update |
ui8LPM | is the low power mode to enter during conversions |
void CAPT_updateSensorRawCount | ( | tSensor * | pSensor, |
tRawConversionStyle | conversion, | ||
tOversamplingStyle | oversampling, | ||
uint8_t | ui8LPM | ||
) |
Update raw count values for a sensor.
This function samples the sensor, but only updates the raw count values for each element- no processing is performed on the data, and the sensor callback function is NOT called upon completion of the update.
pSensor | is a pointer to the sensor to update |
conversion | specifies the conversion style to use. Valid options include:
|
oversampling | specifies the oversampling to use. Valid options include:
|
ui8LPM | is the low power mode to enter during conversions. |
void CAPT_startWakeOnProxMode | ( | tSensor * | pSensor, |
uint8_t | ui8Cycle, | ||
uint16_t | ui16WakeupInterval | ||
) |
Use CAPT_startWakeOnProxMode to configure the peripheral for wake-on-proximity mode. The cycle/sensor selected will be measured autonomously with no CPU unteraction. The following flags will indicate to the application that action needs to be taken:
pSensor | is a pointer to the sensor to use |
ui8Cycle | indicates the cycle of the sensor to load and use for for wakeup |
ui16WakeupInterval | specifies the wakeup interval to use. Valid options include: |
void CAPT_startWakeOnProxModeWithEMCAuto | ( | tSensor * | pSensor, |
uint8_t | ui8Cycle, | ||
uint16_t | ui16WakeupInterval | ||
) |
Only valid on certain devices, please consult device-specific datasheet. Use CAPT_startWakeOnProxModeWithEMCAuto to configure the peripheral for wake-on-proximity mode. The cycle/sensor selected will be measured autonomously with no CPU unteraction. The following flags will indicate to the application that action needs to be taken:
pSensor | is a pointer to the sensor to use |
ui8Cycle | indicates the cycle of the sensor to load and use for for wakeup |
ui16WakeupInterval | specifies the wakeup interval to use. Valid options include:
|
void CAPT_stopWakeOnProxMode | ( | tSensor * | pSensor, |
uint8_t | ui8Cycle | ||
) |
Call CAPT_stopWakeOnProxMode() after calling CAPT_startWakeOnProxMode() to disable wake-on-proximity mode. This function saves the count/LTA data for the loaded cycle, then unloads the cycle from the peripheral.
pSensor | is a pointer to the sensor that is being measured. |
ui8Cycle | indicates the cycle of the sensor being measured. |
void CAPT_stopWakeOnProxModeWithEMCAuto | ( | tSensor * | pSensor, |
uint8_t | ui8Cycle | ||
) |
Only valid on certain devices, please consult device-specific datasheet. Call CAPT_stopWakeOnProxModeWithEMCAuto after calling CAPT_startWakeOnProxModeWithEMCAuto to disable wake-on-proximity mode. This function saves the count/LTA data for the loaded cycle, then unloads the cycle from the peripheral.
pSensor | is a pointer to the sensor that is being measured. |
ui8Cycle | indicates the cycle of the sensor being measured. |
Perform processing for a cycle
Here standard processing is performed on the elements of the cycle. This includes the basics of capacitive sensing such as the long-term average, output status bits (prox/touch) and basic filtering.
pSensor | is a pointer to the sensor of the cycle to process |
pCycle | is a pointer to the cycle to process |
void CAPT_processSensor | ( | tSensor * | pSensor | ) |
Perform generic sensor processing
Here different status bits are updated to summarise the status of the sensor
pSensor | is a pointer to the Sensor Implementation to update |
bool CAPT_testForRecalibration | ( | tSensor * | pSensor | ) |
Sensor Recalibration Management Function - LTA Drift Check
The LTA of each element of the sensor is monitored here, and if any of them drift out of range of the intended calibration values, the function returns true, flagging the application layer that the sensor should be re-calibrated as it has drifted out of range. Currently the drift is fixed at 1/8th of the conversion count.
pSensor | is a pointer to the sensor to test. |
bool CAPT_testForMaxCountRecalibration | ( | tSensor * | pSensor | ) |
Sensor Recalibration Management Function - Max Count Bounds Check
The max count parameter of the sensor is tested here, and if it is set and the runtime re-calibration parameter is set, this function returns true and clears the max count error for the sensor.
pSensor | is a pointer to the sensor to test. |
bool CAPT_testForNegativeTouchRecalibration | ( | tSensor * | pSensor | ) |
Sensor Recalibration Management Function - Negative Touch Check
The negative touch parameter of the sensor is tested here, and if it is set and the runtime re-calibration parameter is set, this function returns true.
pSensor | is a pointer to the sensor to test. |
void CAPT_flagAllElementsForReseed | ( | tSensor * | pSensor | ) |
Flag All Elements for Reseed
Use CAPT_flagAllElementsForReseed() to set the reseed bit for all elements within a sensor.
pSensor | is a pointer to the sensor to process |
void CAPT_updateSensorTimeout | ( | tSensor * | pSensor | ) |
Sensor Timeout algorithm
Update the sensor timeout counter, then test if the timeout threshold has been reached. In that case reseed all the sensor LTAs and clear status bits
pSensor | is a pointer to the Sensor Implementation to update |
void CAPT_updateSensorNoise | ( | tSensor * | pSensor | ) |
Sensor Noise Algorithm
Update the noise status flag of the sensor based on the status of it's elements.
pSensor | is a pointer to the sensor to update. |
uint8_t CAPT_convertAbsToRel | ( | uint16_t | ui16Ref, |
uint16_t | ui16Abs | ||
) |
This function converts a absolute parameter to a relative parameter. This can be thought of as a percentage operation, but a value of 128 is equivalent to 100%. The maximum supported output is 255, or just under 200%.
ui16Ref | is the reference value. |
ui16Abs | is the value to convert with respect to the reference. |
uint16_t CAPT_convertRelToAbs | ( | uint16_t | ui16Ref, |
uint8_t | ui8Rel | ||
) |
This function converts a relative parameter to an absolute parameter. This can be thought of as reverse a percentage operation, but a value of 128 is equivalent to 100%. The relative value passed must be between 0 and 128.
ui16Ref | is the reference value. |
ui8Rel | is the value to convert. with respect to the reference. |
uint64_t CAPT_getElementStateBitField | ( | tSensor * | pSensor, |
tElementStatusType | status | ||
) |
Get a bit field of the requested state of all elements in the sensor.
This function may be called by the application to obtain a bit field containing the requested state of each element within the sensor. The bit field supports up to 64 elements. Elements are mapped to bit positions starting with the first element of the first cycle to the last element of the last cycle. For example, a sensor with two cycles and two elements in each cycle would have the following mapping: Return value bit 0 (0x01): Cycle 0 Element 0 Return value bit 1 (0x02): Cycle 0 Element 1 Return value bit 2 (0x04): Cycle 1 Element 0 Return value bit 3 (0x08): Cycle 1 Element 1
pSensor | is a pointer to the sensor from which to generate the mask |
status | is the element status flag of which to create a field. Valid options are:
|
Register a user's callback function with each sensor
This provides a method for the user to be notified of a sensor "event" such as touch, prox, etc.
The default callback is TL_GenericCallback() if user fails to register their own.
pSensor | = pointer to the Sensor |
user_callback | = pointer to user's callback function |
The default callback for sensor processing is CAPT_processTrackPadSensor() User can override by registering their own callback their own.
pSensor | = pointer to the Trackpad sensor processing |
user_callback | = pointer to user's callback function |
Referenced by CAPT_initUI().
The default callback for gesture processing is CAPT_processTrackPadGesture() User can override by registering their own callback
pFunction | = pointer to the Gesture processing function |
Referenced by CAPT_initUI().
void CAPT_clearSensorProxTouch | ( | tSensor * | pSensor | ) |
Clear all Prox, Touch and NegativeTouch status bits relating to a specific sensor. Here different status bits are cleared in the sensor, and in its elements.
pSensor | is a pointer to the Sensor Implementation to update |
IIR Filter function
A common filter used for capacitive sensing. This filter implements a beta that is a value/255 and processing more than the IIRFilterFast() function. This is usually implemented on properties such as slider/wheel outputs.
pRaw | is a pointer to the new value to enter the filter |
pFiltered | is a pointer to the stored filter value |
ui8Beta | is a fraction of 255 that determines the IIR filter Beta |
IIR Filter (fast) function
A common filter used for capacitive sensing. This filter is faster to process (since the beta is a bitwise shift, and is usually implemented on properties that are large in quantity, such as LTA's and Count values.
pRaw | is a pointer to the new value to enter the filter |
pFiltered | is a pointer to the stored filter value |
ui8Beta | is a shifter value which determines the IIR filter Beta |
void CAPT_reseedFilterAll | ( | tSensor * | pSensor, |
tFilterOption | WhatToFilter | ||
) |
Reseed a filtered data array for a sensor
Perform a reseed on all of the filtered values for a specific sensor. This could be any filtered data such as Counts or Long-term averages.
pSensor | is a pointer to the sensor to reseed |
WhatToFilter | indicates which value is filtered |
void CAPT_reseedFilter | ( | IQ16_t * | pFilter, |
uint16_t | ui16ReseedValue | ||
) |
Reseed a filtered data value for a single data array entry
Perform a reseed on one of the filtered values. This could be any filtered data such as Counts or Long-term averages.
pFilter | is a pointer to the data that must be reseeded |
ui16ReseedValue | is the reseed value |
Update Prox Status
Depending on the senseMethod implemented, calculate the delta as a positive value when changing in the standard direction for the specific method. Counts increase for projected, and decrease for self capacitive. Then check if this exceeds the selected threshold value.
pSensor | is the sensor pointer |
pElement | is a pointer to the element to process |
Update Touch Status
Using the touch threshold, an actual threshold point is calculated for the specific element, and the count value is compared to that threshold. Clearly Projected must be above this threshold, and self capacitive below
pSensor | is the sensor pointer |
pElement | is a pointer to the element to process touch on |
Update LTA filter for specific element based upon four freq measurements
Update the LTA using the latest obtained Count value for the new cycle of sensed data.
pSensor | is the sensor pointer |
pElement | is a pointer to the element which LTA must be updated |
Update Prox Status
Update the prox and debounce status.
pSensor | = pointer to sensor |
pElement | = pointer to the element to process |
Update Touch Status
Using the touch threshold, an actual threshold point is calculated for the specific element, and the count value is compared to that threshold. Clearly Projected must be above this threshold, and self capacitive below
pSensor | is the sensor pointer |
pElement | is a pointer to the element to process touch on |
void CAPT_updateSensorProxTouch | ( | tSensor * | pSensor | ) |
Sensor Global Prox and Touch status update
The global sensor proximity and touch status is updated here. The touch or prox status is set if any of the elements in the sensor have prox or touch states active.
pSensor | is a pointer to the Sensor Implementation to update |
void CAPT_updateSensorWithEMC | ( | tSensor * | pSensor, |
uint8_t | ui8LPM | ||
) |
Update all aspects of a sensor with additional EMC processing applied.
pSensor | is a pointer to the sensor to update |
ui8LPM | is the low power mode to use during conversions |
void CAPT_updateSensorWithEMCAuto | ( | tSensor * | pSensor, |
uint8_t | ui8LPM | ||
) |
Only valid on certain devices, please consult device-specific datasheet. Update all aspects of a sensor with EMC processing applied by FSM.
pSensor | is a pointer to the sensor to update |
ui8LPM | is the low power mode to use during conversions |
Perform processing for a cycle with additional EMC processing applied.
Here standard processing is performed on the elements of the cycle. This includes the basics of capacitive sensing such as the long-term average, output status bits (prox/touch) and basic filtering.
pSensor | is a pointer to the sensor of the cycle to process |
pCycle | is a pointer to the cycle to process |
Use CAPT_updateElementFilteredValuesWithEMC() to update filtered values in the element based on the raw sampled data. Updated values include the filtered count and the filtered noise value.
pSensor | is the parent sensor to pElement. |
pElement | is the element to process. |
Use CAPT_updateSelfElementProxTouchWithEMC() to update the prox/touch status of an element after the filtered count, LTA and noise values have all been updated. This function is for self-capacitance sensors.
pSensor | is the parent sensor to pElement. |
pElement | is the element to process. |
Use CAPT_updateProjElementProxTouchWithEMC() to update the prox/touch status of an element after the filtered count, LTA and noise values have all been updated. This function is for projected-capacitance sensors.
pSensor | is the parent sensor to pElement. |
pElement | is the element to process. |