Device Driver for AMS CCS 811 digital gas sensor for monitoring Indoor Air Quality (IAQ) More...
Device Driver for AMS CCS 811 digital gas sensor for monitoring Indoor Air Quality (IAQ)
The driver is for the usage with RIOT-OS.
The CCS811 is an ultra-low power digital sensor which detects Volatile Organic Compounds (VOC) for Indoor Air Quality (IAQ) monitoring that. The sensor allows to
ccs811module which provides only basic functionality and the
ccs811_fullmodule with additional functionality.
ccs811_full module includes the
ccs811 module automatically. If code size is critical, the
ccs811 module can be used, otherwise using the
ccs811_full module is recommended.
The driver supports the following features when modules
ccs811_full are used.
|read raw and converted gas sensor data (eCO2, TVOC)|
|poling for new sensor gas data|
|power saving using sleep mode with wakeup|
|data ready and threshold interrupt handling|
|ambient temperature calculation with NTC|
|compensate gas readings using an external sensor|
|manual baseline handling|
After power up, the sensor starts automatically in Idle, Low Current Mode (CCS811_MODE_IDLE). To start periodic measurements, the mode of the sensor has to be changed to any measurement mode. Measurement modes with different output data rates are available:
|Mode||Driver symbol||Period||RAW data||IAQ values|
|Idle, Low Current Mode||CCS811_MODE_IDLE||-||-||-|
|Constant Power Mode||CCS811_MODE_1S||1 s||X||X|
|Pulse Heating Mode||CCS811_MODE_10S||10 s||X||X|
|Low Power Pulse Heating Mode||CCS811_MODE_60S||60 s||X||X|
|Constant Power Mode||CCS811_MODE_250MS||250 ms||X||-|
In Constant Power Mode with measurements every 250 ms (CCS811_MODE_250MS) only raw data are available. In all other measurement modes, the Indoor Air Quality (IAQ) values are available additionally. The Constant Power Mode with measurements every 250 ms (CCS811_MODE_250MS) is only intended for systems where an external host system wants to run an algorithm with raw data.
When default configuration parameters from ccs811_params.h are used, the CCS811_MODE_1S measurement mode is used automatically. The application can change the measurement mode either
Once the measurement mode is set, the user task can use function ccs811_read_iaq to fetch the results. The function returns raw data as well as Indoor Air Quality (IAQ) values. If some of the results are not needed, the corresponding parameters can be set to
While raw data represents simply the current through the sensor and the voltage across the sensor with the selected current, IAQ values are the results of the processing of these raw data by the sensor. IAQ values consist of the equivalent CO2 (eCO2) with a range from 400 ppm to 8192 ppm and Total Volatile Organic Compound (TVOC) with a range from 0 ppb to 1187 ppb.
If the ccs811_read_iaq function is called and no new data are available, the function returns the results of the last valid measurement and error code CCS811_ERROR_NO_NEW_DATA.
There are two approaches to wait until new data are available:
When using data-ready interrupts, the default configuration parameter for the interrupt pin can be overridden by defining CCS811_PARAM_INT_PIN before ccs811_params.h is included.
If information about the environment like temperature and humidity are available from another sensor, they can be used by CCS811 to compensate gas readings due to temperature and humidity changes.
Function ccs811_set_environmental_data can be used to set these environmental data. In the following example, the Sensirion SHT3x humidity and temperature sensor is used to fetch environmental data.
CCS811 supports an external interface for connecting a negative thermal coefficient thermistor (R_NTC) to provide a cost effective and power efficient means of calculating the local ambient temperature.
The sensor measures the voltage V_NTC across R_NTC as well as the voltage V_REF across a connected reference resistor (R_REF). Function ccs811_read_ntc can be used at any time to fetch the current resistance of R_NTC. It uses the resistance of R_REF and measured voltages V_REF and V_NTV with the following equation to determine R_NTC:
Using the data sheet of the NTC, the ambient temperature can be calculated. See application note AMS AN000372 for more details. For example, with Adafruit CCS811 Air Quality Sensor Breakout the ambient temperature can be determined as following:
CCS811 supports two types of interrupts that can be used to fetch data:
At the end of each measurement cycle (every 250 ms, 1 second, 10 seconds, or 60 seconds), CCS811 can optionally trigger an interrupt. The signal nINT** is driven low as soon as new sensor values are ready to read. It will stop being driven low when sensor data are read with function ccs811_read_iaq.
The interrupt is disabled by default. It can be enabled using function ccs811_set_int_mode.
The user task can choose that the data ready interrupt is not generated every time when new sensor values become ready but only if the eCO2 value moves from the current range (LOW, MEDIUM, or HIGH) into another range by more than a hysteresis value. Hysteresis is used to prevent multiple interrupts close to a threshold.
The interrupt is disabled by default and can be enabled with function ccs811_set_int_mode. The ranges are defined by the ccs811_set_eco2_thresholds function and its parameters
high as following:
|LOW||below the ||> 400||1500|
|MEDIUM||between the |
|HIGH||above the value of the ||< 8192||2500|
The CCS811 offers a sleep mode with wake-up function. By using the active low nWAKE signal connected to a GPIO, power can be saved. If the nWAKE** signal is low, the CCS811 is active and can communicate over I2C. When this signal is high, the CCS811 goes into sleep mode and can't be reached via I2C. The measuring process is not affected.
The driver supports this feature when the nWAKE signal pin (ccs811_params_t::wake_pin) is configured, see the Configuration section.
Additionally, CCS811 can be disabled with the ccs811_power_down function function, when no measurements are required. For that purpose, the sensor is switched to the idle, low current mode (CCS811_MODE_IDLE). To reactivate the CCS811 in the previous measurement mode, the ccs811_power_up function has to be used.
CCS81 supports automatic baseline correction over a minimum time of 24 hours. Using function ccs811_get_baseline, the current baseline value can be saved before the sensor is powered down. This baseline can then be restored with function ccs811_set_baseline after sensor is powered up again to continue the automatic baseline process.
All driver functions return an error code (ccs811_error_codes_t) to indicate whether its execution was successful or an error happened.
The following figure shows the most simple hardware configuration with CCS811. With this configuration interrupts, the hardware reset, and the sleep mode of the sensor with wake-up feature can't be used. The signals nINT** and nRESET are not connected. The nWAKE signal is permanently pulled low, leaving the CCS811 and I2C constantly active.
If the interrupt signal nINT is used to fetch new data (only with
ccs811_full module), the interrupt pin has to be connected to a GPIO pin.
To use the hardware reset and/or the sleep mode with wake-up feature, additional GPIOs have to be used. This is the most energy-efficient hardware configuration of the sensor but requires more GPIO pins. Used GPIOs must be configured accordingly in driver configuration parameters.
If CCS811 sensor is used in conjunction with another sensor, e.g., a SHT3x sensor, the hardware configuration looks like following:
The following configuration parameters can be used to configure the sensor during its initialization (ccs811_init):
|I2C slave address||ccs811_params_t::i2c_addr||CCS811_PARAM_I2C_ADDR||CCS811_I2C_ADDRESS_1|
|Interrupt pin||ccs811_params_t::int_pin||CCS811_PARAM_INT_PIN||GPIO_PIN(0, 0)|
The default configuration of these parameters can be overridden by defining according macros before including ccs811_params.h, for example:
Alternatively, the complete set of default configuration parameters could also be overridden by a single definition, for example:
|Default configuration for AMS CCS811 digital gas sensors. |
|Register definitions for the AMS CCS811 digital gas sensor. |
|Device Driver for AMS CCS811 digital gas sensor. |