bme680: Driver for BME680 digital environmental sensor
Defines
- BME680_I2C_ADDR_0
- BME680_I2C_ADDR_1
- BME680_MAX_OVERFLOW_VAL
- BME680_HEATER_TEMP_MIN
min.
200 degree Celsius
- BME680_HEATER_TEMP_MAX
max.
200 degree Celsius
- BME680_HEATER_PROFILES
max.
10 heater profiles 0 … 9
- BME680_HEATER_NOT_USED
heater not used profile
Enums
- enum bme680_filter_size_t
Filter size.
Values:
- enumerator BME680_IIR_SIZE_0
Filter is not used.
- enumerator BME680_IIR_SIZE_1
- enumerator BME680_IIR_SIZE_3
- enumerator BME680_IIR_SIZE_7
- enumerator BME680_IIR_SIZE_15
- enumerator BME680_IIR_SIZE_31
- enumerator BME680_IIR_SIZE_63
- enumerator BME680_IIR_SIZE_127
Functions
- esp_err_t bme680_init_desc(bme680_t *dev, uint8_t addr, i2c_port_t port, gpio_num_t sda_gpio, gpio_num_t scl_gpio)
Initialize device descriptor.
- Parameters:
dev – Device descriptor
addr – BME680 address
port – I2C port number
sda_gpio – GPIO pin for SDA
scl_gpio – GPIO pin for SCL
- Returns:
ESP_OKon success
- esp_err_t bme680_free_desc(bme680_t *dev)
Free device descriptor.
- Parameters:
dev – Device descriptor
- Returns:
ESP_OKon success
- esp_err_t bme680_init_sensor(bme680_t *dev)
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 must be connected to an I2C bus.
- Parameters:
dev – Device descriptor
- Returns:
ESP_OKon success
- esp_err_t bme680_force_measurement(bme680_t *dev)
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.
- Parameters:
dev – Device descriptor
- Returns:
ESP_OKon success
- esp_err_t bme680_get_measurement_duration(const bme680_t *dev, uint32_t *duration)
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.
- Parameters:
dev – Device descriptor
duration – [out] Duration of TPHG measurement cycle in ticks or 0 on error
- Returns:
ESP_OKon success
- esp_err_t bme680_is_measuring(bme680_t *dev, bool *busy)
Get the measurement status.
The function can be used to test whether a measurement that was started before is still running.
- Parameters:
dev – Device descriptor
busy – [out] true if measurement is still running or false otherwise
- Returns:
ESP_OKon success
- esp_err_t bme680_get_results_fixed(bme680_t *dev, bme680_values_fixed_t *results)
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).
- Parameters:
dev – Device descriptor
results – [out] pointer to a data structure that is filled with results
- Returns:
ESP_OKon success
- esp_err_t bme680_get_results_float(bme680_t *dev, bme680_values_float_t *results)
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).
- Parameters:
dev – Device descriptor
results – [out] pointer to a data structure that is filled with results
- Returns:
ESP_OKon success
- esp_err_t bme680_measure_fixed(bme680_t *dev, bme680_values_fixed_t *results)
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.
- Parameters:
dev – Device descriptor
results – [out] pointer to a data structure that is filled with results
- Returns:
ESP_OKon success
- esp_err_t bme680_measure_float(bme680_t *dev, bme680_values_float_t *results)
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
vTaskDelayand 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.
- Parameters:
dev – Device descriptor
results – [out] pointer to a data structure that is filled with results
- Returns:
ESP_OKon success
- esp_err_t bme680_set_oversampling_rates(bme680_t *dev, bme680_oversampling_rate_t osr_t, bme680_oversampling_rate_t osr_p, bme680_oversampling_rate_t osr_h)
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 BME680_OSR_NONE to skip the corresponding measurement.
- Parameters:
dev – Device descriptor
osr_t – oversampling rate for temperature measurements
osr_p – oversampling rate for pressure measurements
osr_h – oversampling rate for humidity measurements
- Returns:
ESP_OKon success
- esp_err_t bme680_set_filter_size(bme680_t *dev, bme680_filter_size_t size)
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 (BME680_IIR_SIZE_3).
Please note: If the size of the filter is 0, the filter is not used.
- Parameters:
dev – Device descriptor
size – IIR filter size
- Returns:
ESP_OKon success
- esp_err_t bme680_set_heater_profile(bme680_t *dev, uint8_t profile, uint16_t temperature, uint16_t duration)
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.
- Parameters:
dev – Device descriptor
profile – heater profile 0 … 9
temperature – target temperature in degree Celsius
duration – heating duration in milliseconds
- Returns:
ESP_OKon success
- esp_err_t bme680_use_heater_profile(bme680_t *dev, int8_t profile)
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.
- Parameters:
dev – Device descriptor
profile – 0 … 9 to activate or -1 to deactivate gas measure
- Returns:
ESP_OKon success
- esp_err_t bme680_set_ambient_temperature(bme680_t *dev, int16_t temperature)
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.
- Parameters:
dev – Device descriptor
temperature – ambient temperature in degree Celsius
- Returns:
ESP_OKon success
- struct bme680_values_fixed_t
Fixed point sensor values (fixed THPG values)
- struct bme680_values_float_t
Floating point sensor values (real THPG values)
- struct bme680_settings_t
Sensor parameters that configure the TPHG measurement cycle.
T - temperature measurement P - pressure measurement H - humidity measurement G - gas measurement
Public Members
- bme680_oversampling_rate_t osr_temperature
T oversampling rate (default
BME680_OSR_1X)
- bme680_oversampling_rate_t osr_pressure
P oversampling rate (default
BME680_OSR_1X)
- bme680_oversampling_rate_t osr_humidity
H oversampling rate (default
BME680_OSR_1X)
- bme680_filter_size_t filter_size
IIR filter size (default
BME680_IIR_SIZE_3)
- int8_t heater_profile
Heater profile used (default 0)
- uint16_t heater_temperature[10]
Heater temperature for G (default 320)
- uint16_t heater_duration[10]
Heater duration for G (default 150)
- int8_t ambient_temperature
Ambient temperature for G (default 25)
- struct bme680_calib_data_t
Data structure for calibration parameters.
These calibration parameters are used in compensation algorithms to convert raw sensor data to measurement results.
Public Members
- uint16_t par_t1
calibration data for temperature compensation
- int16_t par_t2
- int8_t par_t3
- uint16_t par_p1
calibration data for pressure compensation
- int16_t par_p2
- int8_t par_p3
- int16_t par_p4
- int16_t par_p5
- int8_t par_p7
- int8_t par_p6
- int16_t par_p8
- int16_t par_p9
- uint8_t par_p10
- uint16_t par_h1
calibration data for humidity compensation
- uint16_t par_h2
- int8_t par_h3
- int8_t par_h4
- int8_t par_h5
- uint8_t par_h6
- int8_t par_h7
- int8_t par_gh1
calibration data for gas compensation
- int16_t par_gh2
- int8_t par_gh3
- int32_t t_fine
temperature correction factor for P and G
- uint8_t res_heat_range
- int8_t res_heat_val
- int8_t range_sw_err
- struct bme680_t
BME680 sensor device data structure type.
Public Members
- i2c_dev_t i2c_dev
I2C device descriptor.
- bool meas_started
Indicates whether measurement started.
- uint8_t meas_status
Last sensor status (for internal use only)
- bme680_settings_t settings
Sensor settings.
- bme680_calib_data_t calib_data
Calibration data of the sensor.