ccs811.hpp

Go to the documentation of this file.

/* SPDX-License-Identifier: Apache-2.0 */
/* Copyright 2017-2019 Peter A. Bigot */
 
#ifndef NRFCXX_SENSOR_CCS811_HPP
#define NRFCXX_SENSOR_CCS811_HPP
#pragma once
 
#include <climits>
 
#include <nrfcxx/gpio.hpp>
#include <nrfcxx/lpm.hpp>
 
namespace nrfcxx {
namespace sensor {
 
class ccs811 : public lpm::lpsm_capable
{
  using super = lpm::lpsm_capable;
 
  // One-shot not available for this sensor.
  using super::lpsm_sample;
 
public:
  static constexpr unsigned int APP_START_DELAY_utt = clock::uptime::from_ms(1U);
 
  static constexpr unsigned int WAKE_DELAY_us = 50U;
 
  static constexpr unsigned int COLD_START_DELAY_utt = clock::uptime::from_ms(20U);
 
  static constexpr unsigned int WARM_START_DELAY_utt = clock::uptime::from_ms(2U);
 
  static constexpr unsigned int DWAKE_DELAY_us = 20U;
 
  static constexpr unsigned int DRESET_DELAY_us = 20U;
 
  static constexpr unsigned int RESET_DELAY_us = 15U;
 
  static constexpr unsigned int CONDITIONING_DELAY_utt = 20U * 60U * clock::uptime::Frequency_Hz;
 
  static constexpr unsigned int BASELINE_CAPTURE_INTERVAL_utt = 24U * 60U * 60U * clock::uptime::Frequency_Hz;
 
  struct iface_config_type
  {
    periph::TWI& twi;
 
    gpio::generic_pin& waken;
 
    gpio::generic_pin& resetn;
 
    int8_t intn_psel;
 
    iface_config_type (const iface_config_type&) = delete;
    iface_config_type& operator= (const iface_config_type&) = delete;
    iface_config_type (iface_config_type&&) = delete;
    iface_config_type& operator= (iface_config_type&&) = delete;
  };
 
  const iface_config_type& iface_config () const
  {
    return iface_config_;
  }
 
  struct retained_state_type
  {
    using flags_type = uint8_t;
 
    uint64_t reset_utt;
 
    uint64_t baselined_utt;
 
    uint16_t baseline;
 
    enum flags_enum : flags_type
    {
      FL_REPORTING = 0x01,
 
      FL_CONDITIONED = 0x02,
 
      FL_BASELINED = 0x04,
 
      FL_DRIVE_MODE_Pos = 6U,
 
      FL_DRIVE_MODE_Msk = (0x03 << FL_DRIVE_MODE_Pos),
    };
 
    uint8_t flags;
  };
 
  struct persisted_state_type
  {
    uint16_t baseline[4];
  };
 
  int update_persisted (persisted_state_type& ps) const;
 
  int restore_from_persisted (const persisted_state_type& ps);
 
  static const retained_state_type& retained_state ()
  {
    return retained_state_;
  }
 
  static void state_setup (const systemState::state_type& ss,
                           bool is_reset,
                           bool retained);
 
  ccs811 (notifier_type setter,
          iface_config_type& ifc,
          bool addr_sec = false);
 
  periph::TWI& twi () const
  {
    return iface_config_.twi;
  }
 
  class scoped_enabler
  {
    // ccs811 needs access to construct these things.
    friend class ccs811;
 
    static constexpr uint8_t FL_ENABLE_TWI = 0x01;
 
    static constexpr uint8_t FL_ASSERT_WAKEn = 0x02;
 
    scoped_enabler (periph::TWI& twi,
                    const gpio::active_low& waken) :
      twi{twi},
      waken{waken},
      flags((twi.enabled() ? 0U : FL_ENABLE_TWI)
            | (waken.asserted() ? 0U : FL_ASSERT_WAKEn))
    {
      if (FL_ENABLE_TWI & flags) {
        result_ = twi.enable();
        if (0 <= result_) {
          result_ = 1;
        }
      }
      // Only assert WAKEn if we don't know that twi enable failed.
      if ((0 <= result_)
          && (FL_ASSERT_WAKEn & flags)) {
        assert();
      }
    }
 
    periph::TWI& twi;
    const gpio::active_low& waken;
    int result_ = 0;
    const uint8_t flags;
 
  public:
    ~scoped_enabler ()
    {
      if (FL_ASSERT_WAKEn & flags) {
        deassert();
      }
      if (FL_ENABLE_TWI & flags) {
        twi.disable();
      }
    }
 
    operator bool () const
    {
      return 0 <= result_;
    }
 
    int result () const
    {
      return result_;
    }
 
    void assert ()
    {
      waken.assert();
      delay_us(WAKE_DELAY_us);
    }
 
    void deassert ()
    {
      waken.deassert();
      delay_us(DWAKE_DELAY_us);
    }
  };
 
  bool intn_asserted () const
  {
    if (0 > intn_psel_) {
      return false;
    }
    return !((1U << intn_psel_) & nrf5::GPIO->IN);
  }
 
  scoped_enabler scoped_enable () const
  {
    return {twi(), waken_};
  }
 
  static constexpr uint8_t HARDWARE_ID = 0x81;
 
  struct version_s
  {
    uint16_t fw_boot_version;
 
    uint16_t fw_app_version;
 
    uint8_t hw_id;
 
    uint8_t hw_version;
  };
 
  int reset () const;
 
  using status_type = uint16_t;
 
  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,
  };
 
  struct observations_type
  {
    uint16_t baseline;
 
    uint16_t eCO2;
 
    uint16_t eTVOC;
 
    status_type status;
 
    bool is_ready () const
    {
      return (ST_DATA_READY & status);
    }
 
    uint16_t raw;
  };
 
  int id_version (version_s& vid) const;
 
  const version_s& id_version() const
  {
    return version_;
  }
 
  const observations_type& observations () const
  {
    return observations_;
  }
 
  struct system_beacon_type
  {
    uint32_t active_ds = 0;
 
    uint32_t bl_age_ds = 0;
 
    uint16_t bl_retained = 0;
 
    uint16_t bl_latest = 0;
 
    uint16_t app_version = 0;
 
    uint8_t hw_version = 0;
 
    uint8_t flags = 0;
 
    static constexpr size_t SPAN = 4+4+2+2+2+1+1;
  };
 
  int fill_system_beacon (system_beacon_type& fr) const;
 
  struct observation_beacon_type
  {
    uint32_t env_data = -1;
 
    uint16_t baseline = 0;
 
    uint16_t eCO2 = 0;
 
    uint16_t eTVOC = 0;
 
    static constexpr size_t SPAN = 4+2+2+2;
 
    int16_t status;
  };
 
  observation_beacon_type observation_beacon () const;
 
  struct threshold_s
  {
    uint16_t eCO2_ppm = 20;
 
    uint16_t eTVOC_ppb = 5;
 
    uint8_t temperature_Cel = 1;
 
    uint8_t humidity_pph = 2;
 
    int env_data_changed (uint32_t ed1,
                          uint32_t ed2) const;
 
    int observation_beacon_changed (const observation_beacon_type& ob1,
                                    const observation_beacon_type& ob2) const;
  };
 
  const lpm::state_machine& machine () const
  {
    return machine_;
  }
 
  static constexpr auto PF_REPORTING = lpm::state_machine::PF_APP_BASE << 0;
 
  static constexpr auto PF_RESTORED = lpm::state_machine::PF_APP_BASE << 1;
 
  static constexpr auto PF_CONDITIONED = lpm::state_machine::PF_APP_BASE << 2;
 
  static constexpr auto PF_BASELINED = lpm::state_machine::PF_APP_BASE << 3;
 
  static constexpr auto PF_CCS811_ERROR = lpm::state_machine::PF_APP_BASE << 4;
 
  static uint32_t encode_env (int16_t temp_cCel,
                              uint16_t rh_pptt);
 
  int status () const;
 
  int env_data (uint32_t enc);
 
  uint32_t env_data () const
  {
    return env_data_;
  }
 
  int baseline () const;
 
  int baseline (uint16_t value) const;
 
  int retain_baseline ();
 
  enum DRIVE_MODE_e : uint8_t
  {
    DM_IDLE = 0,
    DM_1_s = 1,
    DM_10_s = 2,
    DM_60_s = 3,
  };
 
  static constexpr auto DEFAULT_DRIVE_MODE = DM_10_s;
 
  int active_drive_mode () const;
 
  int drive_mode () const
  {
    return drive_mode_;
  }
 
  int drive_mode (unsigned int dm);
 
  unsigned int i2c_address () const
  {
    return addr_;
  }
 
private:
  int lpsm_process_ (int& delay,
                     process_flags_type& pf) override;
 
  int read_u8_ (uint8_t reg) const;
 
  /* Other implementations that require enable_scoped(). */
  int status_ () const;
  int baseline_ () const;
  int baseline_ (uint16_t value) const;
  int fetch_ (observations_type& obs);
 
  /* Fetch the retained (expected) drive mode regardless of machine
   * state. */
  int active_drive_mode_ () const
  {
    const auto rsp = &retained_state_;
    return (retained_state_type::FL_DRIVE_MODE_Msk & rsp->flags) >> retained_state_type::FL_DRIVE_MODE_Pos;
  }
 
  void intn_callback_ (const periph::GPIOTE::sense_status_type*);
 
  static retained_state_type retained_state_;
 
  iface_config_type& iface_config_;
 
  gpio::active_low waken_;
  gpio::active_low resetn_;
 
  periph::GPIOTE::sense_listener intn_listener_;
  observations_type observations_{};
  version_s version_{};
  uint64_t baseline_saved_utt_{};
  uint32_t env_data_ = -1;
 
  int8_t intn_psel_;
  uint8_t addr_;
  uint8_t drive_mode_ = DEFAULT_DRIVE_MODE;
};
 
} // ns sensor
} // ns nrfcxx
 
#endif /* NRFCXX_SENSOR_CCS811_HPP */