Interface to the ams CCS811 indoor air quality sensor. More...

#include <nrfcxx/sensor/ccs811.hpp>

Inheritance diagram for nrfcxx::sensor::ccs811:

Data Structures
struct	iface_config_type
	Structure providing the system resources necessary to interact with the CCS811. More...

struct	observation_beacon_type
	Structure that can be broadcast as a beacon to provide observation data. More...

struct	observations_type
	Captured results after an observation. More...

struct	persisted_state_type
	State that should be persisted in non-volatile memory using the utility::Persist infrastructure. More...

struct	retained_state_type
	Structure holding retained state of the sensor. More...

class	scoped_enabler
	Class obtained from scoped_enable(). More...

struct	system_beacon_type
	Structure that can be broadcast as a beacon to provide detailed system state. More...

struct	threshold_s
	Thresholds for detecting significant changes in readings. More...

struct	version_s
	Aggregate identity and version from hardware and firmware registers. More...

Public Types
enum	STATUS_e : uint16_t { ST_ERROR = 0x01, ST_DATA_READY = 0x08, ST_APP_VALID = 0x10, ST_APP_VERIFY = 0x20, ST_APP_ERASE = 0x40, ST_FW_MODE = 0x80, EI_WRITE_REG_INVALID = 0x0100, EI_READ_REG_INVALID = 0x0200, EI_MEASMODE_INVALID = 0x0400, EI_MAX_RESISTANCE = 0x0800, EI_HEATER_FAULT = 0x1000, EI_HEATER_SUPPLY = 0x2000 }

enum	DRIVE_MODE_e : uint8_t { DM_IDLE = 0, DM_1_s = 1, DM_10_s = 2, DM_60_s = 3 }
	Allowed drive modes for the `MEAS_MODE` register. More...

using	status_type = uint16_t
	Value for a valid CCS811 status. More...

Public Member Functions
const iface_config_type &	iface_config () const
	Access the interface configuration for the sensor.

int	update_persisted (persisted_state_type &ps) const
	Update a persisted state with information from retained state. More...

int	restore_from_persisted (const persisted_state_type &ps)
	Update the retained state with information from persisted state. More...

	ccs811 (notifier_type setter, iface_config_type &ifc, bool addr_sec=false)
	Instantiate the device. More...

periph::TWI &	twi () const
	Directly access the TWI peripheral used to communicate with the device.

bool	intn_asserted () const
	Programmatic test for whether `INTn` is asserted.

scoped_enabler	scoped_enable () const
	Construct and return an RAII object that supports TWI interaction. More...

int	reset () const
	Toggle the RESETn line to reset the sensor. More...

int	id_version (version_s &vid) const
	Read the device hardware and firmware identity and version. More...

const version_s &	id_version () const
	Access the version state managed by the LPM machine.

const observations_type &	observations () const
	Access the most recent collected observations.

int	fill_system_beacon (system_beacon_type &fr) const
	Set the contents of a system beacon frame. More...

observation_beacon_type	observation_beacon () const
	Populate and return an observation beacon structure from the current state. More...

const lpm::state_machine &	machine () const
	Gain read-only access to the LPM machine state.

int	status () const
	Read the `STATUS` and, if necessary, `ERROR_ID` registers. More...

int	env_data (uint32_t enc)
	Set the environment data structure. More...

uint32_t	env_data () const
	Read the last written environment data setting. More...

int	baseline () const
	Read the current baseline value. More...

int	baseline (uint16_t value) const
	Update the baseline value. More...

int	retain_baseline ()
	Record the current baseline in retained state. More...

int	active_drive_mode () const
	Read the drive mode from the active state. More...

int	drive_mode () const
	Read the configured drive mode.

int	drive_mode (unsigned int dm)
	Set the drive mode. More...

unsigned int	i2c_address () const
	Access the I2C address used for the device.

Public Member Functions inherited from nrfcxx::lpm::lpsm_capable
virtual int	lpsm_start ()
	Validate and prepare to initiate an LPM collection. More...

virtual int	lpsm_sample ()
	Ask the LPM infrastructure to initiate a new sample. More...

lpm::state_machine::process_flags_type	lpsm_process ()
	Make progress on an LPM collection. More...

int	lpsm_stop ()

int	lpsm_reset ()

int	lpsm_process_rc () const
	Get the internal result code from the last invocation of lpsm_process_(). More...

const lpm::state_machine &	machine () const
	Gain read-only access to the LPM machine state.

Static Public Member Functions
static const retained_state_type &	retained_state ()
	Access the retained state.

static void	state_setup (const systemState::state_type &ss, bool is_reset, bool retained)
	Function to maintain CCS811 state across resets. More...

static uint32_t	encode_env (int16_t temp_cCel, uint16_t rh_pptt)
	Convert temperature and humidity to CCS811 `ENV_DATA` format. More...

Static Public Attributes
static constexpr unsigned int	APP_START_DELAY_utt = clock::uptime::from_ms(1U)
	Value for maximum t_APP_START in uptime ticks.

static constexpr unsigned int	WAKE_DELAY_us = 50U
	Value for maximum t_WAKE in microseconds.

static constexpr unsigned int	COLD_START_DELAY_utt = clock::uptime::from_ms(20U)
	Value for maximum t_START after power-on in uptime ticks.

static constexpr unsigned int	WARM_START_DELAY_utt = clock::uptime::from_ms(2U)
	Value for maximum t_START after reset in uptime ticks.

static constexpr unsigned int	DWAKE_DELAY_us = 20U
	Value for minimum t_DWAKE in microseconds.

static constexpr unsigned int	DRESET_DELAY_us = 20U
	Value for minimum t_DRESET in microseconds.

static constexpr unsigned int	RESET_DELAY_us = 15U
	Value for minimum t_RESET in microseconds.

static constexpr unsigned int	CONDITIONING_DELAY_utt = 20U * 60U * clock::uptime::Frequency_Hz
	Duration of the conditioning period, in uptime ticks. More...

static constexpr unsigned int	BASELINE_CAPTURE_INTERVAL_utt = 24U * 60U * 60U * clock::uptime::Frequency_Hz
	Duration between retention of the `BASELINE` register.

static constexpr uint8_t	HARDWARE_ID = 0x81
	The value expected to be read back in version_s::hw_id.

static constexpr auto	PF_REPORTING = lpm::state_machine::PF_APP_BASE << 0
	Bit set in non-negative lpsm_process() result when the sensor has started providing observations. More...

static constexpr auto	PF_RESTORED = lpm::state_machine::PF_APP_BASE << 1
	Bit set in non-negative lpsm_process() result when the machine updated the CCS811 baseline from retained state. More...

static constexpr auto	PF_CONDITIONED = lpm::state_machine::PF_APP_BASE << 2
	Bit set in non-negative lpsm_process() result when the sensor has completed its conditioning period.

static constexpr auto	PF_BASELINED = lpm::state_machine::PF_APP_BASE << 3
	Bit set in non-negative lpsm_process() result when the machine saved the `BASELINE` register to retained state. More...

static constexpr auto	PF_CCS811_ERROR = lpm::state_machine::PF_APP_BASE << 4
	Bit set in non-negative lpsm_process() result when a new observation identifies a CCS811 error in observations_type::status.

static constexpr auto	DEFAULT_DRIVE_MODE = DM_10_s
	Default value for drive_mode()

Additional Inherited Members
Protected Types inherited from nrfcxx::lpm::lpsm_capable
using	state_type = state_machine::state_type

using	process_flags_type = state_machine::process_flags_type

Protected Member Functions inherited from nrfcxx::lpm::lpsm_capable
	lpsm_capable (notifier_type notify)
	Create a state machine that records state and supports delayed transitions. More...

virtual int	lpsm_process_ (int &delay, process_flags_type &pf)
	Override to implement machine-specific operations of lpsm_process(). More...

virtual void	lpsm_reset_ ()
	Override to reset state that is held outside the machine.

Protected Attributes inherited from nrfcxx::lpm::lpsm_capable
state_machine	machine_

Detailed Description

Interface to the ams CCS811 indoor air quality sensor.

Note

This device assumes that it can stretch the I2C clock, and it does so. The 200 us timeout that suffices for most I2C sensors used in nrfcxx is insufficient and will result in aborted transactions if separate register operations are initiated too close together. The I2C specification does not limit the duration of a stretched clock (SMBus specifies 35 ms), and the CCS811 data sheet does not provide a maximum stretch. 500 us TWI timeout appears to be adequate.

The application infrastructure support described in GPIOTE::irq_handler must be provided when using ccs811, and the following put in the main routine after the ccs811 instance has been constructed:

NVIC_EnableIRQ(GPIOTE_IRQn);
periph::GPIOTE::enable_sense();

lpm::lpsm_capable::lpsm_process() for this sensor returns the following flags in addition to the diagnostic flags:

Member Typedef Documentation

◆ status_type

using nrfcxx::sensor::ccs811::status_type = uint16_t

Value for a valid CCS811 status.

The low byte corresponds to a value from the STATUS register. If ST_ERROR is cleared, the upper byte is zero, otherwise it is the value of the ERROR_ID register.

Member Enumeration Documentation

◆ DRIVE_MODE_e

enum nrfcxx::sensor::ccs811::DRIVE_MODE_e : uint8_t

Allowed drive modes for the MEAS_MODE register.

Enumerator
DM_IDLE	Idle mode, no measurements will be produced.
DM_1_s	Constant power, measurements every second.
DM_10_s	Pulse mode, measurements every 10 seconds.
DM_60_s	Low-pulse model, measurements every 60 seconds.

◆ STATUS_e

enum nrfcxx::sensor::ccs811::STATUS_e : uint16_t

Enumerator
ST_ERROR	If set the sensor or I2C bus has produced an error. Consult the upper byte of status() for the cause.
ST_DATA_READY	If set new data is available in the ALG_RESULT_DATA register.
ST_APP_VALID	If set a valid application image is available in the sensor.
ST_APP_VERIFY	(Boot mode only) Set indicates that a verify operation succeeded.
ST_APP_ERASE	(Boot mode only) Set indicates that an erase operation succeeded.
ST_FW_MODE	Clear indicates device is in boot mode; set indicates device is in application mode.
EI_WRITE_REG_INVALID	If set an I2C write was attempted to an unwritable register.
EI_READ_REG_INVALID	If set an I2C read was attempted from an unreadable register.
EI_MEASMODE_INVALID	If set an I2C write to `MEAS_MODE` provided an unacceptable value.
EI_MAX_RESISTANCE	If set a the sensor has reached the maximum range.
EI_HEATER_FAULT	If set the heater supply current is out of range.
EI_HEATER_SUPPLY	If set the heater supply voltage is not correct.

Constructor & Destructor Documentation

◆ ccs811()

nrfcxx::sensor::ccs811::ccs811	(	notifier_type	setter,
		iface_config_type &	ifc,
		bool	addr_sec = `false`
	)

Instantiate the device.

Parameters

setter	the mechanism by which the LPM machine notifies the application that it needs to be serviced.
ifc	reference to an externally owned struct providing the resources required to communicate with the device.
addr_sec	true indicates that the secondary I2C address should be used instead of the primary I2C address.

Member Function Documentation

◆ active_drive_mode()

int nrfcxx::sensor::ccs811::active_drive_mode ( ) const

Read the drive mode from the active state.

This need not match the value from drive_mode() if the sensor is not active.

Returns: a value from DRIVE_MODE_e extracted from retained_state_type::meas_mode (matching the MEAS_MODE register), or a negative error code if the sensor is not active.

◆ baseline() [1/2]

int nrfcxx::sensor::ccs811::baseline ( ) const

Read the current baseline value.

Returns: the non-negative value of the baseline register, or a negative error code.

◆ baseline() [2/2]

int nrfcxx::sensor::ccs811::baseline ( uint16_t value ) const

Update the baseline value.

Note: After setting this the read-back value appears to be unchanged from the previous setting, whether written after readings start being produced (about 30 s), or after the conditioning period completes (20 min).

◆ drive_mode()

int nrfcxx::sensor::ccs811::drive_mode ( unsigned int dm )

Set the drive mode.

Parameters

dm	a valid value from DRIVE_MODE_e. All other values are rejected.

Returns: the previous drive mode on success, or a negative error code.

◆ encode_env()

static uint32_t nrfcxx::sensor::ccs811::encode_env	(	int16_t	temp_cCel,
		uint16_t	rh_pptt
	)

static

Convert temperature and humidity to CCS811 ENV_DATA format.

Note: The encoded values are rounded to the nearest half-unit since the CCS811 firmware ignores any finer variation. See threshold_s::env_data_changed() for change detection support.

Parameters

temp_cCel	a temperature reading in centi-Celsius.
rh_pptt	a relative humidity reading, in RH * 100.

Returns: a uint32_t that, when written to the ENV_DATA register records the corresponding environment values.

◆ env_data() [1/2]

uint32_t nrfcxx::sensor::ccs811::env_data ( ) const

inline

Read the last written environment data setting.

Note: This comes from the driver, as the register cannot be read from the CCS811. A value with all 1s set indicates that the driver has not set the register.

Returns: as specified.

◆ env_data() [2/2]

int nrfcxx::sensor::ccs811::env_data ( uint32_t enc )

Set the environment data structure.

Parameters

enc	the temperature and humidity encoded by encode_env().

Returns: non-negative on success, or a negative error code.

◆ fill_system_beacon()

int nrfcxx::sensor::ccs811::fill_system_beacon ( system_beacon_type & fr ) const

Set the contents of a system beacon frame.

Parameters

[out] fr where the frame information should be stored.

Returns: zero on success, or a negative error code.

◆ id_version()

int nrfcxx::sensor::ccs811::id_version ( version_s & vid ) const

Read the device hardware and firmware identity and version.

Parameters

[out] vid where the version information will be stored.

Returns: non-negative on success, or a negative error code.

◆ observation_beacon()

observation_beacon_type nrfcxx::sensor::ccs811::observation_beacon ( ) const

Populate and return an observation beacon structure from the current state.

Note: It is the caller's responsibility to ensure that the state of the observation is valid by revewing the content of observation_beacon_type::status.

◆ reset()

int nrfcxx::sensor::ccs811::reset ( ) const

Toggle the RESETn line to reset the sensor.

Returns: a non-negative value is the delay before the the sensor may be accessed, in uptime ticks. A negative value indicates failure to reset.

◆ restore_from_persisted()

int nrfcxx::sensor::ccs811::restore_from_persisted ( const persisted_state_type & ps )

Update the retained state with information from persisted state.

If ps has a non-zero baseline for the drive mode configured in retained_state_type::meas_mode and retained_state_type::FL_BASELINED is not currently set then retained_state_type::baseline is set from the persisted state and retained_state_type::FL_BASELINED is set.

This function should be invoked on receipt of lpm::state_machine::PF_STARTED so that when PF_CONDITIONED occurs the LPM machine will restore the BASELINE register in the CCS811.

Parameters

ps	the persisted state that may contain a relevant baseline.

Returns: zero on successful update, or a negative error code.

◆ retain_baseline()

int nrfcxx::sensor::ccs811::retain_baseline ( )

Record the current baseline in retained state.

This may be invoked under external control to capture the baseline when it is known the sensor is in clean air.

The invocation fails if the CCS811 has not completed the conditioning period, or does not have an observation from which the baseline can be taken.

Returns: a non-negative baseline on success, or a negative error code.

See also: update_persisted()

◆ scoped_enable()

scoped_enabler nrfcxx::sensor::ccs811::scoped_enable ( ) const

inline

Construct and return an RAII object that supports TWI interaction.

Use this within a scope to assert WAKEn and enable the associated TWI peripheral.

Success of the enable can be assessed from scoped_enabler::result() or treating the enabler as a bool:

if (auto enabler = sensor.scoped_enable()) {
  // invoke methods that interact with sensor
  rc = twi...;
} else {
  // handle interface failure
  rc = enabler.result();
}

Note: Public methods on this class always ensure TWI operations occur within an enabled scope.

◆ state_setup()

static void nrfcxx::sensor::ccs811::state_setup	(	const systemState::state_type &	ss,
		bool	is_reset,
		bool	retained
	)

static

Function to maintain CCS811 state across resets.

This must be invoked from the application's systemState app_handler to ensure telemetry state is properly managed.

◆ status()

int nrfcxx::sensor::ccs811::status ( ) const

Read the STATUS and, if necessary, ERROR_ID registers.

If successful, the low 8 bits of the return value correspond to the value of the STATUS register. If ST_ERROR is set then bits 8..15 of the returned value have the corresponding ERROR_ID register value.

Note: reading ERROR_ID clears that register, so pay attention to the ST_ERROR bit on what you get back: this is the only chance you'll have to see it.

Returns: a non-negative value as documented for status_type, or a negative error code.

◆ update_persisted()

int nrfcxx::sensor::ccs811::update_persisted ( persisted_state_type & ps ) const

Update a persisted state with information from retained state.

If retained_state_type::FL_BASELINED is set then the baseline for the current mode is copied into the appropriate section of ps.

Note: This should be invoked by the application whenever PF_BASELINED is produced, or when save_baseline() is executed under application control. It is the application's responsibility to persist the updated structure.

Parameters

ps	where the persisted state should be stored.

Returns: zero on successful update, or a negative error code.

Field Documentation

◆ CONDITIONING_DELAY_utt

constexpr unsigned int nrfcxx::sensor::ccs811::CONDITIONING_DELAY_utt = 20U * 60U * clock::uptime::Frequency_Hz

staticconstexpr

Duration of the conditioning period, in uptime ticks.

This is the period after initial power-up or measurement start during which the sensor is warming up. The BASELINE register should not be written until after this period elapses.

See AN370: Baseline Save and Restore.

◆ PF_BASELINED

constexpr auto nrfcxx::sensor::ccs811::PF_BASELINED = lpm::state_machine::PF_APP_BASE << 3

staticconstexpr

Bit set in non-negative lpsm_process() result when the machine saved the BASELINE register to retained state.

On receipt of this applications should use update_persisted() to update the non-volatile persisted state in case the volatile retained state is lost due to a power-cycle or uncontrolled reset.

◆ PF_REPORTING

constexpr auto nrfcxx::sensor::ccs811::PF_REPORTING = lpm::state_machine::PF_APP_BASE << 0

staticconstexpr

Bit set in non-negative lpsm_process() result when the sensor has started providing observations.

This is set coincident with the first occurrence of lpm::state_machine::PF_OBSERVATION where STATUS_e::ST_DATA_READY is set.

◆ PF_RESTORED

constexpr auto nrfcxx::sensor::ccs811::PF_RESTORED = lpm::state_machine::PF_APP_BASE << 1

staticconstexpr

Bit set in non-negative lpsm_process() result when the machine updated the CCS811 baseline from retained state.

This will occur in conjunction with PF_CONDITIONED when a baseline is available.

The documentation for this class was generated from the following file:

nrfcxx/sensor/ccs811.hpp

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ status_type

Member Enumeration Documentation

◆ DRIVE_MODE_e

◆ STATUS_e

Constructor & Destructor Documentation

◆ ccs811()

Member Function Documentation

◆ active_drive_mode()

◆ baseline() [1/2]

◆ baseline() [2/2]

◆ drive_mode()

◆ encode_env()

◆ env_data() [1/2]

◆ env_data() [2/2]

◆ fill_system_beacon()

◆ id_version()

◆ observation_beacon()

◆ reset()

◆ restore_from_persisted()

◆ retain_baseline()

◆ scoped_enable()

◆ state_setup()

◆ status()

◆ update_persisted()

Field Documentation

◆ CONDITIONING_DELAY_utt

◆ PF_BASELINED

◆ PF_REPORTING

◆ PF_RESTORED