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 name | Adafruit BME680 |
|---|---|
| Author | Adafruit |
| Include | #include <Adafruit_BME680.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | Gas 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.
- ESP32-C3
- Arduino Uno
- Arduino Nano
- Arduino Mega 2560
- Arduino Leonardo
- SparkFun Pro Micro
- Arduino Micro
- ESP32-C6
- WCH CH32V003
- Raspberry Pi Pico
- Raspberry Pi Pico W
- Seeed XIAO SAMD21
- STM32
- STM32 Nucleo-F411RE
- STM32 Blue Pill
- micro:bit V2
- Arduino Uno R4
- ESP32 DevKit
- ESP32-S3-DevKitC-1
- ESP8266 NodeMCU
- Arduino Pro Mini 3.3 V
- Seeed XIAO ESP32-C3
- ESP32-C3 SuperMini
- Seeed XIAO ESP32-C6
- ESP32-DevKitC V4
- LOLIN32 Lite
- Wemos D1 R32
- Cheap Yellow Display
- TTGO T-Display
- Seeed XIAO ESP32-S3
- ESP32-S3-CAM
- Arduino Nano ESP32
- Arduino Nano RP2040 Connect
- Seeed XIAO RP2040
- Waveshare RP2040-Zero
- Arduino Uno R4 WiFi
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.
#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
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.
Keep going
Try Adafruit BME680 without installing anything
Open the example, change the sketch, and keep your version in a free account.