Build Project

Display Projects

ESP32 OLED Weather Clock: BME280, Wi-Fi and Local Time

Build an ESP32 SSD1306 weather clock with BME280 readings, NTP time, timezone rules and Wi-Fi recovery. Includes wiring, libraries and complete Arduino code.

BeginnerAges 12+90-150 minUnder $35Parent Safe
ESP32 OLED weather clock with display, BME280 sensor, and time/weather readout
Jump to a section

What You Will Build

A USB-powered desk clock with local HH:MM time and date, plus BME280 temperature, humidity and pressure on a 128×64 SSD1306 OLED. Weather is measured in the room, not fetched from an online forecast. The display keeps updating while Wi-Fi reconnects; without a sensor it remains a clock. Before the first NTP sync it shows a waiting message alongside available readings.

Before You Start

Classic ESP32-WROOM-32/32E DevKit with the named GPIOs exposed and unused. Select its exact board profile, or ESP32 Dev Module for an otherwise undocumented generic WROOM board. Arduino IDE 2.x and Arduino-ESP32 3.x; API review baseline 3.3.2, not a claim that it is the latest release. Other ESP32 families need their own pin/USB settings. Serial Monitor: 115200 baud. Examples are reviewed against documentation, not compiled or hardware tested in this content review.

Use a 128×64 I2C SSD1306 module (0x3C in this example; verify 0x3D if needed), and a BME280 I2C breakout documented for 3.3 V supply and 3.3 V bus signals. SH1106 displays need another driver. BMP280 has no humidity measurement. Both modules share SDA21/SCL22 with pull-ups to 3.3 V. No specific breakout vendor is assumed.

Parts

Wiring

The OLED and BME280 share I2C with different addresses. The diagram is a logical connection map, not a physical header layout. Follow actual module pin labels.

ESP32 OLED weather clock wiring diagram with SSD1306 OLED and BME280 on shared I2C

Open wiring diagram full size

  1. 1

    Unplug USB before rewiring. Verify both modules support 3.3 V supply and have no bus pull-ups to 5 V.

  2. 2

    Connect each module VCC/VIN to 3.3 V and GND to ESP32 GND; a VIN label does not prove 5 V compatibility.

  3. 3

    Connect both SDA pins to GPIO21 and SCL pins to GPIO22. Pin order varies by breakout.

  4. 4

    For BME280 labels SDI/SCK, SDI is SDA and SCK is SCL in I2C mode. Follow module documentation for CSB high and SDO address selection.

  5. 5

    Keep jumpers short. Confirm OLED 0x3C/0x3D and BME280 0x76/0x77 with an I2C scan before debugging Wi-Fi.

  6. 6

    Upload with your own credentials in place of the placeholders; open Serial Monitor at 115200 baud.

Wiring Reference

SignalESP32 PinDirectionNotes
OLED and BME280 SDAGPIO21I2C dataShared bus; pull-ups to 3.3 V
OLED and BME280 SCLGPIO22I2C clockWire.begin(21, 22)
Both module power / ground3.3 V / GNDPowerVerify 3.3 V-compatible breakouts
BME280 CSB / SDOModule-dependentMode / addressCSB high for I2C; SDO selects 0x76 or 0x77 per documentation

Libraries and Setup

  • Board and portInstall esp32 by Espressif Systems 3.x; verify the Serial-only first sketch from the IDE setup guide.
  • Adafruit SSD1306 and Adafruit GFX LibraryInstall in Library Manager with required dependencies, including Adafruit BusIO.
  • Adafruit BME280 Library and Adafruit Unified SensorInstall in Library Manager; accept required dependencies.
  • WiFi, Wire and time.hProvided by the ESP32 board package; no separate generic WiFi library needed.

Configure the Example

Replace YOUR_WIFI_SSID and YOUR_WIFI_PASSWORD with a reachable 2.4 GHz network. Do not publish real credentials. Captive portals or blocked DNS/NTP can prevent time sync even when Wi-Fi connects.

TIME_ZONE uses POSIX rules: UTC0 is UTC; PKT-5 is Pakistan UTC+5 (opposite sign to the usual UTC offset). A daylight-saving region needs verified transition rules, not a permanently added hour. For example, EST5EDT,M3.2.0/2,M11.1.0/2 describes US Eastern rules currently used; verify local rules. configTzTime applies local-time rules; NTP supplies the clock time.

Match OLED_ADDRESS and SCREEN_WIDTH/HEIGHT to the module. Sensor detection tries 0x76 then 0x77. readPressure returns Pa; dividing by 100 gives hPa. This is local absolute pressure, not a sea-level weather report.

Control and Recovery Behavior

ConditionResult
Wi-Fi absent at bootContinue drawing sensor/status data; retry every 30 seconds without an indefinite setup wait.
Wi-Fi drops after syncKeep the system clock running and show offline status. It can drift; there is no battery-backed RTC.
Network returnsRequest NTP on the disconnected-to-connected transition; periodic SNTP updates then continue.
Time not yet syncedShow a waiting message; use a 10 ms getLocalTime timeout rather than its default multi-second wait.
Sensor absent or invalidKeep time/status visible and show a warning; retry missing sensor initialization every 10 seconds.

Code

Install the libraries above and match the configuration and wiring before uploading.

oled-weather-clock.ino
#include <WiFi.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <Adafruit_BME280.h>
#include <time.h>
#include <math.h>

constexpr uint8_t I2C_SDA = 21, I2C_SCL = 22;
constexpr uint8_t OLED_ADDRESS = 0x3C;
constexpr int SCREEN_WIDTH = 128, SCREEN_HEIGHT = 64;
const char* WIFI_SSID = "YOUR_WIFI_SSID";
const char* WIFI_PASSWORD = "YOUR_WIFI_PASSWORD";
const char* TIME_ZONE = "UTC0"; // Example: "PKT-5" for UTC+5.
constexpr uint32_t WIFI_RETRY_MS = 30000, SENSOR_RETRY_MS = 10000;
constexpr uint32_t FRAME_MS = 2000;
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);
Adafruit_BME280 bme;
bool bmeReady = false, wasConnected = false;
uint32_t lastWifiAttempt = 0, lastSensorAttempt = 0, lastFrame = 0;

bool deviceResponds(uint8_t address) {
  Wire.beginTransmission(address);
  return Wire.endTransmission() == 0;
}
bool beginBME280() {
  if (bme.begin(0x76, &Wire)) return true;
  return bme.begin(0x77, &Wire);
}
void setup() {
  Serial.begin(115200);
  Wire.begin(I2C_SDA, I2C_SCL);
  // begin() alone does not prove the OLED is present; also check I2C ACK.
  if (!deviceResponds(OLED_ADDRESS) ||
      !display.begin(SSD1306_SWITCHCAPVCC, OLED_ADDRESS, true, false)) {
    Serial.println("OLED address/init failed; check power, wiring and controller.");
    while (true) delay(1000);
  }
  bmeReady = beginBME280();
  Serial.println(bmeReady ? "BME280 ready" : "BME280 missing; clock-only mode");
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(1);
  display.setCursor(0, 0);
  display.println("Weather clock starting");
  display.display();
  WiFi.mode(WIFI_STA);
  WiFi.setAutoReconnect(true);
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  lastWifiAttempt = millis();
  lastSensorAttempt = millis();
}
void loop() {
  const uint32_t now = millis();
  const bool connected = WiFi.status() == WL_CONNECTED;
  if (connected && !wasConnected) {
    Serial.print("Wi-Fi connected: "); Serial.println(WiFi.localIP());
    configTzTime(TIME_ZONE, "pool.ntp.org", "time.nist.gov");
    Serial.println("NTP requested; waiting for valid time");
  } else if (!connected && wasConnected) {
    Serial.println("Wi-Fi lost; keeping display active");
    lastWifiAttempt = now;
  }
  wasConnected = connected;
  if (!connected && now - lastWifiAttempt >= WIFI_RETRY_MS) {
    lastWifiAttempt = now;
    Serial.println("Retrying Wi-Fi; check SSID/password if this repeats");
    WiFi.reconnect();
  }
  if (!bmeReady && now - lastSensorAttempt >= SENSOR_RETRY_MS) {
    lastSensorAttempt = now;
    bmeReady = beginBME280();
    if (bmeReady) Serial.println("BME280 recovered");
  }
  if (now - lastFrame < FRAME_MS) { delay(10); return; }
  lastFrame = now;
  struct tm timeinfo = {};
  const bool timeReady = getLocalTime(&timeinfo, 10);
  display.clearDisplay();
  display.setCursor(0, 0);
  if (timeReady) {
    char clockText[6], dateText[18];
    strftime(clockText, sizeof(clockText), "%H:%M", &timeinfo);
    strftime(dateText, sizeof(dateText), "%a %d %b", &timeinfo);
    display.setTextSize(2); display.println(clockText);
    display.setTextSize(1); display.println(dateText);
  } else {
    display.setTextSize(1); display.println("Time: waiting for NTP");
    Serial.println("Time not synced; check internet/DNS/NTP");
  }
  if (bmeReady) {
    const float t = bme.readTemperature(), h = bme.readHumidity();
    const float pressure = bme.readPressure() / 100.0F;
    if (isfinite(t) && isfinite(h) && isfinite(pressure) && pressure > 0) {
      display.print("Temp: "); display.print(t, 1); display.println(" C");
      display.print("Hum:  "); display.print(h, 0); display.println(" %");
      display.print("Pres: "); display.print(pressure, 0); display.println(" hPa");
    } else {
      display.println("BME280 read failed");
      Serial.println("BME280 invalid readings; will retry initialization");
      bmeReady = false; lastSensorAttempt = now;
    }
  } else display.println("BME280 missing");
  display.println(connected ? "Wi-Fi online" : "Wi-Fi offline: retry");
  display.display();
}

How the Code Works

setup starts I2C, checks the OLED address, tries both sensor addresses and starts Wi-Fi without a blocking connection loop. display.begin uses periphBegin=false because Wire is configured already. An I2C ACK proves a responding device, not the controller identity.

The loop tracks connection changes and retries Wi-Fi at 30-second intervals. Every two seconds it draws time/date, valid readings and status. Missing sensor initialization is retried every ten seconds; non-finite values are not shown as weather. The short getLocalTime timeout keeps a missing time sync from freezing the display.

Expected Output

After NTP succeeds the OLED shows local HH:MM, date, temperature in C, humidity in %, pressure in hPa and Wi-Fi status, updating about every two seconds. Before sync it shows a waiting message; without BME280 it keeps clock/status visible. Serial reports connection/sensor diagnostics. These are expected behaviors to verify, not recorded measurements.

Troubleshooting

  • OLED blank or init failed Scan I2C; match 0x3C/0x3D, SDA21/SCL22, power and ground. Verify SSD1306 128×64 rather than SH1106 or 128×32. ACK alone does not identify the controller.
  • BME280 missing or humidity unavailable Check 0x76/0x77 and I2C mode labels SDI/SCK/CSB/SDO. BMP280 lacks humidity; a wrong device remains in clock-only mode.
  • Wi-Fi keeps retrying Replace both placeholders; check 2.4 GHz SSID, password, signal and router permissions. The display continues updating; after restoring access look for its IP message.
  • Wi-Fi online but time waiting Association is not internet access. Check DNS, outbound UDP123 and captive portal restrictions. Allow time for the first NTP sync.
  • Time differs by hours or daylight saving Edit TIME_ZONE using verified POSIX rules. PKT-5 means UTC+5; a fixed offset does not follow seasonal changes.
  • OLED works alone but fails with sensor Check swapped wires, addresses, pull-up voltage and short jumpers. Remove power before isolating each module.

Checks to Perform on Your Build

  • Verify the Serial-only first sketch and board/port before adding modules.
  • Scan addresses and verify the shared bus at 3.3 V.
  • Compare local time/date against a trusted clock after sync.
  • Remove router access: readings/status should continue; restore it and check reconnection.
  • With power off remove BME280 and restart: clock/status should still work.
  • Check units and room readings; this is not a calibrated weather instrument.

Practical Design Notes

Bring up OLED, BME280, Wi-Fi and time sync in that order. Place BME280 away from regulator heat and direct sunlight. The local display remains useful when a network service fails.

Module supply and bus pull-up voltages are separate checks: a VIN regulator does not prove SDA/SCL are ESP32-safe. Parallel breakout pull-ups can become too strong on larger buses; consult actual module documentation and keep this two-device bus short.

Upgrade Ideas

  • Add a setup screen for timezone and 12-hour or 24-hour display.
  • Show pressure trend arrows after storing recent BME280 readings.
  • Alternate between clock, weather, and Wi-Fi status screens.
  • Add deep sleep or dimming for a desk clock enclosure.

FAQs

Does this fetch a weather forecast?

No. BME280 measures local room conditions; Wi-Fi supplies NTP clock synchronization.

Can it work offline?

After sync the system clock continues while powered, with possible drift. A restart without internet has no valid time until NTP succeeds. No battery-backed RTC is included.

Why is local time wrong?

Set TIME_ZONE to verified POSIX rules. UTC0 is UTC and PKT-5 is UTC+5; daylight-saving regions need transition rules.

Review, Testing, and References

Author: Abdul Mubeen and the ESP32 Engine editorial team. Last updated: 2026-10-08. Reviewed: wiring logic, Arduino code structure, beginner safety, and learning sequence.

Educational level: Beginner. Estimated completion time: 90-150 min. This project is for learning and prototyping; production or unattended hardware needs additional engineering review.