← Beginner's guide to ESP32

Build an ESP32 Wi-Fi clock on an OLED

A desk clock that sets itself from the internet, never drifts and handles daylight saving time automatically. It teaches you how to drive a display and how to get information from the network.

What you will learn

Before you start: do steps 1 to 5 of the beginner's guide. The weather station project introduces I2C, which this display also uses.

Fri 02 Oct 2026 14:35 09 top rows:yellow on atwo-colour panel
What the display shows. On a single-colour OLED the whole screen is one colour. On a yellow/blue panel the top 16 pixel rows are yellow, which suits a date header.

Parts you need

Some links are affiliate links, so I may earn a commission at no extra cost to you. As an Amazon Associate I earn from qualifying purchases. Details. Buy buttons open a store search; check the product matches before you order.

Wire it up

Board unplugged from USB while you wire. The display uses the same four wires as any I2C module.

Read the labels on your display. OLED modules print their four pin names along one edge, but the order is not the same on every module. Some are VCC, GND, SCL, SDA. Others, including the common yellow/blue "0.96 4P IIC" module, are GND, VCC, SCL, SDA. Connecting VCC and GND the wrong way round can damage the display. Match names, never positions.

Wiring shown by pin name. Red = power (3.3V), black = ground, yellow = clock (SCL), blue = data (SDA).
OLED pinConnects to (classic ESP32)
VCC3V3
GNDGND
SCLGPIO 22
SDAGPIO 21
Two common pin orders, left to right along the edge Order A VCC GND SCL SDA Order B (the yellow/blue "0.96 4P IIC" module) GND VCC SCL SDA
Same four signals, different order. Look at the print on your module before connecting anything.
Using an ESP32-S3 or ESP32-C3?
SignalClassic ESP32ESP32-S3ESP32-C3
SDAGPIO 21GPIO 8GPIO 8
SCLGPIO 22GPIO 9GPIO 9

Change SDA_PIN and SCL_PIN at the top of the sketch.

Install the display libraries

  1. In the Arduino IDE, open Sketch, Include Library, Manage Libraries.
  2. Search for Adafruit SSD1306 and click Install. Choose Install all when asked about dependencies (this includes Adafruit GFX Library and Adafruit BusIO).

The code

  1. Open a new sketch and replace everything with the code below. Fill in your Wi-Fi name and password, and choose your time zone string from the table underneath.
  2. Upload it. The display shows "Connecting Wi-Fi...", then "Syncing time...", then the clock.

Choose your time zone

WhereTZ_INFO value
US EasternEST5EDT,M3.2.0,M11.1.0
US CentralCST6CDT,M3.2.0,M11.1.0
US MountainMST7MDT,M3.2.0,M11.1.0
US PacificPST8PDT,M3.2.0,M11.1.0
UK / IrelandGMT0BST,M3.5.0/1,M10.5.0
Central EuropeCET-1CEST,M3.5.0,M10.5.0/3
Sydney, AustraliaAEST-10AEDT,M10.1.0,M4.1.0/3

Other places: search for "POSIX time zone string" and your city. The sign looks backwards: US Eastern is "5", which means five hours behind UTC.

How the code works

Test it

  1. After upload the display shows messages, then the time within a few seconds of the Wi-Fi connecting.
  2. Compare it with your phone. It should match to the second.
  3. Unplug the clock and plug it back in. It sets itself again, with no buttons or settings.

OLED burn-in: a bright image that never changes can slowly mark an OLED. For an always-on clock, turn it off at night, or shift the text a pixel or two every hour. Putting the clock on a power timer is the easiest fix.

Troubleshooting

ProblemWhat to try
Blank screenCheck all four wires and the pin names. Make sure VCC is on 3V3. Run the I2C scanner from the weather station guide: it should find a device at 0x3C (or 0x3D).
Serial says "OLED not found"Wrong address or wiring. Try 0x3D in display.begin().
Stuck on "Connecting Wi-Fi..."Check name and password. The ESP32 needs a 2.4 GHz network.
Stuck on "Syncing time..."Your network may block internet time servers (port 123). Try another network or a phone hotspot.
Time is an hour outWrong TZ_INFO. Check the table, including the daylight saving part.
Garbled or shifted pictureThe display may use the SH1106 chip (a common look-alike). Use the Adafruit SH110X library instead.
Upload fails: "Failed to connect"Hold the BOOT button while the upload starts.

Make it better

Open this project in the Build Finder →

Where to next

Project 5: Plant moisture monitor. Read an analog sensor and calibrate it.  ·  ← Project 3: Weather station

This guide was written from standard Arduino and ESP32 practice and the Adafruit SSD1306 library documentation. It has not been built on every display or ESP32 variant. Not affiliated with the part makers.