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
- ESP32 DevKit boardMain controller with Wi-Fi
- BME280 environmental sensorMeasures temperature, humidity, and pressure
- SSD1306 OLED displayShows clock and weather readings
- Breadboard and jumper wiresPrototype the shared I2C bus
- USB data cableProgramming and testing
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.
-
1
Unplug USB before rewiring. Verify both modules support 3.3 V supply and have no bus pull-ups to 5 V.
-
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
Connect both SDA pins to GPIO21 and SCL pins to GPIO22. Pin order varies by breakout.
-
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
Keep jumpers short. Confirm OLED 0x3C/0x3D and BME280 0x76/0x77 with an I2C scan before debugging Wi-Fi.
-
6
Upload with your own credentials in place of the placeholders; open Serial Monitor at 115200 baud.
Wiring Reference
| Signal | ESP32 Pin | Direction | Notes |
|---|---|---|---|
| OLED and BME280 SDA | GPIO21 | I2C data | Shared bus; pull-ups to 3.3 V |
| OLED and BME280 SCL | GPIO22 | I2C clock | Wire.begin(21, 22) |
| Both module power / ground | 3.3 V / GND | Power | Verify 3.3 V-compatible breakouts |
| BME280 CSB / SDO | Module-dependent | Mode / address | CSB 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
| Condition | Result |
|---|---|
| Wi-Fi absent at boot | Continue drawing sensor/status data; retry every 30 seconds without an indefinite setup wait. |
| Wi-Fi drops after sync | Keep the system clock running and show offline status. It can drift; there is no battery-backed RTC. |
| Network returns | Request NTP on the disconnected-to-connected transition; periodic SNTP updates then continue. |
| Time not yet synced | Show a waiting message; use a 10 ms getLocalTime timeout rather than its default multi-second wait. |
| Sensor absent or invalid | Keep 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.
#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.

