The Ultimate ESP32 Tutorial: Build a WiFi Temperature Logger with BME280

If you want to move beyond blinking LEDs and start pulling real-world environmental data onto your network, this ESP32 tutorial is your baseline. We are building a WiFi-connected temperature, humidity, and barometric pressure logger using the ESP32 and a BME280 sensor. Unlike generic guides that gloss over hardware quirks, this guide targets the exact pinouts of the most common development board, provides production-ready code with I2C and WiFi error handling, and breaks down the exact failure modes you will encounter on the bench.

Parts List & Board Variant Selection

The ESP32 ecosystem is fragmented. Before writing a single line of code, you must know exactly which silicon and breakout you are holding. The code and pin mappings in this tutorial specifically target the ESP32-WROOM-32 DevKit V1 (30-pin variant). If you are using an ESP32-S3, ESP32-C3, or a 38-pin DevKit, the default I2C pins will differ.

Pin Mapping & Wiring Steps

The ESP32-WROOM-32 (30-pin) defaults to GPIO 21 for SDA and GPIO 22 for SCL. While the ESP32's GPIO matrix allows you to remap I2C to almost any pin in software, sticking to the hardware defaults prevents conflicts with boot strapping pins and saves you from debugging phantom I2C bus lockups.

1. De-energize the board: Unplug the USB cable before wiring.
2. Connect Power: Run a jumper from the ESP32 3V3 pin to the BME280 VIN. Do not use the 5V/VIN pin on the ESP32; the BME280 is strictly a 3.3V device and 5V will destroy the sensor's internal CMOS.
3. Connect Ground: Run a jumper from ESP32 GND to BME280 GND.
4. Connect I2C Data: Wire ESP32 GPIO 21 to BME280 SDA.
5. Connect I2C Clock: Wire ESP32 GPIO 22 to BME280 SCL.
6. Verify Pull-ups: If using a bare Bosch BME280 chip or a barebones breakout without onboard resistors, solder 4.7kΩ resistors between the SDA/SCL lines and the 3.3V rail. Without these, the I2C bus will float and fail to initialize.

Complete Compilable Code with Error Handling

This code targets the ESP32 DevKit V1 (ESP32-WROOM-32) using the Arduino IDE (ESP32 Core v3.x). It requires the Adafruit BME280 Library and its dependency, the Adafruit Unified Sensor library, installed via the Library Manager.

Notice the explicit pin definitions and the timeout-based error handling. We do not use infinite while(1) loops on failure; instead, we use the ESP32's hardware watchdog and deep sleep to recover from transient I2C or WiFi brownouts.

#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_BME280.h>
#include <WiFi.h>

// --- PIN DEFINITIONS (ESP32 DevKit V1 30-pin) ---
#define I2C_SDA 21
#define I2C_SCL 22

// --- SENSOR CONFIG ---
// Change to 0x77 if your breakout board has the SDO pad bridged to VCC
#define BME_I2C_ADDR 0x76 
#define SEALEVELPRESSURE_HPA (1013.25)

// --- WIFI CONFIG ---
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
const unsigned long wifiTimeoutMs = 15000;

Adafruit_BME280 bme;

void setup() {
  Serial.begin(115200);
  delay(1000); // Allow serial monitor to connect
  Serial.println("\n--- ESP32 BME280 WiFi Logger Booting ---");

  // 1. Initialize I2C with explicit pins and 400kHz Fast Mode
  Wire.begin(I2C_SDA, I2C_SCL);
  Wire.setClock(400000); 

  // 2. Initialize BME280 with Error Handling
  if (!bme.begin(BME_I2C_ADDR, &Wire)) {
    Serial.println("[FATAL] BME280 init failed. Check wiring and I2C address.");
    Serial.println("[ACTION] Rebooting in 5 seconds to retry...");
    delay(5000);
    ESP.restart();
  }
  Serial.println("[OK] BME280 initialized successfully.");

  // 3. Connect to WiFi with Timeout
  Serial.printf("Connecting to WiFi: %s", ssid);
  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);
  
  unsigned long startAttemptTime = millis();
  while (WiFi.status() != WL_CONNECTED && millis() - startAttemptTime < wifiTimeoutMs) {
    Serial.print(".");
    delay(500);
  }

  if (WiFi.status() != WL_CONNECTED) {
    Serial.println("\n[ERROR] WiFi connection timed out.");
    Serial.println("[ACTION] Entering deep sleep for 60s to save power and retry.");
    esp_sleep_enable_timer_wakeup(60 * 1000000ULL);
    esp_deep_sleep_start();
  }
  
  Serial.printf("\n[OK] Connected! IP: %s\n", WiFi.localIP().toString().c_str());
}

void loop() {
  float tempC = bme.readTemperature();
  float humidity = bme.readHumidity();
  float pressure = bme.readPressure() / 100.0F;

  // Sanity check: BME280 returns NaN if I2C bus locks up mid-read
  if (isnan(tempC) || isnan(humidity) || isnan(pressure)) {
    Serial.println("[WARN] Sensor read returned NaN. Resetting I2C bus.");
    Wire.end();
    delay(10);
    Wire.begin(I2C_SDA, I2C_SCL);
    return; // Skip this loop iteration
  }

  Serial.printf("Temp: %.2f C | Humidity: %.2f %% | Pressure: %.2f hPa\n", tempC, humidity, pressure);
  
  // In a real project, push this data to MQTT/InfluxDB here.
  
  delay(5000); // 5-second polling rate
}

Debugging: First Three Things to Check When It Fails

When your serial monitor spits out errors, do not immediately rewrite the code. Hardware and configuration mismatches cause 95% of ESP32 I2C failures. If you see the error string [FATAL] BME280 init failed. Check wiring and I2C address. or the underlying ESP32 core error [E][Wire.cpp:420] requestFrom(): i2cWriteReadNonStop returned Error 263, check these three things in order:

1. I2C Address Mismatch (0x76 vs 0x77): The Bosch BME280 supports two addresses based on the SDO pin state. If SDO is tied to GND, the address is 0x76. If tied to VCC, it is 0x77. Run an I2C scanner sketch (available in the Arduino IDE examples under Wire > I2C_Scanner) to verify the exact address your breakout is broadcasting, and update the #define BME_I2C_ADDR accordingly.
2. Swapped SDA and SCL Lines: Unlike UART, I2C will not throw a loud error if you swap data and clock; it will simply time out and return Error 263 or fail the bme.begin() check. Verify GPIO 21 is physically connected to SDA, and GPIO 22 to SCL.
3. Missing Pull-Up Resistors or USB Brownout: If the I2C bus initializes but randomly drops out (returning NaN), your I2C lines are likely floating due to missing 4.7kΩ pull-ups. Alternatively, if the ESP32 reboots randomly during WiFi connection, your USB cable or port cannot supply the 500mA+ peak current the ESP32 draws during RF transmission. Use a high-quality, short USB data cable and a 5V/2A power brick.

Extending and Simplifying the Build

This baseline ESP32 tutorial is designed to be modular. Depending on your end goal, you should strip it down or build it up.

How to Simplify (Battery-Powered Remote Node):
If you are running this on a 18650 lithium cell via a TP4056 charger, WiFi and continuous polling will drain the battery in days. Strip out the WiFi.h library entirely. Replace the delay(5000) in the loop with ESP32 deep sleep. Configure the RTC GPIO to wake the board every 15 minutes, take a single reading, log it to the internal SPIFFS/LittleFS filesystem, and go back to sleep. This drops average current draw from ~80mA to under 15µA, yielding months of battery life.

How to Extend (Production IoT Dashboard):
Serial printing is fine for the bench, but for deployment, swap the serial output for an MQTT publisher. Use the PubSubClient library to publish JSON payloads to a Mosquitto broker running on a Raspberry Pi. From there, pipe the MQTT topics into Telegraf and store the time-series data in InfluxDB, visualizing it on a Grafana dashboard. For local feedback, wire an SSD1306 0.96-inch I2C OLED to the same SDA/SCL bus (I2C supports multiple devices as long as addresses don't conflict).

ESP32 Tutorial FAQ

Why does my ESP32 tutorial code fail to upload with "Timed out waiting for packet header"?

This is a bootloader synchronization failure. The ESP32 needs to be pulled into download mode manually if the auto-reset circuit on your specific DevKit clone is poorly designed. To fix it: click the "Upload" button in the Arduino IDE. When the console says "Connecting...", press and hold the BOOT button on the ESP32, then press and release the EN/RST button, and finally release the BOOT button. This forces the chip into UART download mode. Additionally, ensure you are using a USB cable with data lines; charge-only cables will trigger this exact timeout.

Which ESP32 tutorial board variant is best for beginners in 2026?

The standard ESP32-WROOM-32 DevKit V1 (30-pin) remains the most documented and beginner-friendly board due to its breadboard compatibility and massive community support. However, if you are buying new in 2026 and want native USB-C and better deep-sleep power management, the ESP32-S3 DevKitC-1 is the superior upgrade. Note that the S3 uses a different pinout and requires the esp32s3 board selection in the Arduino IDE, so you will need to adjust the I2C pin definitions in the code provided above.

How do I reduce power consumption in this ESP32 tutorial project?

The ESP32 is inherently power-hungry due to its dual-core 240MHz architecture and active WiFi radio. To minimize power: (1) Disable the WiFi radio when not transmitting using WiFi.disconnect(true) and WiFi.mode(WIFI_OFF). (2) Lower the CPU clock speed to 80MHz in the Arduino IDE Tools menu if you aren't doing heavy cryptography. (3) Utilize esp_deep_sleep_start() instead of delay(). In deep sleep, the ESP32 shuts down the CPU and RAM, drawing only ~10µA, waking only via the internal RTC timer or an external interrupt.