Crate embedded_ccs811

This is a platform agnostic Rust driver for the CCS811 ultra-low power digital VOC sensor for monitoring indoor air quality (IAQ) using the embedded-hal traits.

This driver allows you to:

• In application mode:
  • Set the measurement mode. See: set_mode().
  • Check if there is new data ready. See: has_data_ready().
  • Get the algoritm and raw result data. See: data().
  • Get the raw data. See: raw_data().
  • Get the current baseline. See: baseline().
  • Set the baseline. See: set_baseline().
  • Set the environment temperature and relative humidity. See: set_environment().
  • Set the interrupt mode. See: set_interrupt_mode().
  • Set the eCO2 thresholds for interrupts. See: set_eco2_thresholds().
• In boot mode:
  • Start application. See: start_application().
  • Reset, erase, download and verify new application. See: update_application().
  • Erase application. See: erase_application().
  • Verify application. See: verify_application().
  • Download application. See: download_application().
• In either mode:
  • Get the firmware mode. See: firmware_mode().
  • Check whether a valid application is loaded. See: has_valid_app().
  • Get the hardware ID. See: hardware_id().
  • Get the hardware version. See: hardware_version().
  • Get the firmware bootloader version. See: firmware_bootloader_version().
  • Get the firmware application version. See: firmware_application_version().
  • Do a software reset. See: software_reset().

The device

The CCS811 is an ultra-low power digital gas sensor solution which integrates a metal oxide (MOX) gas sensor to detect a wide range of Volatile Organic Compounds (VOCs) for indoor air quality monitoring with a microcontroller unit (MCU), which includes an Analog-to-Digital converter (ADC), and an I²C interface.

CCS811 is based on ams unique micro-hotplate technology which enables a highly reliable solution for gas sensors, very fast cycle times and a significant reduction in average power consumption.

The integrated MCU manages the sensor driver modes and measurements. The I²C digital interface significantly simplifies the hardware and software design, enabling a faster time to market.

CCS811 supports intelligent algorithms to process raw sensor measurements to output equivalent total VOC (eTVOC) and equivalent CO2 (eCO2) values, where the main cause of VOCs is from humans.

CCS811 supports multiple measurement modes that have been optimized for low-power consumption during an active sensor measurement and idle mode extending battery life in portable applications.

Documentation:

• Datasheet
• Programming and interfacing guide

Usage examples (see also examples folder)

To use this driver, import this crate and an embedded_hal implementation, then instantiate the appropriate device.

The CCS811 can be placed in sleep and woken up only for communication. This driver provides two structures: Ccs811Awake and Ccs811 depeding on the waking state.

The Ccs811Awake assumes an awake device and handles only the I2C communication. This can be used when the waking up and sleep of the device is handled manually. Additionally a wrapper Ccs811 is provided, which handles waking up the device before each operation and putting it to sleep afterwards.

Please find additional examples using hardware in this repository: driver-examples

Start the application and take measurements

extern crate linux_embedded_hal as hal;
use embedded_ccs811::{prelude::*, Ccs811, SlaveAddr, MeasurementMode};
use nb::block;

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let nwake = hal::Pin::new(17);
let delay = hal::Delay {};
let address = SlaveAddr::default();
let sensor = Ccs811::new(dev, address, nwake, delay);
let mut sensor = sensor.start_application().ok().unwrap();
sensor.set_mode(MeasurementMode::ConstantPower1s).unwrap();
loop {
    let data = block!(sensor.data()).unwrap();
    println!("eCO2: {}, eTVOC: {}", data.eco2, data.etvoc);
}

Save and restore the baseline

extern crate linux_embedded_hal as hal;
use embedded_ccs811::{prelude::*, Ccs811Awake, SlaveAddr};

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let address = SlaveAddr::default();
let sensor = Ccs811Awake::new(dev, address);
let mut sensor = sensor.start_application().ok().unwrap();
let baseline = sensor.baseline().unwrap();
// ...
sensor.set_baseline(baseline).unwrap();

Set the environment temperature and relative humidity

extern crate linux_embedded_hal as hal;
use embedded_ccs811::{prelude::*, Ccs811Awake, SlaveAddr};

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let address = SlaveAddr::default();
let sensor = Ccs811Awake::new(dev, address);
let mut sensor = sensor.start_application().ok().unwrap();
let temp_c = 25.0;
let rel_humidity = 50.0;
sensor.set_environment(rel_humidity, temp_c).unwrap();

Set the eCO2 thresholds and configure interrupts

Only generate an interrupt when the thresholds are crossed.

extern crate linux_embedded_hal as hal;
use embedded_ccs811::{prelude::*, Ccs811Awake, SlaveAddr, InterruptMode, MeasurementMode};

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let address = SlaveAddr::default();
let sensor = Ccs811Awake::new(dev, address);
let mut sensor = sensor.start_application().ok().unwrap();
sensor.set_eco2_thresholds(1500, 2500).unwrap();
sensor.set_interrupt_mode(InterruptMode::OnThresholdCrossed).unwrap();
sensor.set_mode(MeasurementMode::ConstantPower1s).unwrap();

Get hardware and firmware information

extern crate linux_embedded_hal as hal;
use embedded_ccs811::{prelude::*, Ccs811Awake, SlaveAddr};

let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
let address = SlaveAddr::default();
let mut sensor = Ccs811Awake::new(dev, address);
let hw_id = sensor.hardware_id().unwrap();
let hw_ver = sensor.hardware_version().unwrap();
let fw_boot_ver = sensor.firmware_bootloader_version().unwrap();
let fw_app_ver = sensor.firmware_application_version().unwrap();
println!(
    "HW ID: {}, HW version: {:#?}, FW bootloader version: {:#?}, FW app version: {:#?}",
    hw_id, hw_ver, fw_boot_ver, fw_app_ver
);

Modules

mode	Mode marker
prelude	The prelude is a collection of all the traits for the CCS811 in this crate

Structs

AlgorithmResult	Algorithm result
Ccs811	CCS811 device driver
Ccs811Awake	Already awake CCS811 device driver
DeviceErrors	Array of possible errors since multiple sources are possible.
ModeChangeError	Error type for mode changes when using Ccs811.

Enums

DeviceError	Errors reported by the device
Error	All possible errors generated when using the Ccs811 type.
ErrorAwake	All possible errors when using an the Ccs811Awake type.
FirmwareMode	Firmware mode
InterruptMode	Interrupt generation modes.
MeasurementMode	Measurement modes.
SlaveAddr	Possible slave addresses

Traits

Ccs811AppMode	Methods available when on application mode
Ccs811BootMode	Methods available when on boot mode
Ccs811Device	General CCS811 methods available in either mode