Device Driver for AMS CCS811 digital gas sensor. More...

Detailed Description

Device Driver for AMS CCS811 digital gas sensor.

Author
Gunar Schorcht gunar.nosp@m.@sch.nosp@m.orcht.nosp@m..net

Definition in file ccs811.h.

#include <stdint.h>
#include "periph/gpio.h"
#include "periph/i2c.h"
+ Include dependency graph for ccs811.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ccs811_params_t
 CCS811 device initialization parameters. More...
 
struct  ccs811_t
 CCS811 sensor device data structure. More...
 

Enumerations

enum  ccs811_error_codes_t {
  CCS811_OK, CCS811_ERROR_I2C, CCS811_ERROR_NO_DEV, CCS811_ERROR_NO_APP,
  CCS811_ERROR_NO_NEW_DATA, CCS811_ERROR_NO_IAQ_DATA, CCS811_ERROR_WRITE_REG_INV, CCS811_ERROR_READ_REG_INV,
  CCS811_ERROR_MEASMODE_INV, CCS811_ERROR_THRESH_INV, CCS811_ERROR_MAX_RESISTANCE, CCS811_ERROR_HEATER_FAULT,
  CCS811_ERROR_HEATER_SUPPLY, CCS811_ERROR_NO_INT_PIN, CCS811_ERROR_NO_WAKE_PIN, CCS811_ERROR_NO_RESET_PIN,
  CCS811_ERROR_NOT_SUPPORTED
}
 Driver error codes (returned as negative values) More...
 
enum  ccs811_mode_t {
  CCS811_MODE_IDLE = 0, CCS811_MODE_1S = 1, CCS811_MODE_10S = 2, CCS811_MODE_60S = 3,
  CCS811_MODE_250MS = 4
}
 CCS811 operation modes. More...
 
enum  ccs811_int_mode_t { CCS811_INT_NONE = 0, CCS811_INT_DATA_READY, CCS811_INT_THRESHOLD }
 CCS811 interrupt mode. More...
 

Functions

int ccs811_init (ccs811_t *dev, const ccs811_params_t *params)
 Initialize a CCS811 sensor device. More...
 
int ccs811_read_iaq (const ccs811_t *dev, uint16_t *iaq_tvoc, uint16_t *iaq_eco2, uint16_t *raw_i, uint16_t *raw_v)
 Read IAQ sensor values and/or RAW sensor data. More...
 
int ccs811_read_ntc (const ccs811_t *dev, uint32_t r_ref, uint32_t *r_ntc)
 Read the resistance of connected NTC thermistor. More...
 
int ccs811_data_ready (const ccs811_t *dev)
 Data-ready status function. More...
 
int ccs811_power_down (ccs811_t *dev)
 Power down the sensor. More...
 
int ccs811_power_up (ccs811_t *dev)
 Power up the sensor. More...
 
int ccs811_set_mode (ccs811_t *dev, ccs811_mode_t mode)
 Set the operation mode of the sensor. More...
 
int ccs811_set_int_mode (ccs811_t *dev, ccs811_int_mode_t mode)
 Enable/disable data ready or threshold interrupt signal nINT More...
 
int ccs811_set_environmental_data (const ccs811_t *dev, int16_t temp, int16_t hum)
 Set environmental data. More...
 
int ccs811_set_eco2_thresholds (const ccs811_t *dev, uint16_t low, uint16_t high, uint8_t hyst)
 Set eCO2 thresholds for threshold interrupts. More...
 
int ccs811_get_baseline (const ccs811_t *dev, uint16_t *baseline)
 Get the current baseline value from sensor. More...
 
int ccs811_set_baseline (const ccs811_t *dev, uint16_t baseline)
 Write a previously stored baseline value to the sensor. More...
 

CCS811 I2C addresses

#define CCS811_I2C_ADDRESS_1   (0x5A)
 default
 
#define CCS811_I2C_ADDRESS_2   (0x5B)
 

CCS811 IAQ value ranges

#define CCS811_ECO2_RANGE_MIN   (400)
 eCO2 min in ppm
 
#define CCS811_ECO2_RANGE_MAX   (8192)
 eCO2 max in ppm
 
#define CCS811_TVOC_RANGE_MIN   (0)
 TVOC min in ppb.
 
#define CCS811_TVOC_RANGE_MAX   (1187)
 TVOC min in ppb.
 

Enumeration Type Documentation

◆ ccs811_error_codes_t

Driver error codes (returned as negative values)

Enumerator
CCS811_OK 

no error

CCS811_ERROR_I2C 

I2C communication failure.

CCS811_ERROR_NO_DEV 

device not available

CCS811_ERROR_NO_APP 

could not start application

CCS811_ERROR_NO_NEW_DATA 

no new data (last valid data returned)

CCS811_ERROR_NO_IAQ_DATA 

IAQ data not available in this mode.

CCS811_ERROR_WRITE_REG_INV 

invalid register address on write

CCS811_ERROR_READ_REG_INV 

invalid register address on read

CCS811_ERROR_MEASMODE_INV 

invalid measurement mode

CCS811_ERROR_THRESH_INV 

invalid threshold parameters

CCS811_ERROR_MAX_RESISTANCE 

maximum sensor resistance exceeded

CCS811_ERROR_HEATER_FAULT 

heater current not in range

CCS811_ERROR_HEATER_SUPPLY 

heater voltage not applied correctly

CCS811_ERROR_NO_INT_PIN 

nINT signal pin not configured

CCS811_ERROR_NO_WAKE_PIN 

nWAKE signal pin not configured

CCS811_ERROR_NO_RESET_PIN 

nRESET signal pin not configured

CCS811_ERROR_NOT_SUPPORTED 

function is not supported

Definition at line 50 of file ccs811.h.

◆ ccs811_int_mode_t

CCS811 interrupt mode.

Enumerator
CCS811_INT_NONE 

interrupt generation is disabled (default)

CCS811_INT_DATA_READY 

nINT signal when new data are reade to read

CCS811_INT_THRESHOLD 

nINT signal when new data reach thresholds

Definition at line 84 of file ccs811.h.

◆ ccs811_mode_t

CCS811 operation modes.

Enumerator
CCS811_MODE_IDLE 

Idle, low current mode.

CCS811_MODE_1S 

Constant Power mode, IAQ values every 1 s.

CCS811_MODE_10S 

Pulse Heating mode, IAQ values every 10 s.

CCS811_MODE_60S 

Low Power Pulse Heating, IAQ values every 60 s.

CCS811_MODE_250MS 

Constant Power mode, only RAW data every 250 ms.

Definition at line 73 of file ccs811.h.

Function Documentation

◆ ccs811_data_ready()

int ccs811_data_ready ( const ccs811_t dev)

Data-ready status function.

The function reads the status register and returns CSS811_OK when new data are available. The function is useful for polling the sensor.

Parameters
[in]devDevice descriptor of CCS811 device to read from
Return values
CCS811_OKwhen new data are available
CCS811_ERROR_NO_NEW_DATAwhen no new data are available
CCS811_ERROR_*otherwise, see ccs811_error_codes_t.

◆ ccs811_get_baseline()

int ccs811_get_baseline ( const ccs811_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 using the ccs811_set_baseline function after sensor is powered up again to continue the automatic baseline process.

Parameters
[in]devDevice descriptor of CCS811 device
[in]baselineCurrent baseline value
Return values
CCS811_OKon success
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_init()

int ccs811_init ( ccs811_t dev,
const ccs811_params_t params 
)

Initialize a CCS811 sensor device.

The function resets the CCS811 sensor, checks its availability and initializes it according to the given configuration parameters.

If ccs811_params_t::reset_pin is configured

  • the pin is used for the hardware reset of the sensor, otherwise only a software reset is tried, and
  • the ccs811_init function can be used at any time to reset the sensor.

If ccs811_params_t::wake_pin is configured, it use to switch the sensor into the sleep mode while the I2C interface is not used.

Parameters
[in]devDevice descriptor of CCS811 device to be initialized
[in]paramsConfiguration parameters used by initialization
Note
The I2C implementation of the MCU has to support clock stretching to get CCS811 working.
Return values
CCS811_OKon success
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_power_down()

int ccs811_power_down ( ccs811_t dev)

Power down the sensor.

The feature disables sensor measurements by entering idle mode (CCS811_MODE_IDLE). In addition, the function sets the low active signal ** nWAKE ** to high to completely deactivate the sensor. The sensor is then no longer accessible via I2C. The last sensor measurement mode is saved.

The low active nWAKE signal pin has to be configured (ccs811_params_t::wake_pin) accordingly. Otherwise, the function fails and returns with CCS811_ERROR_NO_WAKE_PIN.

Parameters
[in]devDevice descriptor of CCS811 device to read from
Return values
CCS811_OKon success
CCS811_ERROR_NO_WAKE_PINccs811_params_t::wake_pin not configured
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_power_up()

int ccs811_power_up ( ccs811_t dev)

Power up the sensor.

The function sets the low active signal ** nWAKE ** to low to activate the sensor and switches back from the idle mode (CCS811_MODE_IDLE) to the last measurement mode.

The low active nWAKE signal pin has to be configured (ccs811_params_t::wake_pin) accordingly. Otherwise, the function fails and returns with CCS811_ERROR_NO_WAKE_PIN.

Note
It may take several minutes before accurate readings are generated when the sensor switches back from idle mode to the previous measurement mode.
Parameters
[in]devDevice descriptor of CCS811 device to read from
Return values
CCS811_OKon success
CCS811_ERROR_NO_WAKE_PINccs811_params_t::wake_pin not configured
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_read_iaq()

int ccs811_read_iaq ( const ccs811_t dev,
uint16_t *  iaq_tvoc,
uint16_t *  iaq_eco2,
uint16_t *  raw_i,
uint16_t *  raw_v 
)

Read IAQ sensor values and/or RAW sensor data.

The function reads the IAQ sensor values (TVOC and eCO2) and/or the raw sensor data. For either iaq_tvoc2, iaq_eco2, raw_i, or raw_v also NULL can be passed, if their value are not of interest.

Note
Parameters
[in]devDevice descriptor of CCS811 device to read from
[out]iaq_tvocTVOC total volatile organic compound (0..1187 ppb)
[out]iaq_eco2eCO2 equivalent CO2 (400 - 8192 ppm)
[out]raw_iCurrent through the sensor used for measuring (0..63 uA)
[out]raw_vVoltage across the sensor measured (0..1023 = 1.65 V)
Return values
CCS811_OKon success and new data are returned
CCS811_ERROR_NO_NEW_DATAwhen no new data are available and last measurement results are returned.
CCS811_ERROR_*otherwise, see ccs811_error_codes_t.

◆ ccs811_read_ntc()

int ccs811_read_ntc ( const ccs811_t dev,
uint32_t  r_ref,
uint32_t *  r_ntc 
)

Read 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
[in]devDevice descriptor of CCS811 device to read from
[in]r_refResistance of R_REF in Ohm
[out]r_ntcResistance of R_NTC in Ohm
Return values
CCS811_OKon success
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_set_baseline()

int ccs811_set_baseline ( const ccs811_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 (ccs811_get_baseline) value can be restored after the sensor is powered up to continue the automatic baseline process.

Note
The baseline must be written after the conditioning period of 20 min after power up.
Parameters
[in]devDevice descriptor of CCS811 device
[in]baselineStored baseline value
Return values
CCS811_OKon success
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_set_eco2_thresholds()

int ccs811_set_eco2_thresholds ( const ccs811_t dev,
uint16_t  low,
uint16_t  high,
uint8_t  hyst 
)

Set eCO2 thresholds for threshold interrupts.

Threshold interrupts, if enabled (ccs811_int_mode_t), are generated when new eCO2 value moves from the current range (LOW, MEDIUM or HIGH) to another range by more than one hysteresis value. The hysteresis is used to prevent multiple interrupts near a threshold.

Ranges are defined as following:

Name Range Value Default
LOW below the low parameter > 400 1500
MEDIUM between the low and high parameters
HIGH above the value of the high parameter < 8192 2500
Parameters
[in]devDevice descriptor of CCS811 device
[in]lowThreshold LOW to MEDIUM
[in]highThreshold MEDIUM to HIGH
[in]hystHysteresis value (default 50)
Return values
CCS811_OKon success
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_set_environmental_data()

int ccs811_set_environmental_data ( const ccs811_t dev,
int16_t  temp,
int16_t  hum 
)

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
[in]devDevice descriptor of CCS811 device
[in]tempTemperature [hundredths of a degree Celsius]
[in]humRelative Humidity [hundredths of a percent]
Return values
CCS811_OKon success
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_set_int_mode()

int ccs811_set_int_mode ( ccs811_t dev,
ccs811_int_mode_t  mode 
)

Enable/disable data ready or threshold interrupt signal nINT

CCS811 can trigger either

As soon as an interrupt condition occurs, the signal nINT is driven low. It stops being driven low when the sensor data is read with the ccs811_read_iaq function. ccs811_params_t::int_pin parameter has to be configured.

With CCS811_INT_NONE (the default), interrupt generation is disabled. The interrupt generation is disabled by default.

Parameters
[in]devDevice descriptor of CCS811 device
[in]modeEnable the interrupt if true, otherwise disable it
Return values
CCS811_OKon success
CCS811_ERROR_NO_INT_PINccs811_params_t::int_pin not configured
CCS811_ERROR_*on error, see ccs811_error_codes_t

◆ ccs811_set_mode()

int ccs811_set_mode ( ccs811_t dev,
ccs811_mode_t  mode 
)

Set the operation mode of the sensor.

The function sets the operating mode of the sensor.

The sensor starts periodic measurements with the specified period if the mode parameter is either

The ccs811_read_iaq function can then be used to get sensor data at the same rate to get the results.

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

Note
  • In CCS811_MODE_250MS, only raw data are available. IAQ values would have to be calculated by the host in this mode.
  • Mode timings (the period) are subject to typical 2% tolerance due to accuracy of internal sensor clock.
  • After setting the sensor mode, the sensor needs up to 20 minutes, before accurate readings are generated.
  • When the 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 CCS811_MODE_IDLE for at least 10 minutes before enabling the new mode.
Parameters
[in]devDevice descriptor of CCS811 device
[in]modeCCS811 operation mode
Return values
CCS811_OKon success
CCS811_ERROR_*on error, see ccs811_error_codes_t