Before you start
- Board and pins
- Classic ESP32-WROOM-32 DevKit, Arduino board: ESP32 Dev Module. This example explicitly uses GPIO21 for SDA and GPIO22 for SCL; these are GPIO numbers, not header positions. Other ESP32 boards need a suitable pin map.
- Module assumption
- An I2C BME280 breakout whose manufacturer permits 3.3 V at the chosen supply input, with SDA/SCL pulled up to 3.3 V and CS/SDO configured for I2C. Vendor and exact board variant are unspecified; verify its schematic before wiring. This is not a bare-chip build.
- Software and libraries
- Arduino IDE 2.x; esp32 by Espressif Systems 3.x (API review baseline 3.3.2). Install Adafruit BME280 Library 2.3.0 in Library Manager and accept Adafruit Unified Sensor and Adafruit BusIO dependencies. Wire is included with the core. Serial Monitor: 115200 baud.
- Prerequisites and parts
- Be able to upload a sketch and open Serial Monitor. Use an ESP32 DevKit, verified 3.3 V BME280 breakout, USB data cable and four short jumper wires; use a breadboard if needed. Begin with only this sensor on the bus.
- Expected result
- The sketch reports a responding address and chip ID, confirms BME280 initialization, then prints °C, relative humidity (%) and pressure (hPa) about once a second. Numeric examples below are illustrative, not hardware measurements.
- Verification status
- Reviewed against Espressif, Bosch and Adafruit documentation. Not compiled for an ESP32 or tested on hardware in this update.
BME280 or BMP280?
BME280 measures temperature, relative humidity and air pressure. BMP280 measures temperature and pressure only: it cannot supply humidity. Similar-looking boards and a 0x76/0x77 response do not establish which chip you have.
Bosch specifies chip ID 0x60 at register 0xD0 for BME280, and 0x58 for BMP280. The example checks that register before initializing the BME280 library. A different or unreadable ID calls for a wiring and module-identity check; do not diagnose the sensor from missing humidity alone.
Technical Specifications
Arduino library: Adafruit BME280 Library 2.3.0; dependencies: Adafruit Unified Sensor and Adafruit BusIO
| Specification | Value | Why it matters |
|---|---|---|
| Bare-chip supply limits | VDD 1.71–3.6 V; VDDIO 1.2–3.6 V | These Bosch limits are not a rating for a breakout VIN pin. A regulator may change supply requirements but does not alone level-shift SDA/SCL. |
| Module supply in this example | 3.3 V at a manufacturer-approved input | VIN, VCC and 3V3 labels are not interchangeable guarantees. Check the exact module’s allowed input and regulator requirements. |
| ESP32 signal voltage | SDA and SCL pull-ups to 3.3 V | ESP32 GPIO is not 5 V tolerant. Do not use direct 5 V I2C pull-ups; use an appropriate level-shifting interface if required. |
| Interface | I2C here; the chip also supports SPI | The example uses one shared Wire bus at 100 kHz. SDA carries data; SCL carries the clock. |
| Chip operating ranges | −40 to +85 °C; 0–100% RH; 300–1100 hPa | Ranges do not imply uniform accuracy across all conditions. See Bosch’s specified accuracy conditions; keep the sensor dry. |
| Manufacturer accuracy conditions | Humidity ±3% RH at 20–80% RH and 25 °C; pressure ±1 hPa at 300–1100 hPa and 0–65 °C | Bosch specifications apply under stated conditions, not a guarantee of your assembled board’s readings. |
| Chip temperature accuracy | ±0.5 °C at 0–65 °C in the current Bosch datasheet | This is chip temperature. PCB heat and placement can bias ambient estimates; resolution and accuracy are different. |
Pinout
- VIN / VCC Power input ESP32 3.3 V Use only the supply input documented for your exact board. A VIN label or regulator does not prove 5 V-safe GPIO signals.
- GND Ground reference ESP32 GND Ground must be shared with the ESP32 and every other I2C device.
- SDA / SDI I2C data ESP32 GPIO21 SDA may be labeled SDI on a dual-interface board. Confirm the schematic: SDI is I2C data in I2C mode, whereas SDO is not the SDA connection.
- SCL / SCK I2C clock ESP32 GPIO22 SCL may be labeled SCK on a dual-interface board. Use GPIO22 here; the Wire.begin() pin arguments must match your wiring.
- SDO Address select or SPI data output GND for 0x76 or VDDIO for 0x77 (chip) The chip’s SDO must not float in I2C mode. A breakout may set it with a resistor or address jumper. Verify that configuration; do not add a conflicting connection.
- CS / CSB SPI chip select or I2C mode select HIGH at VDDIO for I2C (chip) The breakout may tie CS/CSB HIGH already. Confirm its schematic; a LOW CS selects SPI, and a floating CS is not a defined I2C configuration.
Wiring Diagram
SDA goes to GPIO21 and SCL to GPIO22 in this sketch. The same chip signals may be labeled SDI and SCK on a board that exposes SPI pins. Follow the module schematic, not its physical pin order or a photograph of another variant.
I2C needs pull-ups on both lines. Many breakouts include them, but this module is unspecified: confirm they connect to 3.3 V. If the module lacks them, add pull-ups sized for the bus’s capacitance, speed and device sink limits. A supply regulator alone does not make 5 V pull-ups safe.
At chip level, CSB must be HIGH for I2C. SDO LOW selects 0x76 and SDO HIGH selects 0x77; SDO must not float. Leave breakout defaults only after checking they establish these levels. Change address jumpers with power disconnected.
| BME280 Pin | ESP32 Pin | Purpose / Notes |
|---|---|---|
| VIN / VCC | 3.3 V | Use a documented 3.3 V-compatible supply input; do not infer a 5 V rating from VIN. |
| GND | GND | Shared ground is required for reliable I2C communication. |
| SDA / SDI | GPIO21 | SDA may be SDI in I2C mode. Use short wires and verify pull-ups to 3.3 V. |
| SCL / SCK | GPIO22 | SCL may be SCK in I2C mode. Must match Wire.begin(21, 22, 100000). |
| SDO | Verified module address setting | At chip level: LOW → 0x76, HIGH at VDDIO → 0x77. Never leave SDO floating. |
| CS / CSB | Verified module I2C setting | CSB must be HIGH at VDDIO. Check whether the board already establishes that level. |
-
1
Disconnect USB before wiring. Verify your exact module accepts 3.3 V on the chosen supply pin.
-
2
Connect that input to ESP32 3.3 V, and GND to ESP32 GND.
-
3
Connect SDA/SDI to GPIO21 and SCL/SCK to GPIO22. Confirm these labels from the module schematic.
-
4
Verify CSB is HIGH and SDO has a defined address-select level, through the board’s documented defaults or jumpers. Confirm SDA/SCL pull-ups are to 3.3 V.
-
5
Install the libraries, select ESP32 Dev Module and the correct port, then upload the example.
-
6
Open Serial Monitor at 115200 baud. It probes 0x76 and 0x77, reads chip ID and initializes a responding BME280. If neither responds, use the I2C scanner linked in Continue learning and the checks below.
Wiring and matching Arduino code
Minimal BME280 readout with address and identity checks
Use the four-wire I2C circuit above, with GPIO21 SDA, GPIO22 SCL and verified 3.3 V supply/pull-ups. Upload this complete Arduino sketch.
#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_BME280.h>
Adafruit_BME280 bme;
bool sensorReady = false;
int readChipId(uint8_t address) {
Wire.beginTransmission(address);
Wire.write(0xD0); // Bosch chip-ID register
if (Wire.endTransmission(false) != 0) return -1;
if (Wire.requestFrom(address, uint8_t(1)) != 1) return -1;
return Wire.read();
}
void setup() {
Serial.begin(115200);
delay(1000);
if (!Wire.begin(21, 22, 100000)) {
Serial.println("I2C bus setup failed.");
return;
}
for (uint8_t address = 0x76; address <= 0x77; ++address) {
Wire.beginTransmission(address);
if (Wire.endTransmission() != 0) continue;
Serial.print("I2C response at 0x");
Serial.println(address, HEX);
int id = readChipId(address);
if (id < 0) {
Serial.println("Chip-ID read failed; check the I2C bus.");
continue;
}
Serial.print("Chip ID: 0x");
Serial.println(id, HEX);
if (id != 0x60) {
Serial.println("Not a BME280 ID (BMP280 is 0x58).");
continue;
}
if (bme.begin(address, &Wire)) {
sensorReady = true;
Serial.println("BME280 initialized.");
break;
}
Serial.println("BME280 initialization failed.");
}
if (!sensorReady) {
Serial.println("No initialized BME280. Check wiring, mode and identity.");
}
}
void loop() {
if (sensorReady) {
float temperatureC = bme.readTemperature();
float humidity = bme.readHumidity();
float pressureHpa = bme.readPressure() / 100.0F;
if (isnan(temperatureC) || isnan(humidity) || isnan(pressureHpa)) {
Serial.println("Invalid reading; check the sensor and bus.");
} else {
Serial.print("Temperature: "); Serial.print(temperatureC, 1);
Serial.print(" C | Humidity: "); Serial.print(humidity, 1);
Serial.print(" % | Pressure: "); Serial.print(pressureHpa, 1);
Serial.println(" hPa");
}
}
delay(1000);
}
The two-address probe reports an I2C response separately from BME280 initialization. A response alone does not identify the chip. The register read checks for short/failed transfers; a valid 0x60 is required before bme.begin(). The delay only sets the print interval for this simple local demonstration. If initialization fails, correct the circuit or module identity and reset the ESP32.
Expected Output
Set Serial Monitor to 115200 baud. For an initialized BME280, expect I2C response at 0x76 (or 0x77), Chip ID: 0x60 and BME280 initialized.
An illustrative reading is: Temperature: 24.1 C | Humidity: 48.7 % | Pressure: 1012.6 hPa. Your numbers depend on the surroundings; they are not pass/fail target values. Readings print about once a second after initialization.
If you see an address response but no initialization, use the chip-ID message and troubleshooting table. No response at either address suggests a bus, supply, mode or connection problem. A full I2C scan finds other responding addresses but still does not identify a sensor.
Pressure units and altitude estimates
Adafruit readTemperature() returns degrees Celsius; readHumidity() returns relative humidity percent. readPressure() returns pascals (Pa). Divide by 100 for hectopascals (hPa): 100 Pa = 1 hPa = 1 mbar. This is local station pressure, not automatically adjusted to sea level.
A weather service may report sea-level pressure, so comparing that number directly with local pressure is misleading. Compare the same type of pressure or apply an appropriate altitude correction. Watch trends over time rather than treating one number as a rain forecast.
For an optional altitude estimate, bme.readAltitude(1013.25F) returns metres using standard sea-level pressure in hPa. Replace 1013.25 with a current local sea-level reference for a more useful estimate. Weather changes and the assumed atmospheric model introduce error: it is not GPS height or a survey measurement, and a fixed reference can make a stationary sensor appear to move.
The library uses factory calibration coefficients for compensation. Temperature reflects the chip’s temperature and can estimate ambient air temperature when placement is suitable. Keep it away from ESP32/regulator heat, direct sunlight, fingers and condensation; allow airflow and settling time.
Troubleshooting
| Problem | Possible cause | Solution |
|---|---|---|
| No response at 0x76 or 0x77 | Supply or ground missing, wrong SDA/SCL, SPI mode, floating address select, missing pull-ups or damaged module. | Disconnect power and verify the module schematic, 3.3 V-compatible supply input, shared GND, GPIO21/22, CSB HIGH, defined SDO and 3.3 V pull-ups. Retry with short wires and only this device; run a full I2C scanner. |
| Address responds but Chip ID is 0x58 | The responding chip identifies as BMP280, which lacks humidity. | Use the BMP280 library for that sensor or obtain a verified BME280. Changing 0x76 to 0x77 cannot add humidity. |
| Chip-ID read failed or a different ID appears | A transaction failed, another device occupies the address, or this is a different sensor. | Check the short-wire bus and pull-ups, isolate this module, verify its identity and compare its manufacturer documentation. An address ACK alone is not proof of BME280. |
| ID is 0x60 but initialization fails | Intermittent I2C, unstable supply or calibration/register communication trouble. | Verify the same Wire bus and pins, power-cycle after correcting connections, then retry with the specified Adafruit library. If failure persists, check the module with its vendor before assuming a software fault. |
| Missing header or compilation error | A required library or the ESP32 board package is missing or the wrong board is selected. | Select ESP32 Dev Module with esp32 by Espressif Systems 3.x. Install Adafruit BME280 Library 2.3.0 and its Unified Sensor and BusIO dependencies. |
| Temperature or humidity is unrealistic | Board heat, restricted airflow, condensation, contamination or a bus fault. | Move the sensor away from heat, keep it dry and allow airflow. Check successful initialization and wiring; missing humidity by itself does not prove BMP280. |
| Pressure or optional altitude differs from a weather app | Local pressure is compared with sea-level pressure, or the altitude reference is outdated. | Compare like pressure units/types. Use current sea-level pressure for readAltitude(); do not treat the result as precise elevation. |
| Works alone but fails beside an OLED | Address collision, wiring problem or combined pull-ups/load affect the bus. | Scan with each device alone and then together. Ensure distinct addresses, shared ground and 3.3 V pull-ups; check effective pull resistance and bus capacitance. |
| Output is unreadable or missing | Wrong port, baud or USB cable, or an earlier initialization message was missed. | Use a data cable, select the correct port, set 115200 baud and reset to see startup diagnostics. |
Where you use it
- ESP32 weather station
- Indoor climate monitor
- Greenhouse environment logger
- Barometric pressure trend tracker
- Approximate altitude monitor
- OLED weather dashboard
- Classroom atmosphere experiment
- Home automation sensor node
Continue learning
Related projects
FAQ
Yes. ESP32 can map I2C to other pins, but you must call Wire.begin(SDA, SCL) with the pins you wired.
Yes. Connect both devices to the same SDA and SCL lines as long as their I2C addresses are different. BME280 is commonly 0x76 or 0x77, while SSD1306 OLED modules are commonly 0x3C or sometimes 0x3D.
Yes, the sensor can be very low power, but the ESP32 must use deep sleep and avoid always-on Wi-Fi for long battery life.
Yes, if protected from rain and direct sun while still allowing airflow. Do not seal it in an airtight box.
Yes. MicroPython has BME280 drivers, but this page focuses on Arduino for beginner consistency.
No. It does not measure VOCs, CO2, smoke, or dust. Use a dedicated air-quality sensor for those.
Technical references
- Bosch BME280 datasheet — Supply limits, chip ID, I2C mode and address selection.
- Bosch BMP280 datasheet — Pressure/temperature sensor identity and 0x58 chip ID.
- Espressif Arduino-ESP32 I2C API — Explicit SDA/SCL selection and Wire transaction APIs.
- Adafruit BME280 Library 2.3.0 implementation — Initialization, measurement units and altitude calculation.
- Adafruit BME280 Library 2.3.0 dependencies — Unified Sensor and BusIO requirements.
Downloads
Official Bosch BME280 datasheet for electrical limits, calibration behavior, I2C/SPI protocol, and measurement accuracy.
Download Datasheet (PDF)