| Since | Origin / Contributor | Maintainer | Source |
|---|---|---|---|
| 2017-10-28 | vsky279 | vsky279 | bme680.c |
This module provides a simple interface to BME680 temperature/air presssure/humidity sensors/air quality sensor (Bosch Sensortec). Compared to the BME280 module the sensor does not support automatic mode which means that it can be setup to perform regular measurements. Every measurement has to be triggered manually.
In order to measure the air quality the sensor needs to be heated first. In the example provided by the manufacturer the sensor is heated to 300 degrees centigrade for a period of 200 ms and then the measurement is taken. These values are taken as default values in this implementation. I have not tested the impact of different temperatures and heating times on the measurement.
This module is able to measure the gas resistance (see Bosch's datasheet). The gas resistance is not the IAQ (Indoor Air Quality) Index. But apparently it can be used as some proxy. The value still should somehow reflect the air quality. It seems that the higher value the air quality is better.
The algorithm for IAQ calculation from the gas restistances (probably measured at different temperatures) is not publicly available. Bosch says that at this point of time the calculations for the Indoor Air Quality index are offered only as a pre-compiled library (see discussion here: BoschSensortec/BME680_driver#6). It is available as the BSEC Library.
The algorithm is implemented in the library bsec/algo/bin/ESP8266/libalgobsec.a. Unfortunately I did not even manage to run the Bosch BSEC example on ESP8266 using this library.
For given air pressure and sea level air pressure returns the altitude in meters as an integer multiplied with 100, i.e. altimeter function.
bme680.altitude(P, QNH)
Pmeasured pressureQNHcurrent sea level pressure
altitude in meters of measurement point
For given temperature and relative humidity returns the dew point in Celsius as an integer multiplied with 100.
bme680.dewpoint(H, T)
Hrelative humidity in percent multiplied by 1000.Ttemperate in Celsius multiplied by 100.
dew point in Celsius
For given altitude converts the air pressure to sea level air pressure.
bme680.qfe2qnh(P, altitude)
Pmeasured pressurealtitudealtitude in meters of measurement point
sea level pressure
Reads the sensor and returns the temperature, the air pressure, the air relative humidity and
bme680.read([altitude])
- (optional)
altitude- altitude in meters of measurement point. If provided also the air pressure converted to sea level air pressure is returned.
Ttemperature in Celsius as an integer multiplied with 100Pair pressure in hectopascals multiplied by 100Hrelative humidity in percent multiplied by 1000Ggas resistanceQNHair pressure in hectopascals multiplied by 100 converted to sea level
Any of these variables is nil if the readout of given measure was not successful.
The measured values can be read only once. Following attempts to read values will return nil. A new startreadout() needs to be called first before next read().
Starts readout (turns the sensor into forced mode). After the readout the sensor turns to sleep mode.
bme680.startreadout(delay, callback)
delaysets sensor to forced mode and calls thecallback(if provided) after given number of milliseconds. For 0 the default delay is calculated by the formula provided by Bosch. Apparently for certain combinations of oversamplings setup the the delay returned by the formula is not sufficient and the readout is not ready (make sure you are not reading the previous measurement). For default parameters (2x, 16x, 1x) the calculated delay is 121 ms while in reality 150 ms are needed to get the result.callbackif provided it will be invoked after givendelay. The sensor reading should be finalized by then so.
nil
Initializes module. Initialization is mandatory before read values.
bme680.setup([temp_oss, press_oss, humi_oss, heater_temp, heater_duration, IIR_filter, cold_start])
- (optional)
temp_oss- Controls oversampling of temperature data. Default oversampling is 2x. - (optional)
press_oss- Controls oversampling of pressure data. Default oversampling is 16x. - (optional)
humi_oss- Controls oversampling of humidity data. Default oversampling is 1x - (optional)
heater_temp- - (optional)
heater_duration- - (optional)
IIR_filter- Controls the time constant of the IIR filter. Default fitler coefficient is 31. - (optional)
cold_start- If 0 then the bme680 chip is not initialised. Usefull in a battery operated setup when the ESP deep sleeps and on wakeup needs to initialise the driver (the module) but not the chip itself. The chip was kept powered (sleeping too) and is holding the latest reading that should be fetched quickly before another reading starts (bme680.startreadout()). By default the chip is initialised.
temp_oss, press_oss, humi_oss |
Data oversampling |
|---|---|
| 0 | Skipped (output set to 0x80000) |
| 1 | oversampling ×1 |
| 2 | oversampling ×2 |
| 3 | oversampling ×4 |
| 4 | oversampling ×8 |
| 5 | oversampling ×16 |
IIR_filter |
Filter coefficient |
|---|---|
| 0 | Filter off |
| 1 | 1 |
| 2 | 3 |
| 3 | 7 |
| 4 | 15 |
| 5 | 31 |
| 6 | 63 |
| 7 | 127 |
nil if initialization has failed (no sensor connected?)
alt=320 -- altitude of the measurement place
sda, scl = 3, 4
i2c.setup(0, sda, scl, i2c.SLOW) -- call i2c.setup() only once
bme680.setup()
-- delay calculated by formula provided by Bosch: 121 ms, minimum working (empirical): 150 ms
bme680.startreadout(150, function ()
T, P, H, G, QNH = bme680.read(alt)
if T then
local Tsgn = (T < 0 and -1 or 1); T = Tsgn*T
print(string.format("T=%s%d.%02d", Tsgn<0 and "-" or "", T/100, T%100))
print(string.format("QFE=%d.%03d", P/100, P%100))
print(string.format("QNH=%d.%03d", QNH/100, QNH%100))
print(string.format("humidity=%d.%03d%%", H/1000, H%1000))
print(string.format("gas resistance=%d", G))
D = bme680.dewpoint(H, T)
local Dsgn = (D < 0 and -1 or 1); D = Dsgn*D
print(string.format("dew_point=%s%d.%02d", Dsgn<0 and "-" or "", D/100, D%100))
end
end)