BME680 Temperature/Humidity/Pressure/Gas sensor

Driver for the Bosch BME680 sensor. More...

Detailed Description

Driver for the Bosch BME680 sensor.

Introduction

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_t dev;
...
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

Files
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...

Macros
#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.

Typedefs
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...

Enumerations
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...

Functions
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...

Variables
bme680_t *	bme680_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.

Enumerator
BME680_NULL_PTR	NULL pointer check failed.
BME680_COM_FAILED	Communication with the device failed.
BME680_NO_DEV	Device doesn't exist.
BME680_INVALID	Invalid value or length.
BME680_NO_NEW_DATA	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.

Parameters

[in,out]

dev

device descriptor of the sensor

Returns

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.

Parameters

[in,out]	dev	device descriptor of the sensor
[out]	data	pointer to a data structure with the field data

Returns

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.

Parameters

[in,out]

dev

device descriptor of the sensor

Returns

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.

Parameters

[in,out]	dev	device descriptor of the sensor to initialize
[in]	params	configuration parameters

Returns

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.

Parameters

[in,out]	dev	device descriptor of the sensor
[in]	temp	ambient temperature in degC.

Returns

0 on success

< 0 on error