Arduino library · Sensors

Adafruit BME680: weather and gas resistance in one reading

Yes. You can use the Adafruit BME680 library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (Gas and weather, BME680). The example below, "The BME680 test: weather and gas every two seconds", runs on the Arduino Uno R3.

Built in on Mokxi: #include <Adafruit_BME680.h> and it builds, with nothing to install. Free, and no account needed.

What Adafruit BME680 does

The BME680 is Bosch’s weather sensor with a gas sensor added: a tiny heated metal-oxide plate whose resistance falls when volatile compounds are in the air. Besides temperature, humidity and pressure, it reports that resistance in ohms. The BME688 works with the same calls. Adafruit’s library talks to either over I2C at 0x77 by default.

Each reading is one forced cycle: the chip measures temperature, pressure and humidity with the oversampling you set, heats the gas plate to the chosen temperature for the chosen time, measures its resistance and goes back to sleep. performReading() runs the whole cycle and fills bme.temperature, bme.pressure in pascals, bme.humidity and bme.gas_resistance in ohms. It blocks while the cycle runs; beginReading() and endReading() split it in two so loop() can do other work meanwhile.

Gas resistance is not an air quality index. It depends on the heater settings, the humidity and the individual sensor, so compare it with that sensor’s own reading in clean air, where higher means cleaner. Bosch’s BSEC library computes an index from it; this library does not. In Mokxi the bme680 part has sliders for all four values, and the SPI constructors compile but the part is always read over I2C.

Library Manager nameAdafruit BME680
AuthorAdafruit
Include#include <Adafruit_BME680.h>
Boardsevery board Mokxi compiles for but ATtiny85
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesGas and weather, BME680

Install it

It builds on every board Mokxi compiles for but ATtiny85.

In Mokxi it is built in: #include <Adafruit_BME680.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "Adafruit BME680" by Adafruit from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add Adafruit BME680 to lib_deps in PlatformIO. Mokxi follows the calls of release 2.0.6, so a sketch written here builds there too.

What to know in the simulator: Over I2C; the SPI constructors compile but the part is read on the I2C bus.

The calls you will use

In the order a sketch meets them.

Adafruit_BME680 bme

Creates the driver for I2C.

bme.begin()

Resets the chip, checks its ID, reads the calibration and applies the library’s defaults. Returns false when missing; begin(0x76) is the other address.

bme.setTemperatureOversampling(BME680_OS_8X)

More oversampling means less noise and a longer cycle. setHumidityOversampling() and setPressureOversampling() work the same way.

bme.setIIRFilterSize(BME680_FILTER_SIZE_3)

Smooths sudden pressure and temperature changes, such as a door slamming.

bme.setGasHeater(320, 150)

Heats the gas plate to 320 °C for 150 ms each cycle, the tutorial’s values. setGasHeater(0, 0) turns the heater off.

bme.performReading()

Runs one cycle and fills the four fields. Returns false when it failed.

if (bme.performReading()) {
  Serial.print(bme.temperature);
  Serial.print(" C  ");
  Serial.println(bme.gas_resistance);
}

bme.beginReading()

Starts a cycle and returns the millis() time it will finish. endReading() waits for it and fills the fields.

bme.readAltitude(1013.25)

Meters above sea level for a sea-level pressure given in hPa. It takes its own reading.

Example: The BME680 test: weather and gas every two seconds

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
#include <Wire.h>
#include "Adafruit_BME680.h"

#define SEALEVELPRESSURE_HPA (1013.25)

Adafruit_BME680 bme;

void setup() {
  Serial.begin(9600);
  if (!bme.begin()) {
    Serial.println("Could not find a valid BME680 sensor, check wiring!");
    while (1);
  }
  bme.setTemperatureOversampling(BME680_OS_8X);
  bme.setHumidityOversampling(BME680_OS_2X);
  bme.setPressureOversampling(BME680_OS_4X);
  bme.setIIRFilterSize(BME680_FILTER_SIZE_3);
  bme.setGasHeater(320, 150);  // 320 C for 150 ms
}

void loop() {
  if (!bme.performReading()) {
    Serial.println("Failed to perform reading :(");
    return;
  }
  Serial.print("Temperature = ");
  Serial.print(bme.temperature, 1);
  Serial.println(" *C");
  Serial.print("Pressure = ");
  Serial.print(bme.pressure / 100.0, 1);
  Serial.println(" hPa");
  Serial.print("Humidity = ");
  Serial.print(bme.humidity, 1);
  Serial.println(" %");
  Serial.print("Gas = ");
  Serial.print((bme.gas_resistance + 500) / 1000);
  Serial.println(" KOhms");
  delay(2000);
}

Wiring

  • Arduino Uno R3 A4 to Gas and weather, BME680 SDA
  • Arduino Uno R3 A5 to Gas and weather, BME680 SCL
  • Arduino Uno R3 5V to Gas and weather, BME680 VIN
  • Arduino Uno R3 GND to Gas and weather, BME680 GND

Open it in the editor, wired and ready to run

Common errors and how to fix them

Could not find a valid BME680 sensor, check wiring!

begin() found no BME680 ID at 0x77. Many boards wire SDO low, which puts the chip at 0x76: try bme.begin(0x76), or run an I2C scanner to see which answers.

Pressure prints as 100000 when a weather report says 1000

bme.pressure is in pascals, not hectopascals. Divide it by 100.0 before printing, as the example does, to get the familiar figure.

Temperature reads a little high compared with a room thermometer

The gas heater warms the chip on every cycle. Read less often, shorten the heater time, or switch it off with setGasHeater(0, 0) when gas readings are not needed.

Questions and answers

How do I get an air quality index from a BME680?

Bosch’s BSEC library turns gas resistance into an index, but this library does not. A simple start is to log the resistance in fresh air and watch for drops below it.

Why does each BME680 reading take so long?

The cycle includes the heater time, 150 ms in the example, plus the conversions. beginReading() lets the sketch keep working while it runs.

Projects that use Adafruit BME680

Built-in projects that include it. Each page has the full sketch and opens in the editor, already wired.

Try Adafruit BME680 without installing anything

Open the example, change the sketch, and keep your version in a free account.