RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity

drivers/ccs811: fix of documentation

Browse Source
This commit is contained in:
Gunar Schorcht 2021-11-09 19:50:01 +01:00
parent 70744a7a92
commit 8e88906445
1 changed files with 90 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
drivers/ccs811/doc.txt
View File

@ -5,33 +5,33 @@
@brief Device Driver for AMS CCS 811 digital gas sensor for monitoring
Indoor Air Quality (IAQ)
# Driver for the ams CCS811 digital gas sensor for monitoring indoor air quality.
\section ccs811 CCS811 digital gas sensor for monitoring indoor air quality
The driver is for the usage with [RIOT-OS](https://github.com/RIOT-OS/RIOT).
## <a name="toc"> Table of contents </a>
## Table of contents {#ccs811_toc}
1. [Overview](#overview)
1. [About the sensor](#about)
2. [Supported features](#supported)
2. [Measurement Process](#measurement_process)
1. [Sensor modes](#sensor_modes)
2. [Measurement results](#measurement_results)
3. [Compensation](#compensation)
4. [Negative Thermal Coefficient Thermistor (NTC)](#ntc)
5. [Interrupts](#interrupts)
1. [Data ready interrupt](#data_ready_interrupt)
2. [Threshold interrupt](#threshold interrupt)
6. [Power Saving](#power saving)
7. [Baseline](#baseline)
8. [Error Handling](#error_handling)
19. [Configuration](#configuration)
1. [Hardware Configurations](#hardware_configuration)
2. [Driver Configuration Parameters](#driver_configuration)
1. [Overview](#ccs811_overview)
1. [About the sensor](#ccs811_about)
2. [Supported features](#ccs811_supported)
2. [Measurement Process](#ccs811_measurement_process)
1. [Sensor modes](#ccs811_sensor_modes)
2. [Measurement results](#ccs811_measurement_results)
3. [Compensation](#ccs811_compensation)
4. [Negative Thermal Coefficient Thermistor (NTC)](#ccs811_ntc)
5. [Interrupts](#ccs811_interrupts)
1. [Data ready interrupt](#ccs811_data_ready_interrupt)
2. [Threshold interrupt](#ccs811_threshold_interrupt)
6. [Power Saving](#ccs811_power_saving)
7. [Baseline](#ccs811_baseline)
8. [Error Handling](#ccs811_error_handling)
19. [Configuration](#ccs811_configuration)
1. [Hardware Configurations](#ccs811_hardware_configuration)
2. [Driver Configuration Parameters](#ccs811_driver_configuration)
## <a name="overview"> Overview </a> &nbsp;&nbsp; [[TOC](#toc)]
## Overview {#ccs811_overview}
### <a name="about"> About the sensor </a> &nbsp;&nbsp; [[TOC](#toc)]
### About the sensor {#ccs811_about}
The CCS811 is an ultra-low power digital sensor which detects **Volatile
Organic Compounds (VOC)** for **Indoor Air Quality (IAQ)** monitoring that.
@ -52,7 +52,9 @@ The sensor allows to
The I2C implementation of the MCU has to support clock stretching
to get CCS811 working.
### <a name="supported"> Supported Features </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
### Supported Features {#ccs811_supported}
@note There are two driver module versions, the `ccs811` module
which provides only basic functionality and the `ccs811_full`
@ -75,9 +77,11 @@ ambient temperature calculation with NTC | `ccs811_full`
compensate gas readings using an external sensor | `ccs811_full`
manual baseline handling | `ccs811_full`
## <a name="measurement_process"> Measurement Process </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
### <a name="sensor_modes"> Sensor modes </a> &nbsp;&nbsp; [[TOC](#toc)]
## Measurement Process {#ccs811_measurement_process}
### Sensor modes {#ccs811_sensor_modes}
After power up, the sensor starts automatically in *Idle, Low Current
Mode* (#CCS811_MODE_IDLE). To start periodic measurements, the mode of
@ -125,7 +129,9 @@ application can change the measurement mode either
- by using the #ccs811_set_mode function, or
- by defining **CCS811_PARAM_MODE** before **ccs811_params.h** is included.
## <a name="measurement_results"> Measurement results </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
## Measurement results {#ccs811_measurement_results}
Once the measurement mode is set, the user task can use function
#ccs811_read_iaq to fetch the results. The function returns **raw data**
@ -139,7 +145,7 @@ 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.
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
uint16_t iaq_tvoc;
uint16_t iaq_eco2;
uint16_t raw_i;
@ -153,7 +159,7 @@ else {
... /* error handling */
}
...
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the #ccs811_read_iaq function is called and no new data are
available, the function returns the results of the last valid
@ -164,7 +170,7 @@ There are two approaches to wait until new data are available:
- data-ready interrupt (#CCS811_INT_DATA_READY)
- data-ready status function (#ccs811_data_ready)
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
uint16_t iaq_tvoc;
uint16_t iaq_eco2;
uint16_t raw_i;
@ -177,12 +183,12 @@ if (ccs811_data_ready (&sensor) == CCS811_OK &&
...
}
...
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
## <a name="compensation"> Compensation </a> &nbsp;&nbsp; [[TOC](#toc)]
## Compensation {#ccs811_compensation}
If information about the environment like temperature and humidity are
available from another sensor, they can be used by CCS811 to compensate
@ -194,7 +200,7 @@ 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.
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
int16_t temperature; /* in hundredths of a degree Celsius */
int16_t humidity; /* in hundredths of a percent */
...
@ -202,9 +208,11 @@ if (sht3x_get_results (sht3x, &temperature, &humidity))
/* set CCS811 environmental data with values fetched from SHT3x */
ccs811_set_environmental_data (ccs811, temperature, humidity);
...
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## <a name="ntc"> Negative Thermal Coefficient Thermistor (NTC) </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
## Negative Thermal Coefficient Thermistor (NTC) {#ccs811_ntc}
CCS811 supports an external interface for connecting a negative thermal
coefficient thermistor (R_NTC) to provide a cost effective and power
@ -218,9 +226,9 @@ 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:
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
R_NTC = R_REF / V_REF * V_NTC
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using the data sheet of the NTC, the ambient temperature can be
calculated. See application note AMS AN000372 for more details.
@ -228,7 +236,7 @@ For example, with
[Adafruit CCS811 Air Quality Sensor Breakout](https://www.adafruit.com/product/3566)
the ambient temperature can be determined as following:
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
...
#define CCS811_R_REF 100000 /* resistance of the reference resistor */
#define CCS811_R_NTC 10000 /* resistance of NTC at a reference temperature */
@ -247,9 +255,11 @@ ntc_temp += 1.0 / (CCS811_R_NTC_TEMP + 273.15); /* 3 */
ntc_temp = 1.0 / ntc_temp; /* 4 */
ntc_temp -= 273.15; /* 5 */
....
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## <a name="interrupts"> Interrupts </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
## Interrupts {#ccs811_interrupts}
CCS811 supports two types of interrupts that can be used to fetch data:
@ -260,7 +270,9 @@ CCS811 supports two types of interrupts that can be used to fetch data:
- Interrupts can only be used with the `ccs811_full` module.
- It is not possible to use both interrupts at the same time.
### <a name="data_ready_interrupt"> Data ready interrupt </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
### Data ready interrupt {#ccs811_data_ready_interrupt}
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
@ -271,14 +283,16 @@ It will stop being driven low when sensor data are read with function
The interrupt is disabled by default. It can be enabled using function
#ccs811_set_int_mode.
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
...
/* enable the data ready interrupt */
ccs811_set_int_mode (&sensor, CCS811_INT_DATA_READY);
...
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### <a name="threshold interrupt"> Threshold interrupt </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
### Threshold interrupt {#ccs811_threshold_interrupt}
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
@ -297,15 +311,17 @@ LOW | below the \p low parameter | > 400 | 1500
MEDIUM | between the \p low and \p high parameters | | |
HIGH | above the value of the \p high parameter | < 8192 | 2500
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
...
/* set threshold parameters and enable threshold interrupt mode */
ccs811_set_eco2_thresholds (&sensor, 600, 1100, 40);
ccs811_set_int_mode (&sensor, CCS811_INT_THRESHOLD);
...
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## <a name="power saving"> Power Saving </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
## Power Saving {#ccs811_power_saving}
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
@ -315,7 +331,7 @@ 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](#Configuration) section.
[Configuration](#ccs811_configuration) section.
@note If the **nWAKE** signal pin is not used, it must be permanently pulled
down. Sleep mode/wake-up feature can not be used in this case.
@ -333,7 +349,9 @@ Therefore, the best power-saving solution is to leave the sensor in any
measurement mode and to use it with data-ready interrupt
(#CCS811_INT_DATA_READY) in conjunction with the **nWAKE** signal pin.
## <a name="baseline"> Baseline </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
## Baseline {#ccs811_baseline}
CCS81 supports automatic baseline correction over a minimum time of
24 hours. Using function #ccs811_get_baseline, the current baseline
@ -343,14 +361,18 @@ is powered up again to continue the automatic baseline process.
@note This feature can only be used with the `ccs811_full` module.
## <a name="error_handling"> Error Handling </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
## Error Handling {#ccs811_error_handling}
All driver functions return an error code (#ccs811_error_codes_t) to
indicate whether its execution was successful or an error happened.
## <a name="configuration"> Configuration </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
### <a name="hardware_configuration"> Hardware Configurations </a> &nbsp;&nbsp; [[TOC](#toc)]
## Configuration {#ccs811_configuration}
### Hardware Configurations {#ccs811_hardware_configuration}
The following figure shows the most simple hardware configuration with CCS811.
With this configuration interrupts, the hardware reset, and the sleep
@ -358,7 +380,7 @@ 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.
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------+ +--------+
| MCU | | CCS811 |
| | | |
@ -366,12 +388,12 @@ permanently pulled low, leaving the CCS811 and I2C constantly active.
| SDA <-------> SDA |
| GND --------> /WAKE |
+--------+ +--------+
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------+ +--------+
| MCU | | CCS811 |
| | | |
@ -380,7 +402,7 @@ the interrupt pin has to be connected to a GPIO pin.
| GPIO <-------> /INT |
| GND --------> /WAKE |
+--------+ +--------+
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
@ -388,7 +410,7 @@ hardware configuration of the sensor but requires more GPIO pins.
Used GPIOs must be configured accordingly in driver [configuration
parameters](#ccs811_driver_configuration).
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------+ +--------+
| MCU | | CCS811 |
| | | |
@ -398,12 +420,12 @@ parameters](#ccs811_driver_configuration).
| GPIOy --------> /WAKE |
| GPIOz --------> /RESET |
+--------+ +--------+
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If CCS811 sensor is used in conjunction with another sensor, e.g.,
a SHT3x sensor, the hardware configuration looks like following:
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------+ +--------+
| MCU | | CCS811 |
| | | |
@ -416,9 +438,11 @@ a SHT3x sensor, the hardware configuration looks like following:
| | +----> SCL |
| | +--> SDA |
+--------+ +--------+
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
### <a name="driver_configuration"> Driver Configuration Parameters </a> &nbsp;&nbsp; [[TOC](#toc)]
[Back to table of contents](#ccs811_toc)
### Driver Configuration Parameters {#ccs811_driver_configuration}
The following configuration parameters can be used to configure the
sensor during its initialization (#ccs811_init):
@ -435,7 +459,7 @@ Reset pin | ccs811_params_t::reset_pin | CCS811_PARAM_RESET_PIN | #GPIO_
The default configuration of these parameters can be overridden by
defining according macros before including **ccs811_params.h**, for example:
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
#define CCS811_PARAM_I2C_DEV (I2C_DEV(1))
#define CCS811_PARAM_I2C_ADDR (CCS811_I2C_ADDRESS_2)
#define CCS811_PARAM_MODE (CCS811_MODE_10S)
@ -446,11 +470,11 @@ defining according macros before including **ccs811_params.h**, for example:
...
#include "ccs811.h"
#include "ccs811_params.h"
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternatively, the complete set of default configuration parameters could
also be overridden by a single definition, for example:
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
#define CCS811_PARAMS { .i2c_dev = I2C, \
.i2c_addr = CCS811_I2C_ADDRESS_2, \
.mode = CCS811_MODE_10S, \
@ -459,5 +483,8 @@ also be overridden by a single definition, for example:
.int_pin = GPIO_PIN(0, 2), \
.int_mode = CCS811_INT_DATA_READY, \
}
```
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[Back to table of contents](#ccs811_toc)
*/