382022f507
BME680 is an ulta-low-power environmental sensor that integrates temperature, pressure, humidity and gas sensors in only one unit.
351 lines
15 KiB
C
351 lines
15 KiB
C
/*
|
|
* 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. Measurement
|
|
* 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__ */
|