Air Quality Measurement (IAQ) with the BME680

One of the main features of the BME680 sensor is its ability to measure the air quality of indoor environments. That sounds great, until you realize, that the actual output of the BME680 is not a clear, easy-to-understand value like the IAQ-Index, but it delivers instead a resistance value in ohms.


What a bummer! Yeah, I know, the resistance of the internal heating plate of the sensor does vary with the presence of certain substances in the air. But interpreting the air quality from that resistance value is really not straightforward and subject to interpretation. 


To be fair, the good folks at Bosch Sensortec did not develop the BME680 with the Arduino Uno in mind. The sensor shows its real potential when used together with the BSEC algorithm (Bosch Sensortec Environment Cluster). The BSEC algorithm calculates the IAQ-index based not only on measured values (temperature, humidity, pressure and resistance), but also based on previous measurements.


Developed to run with the powerful processors inside modern smartphones, the BSEC algorithm does not run smoothly on an 8-bit microcontroller (as far as I can tell!). But it does run on the popular ESP8266 WiFi microcontroller. So this is what you will learn here: how to connect the BME680 to the ESP8266 and measure the IAQ-index.

Connecting the Arduino IDE to the ESP8266

Just as the ATmega328 is the microcontroller running the Arduino Uno, the ESP8266 microcontroller is the main component of the open source platform NodeMCU. There are plenty of great resources on the internet about the NodeMCU, so here we will just focus on programming the NodeMCU with the Arduino IDE and using it to read a BME680. OK, so let's get started:

Tutorial: BME680
Tutorial: NodeMCU with ESP8266

1.     Open the Arduino IDE (I am using version 1.8.5) and go to File > Preferences. Now copy and paste the following address into the field Additional Boards Manager URLs, as shown in the picture below, and click OK.

Arduino IDE: Opening Preferences
Arduino IDE: Adding an Additional Boards Manager URL

2.     Go to Tools > Boards: > Boards Manager... and search for the esp8266 library by the ESP8266 Community. I am currently using the version 2.2.0, but it should probably run just as well with newer versions.

Arduino IDE: Opening Boards Manager
Arduino IDE: Installing ESP8266 Board

3.     Go to Tools > Boards: > NodeMCU 1.0 board (ESP-12E Module) to connect to the ESP8266.

Arduino IDE: Selecting NodeMCU board

If you did everything right, then the NodeMCU board info will be shown at the bottom of the Arduino IDE.

Arduino IDE: Successful Installation of NodeMCU Board on Arduino IDE

Integrating the BSEC Library to the Arduino IDE

4.     Download the BSEC library and the example sketch. This are all contained in the following zip-file:

5.     Unzip the file into your Arduino folder. This can be found under: 



The folder BlueDot_BME680_ESP8266 should now contain another folder named bsec_example_iot along with the following files:

BSEC files within zip-file

6.     Now copy the file libalgobsec.a and paste it into the following folder:



Yes, this folder is really well hidden. Even more so, because the folder AppData is usually not shown on the Windows Explorer. If you are not sure how to show hidden files and folders in Windows (it's really easy), check out these links from Microsoft: 


View hidden files and folders in Windows 10 (in English) or Anzeigen versteckter Dateien (in German)


7.     Go to the following folder:



This folder is very close to the last one and there you will find several files with the ending .ld. Open the following file with a text editor:

Any text editor should do, like Wordpad or Programmer's Notepad (which I prefer). Using the regular txt-Editor program from Windows, however, is not very practical, because it displays the entire code as a single block.

8.     After opening the file, go way down to line 156 and look for this piece of code:


*libm.a:(.literal .text .literal.* .text.*)

Tutorial: BSEC files - ld file - Before Changes

9.     Found it? Great! Now copy the following line of code and insert it on line 157 (bellow the piece of code shown above):


*libalgobsec.a:(.literal .text .literal.* .text.*)

The code should now look like this:

Tutorial: BSEC files - ld file - After Changes

10.     Save and close the file.


11.     Now go up to the following folder:



12.     Open the file platform.txt.


13.     Look for the following piece of code on line 33:


compiler.c.elf.libs=-lm -lgcc -lhal -lphy -lpp -lnet80211 -lwpa -lcrypto -lmain -lwps -laxtls -lsmartconfig -lmesh -lwpa2 {build.lwip_lib}

Tutorial: BSEC files - platform.txt - Before Changes

14.     Did you find it? Good, because we now need to add this little piece of code at the end of the line.



Your code should now look like this:

Tutorial: BSEC files - platform.txt - After Changes

15.     That's it! Don't forget to save and close the file.

Connecting the BME680 sensor to the NodeMCU board

16.     Now it is time to connect the BME680 sensor to the NodeMCU board. The header pins of the NodeMCU board are already soldered. In this example I am using the board NodeMCU Lolin V3. You will need five pins from this board to connect to the BME680 sensor: two ground pins (G), 3V, D3 and D4.

Tutorial: NodeMCU Lolin V3

17.     Connect the BME680 sensor to the NodeMCU board as follows: 


BME680 (VCC pin) >>  NodeMCU (3V pin)
BME680 (GND pin) >> NodeMCU (G)
BME680 (SDI pin) >> NodeMCU (D3)
BME680 (SCK pin) >> NodeMCU (D4)
BME680 (SDO pin) >> NodeMCU (G)

Connecting the SDO pin from the BME680 to the GND is important, because the original code was programmed to use the alternative I2C address (0x77). You can access this I2C address from the BME680 sensor by connecting the SDO pin to the Ground.

Tutorial: Connecting NodeMCU to BME680

18.     Finally, connect the NodeMCU board to your PC through a MicroUSB cable.


19.     Open the example sketch bsec_iot_example.ino, which you downloaded with the zip-file.

Tutorial: Opening bsec_iot_example.ino

20.     Select the COM Port for the NodeMCU board under Tools 

Tutorial: Opening COM Port

21. Compile and run the sketch. You don't need to make any changes to the code. Please note that the Baud Rate from the Serial Monitor should be set at 115200. 


When the code starts running, it will display the temperature in °C, the relative humidity in % and the IAQ index as an absolute value ranging from 0 (clean air) to 500 (a heavily polluted air).

Tutorial: Starting IAQ Measurement

The initial value of the IAQ index is 25.00. and it stays that way for a good while. Only after several minutes does the IAQ value starts to drift. But don't be surprised if the IAQ index remains low for a while, because according to the BME680 Datasheet (Page 23, Section Indoor-air-quality).

Tutorial: Measurement IAQ-Index with BME680 and ESP8266