ccs811: Driver for AMS CCS811 digital gas sensor

Defines

CCS811_I2C_ADDRESS_1

< CCS811 I2C addresses

default

CCS811_I2C_ADDRESS_2
CCS811_ERR_BASE

CCS811 driver error codes ORed with error codes for I2C the interface.

CCS811_ERR_BOOT_MODE

firmware is in boot mode

CCS811_ERR_NO_APP

no application firmware loaded

CCS811_ERR_NO_NEW_DATA

no new data samples are ready

CCS811_ERR_NO_IAQ_DATA

no new data samples are ready

CCS811_ERR_HW_ID

wrong hardware ID

CCS811_ERR_INV_SENS

invalid sensor ID

CCS811_ERR_WR_REG_INV

invalid register addr on write

CCS811_ERR_RD_REG_INV

invalid register addr on read

CCS811_ERR_MM_INV

invalid measurement mode

CCS811_ERR_MAX_RESIST

max sensor resistance reached

CCS811_ERR_HEAT_FAULT

heater current not in range

CCS811_ERR_HEAT_SUPPLY

heater voltage not correct

CCS811_ERR_WRONG_MODE

wrong measurement mode

CCS811_ERR_RD_STAT_FAILED

read status register failed

CCS811_ERR_RD_DATA_FAILED

read sensor data failed

CCS811_ERR_APP_START_FAIL

sensor app start failure

CCS811_ERR_WRONG_PARAMS

wrong parameters used

CCS_ECO2_RANGE_MIN
CCS_ECO2_RANGE_MAX
CCS_TVOC_RANGE_MIN
CCS_TVOC_RANGE_MAX

Enums

enum ccs811_mode_t

CCS811 operation modes.

Values:

enumerator CCS811_MODE_IDLE

Idle, low current mode.

enumerator CCS811_MODE_1S

Constant Power mode, IAQ values every 1 s.

enumerator CCS811_MODE_10S

Pulse Heating mode, IAQ values every 10 s.

enumerator CCS811_MODE_60S

Low Power Pulse Heating, IAQ values every 60 s.

enumerator CCS811_MODE_250MS

Constant Power mode, RAW data every 250 ms.

Functions

esp_err_t ccs811_init_desc(ccs811_dev_t *dev, uint8_t addr, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)

Initialize device descriptor.

Parameters:

  • dev – Pointer to the sensor device data structure

  • addr – Sensor address

  • port – I2C port number

  • sda_gpio – GPIO pin number for SDA

  • scl_gpio – GPIO pin number for SCL

Returns:

ESP_OK on success

esp_err_t ccs811_free_desc(ccs811_dev_t *dev)

Free device descriptor.

Parameters:

dev – Pointer to the sensor device data structure

Returns:

ESP_OK on success

esp_err_t ccs811_init(ccs811_dev_t *dev)

Initialize a CCS811 sensor.

The function initializes the CCS811 sensor and checks its availability.

Parameters:

dev – Pointer to the sensor device data structure

Returns:

ESP_OK on success

esp_err_t ccs811_set_mode(ccs811_dev_t *dev, ccs811_mode_t mode)

Set the operation mode of the sensor.

The function sets the operating mode of the sensor. If the parameter mode is either CCS811_MODE_1S, CCS811_MODE_10S, CCS811_MODE_60S or CCS811_MODE_250MS, the sensor starts a periodic measurement with the specified period. Function ccs811_get_results() can then be used at the same rate to get the results.

In CCS811_MODE_1S, CCS811_MODE_10S and CCS811_MODE_60S, raw sensor data as well as IAQ values calculated by the sensor values are available. In CCS811_MODE_250MS, only raw data are available.

In case, parameter mode is CCS811_MODE_IDLE, the sensor does not perform any measurements.

Please note: Mode timings are subject to typical 2% tolerance due to accuracy of internal sensor clock.

Please note: After setting the sensor mode, the sensor needs up to 20 minutes, before accurate readings are generated.

Please note: When a sensor operating mode is changed to a new mode with a lower sample rate, e.g., from CCS811_MODE_60S to CCS811_MODE_1S, it should be placed in mode_idle for at least 10 minutes before enabling the new mode.

Parameters:

  • dev – Pointer to the sensor device data structure

  • mode – Operation mode of the sensor

Returns:

ESP_OK on success

esp_err_t ccs811_get_results(ccs811_dev_t *dev, uint16_t *iaq_tvoc, uint16_t *iaq_eco2, uint8_t *raw_i, uint16_t *raw_v)

Get latest IAQ sensor values and/or RAW sensor data.

The function reads the IAQ sensor values (TVOC and eCO2) and/or the raw sensor data. If some of the results are not needed, the corresponding pointer parameters can be set to NULL.

Please note: If the function is called and no new data are available, e.g., due to the sensor mode time tolerance of 2%, the function still returns successfully. In this case, the results of the last measurement are returned and the error code CCS811_ERR_NO_NEW_DATA is set.

Please note: In CCS811_MODE_250MS, only RAW data are available. In that case, the function fails with error_code CCS811_ERR_NO_IAQ_DATA if parameters iaq_tvoc and iaq_eco2 are not NULL.

Parameters:

  • dev – pointer to the sensor device data structure

  • iaq_tvoc – TVOC total volatile organic compound (0 - 1187 ppb)

  • iaq_eco2 – eCO2 equivalent CO2 (400 - 8192 ppm)

  • raw_i – current through the sensor used for measuring (0 - 63 uA)

  • raw_v – voltage across the sensor measured (0 - 1023 = 1.65 V)

Returns:

ESP_OK on success

esp_err_t ccs811_get_ntc_resistance(ccs811_dev_t *dev, uint32_t r_ref, uint32_t *res)

Get the resistance of connected NTC thermistor.

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 the R_NTC as well as the voltage V_REF across a connected reference resistor (R_REF). The function returns the current resistance of R_NTC using the equation 

     R_NTC = R_REF / V_REF * V_NTC
Using the data sheet of the NTC, the ambient temperature can be calculated.

Parameters:

  • dev – pointer to the sensor device data structure

  • r_ref – resistance of R_REF in Ohm

  • res – [out] resistance of R_NTC in Ohm

Returns:

ESP_OK on success

esp_err_t ccs811_set_environmental_data(ccs811_dev_t *dev, float temperature, float humidity)

Set environmental data.

If information about the environment are available from another sensor, they can be used by CCS811 to compensate gas readings due to temperature and humidity changes.

Parameters:

  • dev – pointer to the sensor device data structure

  • temperature – measured temperature in degree Celsius

  • humidity – measured relative humidity in percent

Returns:

ESP_OK on success

esp_err_t ccs811_enable_interrupt(ccs811_dev_t *dev, bool enabled)

Enable or disable data ready interrupt signal nINT

At the end of each measurement cycle (250ms, 1s, 10s, 60s), 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_get_results.

The interrupt is disabled by default.

Parameters:

  • dev – pointer to the sensor device data structure

  • enabled – if true, the interrupt is enabled, or disabled otherwise

Returns:

ESP_OK on success

esp_err_t ccs811_set_eco2_thresholds(ccs811_dev_t *dev, uint16_t low, uint16_t high, uint8_t hysteresis)

Set eCO2 threshold mode for data ready interrupts.

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.

  • LOW below parameter value low

  • MEDIUM between parameter values low and high

  • HIGH above parameter value high is range HIGH.

If all parameters have valid values, the function sets the thresholds and enables the data ready interrupt. Using 0 for all parameters disables the interrupt.

The interrupt is disabled by default.

Parameters:

  • dev – pointer to the sensor device data structure

  • low – threshold LOW to MEDIUM (> 400, default 1500)

  • high – threshold MEDIUM to HIGH (< 8192, default 2500)

  • hysteresis – hysteresis value (default 50)

Returns:

ESP_OK on success

esp_err_t ccs811_get_baseline(ccs811_dev_t *dev, uint16_t *baseline)

Get the current baseline value from sensor.

The sensor supports automatic baseline correction over a minimum time of 24 hours. Using this function, the current baseline value can be saved before the sensor is powered down. This baseline can then be restored after sensor is powered up again to continue the automatic baseline process.

Parameters:

  • dev – pointer to the sensor device data structure

  • baseline – [out] current baseline value on success, or 0 on error

Returns:

ESP_OK on success

esp_err_t ccs811_set_baseline(ccs811_dev_t *dev, uint16_t baseline)

Write a previously stored baseline value to the sensor.

The sensor supports automatic baseline correction over a minimum time of 24 hours. Using this function, a previously saved baseline value be restored after the sensor is powered up to continue the automatic baseline process.

Please note: The baseline must be written after the conditioning period of 20 min after power up.

Parameters:

  • dev – pointer to the sensor device data structure

  • baseline – baseline to be set

Returns:

ESP_OK on success

struct ccs811_dev_t
#include <ccs811.h>

CCS811 sensor device data structure.

Public Members

i2c_dev_t i2c_dev

I2C device handle.

ccs811_mode_t mode

operation mode