BME680 Library  0.5
Library for the Bosch BME680 Air Quality sensor
bme680.h File Reference

Sensor driver for the Bosch BME680 air quality sensor. This library supports i2c and 4-wire SPI connections, reads temperature, pressure, relative humidity, and VOC levels, and provides limited support for adjusting the sensors settings. More...

#include "simpletools.h"

Go to the source code of this file.

Data Structures

struct  bme680_st
 

Macros

#define BME680_H
 
#define CELSIUS   (0)
 
#define FAHRENHEIT   (1)
 
#define KELVIN   (2)
 
#define PASCALS   (0)
 
#define MMHG   (1)
 
#define INHG   (2)
 
#define PSI   (3)
 
#define METERS   (0)
 
#define FEET   (1)
 
#define BME680_OS_NONE   (0)
 
#define BME680_OS_1X   (1)
 
#define BME680_OS_2X   (2)
 
#define BME680_OS_4X   (3)
 
#define BME680_OS_8X   (4)
 
#define BME680_OS_16X   (5)
 
#define BME680_FILTER_SIZE_0   (0)
 
#define BME680_FILTER_SIZE_1   (1)
 
#define BME680_FILTER_SIZE_3   (2)
 
#define BME680_FILTER_SIZE_7   (3)
 
#define BME680_FILTER_SIZE_15   (4)
 
#define BME680_FILTER_SIZE_31   (5)
 
#define BME680_FILTER_SIZE_63   (6)
 
#define BME680_FILTER_SIZE_127   (7)
 
#define BME680_SETTING_AMB_TEMP   (0)
 
#define BME680_SETTING_HEATER_TEMP   (1)
 
#define BME680_SETTING_HEATER_DURATION   (2)
 
#define BME680_SETTING_FILTER_SIZE   (3)
 
#define BME680_SETTING_TEMP_SAMPLES   (4)
 
#define BME680_SETTING_PRESSURE_SAMPLES   (5)
 
#define BME680_SETTING_HUMIDITY_SAMPLES   (6)
 

Typedefs

typedef struct bme680_st bme680_t
 
typedef bme680_t bme680
 

Functions

bme680_tbme680_openI2C (i2c *i2c_bus, char i2c_addr)
 Initialize a BME680 sensor into i2c mode. More...
 
bme680_tbme680_openSPI (char pin_sdo, char pin_clk, char pin_sdi, char pin_cs)
 Initialize a BME680 sensor into 4-wire SPI mode. More...
 
void bme680_begin (bme680_t *dev)
 Internal function used to set the values in the bme680_t structure to their default values. More...
 
char bme680_loadSettings (bme680_t *dev)
 Loads settings values that have been saved in the bme680_t structure into the BME680 sensor. More...
 
char bme680_readSensor (bme680_t *dev)
 Instructs the BME680 sensor to take a reading.
Readings take approximately 200ms and should be retireved using bme680_temperature(), bme680_pressure(), bme680_humidity(), bme680_altitude(), and bme680_gasResistance(). More...
 
void bme680_write (bme680_t *dev, unsigned char reg_addr, unsigned char *reg_data, unsigned short len)
 Internal function used to read values from the specified registers of the BME680 sensor. More...
 
void bme680_read (bme680_t *dev, unsigned char reg_addr, unsigned char *reg_data, unsigned short len)
 Internal function used to write values to the specified registers of the BME680 sensor. More...
 
void bme680_configure (bme680_t *dev, char setting, int value)
 Change configurable settings for the BME680 sensor. More...
 
void bme680_close (bme680_t *dev)
 Close and free the memory used by the bme680 device structure. More...
 
float bme680_temperature (bme680_t *dev, char unit)
 Retrieve the temperature from the last read of the BME680 device. More...
 
float bme680_pressure (bme680_t *dev, char unit)
 Retrieve the temperature from the last read of the BME680 device. More...
 
float bme680_altitude (bme680_t *dev, char unit)
 Retrieve the estimated altitude from the last read of the BME680 device. More...
 
float bme680_humidity (bme680_t *dev)
 Retrieve the relative humidity as a percentage from the last read of the BME680 device. More...
 
float bme680_gasResistance (bme680_t *dev)
 Retrieve the relative humidity as a percentage from the last read of the BME680 device. More...
 
void bme680_heaterEnable (bme680_t *dev)
 Allows the BME680 to send current to the heating element for its gas sensor. More...
 
void bme680_heaterDisable (bme680_t *dev)
 Turns off the current that the BME680 sends to the heating element for its gas sensor. More...
 

Detailed Description

Sensor driver for the Bosch BME680 air quality sensor. This library supports i2c and 4-wire SPI connections, reads temperature, pressure, relative humidity, and VOC levels, and provides limited support for adjusting the sensors settings.

Author
Matthew Matz
Version
0.5

Macro Definition Documentation

◆ BME680_FILTER_SIZE_0

#define BME680_FILTER_SIZE_0   (0)

IIR (Low-pass) filter setting used in bme680_configure()

◆ BME680_FILTER_SIZE_1

#define BME680_FILTER_SIZE_1   (1)

IIR (Low-pass) filter setting used in bme680_configure()

◆ BME680_FILTER_SIZE_127

#define BME680_FILTER_SIZE_127   (7)

IIR (Low-pass) filter setting used in bme680_configure()

◆ BME680_FILTER_SIZE_15

#define BME680_FILTER_SIZE_15   (4)

IIR (Low-pass) filter setting used in bme680_configure()

◆ BME680_FILTER_SIZE_3

#define BME680_FILTER_SIZE_3   (2)

IIR (Low-pass) filter setting used in bme680_configure()

◆ BME680_FILTER_SIZE_31

#define BME680_FILTER_SIZE_31   (5)

IIR (Low-pass) filter setting used in bme680_configure()

◆ BME680_FILTER_SIZE_63

#define BME680_FILTER_SIZE_63   (6)

IIR (Low-pass) filter setting used in bme680_configure()

◆ BME680_FILTER_SIZE_7

#define BME680_FILTER_SIZE_7   (3)

IIR (Low-pass) filter setting used in bme680_configure()

◆ BME680_OS_16X

#define BME680_OS_16X   (5)

Over-sampling setting (16x) used in bme680_configure()

◆ BME680_OS_1X

#define BME680_OS_1X   (1)

Over-sampling setting (1x) used in bme680_configure()

◆ BME680_OS_2X

#define BME680_OS_2X   (2)

Over-sampling setting (2x) used in bme680_configure()

◆ BME680_OS_4X

#define BME680_OS_4X   (3)

Over-sampling setting (4x) used in bme680_configure()

◆ BME680_OS_8X

#define BME680_OS_8X   (4)

Over-sampling setting (8x) used in bme680_configure()

◆ BME680_OS_NONE

#define BME680_OS_NONE   (0)

Over-sampling setting (None) used in bme680_configure()

◆ BME680_SETTING_AMB_TEMP

#define BME680_SETTING_AMB_TEMP   (0)

Setting constant used in bme680_configure()

◆ BME680_SETTING_FILTER_SIZE

#define BME680_SETTING_FILTER_SIZE   (3)

Setting constant used in bme680_configure()

◆ BME680_SETTING_HEATER_DURATION

#define BME680_SETTING_HEATER_DURATION   (2)

Setting constant used in bme680_configure()

◆ BME680_SETTING_HEATER_TEMP

#define BME680_SETTING_HEATER_TEMP   (1)

Setting constant used in bme680_configure()

◆ BME680_SETTING_HUMIDITY_SAMPLES

#define BME680_SETTING_HUMIDITY_SAMPLES   (6)

Setting constant used in bme680_configure()

◆ BME680_SETTING_PRESSURE_SAMPLES

#define BME680_SETTING_PRESSURE_SAMPLES   (5)

Setting constant used in bme680_configure()

◆ BME680_SETTING_TEMP_SAMPLES

#define BME680_SETTING_TEMP_SAMPLES   (4)

Setting constant used in bme680_configure()

◆ CELSIUS

#define CELSIUS   (0)

Measurement Unit for bme680_temperature()

◆ FAHRENHEIT

#define FAHRENHEIT   (1)

Measurement Unit for bme680_temperature()

◆ FEET

#define FEET   (1)

Measurement Unit for bme680_altitude()

◆ INHG

#define INHG   (2)

Measurement Unit for bme680_pressure()

◆ KELVIN

#define KELVIN   (2)

Measurement Unit for bme680_temperature()

◆ METERS

#define METERS   (0)

Measurement Unit for bme680_altitude()

◆ MMHG

#define MMHG   (1)

Measurement Unit for bme680_pressure()

◆ PASCALS

#define PASCALS   (0)

Measurement Unit for bme680_pressure()

◆ PSI

#define PSI   (3)

Measurement Unit for bme680_pressure()

Function Documentation

◆ bme680_altitude()

float bme680_altitude ( bme680_t dev,
char  unit 
)

Retrieve the estimated altitude from the last read of the BME680 device.

Note
this is calcualted from the pressure measurement. It is not reliable for high altitudes, and it is affected by the ambient (barometric) pressure due to weather. For that reason, the BME680 is better for measuring changes in altitude versus absolute altitude.
Parameters
*devPointer to the bme680 device.
unitUnit of meaure to return the measurement in.
May be METERS or FEET.

◆ bme680_begin()

void bme680_begin ( bme680_t dev)

Internal function used to set the values in the bme680_t structure to their default values.

Parameters
*devpointer to the bme680 device.

◆ bme680_close()

void bme680_close ( bme680_t dev)

Close and free the memory used by the bme680 device structure.

Parameters
*devpointer to the bme680 device.

◆ bme680_configure()

void bme680_configure ( bme680_t dev,
char  setting,
int  value 
)

Change configurable settings for the BME680 sensor.

Parameters
*devpointer to the bme680 device.
settingthe setting to change. May be

Ambient Temperature in deg C (BME680_SETTING_AMB_TEMP) - default is 25. Heater Temperature in deg C (BME680_SETTING_HEATER_TEMP) - default is 320. Heater Duration in ms (BME680_SETTING_HEATER_DURATION) - default is 150. Low-pass filter size (BME680_SETTING_FILTER_SIZE) - default is BME680_FILTER_SIZE_3. Temperature samples to take (BME680_SETTING_TEMP_SAMPLES) - default is BME680_OS_8X. Pressure samples to take (BME680_SETTING_PRESSURE_SAMPLES) - default is BME680_OS_4X. Humidity samples to take (BME680_SETTING_HUMIDITY_SAMPLES) - default is BME680_OS_2X.

Parameters
valuethe value to write into that setting.

◆ bme680_gasResistance()

float bme680_gasResistance ( bme680_t dev)

Retrieve the relative humidity as a percentage from the last read of the BME680 device.

Parameters
*devpointer to the bme680 device.

◆ bme680_heaterDisable()

void bme680_heaterDisable ( bme680_t dev)

Turns off the current that the BME680 sends to the heating element for its gas sensor.

Parameters
*devpointer to the bme680 device.

◆ bme680_heaterEnable()

void bme680_heaterEnable ( bme680_t dev)

Allows the BME680 to send current to the heating element for its gas sensor.

Parameters
*devpointer to the bme680 device.

◆ bme680_humidity()

float bme680_humidity ( bme680_t dev)

Retrieve the relative humidity as a percentage from the last read of the BME680 device.

Parameters
*devpointer to the bme680 device.

◆ bme680_loadSettings()

char bme680_loadSettings ( bme680_t dev)

Loads settings values that have been saved in the bme680_t structure into the BME680 sensor.

Note
Must be called after calling bem680_init...() and before calling bme_readSensor().
Parameters
*devpointer to the bme680 device.

◆ bme680_openI2C()

bme680_t* bme680_openI2C ( i2c *  i2c_bus,
char  i2c_addr 
)

Initialize a BME680 sensor into i2c mode.

Parameters
*i2c_buspointer to an i2c bus that has already been opened with i2c_open();.
i2c_addrthe i2c address of the device, usualy 0x76 or 0x77.
Returns
bme680_t device identifier for use with functions in bme680 library.

◆ bme680_openSPI()

bme680_t* bme680_openSPI ( char  pin_sdo,
char  pin_clk,
char  pin_sdi,
char  pin_cs 
)

Initialize a BME680 sensor into 4-wire SPI mode.

Parameters
pin_sdothe BME680's SDO (MISO) pin.
pin_clkthe BME680's CLK (clock) pin.
pin_sdithe BME680's SDI (MOSI) pin.
pin_csthe BME680's CS (select) pin.
Returns
bme680_t device identifier for use with functions in bme680 library.

◆ bme680_pressure()

float bme680_pressure ( bme680_t dev,
char  unit 
)

Retrieve the temperature from the last read of the BME680 device.

Parameters
*devpointer to the bme680 device.
unitUnit of meaure to return the measurement in.
May be PASCALS, MMHG, INHG, or PSI.

◆ bme680_read()

void bme680_read ( bme680_t dev,
unsigned char  reg_addr,
unsigned char *  reg_data,
unsigned short  len 
)

Internal function used to write values to the specified registers of the BME680 sensor.

Parameters
*devpointer to the bme680 device.
reg_addrthe address of first register to write to.
*reg_datathe array containing alternating data and address bytes to write.
lenthe total number of data and address bytes to write.

◆ bme680_readSensor()

char bme680_readSensor ( bme680_t dev)

Instructs the BME680 sensor to take a reading.
Readings take approximately 200ms and should be retireved using bme680_temperature(), bme680_pressure(), bme680_humidity(), bme680_altitude(), and bme680_gasResistance().

Note
The internal heating element for the gas (VOC) sensor can skew temperature and humidity readings if the sensor is read at intervals of under 3 seconds. If frequent temperature and humidity readings are desired, use bme680_heaterDisable() to prevent the heating element from turning on.
Parameters
*devpointer to the bme680 device.

◆ bme680_temperature()

float bme680_temperature ( bme680_t dev,
char  unit 
)

Retrieve the temperature from the last read of the BME680 device.

Parameters
*devPointer to the bme680 device.
unitUnit of meaure to return the measurement in.
May be CELSIUS, FAHRENHEIT, or KELVIN

◆ bme680_write()

void bme680_write ( bme680_t dev,
unsigned char  reg_addr,
unsigned char *  reg_data,
unsigned short  len 
)

Internal function used to read values from the specified registers of the BME680 sensor.

Parameters
*devpointer to the bme680 device.
reg_addrthe address of register to begin reading from.
*reg_datathe array to store the received data into.
lenthe number of bytes to read.