From 8e88906445d341380fa39f36bd2240060bd5ac24 Mon Sep 17 00:00:00 2001 From: Gunar Schorcht Date: Tue, 9 Nov 2021 19:50:01 +0100 Subject: [PATCH] drivers/ccs811: fix of documentation --- drivers/ccs811/doc.txt | 153 ++++++++++++++++++++++++----------------- 1 file changed, 90 insertions(+), 63 deletions(-) diff --git a/drivers/ccs811/doc.txt b/drivers/ccs811/doc.txt index dd9f42130a..1767e62306 100644 --- a/drivers/ccs811/doc.txt +++ b/drivers/ccs811/doc.txt @@ -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). -## Table of contents +## 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) -## Overview    [[TOC](#toc)] +## Overview {#ccs811_overview} -### About the sensor    [[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. -### Supported Features    [[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` -## Measurement Process    [[TOC](#toc)] +[Back to table of contents](#ccs811_toc) -### Sensor modes    [[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. -## Measurement results    [[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. -## Compensation    [[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); ... -``` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -## Negative Thermal Coefficient Thermistor (NTC)    [[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 */ .... -``` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -## Interrupts    [[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. -### Data ready interrupt    [[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); ... -``` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -### Threshold interrupt    [[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); ... -``` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -## Power Saving    [[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. -## Baseline    [[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. -## Error Handling    [[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. -## Configuration    [[TOC](#toc)] +[Back to table of contents](#ccs811_toc) -### Hardware Configurations    [[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 | +--------+ +--------+ -``` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -### Driver Configuration Parameters    [[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) + */