What you will learn
- How to draw text on a pixel display with the Adafruit GFX library.
- How NTP (Network Time Protocol) gives the ESP32 the exact time, with no clock chip needed.
- How to set your time zone so daylight saving changes happen on their own.
Before you start: do steps 1 to 5 of the beginner's guide. The weather station project introduces I2C, which this display also uses.
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.
| OLED pin | Connects to (classic ESP32) |
|---|---|
| VCC | 3V3 |
| GND | GND |
| SCL | GPIO 22 |
| SDA | GPIO 21 |
Using an ESP32-S3 or ESP32-C3?
| Signal | Classic ESP32 | ESP32-S3 | ESP32-C3 |
|---|---|---|---|
| SDA | GPIO 21 | GPIO 8 | GPIO 8 |
| SCL | GPIO 22 | GPIO 9 | GPIO 9 |
Install the display libraries
- In the Arduino IDE, open Sketch, Include Library, Manage Libraries.
- Search for Adafruit SSD1306 and click Install. Choose Install all when asked about dependencies (this includes Adafruit GFX Library and Adafruit BusIO).
The code
- 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.
- Upload it. The display shows "Connecting Wi-Fi...", then "Syncing time...", then the clock.
Choose your time zone
| Where | TZ_INFO value |
|---|---|
| US Eastern | EST5EDT,M3.2.0,M11.1.0 |
| US Central | CST6CDT,M3.2.0,M11.1.0 |
| US Mountain | MST7MDT,M3.2.0,M11.1.0 |
| US Pacific | PST8PDT,M3.2.0,M11.1.0 |
| UK / Ireland | GMT0BST,M3.5.0/1,M10.5.0 |
| Central Europe | CET-1CEST,M3.5.0,M10.5.0/3 |
| Sydney, Australia | AEST-10AEDT,M10.1.0,M4.1.0/3 |
How the code works
Adafruit_SSD1306 display(128, 64, &Wire, -1)describes a 128 by 64 pixel screen on the I2C bus.- Drawing happens in memory.
clearDisplay()wipes it,setCursor(x, y)picks where,print()draws text, anddisplay()finally sends it to the screen. setTextSize(3)makes each character 3 times bigger (18 by 24 pixels), which is why "14:35" fits the width.configTzTime()starts the time sync in the background.getLocalTime()returns the time once it is ready. Daylight saving changes happen on their own because the zone string includes the rules.strftime()turns the time into text.%His hours (24-hour),%Mminutes,%Sseconds,%a %d %b %Ythe date.
Test it
- After upload the display shows messages, then the time within a few seconds of the Wi-Fi connecting.
- Compare it with your phone. It should match to the second.
- 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
| Problem | What to try |
|---|---|
| Blank screen | Check 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 out | Wrong TZ_INFO. Check the table, including the daylight saving part. |
| Garbled or shifted picture | The 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
- Add a button to flip between 12 and 24 hour time, and between date styles.
- Show the temperature from a BME280 (the weather station sensor) on the second line.
- Add an alarm: when the time matches, sound the buzzer from project 1.
- Dim or blank the display at night using
display.dim(true)ordisplay.ssd1306_command(SSD1306_DISPLAYOFF).
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