Adafruit_BME690.cpp

/*!
 * @file Adafruit_BME690.cpp
 *
 * @mainpage Adafruit BME690 temperature, humidity, barometric pressure and gas
 * sensor driver
 *
 * @section intro_sec Introduction
 *
 * This is the documentation for Adafruit's BME690 driver for the
 * Arduino platform.  It is designed specifically to work with the
 * Adafruit BME690 breakout: https://www.adafruit.com/products/TBD
 *
 * These sensors use I2C or SPI to communicate, 2 or 4 pins are required
 * to interface with the breakout.
 *
 * Adafruit invests time and resources providing this open source code,
 * please support Adafruit and open-source hardware by purchasing
 * products from Adafruit!
 *
 * @section author Author
 *
 * Written by Ladyada for Adafruit Industries.
 *
 * @section license License
 *
 * BSD license, all text here must be included in any redistribution.
 *
 */

#include "Adafruit_BME690.h"

#include "Arduino.h"

// #define BME690_DEBUG

/** Our hardware interface functions **/
static int8_t i2c_read(uint8_t reg_addr, uint8_t* reg_data, uint32_t len,
                       void* interface);
static int8_t i2c_write(uint8_t reg_addr, const uint8_t* reg_data, uint32_t len,
                        void* interface);
static int8_t spi_read(uint8_t reg_addr, uint8_t* reg_data, uint32_t len,
                       void* interface);
static int8_t spi_write(uint8_t reg_addr, const uint8_t* reg_data, uint32_t len,
                        void* interface);
static void delay_usec(uint32_t us, void* intf_ptr);

// PUBLIC FUNCTIONS

/*!
 *  @brief  Instantiates sensor with i2c.
 *  @param  *theWire
 *          optional Wire object
 */
Adafruit_BME690::Adafruit_BME690(TwoWire* theWire)
    : _meas_start(0), _meas_period(0) {
  _wire = theWire;
}

/*!
 *  @brief  Instantiates sensor with Hardware SPI.
 *  @param  cspin
 *          SPI chip select.
 *  @param  theSPI
 *          optional SPI object
 */
Adafruit_BME690::Adafruit_BME690(int8_t cspin, SPIClass* theSPI)
    : _meas_start(0), _meas_period(0) {
  _spidev = new Adafruit_SPIDevice(cspin, BME69X_DEFAULT_SPIFREQ,
                                   SPI_BITORDER_MSBFIRST, SPI_MODE0, theSPI);
}

/*!
 *  @brief  Instantiates sensor with Software (bit-bang) SPI.
 *  @param  cspin
 *          SPI chip select
 *  @param  mosipin
 *          SPI MOSI (Data from microcontroller to sensor)
 *  @param  misopin
 *          SPI MISO (Data to microcontroller from sensor)
 *  @param  sckpin
 *          SPI Clock
 */
Adafruit_BME690::Adafruit_BME690(int8_t cspin, int8_t mosipin, int8_t misopin,
                                 int8_t sckpin)
    : _meas_start(0), _meas_period(0) {
  _spidev = new Adafruit_SPIDevice(cspin, sckpin, misopin, mosipin,
                                   BME69X_DEFAULT_SPIFREQ,
                                   SPI_BITORDER_MSBFIRST, SPI_MODE0);
}

/*!
 *  @brief  Initializes the sensor
 *          Hardware ss initialized, verifies it is in the I2C or SPI bus, then
 * reads calibration data in preparation for sensor reads.
 *  @param  addr
 *          Optional parameter for the I2C address of BME690. Default is 0x77
 *  @param  initSettings
 *          Optional parameter for initializing the sensor settings.
 *          Default is true.
 *  @return True on sensor initialization success. False on failure.
 */
bool Adafruit_BME690::begin(uint8_t addr, bool initSettings) {
  gas_valid = false;
  heater_stable = false;
  gas_index = 0;
  meas_index = 0;

  if (_spidev) {
    if (!_spidev->begin())
      return false;
  } else {
    if (!_i2cdev) {
      _i2cdev = new Adafruit_I2CDevice(addr, _wire);
    }
    if (!_i2cdev->begin())
      return false;
  }

  // Set up BME69x device structure
  gas_sensor.chip_id = BME69X_CHIP_ID;
  gas_sensor.intf = _spidev ? BME69X_SPI_INTF : BME69X_I2C_INTF;
  gas_sensor.read = _spidev ? spi_read : i2c_read;
  gas_sensor.write = _spidev ? spi_write : i2c_write;
  gas_sensor.delay_us = delay_usec;
  gas_sensor.intf_ptr = _spidev ? (void*)_spidev : (void*)_i2cdev;

  int8_t rslt = bme69x_init(&gas_sensor);
  if (rslt != BME69X_OK)
    return false;

  if (initSettings) {
    // Set the temperature, pressure and humidity settings
    gas_conf.filter = BME69X_FILTER_OFF;
    gas_conf.odr = BME69X_ODR_NONE;
    gas_conf.os_hum = BME69X_OS_2X;
    gas_conf.os_pres = BME69X_OS_4X;
    gas_conf.os_temp = BME69X_OS_8X;
    rslt = bme69x_set_conf(&gas_conf, &gas_sensor);
    if (rslt != BME69X_OK)
      return false;

    // Set the remaining gas sensor settings and link the heating profile
    gas_heatr_conf.enable = BME69X_ENABLE;
    gas_heatr_conf.heatr_temp = 320;
    gas_heatr_conf.heatr_dur = 150;
    rslt =
        bme69x_set_heatr_conf(BME69X_FORCED_MODE, &gas_heatr_conf, &gas_sensor);
    if (rslt != BME69X_OK)
      return false;
  }

  _sensorID = gas_sensor.chip_id;
  return true;
}

/*!
 *   @brief  Performs a reading and returns the ambient temperature.
 *   @return Temperature in degrees Celsius
 */
float Adafruit_BME690::readTemperature() {
  performReading();
  return temperature;
}

/*!
 *   @brief  Performs a reading and returns the barometric pressure.
 *   @return Barometric pressure in Pascals
 */
float Adafruit_BME690::readPressure() {
  performReading();
  return pressure;
}

/*!
 *   @brief  Performs a reading and returns the relative humidity.
 *   @return Relative humidity as floating point
 */
float Adafruit_BME690::readHumidity() {
  performReading();
  return humidity;
}

/*!
 *   @brief  Performs a reading and returns the gas resistance.
 *   @return Gas resistance in Ohms
 */
uint32_t Adafruit_BME690::readGas() {
  performReading();
  return gas_resistance;
}

/*!
 *  @brief Calculates the altitude (in meters).
 *
 *  Reads the current atmospheric pressure (in hPa) from the sensor and
 * calculates via the provided sea-level pressure (in hPa).
 *
 *  @param  seaLevel      Sea-level pressure in hPa
 *  @return Altitude in meters
 */
float Adafruit_BME690::readAltitude(float seaLevel) {
  // Equation taken from BMP180 datasheet (page 16):
  //  http://www.adafruit.com/datasheets/BST-BMP180-DS000-09.pdf

  // Note that using the equation from wikipedia can give bad results
  // at high altitude.  See this thread for more information:
  //  http://forums.adafruit.com/viewtopic.php?f=22&t=58064
  float atmospheric = readPressure() / 100.0F;
  return 44330.0 * (1.0 - pow(atmospheric / seaLevel, 0.1903));
}

/*!
 *  @brief  Set the temperature oversampling
 *  @param  os
 *          Oversampling setting, can be BME690_OS_NONE (turn off temp reading),
 *          BME690_OS_1X, BME690_OS_2X, BME690_OS_4X, BME690_OS_8X,
 * BME690_OS_16X
 *  @return True on success, False on failure
 */
bool Adafruit_BME690::setTemperatureOversampling(uint8_t os) {
  gas_conf.os_temp = os;
  return bme69x_set_conf(&gas_conf, &gas_sensor) == BME69X_OK;
}

/*!
 *  @brief  Set the pressure oversampling
 *  @param  os
 *          Oversampling setting, can be BME690_OS_NONE (turn off pressure
 * reading), BME690_OS_1X, BME690_OS_2X, BME690_OS_4X, BME690_OS_8X,
 * BME690_OS_16X
 *  @return True on success, False on failure
 */
bool Adafruit_BME690::setPressureOversampling(uint8_t os) {
  gas_conf.os_pres = os;
  return bme69x_set_conf(&gas_conf, &gas_sensor) == BME69X_OK;
}

/*!
 *  @brief  Set the humidity oversampling
 *  @param  os
 *          Oversampling setting, can be BME690_OS_NONE (turn off humidity
 * reading), BME690_OS_1X, BME690_OS_2X, BME690_OS_4X, BME690_OS_8X,
 * BME690_OS_16X
 *  @return True on success, False on failure
 */
bool Adafruit_BME690::setHumidityOversampling(uint8_t os) {
  gas_conf.os_hum = os;
  return bme69x_set_conf(&gas_conf, &gas_sensor) == BME69X_OK;
}

/*!
 *  @brief  Set the IIR filter size
 *  @param  fs
 *          Size of the filter (in samples to average)
 *  @return True on success, False on failure
 */
bool Adafruit_BME690::setIIRFilterSize(uint8_t fs) {
  gas_conf.filter = fs;
  return bme69x_set_conf(&gas_conf, &gas_sensor) == BME69X_OK;
}

/*!
 *  @brief  Set the gas heater temperature and time
 *  @param  heaterTemp
 *          Target temperature in degrees Celsius. Between 200-400
 *  @param  heaterTime
 *          Time to keep heater on in milliseconds, between 1-4032 ms
 *  @return True on success, False on failure
 */
bool Adafruit_BME690::setGasHeater(uint16_t heaterTemp, uint16_t heaterTime) {
  gas_heatr_conf.heatr_temp = heaterTemp;
  gas_heatr_conf.heatr_dur = heaterTime;
  return bme69x_set_heatr_conf(BME69X_FORCED_MODE, &gas_heatr_conf,
                               &gas_sensor) == BME69X_OK;
}

bool Adafruit_BME690::setGasHeaterProfile(uint16_t* temps, uint16_t* durations,
                                          uint8_t profileLen) {
  if (profileLen > 10)
    return false;

  gas_heatr_conf.enable = BME69X_ENABLE;

  for (uint8_t i = 0; i < profileLen; i++) {
    gas_heatr_conf.heatr_temp_prof[i] = temps[i];
    gas_heatr_conf.heatr_dur_prof[i] = durations[i];
  }
  gas_heatr_conf.profile_len = profileLen;

  return bme69x_set_heatr_conf(BME69X_SEQUENTIAL_MODE, &gas_heatr_conf,
                               &gas_sensor) == BME69X_OK;
}

bool Adafruit_BME690::enableGas(bool enable) {
  gas_heatr_conf.enable = enable ? BME69X_ENABLE : BME69X_DISABLE;
  return bme69x_set_heatr_conf(BME69X_FORCED_MODE, &gas_heatr_conf,
                               &gas_sensor) == BME69X_OK;
}

/*!
 *  @brief  Set the output data rate
 *  @param  odr
 *          Output data rate setting
 *  @return True on success, False on failure
 */
bool Adafruit_BME690::setODR(uint8_t odr) {
  gas_conf.odr = odr;
  return bme69x_set_conf(&gas_conf, &gas_sensor) == BME69X_OK;
}

/*!
 *  @brief  Soft reset the sensor
 *  @return True on success, False on failure
 */
bool Adafruit_BME690::softReset() {
  return bme69x_soft_reset(&gas_sensor) == BME69X_OK;
}

/*!
 *  @brief  Run the sensor self-test
 *  @return True if self-test passed, False if failed
 */
bool Adafruit_BME690::selfTest() {
  return bme69x_selftest_check(&gas_sensor) == BME69X_OK;
}

/*!
 *  @brief  Get the chip ID
 *  @return Chip ID (should be 0x61 for BME690)
 */
uint8_t Adafruit_BME690::getChipID() {
  return gas_sensor.chip_id;
}

/*!
 *  @brief  Get the variant ID (gas heater variant)
 *  @return Variant ID (0x00 = low, 0x01 = high gas variant)
 */
uint8_t Adafruit_BME690::getVariantID() {
  return gas_sensor.variant_id;
}

/*!
 *  @brief  Get the current operation mode
 *  @return Operation mode (0=sleep, 1=forced, 2=parallel, 3=sequential)
 */
uint8_t Adafruit_BME690::getOperationMode() {
  uint8_t mode;
  bme69x_get_op_mode(&mode, &gas_sensor);
  return mode;
}

bool Adafruit_BME690::setOperationMode(uint8_t mode) {
  return bme69x_set_op_mode(mode, &gas_sensor) == BME69X_OK;
}

bool Adafruit_BME690::setSleepMode() {
  return setOperationMode(BME69X_SLEEP_MODE);
}

/*!
 *  @brief Performs a full reading of all 4 sensors in the BME690.
 *         Assigns the internal Adafruit_BME690#temperature,
 * Adafruit_BME690#pressure, Adafruit_BME690#humidity and
 * Adafruit_BME690#gas_resistance member variables
 *  @return True on success, False on failure
 */
bool Adafruit_BME690::performReading() {
  return endReading();
}

/*!
 *  @brief  Begin an asynchronous reading
 *  @return When the reading will be ready, in millis()
 */
uint32_t Adafruit_BME690::beginReading() {
  if (_meas_start != 0) {
    /* A reading is already in progress */
    return _meas_start + _meas_period;
  }

  int8_t rslt = bme69x_set_op_mode(BME69X_FORCED_MODE, &gas_sensor);
  if (rslt != BME69X_OK)
    return 0; // error

  uint32_t meas_dur =
      bme69x_get_meas_dur(BME69X_FORCED_MODE, &gas_conf, &gas_sensor);
  _meas_period = meas_dur / 1000; // Convert to milliseconds
  _meas_start = millis();

  return _meas_start + _meas_period;
}

/*!
 *  @brief  End an asynchronous reading
 *          If the asynchronous reading is still in progress, block until it
 * ends. If no asynchronous reading is in progress, this is equivalent to
 * performReading().
 *  @return Whether success
 */
bool Adafruit_BME690::endReading() {
  struct bme69x_data data;
  uint8_t n_fields;

  int8_t rslt = bme69x_set_op_mode(BME69X_FORCED_MODE, &gas_sensor);
  if (rslt != BME69X_OK)
    return false;

  uint32_t meas_dur =
      bme69x_get_meas_dur(BME69X_FORCED_MODE, &gas_conf, &gas_sensor);
  if (meas_dur == 0) {
    return false;
  }

  uint32_t total_dur = meas_dur / 1000; // Convert microseconds to milliseconds
  if (gas_heatr_conf.enable == BME69X_ENABLE) {
    total_dur += gas_heatr_conf.heatr_dur;
  }
  delay(total_dur);

  rslt = bme69x_get_data(BME69X_FORCED_MODE, &data, &n_fields, &gas_sensor);
  if (rslt != BME69X_OK)
    return false;

  if (n_fields == 0) {
    return false;
  }

  temperature = data.temperature;
  pressure = data.pressure;
  humidity = data.humidity;
  gas_resistance = data.gas_resistance;
  gas_valid = (data.status & BME69X_GASM_VALID_MSK) != 0;
  heater_stable = (data.status & BME69X_HEAT_STAB_MSK) != 0;
  gas_index = data.gas_index;
  meas_index = data.meas_index;

  _meas_start = 0; // Allow new measurement to begin
  _meas_period = 0;

  return true;
}

/*!
 *  @brief  Get remaining time for an asynchronous reading
 *  @return Remaining millis, 0 if ready, -1 if no reading in progress
 */
int Adafruit_BME690::remainingReadingMillis() {
  if (_meas_start == 0)
    return reading_not_started;

  int remainingTime = (_meas_start + _meas_period) - millis();
  return remainingTime < 0 ? reading_complete : remainingTime;
}

// PRIVATE FUNCTIONS

/*!
 *  @brief  Read data from sensor via I2C
 */
static int8_t i2c_read(uint8_t reg_addr, uint8_t* reg_data, uint32_t len,
                       void* interface) {
  Adafruit_I2CDevice* dev = (Adafruit_I2CDevice*)interface;
  if (!dev->write_then_read(&reg_addr, 1, reg_data, len))
    return 1;
  return 0;
}

/*!
 *  @brief  Write data to sensor via I2C
 */
static int8_t i2c_write(uint8_t reg_addr, const uint8_t* reg_data, uint32_t len,
                        void* interface) {
  Adafruit_I2CDevice* dev = (Adafruit_I2CDevice*)interface;
  uint8_t buffer[len + 1];
  buffer[0] = reg_addr;
  memcpy(buffer + 1, reg_data, len);
  if (!dev->write(buffer, len + 1))
    return 1;
  return 0;
}

/*!
 *  @brief  Read data from sensor via SPI
 */
static int8_t spi_read(uint8_t reg_addr, uint8_t* reg_data, uint32_t len,
                       void* interface) {
  Adafruit_SPIDevice* dev = (Adafruit_SPIDevice*)interface;
  reg_addr |= 0x80; // Set read bit
  if (!dev->write_then_read(&reg_addr, 1, reg_data, len))
    return 1;
  return 0;
}

/*!
 *  @brief  Write data to sensor via SPI
 */
static int8_t spi_write(uint8_t reg_addr, const uint8_t* reg_data, uint32_t len,
                        void* interface) {
  Adafruit_SPIDevice* dev = (Adafruit_SPIDevice*)interface;
  reg_addr &= 0x7F; // Clear read bit
  uint8_t buffer[len + 1];
  buffer[0] = reg_addr;
  memcpy(buffer + 1, reg_data, len);
  if (!dev->write(buffer, len + 1))
    return 1;
  return 0;
}

/*!
 *  @brief  Delay function for BME69x API
 */
static void delay_usec(uint32_t us, void* intf_ptr) {
  delayMicroseconds(us);
}