/* * Driver for Bosch Sensortec BME680 digital temperature, humidity, pressure * and gas sensor connected to I2C or SPI * * This driver is for the usage with the ESP8266 and FreeRTOS (esp-open-rtos) * [https://github.com/SuperHouse/esp-open-rtos]. It is also working with ESP32 * and ESP-IDF [https://github.com/espressif/esp-idf.git] as well as Linux * based systems using a wrapper library for ESP8266 functions. * * --------------------------------------------------------------------------- * * 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__ // 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 #include "bme680_types.h" #include "bme680_platform.h" // 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_MEAS_STILL_RUNNING ( 6 << 8) #define BME680_FORCE_MODE_FAILED ( 7 << 8) #define BME680_NO_NEW_DATA ( 8 << 8) #define BME680_WRONG_HEAT_PROFILE ( 9 << 8) #define BME680_MEAS_GAS_NOT_VALID (10 << 8) #define BME680_HEATER_NOT_STABLE (11 << 8) // Driver range definitions #define BME680_HEATER_TEMP_MIN 200 // min. 200 degree Celsius #define BME680_HEATER_TEMP_MAX 400 // max. 200 degree Celsius #define BME680_HEATER_PROFILES 10 // max. 10 heater profiles 0 ... 9 #define BME680_HEATER_NOT_USED -1 // heater not used profile #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 the * the following default settings: * * - Oversampling rate for temperature, pressure, humidity is osr_1x * - Filter size for pressure and temperature is iir_size 3 * - Heater profile 0 with 320 degree C and 150 ms duration * * 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); /** * @brief Force one single TPHG measurement * * The function triggers the sensor to start one THPG measurement cycle. * Parameters for the measurement like oversampling rates, IIR filter sizes * and heater profile can be configured before. * * Once the TPHG measurement is started, the user task has to wait for the * results. The duration of the TPHG measurement can be determined with * function *bme680_get_measurement_duration*. * * @param dev pointer to the sensor device data structure * @return true on success, false on error */ bool bme680_force_measurement (bme680_sensor_t* dev); /** * @brief Get estimated duration of a TPHG measurement * * The function returns an estimated duration of the TPHG measurement cycle * in RTOS ticks for the current configuration of the sensor. * * This duration is the time required by the sensor for one TPHG measurement * until the results are available. It strongly depends on which measurements * are performed in the THPG measurement cycle and what configuration * parameters were set. It can vary from 1 RTOS (10 ms) tick up to 4500 RTOS * ticks (4.5 seconds). * * If the measurement configuration is not changed, the duration can be * considered as constant. * * @param dev pointer to the sensor device data structure * @return duration of TPHG measurement cycle in ticks or 0 on error */ uint32_t bme680_get_measurement_duration (const bme680_sensor_t *dev); /** * @brief Get the measurement status * * The function can be used to test whether a measurement that was started * before is still running. * * @param dev pointer to the sensor device data structure * @return true if measurement is still running or false otherwise */ bool 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 it waits * 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 from 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 from 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 a heater profile for gas measurements * * The sensor integrates a heater for the gas measurement. Parameters for this * heater are defined by so called heater profiles. The sensor supports up to * 10 heater profiles, which are numbered from 0 to 9. Each profile consists of * a temperature set-point (the target temperature) and a heating duration. * * This function sets the parameters for one of the heater profiles 0 ... 9. * To activate the gas measurement with this profile, use function * *bme680_use_heater_profile*, see below. * * Please note: According to the data sheet, a 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 profile heater profile 0 ... 9 * @param temperature target 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, uint8_t profile, uint16_t temperature, uint16_t duration); /** * @brief Activate gas measurement with a given heater profile * * The function activates the gas measurement with one of the heater * profiles 0 ... 9 or deactivates the gas measurement completely when * -1 or BME680_HEATER_NOT_USED is used as heater profile. * * Parameters of the activated heater profile have to be set before with * function *bme680_set_heater_profile* otherwise the function fails. * * If several heater profiles have been defined with function * *bme680_set_heater_profile*, a sequence of gas measurements with different * heater parameters can be realized by a sequence of activations of different * heater profiles for successive TPHG measurements using this function. * * @param dev pointer to the sensor device data structure0 * * @param profile 0 ... 9 to activate or -1 to deactivate gas measure * @return true on success, false on error */ bool bme680_use_heater_profile (bme680_sensor_t* dev, int8_t profile); /** * @brief Set ambient temperature * * The heater resistance calculation algorithm takes into account the ambient * temperature of the sensor. This function can be used to set this ambient * temperature. Either values determined from the sensor itself or from * another temperature sensor can be used. The default ambient temperature * is 25 degree Celsius. * * @param dev pointer to the sensor device data structure * @param temperature ambient temperature in degree Celsius * @return true on success, false on error */ bool bme680_set_ambient_temperature (bme680_sensor_t* dev, int16_t temperature); #ifdef __cplusplus } #endif /* End of CPP guard */ #endif /* __BME680_H__ */