BME680 Temperature/Humidity/Pressure/Gas sensor

Driver for the Bosch BME680 sensor. More...

Detailed Description

Driver for the Bosch BME680 sensor.


The driver allows the use of BME680 sensors connected either via I2C or SPI. Instead of implementing a complete driver, it simply uses the BME680 vendor driver written and maintained by Bosch Sensortec as a package.

Even though this driver interface provides an easy-to-use API, the vendor's driver API can still be used directly. This becomes necessary, for example, if the settings of the ambient temperature have to be updated from measurements with other sensors for gas measurement.

All functions of the vendor's driver API require a reference to a sensor device structure of type struct bme680_dev. Use macro BME680_SENSOR(dev) for a given device descriptor of type bme680_t to the according sensor device structure of type struct bme680_dev, for example:

BME680_SENSOR(dev).amb_temp = value_from_other_sensor;
bme680_set_sensor_settings(BME680_GAS_MEAS_SEL, &BME680_SENSOR(dev));

Refer to the code documentation at GitHub for detailed information on the API of the vendor driver.

Sensor Operation Modes

The BME680 sensor supports only two modes, sleep mode and forced mode, in which measurements are taken. After the power-on sequence, the sensor automatically starts in sleep mode. To start a measurement, the sensor must switch to forced mode. In this mode it performs exactly one measurement of temperature, pressure, humidity and gas in this order, the so-called TPHG measurement cycle. After executing this TPHG measurement cycle, the raw data from the sensor is available and the sensor automatically returns to sleep mode

Ambient Temperature

The sensor is initialized with a fixed ambient temperature defined by the parameter settings in bme680_params. However, precise gas measurements require the calculation of the heating resistance based on the ambient temperature.

The temperature of the internal temperature sensor is typically higher than the actual ambient temperature due to the self-heating of the sensor. element. It should therefore not be used to set the ambient temperature unless gas measurements are very infrequent and self-heating is negligible. Rather another temperature sensor should be used for that purpose.

Function bme680_set_ambient_temp can be used to change the ambient temperature.

Using the Sensor

Using the BME680 consists of the following steps

  1. Trigger the sensor with bme680_force_measurement to change to the forced mode and perform a THPG cycle.
  2. Wait at least the time returned by bme680_get_duration until the THPG cycle is finished.
  3. Use bme680_get_data to fetch raw sensor data and convert them to the resulting sensor values

Driver Configuration

BME680 sensors are connected either via I2C or SPI. Which interface is used by which BME680 sensor is defined by the parameters in bme680_params. The respective driver implementation is enabled by the modules bme680_i2c and bme680_spi. Several BME680 sensors and a mixed configuration of I2C and SPI can be used in one application.

USEMODULE='bme680_spi bme680_i2c' make BOARD=... -C tests/driver_bme680

The vendor driver allows the use of floating point conversions. In order to use these floating point conversions, module bme680_fp has to be enabled:

USEMODULE='bme680_fp bme680_i2c' make BOARD=... -C tests/driver_bme680


file  bme680_params.h
 Default configuration for BME680 device driver.
file  bme680.h
 Interface definition for the Bosch BME680 sensor.

Data Structures

struct  bme680_field_data
 BME680 sensor field data. More...
struct  bme680_intf_i2c_t
 BME680 I2C parameters. More...
struct  bme680_intf_spi_t
 BME680 SPI parameters. More...
union  bme680_intf_t
 BME680 Hardware interface parameters union. More...
struct  bme680_params_t
 BME680 device initialization parameters. More...
struct  bme680_t
 BME680 device descriptor. More...


#define BME680_I2C_ADDR_1   (0x76)
 I2C address when SDO pin is LOW.
#define BME680_I2C_ADDR_2   (0x77)
 I2C address when SDO pin is HIGH.
#define BME680_SENSOR(d)   (*((struct bme680_dev *)d))
 Converts a BME680 device descriptor to the BME680 sensor device structure for the vendor BME680 device driver.


typedef struct bme680_field_data bme680_field_data_t
 Shortcut type definition for BME680 sensor field data.
typedef struct bme680_dev bme680_dev_t
 Shortcut type definition for BME680 sensor device structure. More...


enum  {
  BME680_NULL_PTR = -1, BME680_COM_FAILED = -2, BME680_NO_DEV = -3, BME680_INVALID = -4,
  BME680_NO_NEW_DATA = -5
 Named return values. More...


int bme680_init (bme680_t *dev, const bme680_params_t *params)
 Initialize the BME680 sensor. More...
int bme680_force_measurement (bme680_t *dev)
 Force a single TPHG measurement cycle. More...
int bme680_get_duration (bme680_t *dev)
 Duration one THPG measurement cycle. More...
int bme680_get_data (bme680_t *dev, bme680_field_data_t *data)
 Get results of a TPHG measurement. More...
int bme680_set_ambient_temp (bme680_t *dev, int8_t temp)
 Set the ambient temperature. More...


bme680_tbme680_devs []
 References to BME680 sensor devices used by the HAL functions.
unsigned int bme680_devs_numof
 Number of initialized BME680 sensor devices in bme680_devs.

Typedef Documentation

◆ bme680_dev_t

typedef struct bme680_dev bme680_dev_t

Shortcut type definition for BME680 sensor device structure.

See also
struct bme680_dev

Definition at line 187 of file bme680.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Named return values.


NULL pointer check failed.


Communication with the device failed.


Device doesn't exist.


Invalid value or length.


No new data.

Definition at line 144 of file bme680.h.

Function Documentation

◆ bme680_force_measurement()

int bme680_force_measurement ( bme680_t dev)

Force a single TPHG measurement cycle.

The function triggers the sensor to start one THPG measurement cycle. The duration of the TPHG measurement cycle depends on the selected parameters. It can vary from 1.25 ms to 4.5 seconds. The duration of the measurement cycle can be determined with the bme680_get_duration function.

[in,out]devdevice descriptor of the sensor
0 on success
< 0 on error

◆ bme680_get_data()

int bme680_get_data ( bme680_t dev,
bme680_field_data_t data 

Get results of a TPHG measurement.

The function returns the results of a TPHG measurement that has been started before with bme680_force_measurement. For that purpose, the function fetches the raw sensor data and converts them into sensor values. If the measurement is still running, the function fails and returns invalid values.

[in,out]devdevice descriptor of the sensor
[out]datapointer to a data structure with the field data
0 on success
< 0 on error

◆ bme680_get_duration()

int bme680_get_duration ( bme680_t dev)

Duration one THPG measurement cycle.

This function determines the duration of one THPG measurement cycle according to the selected parameter settings. The duration can be used to wait for the measurement results once a THPG measurement has been started with bme680_force_measurement.

[in,out]devdevice descriptor of the sensor
duration of one THPG measurement cylce in milliseconds.
< 0 on error

◆ bme680_init()

int bme680_init ( bme680_t dev,
const bme680_params_t params 

Initialize the BME680 sensor.

[in,out]devdevice descriptor of the sensor to initialize
[in]paramsconfiguration parameters
0 on success
< 0 on error

◆ bme680_set_ambient_temp()

int bme680_set_ambient_temp ( bme680_t dev,
int8_t  temp 

Set the ambient temperature.

The function sets the ambient temperature for the calculation of the heater resistance.

[in,out]devdevice descriptor of the sensor
[in]tempambient temperature in degC.
0 on success
< 0 on error