Introduction: Simplest ESP8266 Local Time Internet Clock With OLED

Picture of Simplest ESP8266 Local Time Internet Clock With OLED

I was looking for a straightforward clock to use with a 128x64 OLED I got from Adafruit but found that a lot of the implementations were too cumbersome, involved a ton of code, weren't clear on what NTP servers to use and how, and basically offered very little in terms of making a clock with the LOCAL time (not UTC, which is easy enough to get). So I set about doing my own research and ended up with this simple clock that leverages already made libraries to minimize the code footprint, while offering some interesting tweaks in displaying the time (like AM/PM, 12-hour format, names for months, days, etc). This instructable assumes you have some experience programming ESP-01s but if not, there are a ton of wonderful tutorials available on Instructables! Enjoy!

Step 1: Components

For this instructable you will need:

  • ESP8266-01 module
  • 128x64 OLED with I2C interface
  • 3.3V power supply
  • A way to program the ESP-01

Step 2: Wire It Up!

Picture of Wire It Up!

The wiring is simple. Just follow the diagram above and connect the wires. Then get a 3.3V power supply (I used a step-down module to go from 12V to 3.3 but you can use whatever you have in your arsenal as long as it outputs 3.3V and at least 0.5 A).

Step 3: Program the ESP-01

This step can be frustrating if you haven't done it before, but once you get the hang of how the ESP boards work and have the correct drivers and libraries installed in Arduino, you can go ahead and use the following code. But first, you will need to download and install the following libraries:

You may need to modify some of the code according to what OLED you're using (as long as it's SSD1306 it'll work but you may need to update the hex I2C address) and then you may have to change some of the Timezone rules depending on your timezone and daylight savings time rules. Then upload the code attached and you should be done!

Step 4: See It Go!

Picture of See It Go!

Once you have programmed the ESP, plugged everything in, make sure you have 3.3V going into the setup and then power it on and see your correct time on the tiny display!


meahdi (author)2017-07-23


I like this project

How can i change time zone to my local time

wangzhen (author)meahdi2017-12-24

youcan do that: setTime(nettime + x * 3600);

Im in china so x = 8 setTime(nettime + 8 * 3600);

meahdi (author)wangzhen2017-12-25

Thanks for your help

Löwenherz made it! (author)2017-09-25

Great, thank you for this well functioning simple example!
I'd never been able to create it myself. I run this sketch on a NodeMCU ESP8266 Lolin with a few adaption in my code. Simply awsom!

RomanL33 (author)2017-09-14

Dobrý den, poradí mi někdo jak změním časové pásmo? Děkuji Roman

meahdi (author)2017-07-23


I like this project

How can i change time zone to my local time

meahdi (author)2017-07-23


I like this project

How can i change time zone to my local time

meahdi (author)2017-07-23


I like this project

How can i change time zone to my local time

meahdi (author)2017-07-23


I like this project

How can i change time zone to my local time

meahdi (author)2017-07-23


I like this project

How can i change time zone to my local time

meahdi (author)2017-07-23


I like this Project and want to make it

How can i change time zone to my local time?

QuickFix (author)2017-07-09

Thanks for this project; I needed some working example code and your's just fit the bill.

I had to include "TimeLib.h" to "Timezone.cpp" (got both libraries from the GitHub-master) or else it wouldn't compile

nodoubtman (author)2017-06-16

Thank you so much!!!... i was seeking for this kind of project

you are the best :))

soubir15 (author)2017-05-18

Hi Michael,

After using this clock for a few days, there seems to me a time sync problem. First the time goes off by a few seconds and later off by a few minutes. Any insight why this is happening. I am already using my local ntp server.

soubir15 (author)2017-05-11

Hi There,

This is a great a simple code for a person like me, I made one. Thank you so much for this. I just have one question, I would like to increase the size of the digits, how do I do that ?

MichaelB247 (author)soubir152017-05-11

The digit size is controlled by the SSD1306.h library so you can check out their documentation on Github:
Unfortunately, 24 is the biggest supported size on the default font with this library but the link above contains some info about custom fonts under the heading 'Text operations'. Hope this helps

soubir15 (author)MichaelB2472017-05-11

Thank you for your reply. This clock is great , but just want a bigger display. Do you suggest using 1.3" display or you have any other recommendations ?

Thanks in advance.


MichaelB247 (author)soubir152017-05-11

What's pictured is actually a 1.3" display so as far as I know that's the biggest size that's common with the I2C LCDs...

DavidR43 (author)2017-04-29

Is there any tutorial to upload program on ESP8266 via FTDI? Please Help

MichaelB247 (author)DavidR432017-05-01

I found this resource to be very helpful:
Only thing I forgot to do was to disconnect the GPIO 0 pin when not uploading to the ESP (which wasn't really clear in the tutorial). Other than that, the guide is a great place to start. Hope this helps.

fjs11 made it! (author)2017-04-27

Easy to build, I used an ESP-01, 128x64 Display and a regulator for 3.3 V. Yes, I changed language and time display to 24hour.

ChrisP105 (author)fjs112017-04-28


Can you let me know what regulator you used? I'm having trouble finding something that will handle the 0.5A pull.

fjs11 (author)ChrisP1052017-04-28

I used a part from Aliexpress "5V To 3.3V DC-DC Step-Down Power Supply Buck Module AMS1117 800MA",

10 pcs for 3.43 $.

MichaelB247 (author)ChrisP1052017-04-28

You should look at AMS1117 for a good, cheap regulator that's also quite small. That, plus a USB port or charger and a decoupling 10 uF capacitor and you should be good to go. Takes some soldering but it ends up being cheaper and smaller than off-the-shelf stuff.

MichaelB247 (author)fjs112017-04-28

Very nice! I like the idea of using a rechargeable Li-ion battery and making the whole thing portable!

BobM9 (author)2017-04-26

Finally, something that will convert time for me. I dreaded having to write the code myself. A good source for time, instead of say a timezone server would be, you can connect to the HTTP, pull the HTML on a simple search, and look for "Date:" and it returns the date time in GMT at +1 character. You should be able to use this for local time then in combination with the libraries he has here. seems to be much faster than connecting to servers that have the time exposed for some reason - guessing bandwidth they use.

MichaelB247 (author)BobM92017-04-28

Yes, using the HTML headers from the GET request will give you the same UTC time. I did try going that route too, but it wasn't quite as simple as using the NTP library. I did also notice the ntp servers being a bit laggy but oh well..

BobM9 (author)MichaelB2472017-04-28

When I swing back around to that project I will post the interface if needed. I was going to use it for a temperature alert that emailed to GMAIL every couple hours when required. I got sidelined when I realized that the deepsleep mode on the 8266 really only had a 15 minute (roughly) usability. So, I'm working on both the wake-up circuit and using the non-volatile memory for a count down in 15 min intervals. When I'm done with that I will get back to the GMT conversion. It can't be that hard. The server response time thing can cause real problems with timeouts if your project is say a PIR detector for intrusion that needs to function quickly. So, the google thing was pretty useful, but only until GMT can be converted to local. But I still need to look at these in any case. THX

mjrovai made it! (author)2017-04-26

Great and simple project. Also works fine with NodeMCU.

==> Data to I2C SDA (GPIO 0 ==> NodeMCU D3)

==> Clock to I2C SCL (GPIO 2 ==>NodeMCU D4)

// Clk to I2C SCL (GPIO 2 ==>D4)

dipa57 made it! (author)2017-04-25

Nice, thank you for searing with us...

florindgis (author)2017-04-22

Very nice work and simple!!!!

It would be nice if you could add some simple things like: dim the display according to ambient light (at night display could be too bright) and turn on the display only when needed (e.g. to save battery life).

That would ad just a few components (a LDR, a simple momentary switch, an IR sensor for distance -sensing the waive of hand or a mic -make a noise awaken the display).

The clock will still be simple and compact.

Anyway, very nice work!

TomK32 (author)florindgis2017-04-22

Dimming those OLEDs is possible but the effect almost unnoticeable. A bigger issue is the digits burning into it like we had with the CRT monitors in the olden days.
Turning off the wifi after getting the date, that's something to consider, also reducing how often the time is pulled (currently every minute, that's far too often)

florindgis (author)TomK322017-04-24

Turning off the display when not needed (avoiding "CRT like effect") and turning off wifi would be nice to be implemented.

Maibe in an upgrade or future project?

MichaelB247 (author)florindgis2017-04-24

Yes, the 'improved' version would have a proper clock object to count seconds/minutes/hours using the internal microcontroller and then only sync the time with the server every few hours (or less?) But while the current code is not as efficient as it's constantly connected, it is simpler. But yes, in the future I want to add the 'offline' functionality somehow. I'll have to look into OLED burn-in effects as I haven't had much experience on that front

JeffM15 (author)MichaelB2472017-04-25

Maybe move the data around on the screen to avoid burn in.

TomK32 (author)MichaelB2472017-04-24

Michael, it already has a "proper clock object", that's why you are calling timeClient.update() which keeps time according to the accuracy of the micro and only refreshens from the ntp server every NTP_INTERVAL seconds.

MichaelB247 (author)TomK322017-04-25

Right! I've been playing with it and yes, I will be changing the sync interval to a lot longer so the connection doesn't get used so much

grayl (author)2017-04-23

Correct me if I am wrong, but this looks like it requires a constant Internet connection to get the time to display, right?

MichaelB247 (author)grayl2017-04-24

Yes. You could change it and only connect it as you like but currently it pulls the time through the UDP connection every 10 seconds.

MichaelB247 (author)MichaelB2472017-04-25

So correction: it keeps the UDP port open for syncing but you can set sync interval to be way more than 10 seconds - the time client object keeps track of time between syncs

MichaelB247 (author)MichaelB2472017-04-25

That said, you would have to change the code somewhat since currently it checks whether the connection is open every 10 seconds and only displays time if it is

JeffM15 (author)MichaelB2472017-04-25

Suggestion. Maybe add a I2C - RTC $1 on eBay. Change the code to read the RTC and update display. and then hit NTP server and update RTC every 6 hours over the inet.
Just a suggestion.


GabrielK32 (author)2017-04-25

Thank you for sharing!
You may be interested to have a look in my project concerning timezones as it was a nightmare for me :)

src/core/ITime and src/core/TZTime are two functions you may be interested in.
I have moved to PlatformIO instead of Arduino IDE (easier to develop).

GabrielK32 (author)GabrielK322017-04-25

I bought these NodeMCU V3 that simplify the development on the ESP8266 :)

josefn1 (author)2017-04-22

Very nice and simple project.
Could you add sketch for 24-hour format?

TomK32 (author)josefn12017-04-22

It's just a few simple changes as you can see here:

This is the file you can copy and try out.

josefn1 (author)TomK322017-04-23

Thanks, time is now displayed in a 24-hour format.

About This Instructable




More by MichaelB247:Simplest ESP8266 Local Time Internet Clock With OLEDESP8266 ESP-01 Programming JigAdding Daylight Savings Time to Your RTC
Add instructable to: