Source: https://mokxi.com/libraries/adafruit-bme680
Updated: 2026-11-22

Libraries / Sensors

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.

Run the example in Mokxi See the calls

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.

### 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

### 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.

Kitchen air A BME680 learns the clean air’s gas reading, then calls out bad air when cooking smoke pulls it down, with the weather alongside.

## Keep going

### Learn

- Arduino BME680: Air Quality, Gas and Weather
- I2C Scanner for Arduino and ESP32, and Fixes

### Parts

- Gas and weather, BME680

### More sensors libraries

- DHT sensor library
- DHT20
- VL53L0X
- Adafruit_VL53L0X
- HX711 Arduino Library
- MPU6050
- Adafruit MPU6050
- BME280
- arduino-sht
- Sensirion I2C SHT3x
- SHT4x
- forcedBMX280
- BlueDot BME280 Library
- Grove - Barometer Sensor BME280

Every built-in library · Open the editor

## Try Adafruit BME680 without installing anything

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

Start building free

Open the editor
