CSLIB Capacitive Sensing Library
Description
Capacitive sensing firmware library for Silicon Labs MCUs.
Introduction
The capacitive sensing library provides pre-compiled code set that performs touch qualification, filtering, and state maintanence for capacitive sensing-enabled Silicon Laboratories MCUs.
The library functions using calls into a device layer that interfaces with hardware peripherals.
Data Structures |
|
union | SI_UU32 |
Union used to address upper bytes of 32-bit exponential average easily.
|
|
struct | SensorStruct_t |
Stores all runtime values for an enabled capacitive sensor.
|
|
Functions |
|
uint8_t | CSLIB_anySensorSingleActive (void) |
Checks to see if any enabled sensor is single active.
|
|
uint8_t | CSLIB_isSensorSingleActive (uint8_t index) |
Checks if a sensor is single active.
|
|
uint8_t | CSLIB_anySensorDebounceActive (void) |
Checks to see if any enabled sensor is debounce active.
|
|
uint8_t | CSLIB_isSensorDebounceActive (uint8_t index) |
Checks if a sensor is debounce active.
|
|
void | CSLIB_nodePushRaw (uint8_t index, uint32_t newValue) |
Pushes new sensor sample into sensor node buffer.
|
|
uint16_t | CSLIB_nodeGetRaw (uint8_t sensorIndex, uint8_t bufferIndex) |
Reads a node structure sensor's raw buffer value.
|
|
int16_t | CSLIB_getUnpackedTouchDelta (uint8_t index) |
Read touch delta from sensor node struct and expand from 8-bit value.
|
|
void | CSLIB_resetSensorStruct (uint8_t sensorIndex, uint16_t fillValue) |
Resets an element of the sensor node struct back to defaults.
|
|
void | CSLIB_initHardware (void) |
Initializes capacitive sensing-related peripherals.
|
|
void | CSLIB_initLibrary (void) |
Initializes capacitive sensing state variables.
|
|
void | CSLIB_update (void) |
Scans capacitive sensing inputs, processes and updates state variables.
|
|
uint32_t | CSLIB_scanSensorCB (uint8_t index) |
Performs capacitive sensing conversion on a sensor.
|
|
void | CSLIB_lowPowerUpdate (void) |
Checks timing and possibly enters low power mode.
|
|
void | CSLIB_lowPowerUpdateCheckAppBuilder (void) |
Checks timing and possibly enters low power mode.
|
|
void | CSLIB_lowPowerUpdateExitAppBuilder (void) |
Exits low power state for CSLIB.
|
|
uint16_t | CSLIB_getNoiseAdjustedSensorData (uint8_t index) |
Returns raw or filtered sensor data, based on characterized interference.
|
|
uint16_t | CSLIB_getNormalizedDelta (uint8_t sensor_index, uint16_t flood_level) |
Get baseline-adjusted, noise-adjusted touch delta.
|
|
void | CSLIB_configureSensorForSleepModeCB (void) |
Callback to configure sensors for sleep mode.
|
|
void | CSLIB_configureSensorForActiveModeCB (void) |
Callback to confiure sensors for active mode.
|
|
void | CSLIB_configureTimerForSleepModeCB (void) |
Configure timer for sleep mode.
|
|
void | CSLIB_configureTimerForActiveModeCB (void) |
Callback to configure timer for active mode scanning.
|
|
void | CSLIB_enterLowPowerStateCB (void) |
Callback to enter low power mode.
|
|
void | CSLIB_checkTimerCB (void) |
Check wake sources.
|
|
void | CSLIB_baselineInitEnableCB (void) |
Modify capacitive sense config for baseline initialization.
|
|
void | CSLIB_baselineInitDisableCB (void) |
Restore capacitive sensing config to operational state.
|
|
Macros |
|
#define | DEF_SENSOR_BUFFER_SIZE 2 |
Defines the depth of the raw buffer. Note: this value should not be changed.
|
|
#define | DEBOUNCE_ACTIVE_MASK 0x80 |
Bit that is set when sensor is qualified active.
|
|
#define | SINGLE_ACTIVE_MASK 0x40 |
Bit that is set when sensor is candidate active.
|
|
Enumerations |
|
enum |
CSLIB_noiseLevels
{
low = 1, mid = 2, high = 3 } |
Defines all noise characterization states the CSLIB will use for characterization.
|
|
Variables |
|
uint8_t | timerTick |
Global counter incremented by the system timer.
|
|
uint8_t | noise_level |
Stores interference characterization level, 0 being lowest and 3 being highest.
|
|
SensorStruct_t | CSLIB_node [] |
Sensor node data structure.
|
|
uint8_t | disable_sleep_and_stall |
Bit that can be set to disable entrance to sleep, overriding timers.
|
|
uint8_t | CSLIB_numSensors |
Size of the sensor node struct, should only be changed at compile time by editing DEF_NUM_SENSORS.
|
|
uint8_t | CSLIB_sensorBufferSize |
Size of raw data buffers within sensor node struct elements, should not be changed.
|
|
uint8_t | CSLIB_buttonDebounce |
Sets the number of consecutive values above/below threshold before button is qualified/disqualified.
|
|
uint16_t | CSLIB_activeModePeriod |
Sets the scan period in ms for active mode scanning. Defaults to DEF_ACTIVE_MODE_PERIOD.
|
|
uint16_t | CSLIB_systemNoiseAverage |
Describes average interference seen as a percentage of the average touch delta.
|
|
uint16_t | CSLIB_sleepModePeriod |
Sets the scan period in ms for sleep mode scanning. Defaults to DEF_ACTIVE_MODE_PERIOD.
|
|
uint16_t | CSLIB_countsBeforeSleep |
Sets the number of consecutive scans without a single qualified touch before entering sleep mode.
|
|
uint8_t | CSLIB_freeRunSetting |
Configures whether system goes to sleep between scans in active mode.
|
|
uint8_t | CSLIB_sleepModeEnable |
Sets whether the system is allowed to ever use sleep mode scanning.
|
|
const uint8_t | CSLIB_inactiveThreshold [] |
Array storring percentages within touch deltas below which touch release events are qualified.
|
|
const uint8_t | CSLIB_activeThreshold [] |
Array storring percentages within touch deltas below which touch events are qualified.
|
|
const uint8_t | CSLIB_averageTouchDelta [] |
Array of expected conversion output codes between inactive and active sensor states.
|
|
Function Documentation
◆ CSLIB_anySensorSingleActive()
uint8_t CSLIB_anySensorSingleActive | ( | void |
|
) |
Checks to see if any enabled sensor is single active.
This function checks the SINGLE_ACTIVE_MASK in the sensor node structure for all enabled sensors. If any sensor's SINGLE_ACTIVE_MASK is set, meaning that the sensor is a candidate active sensor, the the function returns TRUE. Otherwise it returns FALSE.
- Returns
- 1 if any sensor is active, 0 otherwise
◆ CSLIB_isSensorSingleActive()
uint8_t CSLIB_isSensorSingleActive | ( | uint8_t |
index
|
) |
Checks if a sensor is single active.
- Parameters
-
index
into sensor node element to be checked
This checks to see if any enabled sensor is a candidate active sensor.
- Returns
- 1 if element selected by index is single active, 0 otherwise
◆ CSLIB_anySensorDebounceActive()
uint8_t CSLIB_anySensorDebounceActive | ( | void |
|
) |
Checks to see if any enabled sensor is debounce active.
Checks to see if any enabled sensor is qualified active, meaning that the data from the sensor on this input has risen above the active threshold for a consecutive number of samples equaling at least the value defined by DEF_DEBOUNCE_COUNTS.
- Returns
- 1 if any enabled sensor is debounce active, 0 otherwise
◆ CSLIB_isSensorDebounceActive()
uint8_t CSLIB_isSensorDebounceActive | ( | uint8_t |
index
|
) |
Checks if a sensor is debounce active.
- Parameters
-
index
into sensor node element to be checked
This checks to see if any enabled sensor is a qualified active sensor.
- Returns
- 1 if element selected by index is debounce active, 0 otherwise
◆ CSLIB_nodePushRaw()
void CSLIB_nodePushRaw | ( | uint8_t |
index,
|
uint32_t |
newValue
|
||
) |
Pushes new sensor sample into sensor node buffer.
- Parameters
-
index
index into sensor node array newValue
value to be pushed at index
This function is used by the device layer of code that interfaces with capacitive sensing hardware. When CSLIB_update() calls into the device layer to convert a new sample set using CSLIB_scanSensorCB() , the device layer implementation of CSLIB_scanSensorCB should use this routine to push newly converted samples into the sensor node structure for processing within the library.
◆ CSLIB_nodeGetRaw()
uint16_t CSLIB_nodeGetRaw | ( | uint8_t |
sensorIndex,
|
uint8_t |
bufferIndex
|
||
) |
Reads a node structure sensor's raw buffer value.
- Parameters
-
sensorIndex
The element of the sensor node structure bufferIndex
The element inside the sensor node element's raw data buffer
This function can be used to read values in the raw data buffer at bufferIndex of an enabled sensor specified by sensorIndex.
- Note
- sensorIndex should not exceed the value defined by CSLIB_numSensors
- bufferIndex should not exceed the value defined by CSLIB_sensorBufferSize
- Returns
- the value in the raw data buffer
◆ CSLIB_getUnpackedTouchDelta()
int16_t CSLIB_getUnpackedTouchDelta | ( | uint8_t |
index
|
) |
Read touch delta from sensor node struct and expand from 8-bit value.
- Parameters
-
index
Designates the sensor touch delta to be read
This function returns the 8-bit compressed touch delta as an uncompressed 16 bit value.
- Returns
- 16-bit signed touch delta value of a sensor defined by index
◆ CSLIB_resetSensorStruct()
void CSLIB_resetSensorStruct | ( | uint8_t |
sensorIndex,
|
uint16_t |
fillValue
|
||
) |
Resets an element of the sensor node struct back to defaults.
- Parameters
-
sensorIndex
index of sensor node struct to reset fillValue
value to be used when filling raw data buffer
This function is called during initialization to reset the sensor at node sensorIndex back to back to its power-on state.
◆ CSLIB_initHardware()
void CSLIB_initHardware | ( | void |
|
) |
Initializes capacitive sensing-related peripherals.
This function calls into the library, which in turn calls into the device layer functions initializing the sensing and timing hardware used during capacitive sensing conversions.
◆ CSLIB_initLibrary()
void CSLIB_initLibrary | ( | void |
|
) |
Initializes capacitive sensing state variables.
This function resets all state variables in the sensor node struct and library-internal state variables to default.
◆ CSLIB_update()
void CSLIB_update | ( | void |
|
) |
Scans capacitive sensing inputs, processes and updates state variables.
This function should be called in a firmware project's main() loop. The function will execute a capacitive sensing scan sequence, filter samples, examine samples for qualified touches, and update other state variables.
◆ CSLIB_scanSensorCB()
uint32_t CSLIB_scanSensorCB | ( | uint8_t |
index
|
) |
Performs capacitive sensing conversion on a sensor.
- Parameters
-
index
The sensor to be scanned, corresponds to sensor node struct
This device layer function is called from within library code after CSLIB_update() is called in the main loop. The function is responsible for any configuration of the capacitive sensing block necessary to perform the scan.
- Returns
- the newly converted capacitive sensing output
Performs capacitive sensing conversion on a sensor.
Uses EM1 while waiting for the result from each sensor.
Performs capacitive sensing conversion on a sensor.
Configures CSEN for a single conversion with no DMA. In this implementation, scanSensor is not used during operation because the system uses scan+DMA transfers instead. In this implementation, scanSensor is only called in baseline initialization and so SAR mode is used.
◆ CSLIB_lowPowerUpdate()
void CSLIB_lowPowerUpdate | ( | void |
|
) |
Checks timing and possibly enters low power mode.
This function checks the time in the system relative to active mode scan period timing. It should be called in the firmware project's main() while(1) loop.
If FREE_RUN_SETTING is set to 0, the function will enter low power until the next active mode scan period.
If FREE_RUN_SETTING is set to 1, the function will exit, allowing for another iteration in the main() loop.
If CSLIB_lowPowerUpdate() finds that no qualified touches have been found in a time specified by COUNTS_BEFORE_SLEEP multiplied by ACTIVE_MODE_SCAN_PERIOD, the function initializes the system to run in its sleep scanning mode and enters a low power state.
◆ CSLIB_lowPowerUpdateCheckAppBuilder()
void CSLIB_lowPowerUpdateCheckAppBuilder | ( | void |
|
) |
Checks timing and possibly enters low power mode.
This function checks the time in the system relative to active mode scan period timing.
If CSLIB_lowPowerUpdate() finds that no qualified touches have been found in a time specified by COUNTS_BEFORE_SLEEP multiplied by ACTIVE_MODE_SCAN_PERIOD, the function initializes the system to run in its sleep scanning mode. The calling system stack will intiate low power entry.
◆ CSLIB_lowPowerUpdateExitAppBuilder()
void CSLIB_lowPowerUpdateExitAppBuilder | ( | void |
|
) |
Exits low power state for CSLIB.
This function is called by the interface layer when it detects a threshold crossing interrupt. The function will return to normal CSLIB operation.
◆ CSLIB_getNoiseAdjustedSensorData()
uint16_t CSLIB_getNoiseAdjustedSensorData | ( | uint8_t |
index
|
) |
Returns raw or filtered sensor data, based on characterized interference.
- Parameters
-
index
Sensor node element whose data is to be read
This function either returns the newest raw data for a sensor, or the newest filtered data for a sensor, depending on which data type the interference characterization algorithm determines to be necessary to show current sensor state. In low interference environments, raw data will be returned. In higher interference states, filtered data will be returned.
- Returns
- sensor data from sensor node struct defined index
◆ CSLIB_getNormalizedDelta()
uint16_t CSLIB_getNormalizedDelta | ( | uint8_t |
sensor_index,
|
uint16_t |
flood_level
|
||
) |
Get baseline-adjusted, noise-adjusted touch delta.
- Parameters
-
sensor_index
Index into sensor node struct flood_level
additional value that can be subtracted in addition to baseline
Returns value that is raw or filtered data minus the sensor's baseline. flood_level can be used to remove additional margin along with baseline.
- Returns
- Absolute delta between baseline and raw/filtered data
◆ CSLIB_configureSensorForSleepModeCB()
void CSLIB_configureSensorForSleepModeCB | ( | void |
|
) |
Callback to configure sensors for sleep mode.
Callback routine used if low power mode is included in build, this function configures the capacitive sensing block and inputs for sleep mode.
Callback to configure sensors for sleep mode.
Configures sensor peripheral(s) for sleep mode scanning
◆ CSLIB_configureSensorForActiveModeCB()
void CSLIB_configureSensorForActiveModeCB | ( | void |
|
) |
Callback to confiure sensors for active mode.
Callback routine to configure sensors for active mode scanning.
Callback to confiure sensors for active mode.
This is a top-level call to configure the sensor to its operational state during active mode.
◆ CSLIB_configureTimerForSleepModeCB()
void CSLIB_configureTimerForSleepModeCB | ( | void |
|
) |
Configure timer for sleep mode.
If low power mode is included in build, this function sets the wake-up event to the sleep mode scan period.
This is a top-level call to configure the timer to sleep mode, one of the two defined modes of operation in the system. This instance of the function configures the SmaRTClock to the frequency defined in cslib_config.h.
◆ CSLIB_configureTimerForActiveModeCB()
void CSLIB_configureTimerForActiveModeCB | ( | void |
|
) |
Callback to configure timer for active mode scanning.
Configures the timer to initiate a scan as defined by active mode scan period.
Callback to configure timer for active mode scanning.
This is a top-level call to configure the timer to active mode, one of the two defined modes of operation in the system. This instance of the function configures the SmaRTClock to the frequency defined in cslib_config.h.
◆ CSLIB_enterLowPowerStateCB()
void CSLIB_enterLowPowerStateCB | ( | void |
|
) |
Callback to enter low power mode.
If low power mode is included in build, this function mode-switches the core to a low power state.
Callback to enter low power mode.
Re-enable and get system ready for active mode
◆ CSLIB_checkTimerCB()
void CSLIB_checkTimerCB | ( | void |
|
) |
Check wake sources.
This function examines the system timer to check for wake events.
This callback function examines the system timer to check for wake events.
Check wake sources.
This callback function examines the system timer to check for wake events.
Check wake sources.
◆ CSLIB_baselineInitEnableCB()
void CSLIB_baselineInitEnableCB | ( | void |
|
) |
Modify capacitive sense config for baseline initialization.
Saves configuration state and makes device-level modifications appropriate to baseline initialization using the CSLIB_scanSensorCB() function.
Modify capacitive sense config for baseline initialization.
Called before a baseline for a sensor has been initialized.
Modify capacitive sense config for baseline initialization.
Called before a baseline for a sensor has been initialized. In the case of the CSEN implementation, no configuration is necessary.
◆ CSLIB_baselineInitDisableCB()
void CSLIB_baselineInitDisableCB | ( | void |
|
) |
Restore capacitive sensing config to operational state.
This function reverts any baseline-related capactive sensing config.
Restore capacitive sensing config to operational state.
Called after a baseline for a sensor has been initialized.
Macro Definition Documentation
◆ DEF_SENSOR_BUFFER_SIZE
#define DEF_SENSOR_BUFFER_SIZE 2 |
Defines the depth of the raw buffer. Note: this value should not be changed.
◆ DEBOUNCE_ACTIVE_MASK
#define DEBOUNCE_ACTIVE_MASK 0x80 |
Bit that is set when sensor is qualified active.
◆ SINGLE_ACTIVE_MASK
#define SINGLE_ACTIVE_MASK 0x40 |
Bit that is set when sensor is candidate active.
Enumeration Type Documentation
◆ CSLIB_noiseLevels
enum CSLIB_noiseLevels |
Variable Documentation
◆ timerTick
uint8_t timerTick |
Global counter incremented by the system timer.
◆ noise_level
uint8_t noise_level |
Stores interference characterization level, 0 being lowest and 3 being highest.
◆ CSLIB_node
SensorStruct_t CSLIB_node[] |
Sensor node data structure.
◆ disable_sleep_and_stall
uint8_t disable_sleep_and_stall |
Bit that can be set to disable entrance to sleep, overriding timers.
◆ CSLIB_numSensors
uint8_t CSLIB_numSensors |
Size of the sensor node struct, should only be changed at compile time by editing DEF_NUM_SENSORS.
◆ CSLIB_sensorBufferSize
uint8_t CSLIB_sensorBufferSize |
Size of raw data buffers within sensor node struct elements, should not be changed.
◆ CSLIB_buttonDebounce
uint8_t CSLIB_buttonDebounce |
Sets the number of consecutive values above/below threshold before button is qualified/disqualified.
Defaults to DEF_BUTTON_DEBOUNCE
◆ CSLIB_activeModePeriod
uint16_t CSLIB_activeModePeriod |
Sets the scan period in ms for active mode scanning. Defaults to DEF_ACTIVE_MODE_PERIOD.
◆ CSLIB_systemNoiseAverage
uint16_t CSLIB_systemNoiseAverage |
Describes average interference seen as a percentage of the average touch delta.
100 would mean that average sample to sample interference is equal to the average touch delta configured in the system.
◆ CSLIB_sleepModePeriod
uint16_t CSLIB_sleepModePeriod |
Sets the scan period in ms for sleep mode scanning. Defaults to DEF_ACTIVE_MODE_PERIOD.
◆ CSLIB_countsBeforeSleep
uint16_t CSLIB_countsBeforeSleep |
Sets the number of consecutive scans without a single qualified touch before entering sleep mode.
◆ CSLIB_freeRunSetting
uint8_t CSLIB_freeRunSetting |
Configures whether system goes to sleep between scans in active mode.
1 means that the system is in free run mode and will not go to sleep. 0 means that the system will take a single scan within an active mode scan period and will then enter sleep once CSLIB_lowPowerUpdate() is called. The system will stay asleep until the next active mode scan period begins.
◆ CSLIB_sleepModeEnable
uint8_t CSLIB_sleepModeEnable |
Sets whether the system is allowed to ever use sleep mode scanning.
If set to 0, the system will always remain in active mode. If set to 1, the system is allowed to perform sleep mode scanning when conditions permit it.
◆ CSLIB_inactiveThreshold
const uint8_t CSLIB_inactiveThreshold[] |
Array storring percentages within touch deltas below which touch release events are qualified.
Array storring percentages within touch deltas below which touch release events are qualified.
◆ CSLIB_activeThreshold
const uint8_t CSLIB_activeThreshold[] |
Array storring percentages within touch deltas below which touch events are qualified.
Array storring percentages within touch deltas below which touch events are qualified.
◆ CSLIB_averageTouchDelta
const uint8_t CSLIB_averageTouchDelta[] |
Array of expected conversion output codes between inactive and active sensor states.
Array of expected conversion output codes between inactive and active sensor states.