/* * Driver for Bosch Sensortec BME680 digital temperature, humidity, pressure and * gas sensor connected to I2C or SPI * * Part of esp-open-rtos [https://github.com/SuperHouse/esp-open-rtos] * * --------------------------------------------------------------------------- * * The BSD License (3-clause license) * * Copyright (c) 2017 Gunar Schorcht (https://github.com/gschorcht] * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * 3. Neither the name of the copyright holder nor the names of its * contributors may be used to endorse or promote products derived from this * software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ #ifndef __BME680_H__ #define __BME680_H__ #include "bme680/bme680_types.h" // Uncomment one of the following defines to enable debug output // #define BME680_DEBUG_LEVEL_1 // only error messages // #define BME680_DEBUG_LEVEL_2 // debug and error messages // BME680 addresses #define BME680_I2C_ADDRESS_1 0x76 // SDO pin is low #define BME680_I2C_ADDRESS_2 0x77 // SDO pin is high // BME680 chip id #define BME680_CHIP_ID 0x61 // BME680_REG_ID<7:0> // Definition of error codes #define BME680_OK 0 #define BME680_NOK -1 #define BME680_INT_ERROR_MASK 0x000f #define BME680_DRV_ERROR_MASK 0xfff0 // Error codes for I2C and SPI interfaces ORed with BME680 driver error codes #define BME680_I2C_READ_FAILED 1 #define BME680_I2C_WRITE_FAILED 2 #define BME680_I2C_BUSY 3 #define BME680_SPI_WRITE_FAILED 4 #define BME680_SPI_READ_FAILED 5 #define BME680_SPI_BUFFER_OVERFLOW 6 #define BME680_SPI_SET_PAGE_FAILED 7 // BME680 driver error codes ORed with error codes for I2C and SPI interfaces #define BME680_RESET_CMD_FAILED (1 << 8) #define BME680_WRONG_CHIP_ID (2 << 8) #define BME680_READ_CALIB_DATA_FAILED (3 << 8) #define BME680_MEAS_ALREADY_RUNNING (4 << 8) #define BME680_MEAS_NOT_RUNNING (5 << 8) #define BME680_FORCE_MODE_FAILED (6 << 8) #define BME680_NO_NEW_DATA (7 << 8) // Driver range definitions #define BME680_HEATER_TEMP_MIN 200 // min. 200 degree Celsius #define BME680_HEATER_TEMP_MAX 400 // max. 200 degree Celsius #ifdef __cplusplus extern "C" { #endif /** -------------------------------------------------------------------------- * * Functional Description of the BME680 sensor * * The BME680 sensor only support two modes, the sleep mode and the forced * mode in which measurements are done. After power-up sequence, the sensor * automatically starts in sleep mode. To start a measurement, the sensor has * to switch in the forced mode. In this mode it performs exactly one * measurement of temperature, pressure, humidity, and gas in that order, * the so-called TPHG measurement cycle. After the execution of this TPHG * measurement cycle, raw sensor data are available and the sensor returns * automatically back to sleep mode. * * Using the BME680 consists of the following steps * * 1. Trigger the sensor to switch into forced mode to perform one THPG cycle * 2. Wait until the THPG cycle has been finished (measurement duration) * 3. Fetch raw sensor data, compensate and convert them to sensor values * * --------------------------------------------------------------------------- */ /** * @brief Initialize a BME680 sensor * * The function initializes the sensor device data structure, probes the * sensor, soft resets the sensor, and configures the sensor with default * settings: * * - Oversampling rate for temperature, pressure, humidity is osr_1x * - Filter size for pressure and temperature is iir_size 3 * - Heater profile for gas is 320 degree Celsius for 150 milliseconds. * * The sensor can be connected either to an I2C or a SPI bus. In both cases, * the parameter *bus* specifies the ID of the corresponding bus. Please note * that in case of SPI, bus 1 has to be used since bus 0 is used for system * flash memory. * * If parameter *addr* is greater than 0, it defines a valid I2C slave address * and the sensor is connected to an I2C bus. In that case parameter *cs* is * ignored. * * If parameter *addr* is 0, the sensor is connected to a SPI bus. In that * case, parameter *cs* defines the GPIO used as CS signal * * @param bus I2C or SPI bus at which BME680 sensor is connected * @param addr I2C addr of the BME680 sensor, 0 for SPI * @param cs SPI CS GPIO, ignored for I2C * @return pointer to sensor data structure, or NULL on error */ bme680_sensor_t* bme680_init_sensor (uint8_t bus, uint8_t addr, uint8_t cs_pin); /** * @brief Force one single TPHG measurement * * The function triggers the sensor to start one THPG measurement cycle in * forced mode, the only measurement mode supported by the BME680. Parameters * for the measurement like oversampling rates, IIR filter sizes and heater * profile can be configured before. * * On success, the function returns an estimated measurement duration given * in RTOS ticks. This is the time in ticks needed by the sensor before * measurement results become available. The user task has to wait this * duration before it can use function *bme680_get_results_fixed* or * function *bme680_get_results_float* to fetch the measurement results. * * The measurement duration strongly depends on which measurements in the THPG * measurement cycle are performed and which configuration parameters were set. * It can vary from 1 RTOS (10 ms) tick up to 4500 RTOS ticks (4.5 seconds). * * @param dev pointer to the sensor device data structure * @return measurement duration given in RTOS ticks or -1 on error */ int32_t bme680_force_measurement (bme680_sensor_t* dev); /** * @brief Get remaining duration of a running measurement * * The function can be used to test whether a measurement has been started * and how long it still takes before measurement results become * available. The return value is given in RTOS ticks and can be * * >0 in case the measurement is is still running, * 0 in case the measurement has been already finished, or * <0 in case of error. * * That is, a return value greater than 0 indicates that the measurement * results are still not available and the user task has to wait that time. * * @param dev pointer to the sensor device data structure * @return remaining measurement duration in RTOS ticks or -1 on error */ int32_t bme680_is_measuring (bme680_sensor_t* dev); /** * @brief Get results of a measurement in fixed point representation * * The function returns the results of a TPHG measurement that has been * started before. If the measurement is still running, the function fails * and returns invalid values (see type declaration). * * @param dev pointer to the sensor device data structure * @param results pointer to a data structure that is filled with results * @return true on success, false on error */ bool bme680_get_results_fixed (bme680_sensor_t* dev, bme680_values_fixed_t* results); /** * @brief Get results of a measurement in floating point representation * * The function returns the results of a TPHG measurement that has been * started before. If the measurement is still running, the function fails * and returns invalid values (see type declaration). * * @param dev pointer to the sensor device data structure * @param results pointer to a data structure that is filled with results * @return true on success, false on error */ bool bme680_get_results_float (bme680_sensor_t* dev, bme680_values_float_t* results); /** * @brief Start a measurement, wait and return the results (fixed point) * * This function is a combination of functions above. For convenience it * starts a TPHG measurement using *bme680_force_measurement*, then waits it * the measurement duration for the results using *vTaskDelay* and finally it * returns the results using function *bme680_get_results_fixed*. * * Note: Since the calling task is delayed using function *vTaskDelay*, this * function must not be used when it is called by a software timer callback * function. * * @param dev pointer to the sensor device data structure * @param results pointer to a data structure that is filled with results * @return true on success, false on error */ bool bme680_measure_fixed (bme680_sensor_t* dev, bme680_values_fixed_t* results); /** * @brief Start a measurement, wait and return the results (floating point) * * This function is a combination of functions above. For convenience it * starts a TPHG measurement using *bme680_force_measurement*, then it waits * the measurement duration for the results using *vTaskDelay* and finally it * returns the results using function *bme680_get_results_float*. * * Note: Since the calling task is delayed using function *vTaskDelay*, this * function must not be used when it is called by a software timer callback * function. * * @param dev pointer to the sensor device data structure * @param results pointer to a data structure that is filled with results * @return true on success, false on error */ bool bme680_measure_float (bme680_sensor_t* dev, bme680_values_float_t* results); /** * @brief Set the oversampling rates for measurements * * The BME680 sensor allows to define individual oversampling rates for * the measurements of temperature, pressure and humidity. Using an * oversampling rate of *osr*, the resolution of raw sensor data can be * increased by ld(*osr*) bits. * * Possible oversampling rates are 1x (default), 2x, 4x, 8x, 16x, see type * *bme680_oversampling_rate_t*. The default oversampling rate is 1. * * Please note: Use *osr_none* to skip the corresponding measurement. * * @param dev pointer to the sensor device data structure * @param ost oversampling rate for temperature measurements * @param osp oversampling rate for pressure measurements * @param osh oversampling rate for humidity measurements * @return true on success, false on error */ bool bme680_set_oversampling_rates (bme680_sensor_t* dev, bme680_oversampling_rate_t osr_t, bme680_oversampling_rate_t osr_p, bme680_oversampling_rate_t osr_h); /** * @brief Set the size of the IIR filter * * The sensor integrates an internal IIR filter (low pass filter) to reduce * short-term changes in sensor output values caused by external disturbances. * It effectively reduces the bandwidth of the sensor output values. * * The filter can optionally be used for pressure and temperature data that * are subject to many short-term changes. Using the IIR filter, increases the * resolution of pressure and temperature data to 20 bit. Humidity and gas * inside the sensor does not fluctuate rapidly and does not require such a * low pass filtering. * * The default filter size is 3 (*iir_size_3*). * * Please note: If the size of the filter is 0, the filter is not used. * * @param dev pointer to the sensor device data structure * @param size IIR filter size * @return true on success, false on error */ bool bme680_set_filter_size(bme680_sensor_t* dev, bme680_filter_size_t size); /** * @brief Set the heater profile for gas measurements * * For gas measurement the sensor integrates a heater. The paremeters for * this heater are defined by a heater profile. Such a heater profile * consists of a temperature setting point (the target temperature) and the * heating duration. The target temperature is converted to the heater * resistance value. * * Even though the sensor supports up to 10 different profiles, only one * profile is used by this driver for simplicity. The temperature setting * point and the heating duration of this profile can be defined by this * function. Default values are 320 degree Celsius as target temperature and * 150 ms heating duration. * * Please note: To disable the measurement of gas, set the heating duration * to 0 ms. * * Please note: According to the data sheet, target temperatures of between * 200 and 400 degrees Celsius are typical and about 20 to 30 ms are necessary * for the heater to reach the desired target temperature. * * @param dev pointer to the sensor device data structure * @param temperature heating temperature in degree Celsius * @param duration heating duration in milliseconds * @return true on success, false on error */ bool bme680_set_heater_profile (bme680_sensor_t* dev, uint16_t temperature, uint16_t duration); /** * @brief Set ambient temperature * * The heater resistance conversion algorithm takes into account the ambient * temperature of the sensor. This function can be used to set this ambient * temperature. Either values determined from this or another temperature * sensor can be used. The default ambient temperature is 25 degree Celsius. */ bool bme680_set_ambient_temperature (bme680_sensor_t* dev, int16_t temperature); #ifdef __cplusplus } #endif /* End of CPP guard */ #endif /* __BME680_H__ */