EFM32 Happy Gecko Software Documentation
efm32hg-doc-5.1.2
|
Capacitive sensing firmware library for Silicon Labs MCUs and SoCs.
The capacitive sensing library provides pre-compiled code set that performs touch qualification, filtering, and state maintanence for capacitive sensing-enabled Silicon Laboratories MCUs and SoCs.
The library functions using calls into a device layer that interfaces with hardware peripherals.
Data Structures | |
struct | SensorStruct_t |
Stores all runtime values for an enabled capacitive sensor. More... | |
union | SI_UU32 |
Union used to address upper bytes of 32-bit exponential average easily. More... | |
Macros | |
#define | DEBOUNCE_ACTIVE_MASK 0x80 |
Bit that is set when sensor is qualified active. | |
#define | DEF_SENSOR_BUFFER_SIZE 2 |
Defines the depth of the raw buffer. Note: this value should not be changed. | |
#define | SINGLE_ACTIVE_MASK 0x40 |
Bit that is set when sensor is candidate active. | |
Typedefs | |
typedef union SI_UU32 | SI_UU32_t |
Union used to address upper bytes of 32-bit exponential average easily. | |
Functions | |
uint8_t | CSLIB_anySensorDebounceActive (void) |
uint8_t | CSLIB_anySensorSingleActive (void) |
uint16_t | CSLIB_getNoiseAdjustedSensorData (uint8_t index) |
uint16_t | CSLIB_getUnpackedTouchDelta (uint8_t index) |
void | CSLIB_initHardware (void) |
void | CSLIB_initLibrary (void) |
uint8_t | CSLIB_isSensorDebounceActive (uint8_t index) |
uint8_t | CSLIB_isSensorSingleActive (uint8_t index) |
void | CSLIB_lowPowerUpdate (void) |
uint16_t | CSLIB_nodeGetRaw (uint8_t sensorIndex, uint8_t bufferIndex) |
void | CSLIB_nodePushRaw (uint8_t index, uint16_t newValue) |
void | CSLIB_resetSensorStruct (uint8_t sensorIndex, uint16_t fillValue) |
void | CSLIB_update (void) |
uint16_t | scanSensor (uint8_t index) |
Variables | |
uint16_t | CSLIB_activeModePeriod |
Sets the scan period in ms for active mode scanning. Defaults to DEF_ACTIVE_MODE_PERIOD. | |
uint8_t | CSLIB_buttonDebounce |
Sets the number of consecutive values above/below threshold before button is qualified/disqualified. Defaults to DEF_BUTTON_DEBOUNCE. | |
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. 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. | |
SensorStruct_t | CSLIB_node [] |
Sensor node data structure. | |
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_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. | |
uint16_t | CSLIB_sleepModePeriod |
Sets the scan period in ms for sleep mode scanning. Defaults to DEF_ACTIVE_MODE_PERIOD. | |
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. | |
uint8_t | disable_sleep_and_stall |
Bit that can be set to disable entrance to sleep, overriding timers. | |
uint8_t | noise_level |
Stores interference characterization level, 0 being lowest and 3 being highest. | |
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.
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.
uint16_t CSLIB_getNoiseAdjustedSensorData | ( | uint8_t | index | ) |
Returns raw or filtered sensor data, based on characterized interference
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.
uint16_t CSLIB_getUnpackedTouchDelta | ( | uint8_t | index | ) |
Read touch delta from sensor node struct and expand from 8-bit value
index | Designates the sensor touch delta to be read |
This function returns the 8-bit compressed touch delta as an uncompressed 16 bit value.
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.
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.
uint8_t CSLIB_isSensorDebounceActive | ( | uint8_t | index | ) |
Checks if a sensor is debounce active
index | into sensor node element to be checked |
This checks to see if any enabled sensor is a qualified active sensor.
uint8_t CSLIB_isSensorSingleActive | ( | uint8_t | index | ) |
Checks if a sensor is single active
index | into sensor node element to be checked |
This checks to see if any enabled sensor is a candidate active sensor.
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.
uint16_t CSLIB_nodeGetRaw | ( | uint8_t | sensorIndex, |
uint8_t | bufferIndex | ||
) |
Reads a node structure sensor's raw buffer value
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.
void CSLIB_nodePushRaw | ( | uint8_t | index, |
uint16_t | newValue | ||
) |
Pushes new sensor sample into sensor node buffer
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 scanSensor(), the device layer implementation of scanSensor() should use this routine to push newly converted samples into the sensor node structure for processing within the library.
void CSLIB_resetSensorStruct | ( | uint8_t | sensorIndex, |
uint16_t | fillValue | ||
) |
Resets an element of the sensor node struct back to defaults
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.
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.
uint16_t scanSensor | ( | uint8_t | index | ) |
Performs capacitive sensing conversion on a sensor
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.