ESP32Time: the ESP32’s own clock, set and read in one line
Every ESP32 keeps a clock in its C library, the one configTime() and time() use, but reading and setting it takes a struct tm and a few calls to the standard C functions. ESP32Time, by Felix Biego, wraps that clock in a small class: setTime() with numbers, getTime() with a format string, and getters for each field. No external RTC module is needed.
Built in on Mokxi: #include <ESP32Time.h> and it builds, with nothing to install. Free, and no account needed.
What ESP32Time does
The constructor takes an offset in seconds from UTC, so ESP32Time rtc(3600) reads an hour ahead. setTime() takes seconds, minutes, hours, day, month and year, or a Unix epoch, and treats what you give it as UTC; every getter except getEpoch() adds the offset. getTime() accepts the same strftime codes as the C library, such as %A, %B, %d and %H:%M:%S.
Because it is only the chip’s clock, the time is lost at every power cut and reset, and it drifts a little each day. Pair it with NTP through configTime() on a networked board, or with a DS3231 module when there is no network. In Mokxi this library is fully simulated on the ESP32, C3 and S3 boards; the example sets 17 January 2021 and prints it each second.
| Library Manager name | ESP32Time |
|---|---|
| Author | Felix Biego |
| Include | #include <ESP32Time.h> |
| Boards | ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
Install it
It builds on ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32.
In Mokxi it is built in: #include <ESP32Time.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "ESP32Time" by Felix Biego from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add ESP32Time to lib_deps in PlatformIO. Mokxi follows the calls of release 2.0.6, so a sketch written here builds there too.
The calls you will use
In the order a sketch meets them.
ESP32Time rtc(3600)
Creates the clock with an offset of 3600 seconds from UTC. Leave the argument out for UTC.
rtc.setTime(30, 24, 15, 17, 1, 2021)
Sets the time to 15:24:30 on 17 January 2021, as UTC. Seconds come first; the year comes last.
rtc.getTime("%A, %B %d %Y %H:%M:%S")
Returns the local time formatted with strftime codes. With no argument it gives HH:MM:SS.
rtc.getDateTime(true)
The date and time in one String, with the day and month spelled out when passed true and abbreviated otherwise.
rtc.getEpoch()
Seconds since 1970 in UTC, without the offset. Use getLocalEpoch() for the offset version.
rtc.getHour(true)
The hour, 0 to 23 when passed true. With no argument it is 1 to 12, for use with getAmPm().
rtc.getMonth()
The month from 0 for January to 11 for December, as in the C library. Add 1 before printing.
rtc.getTimeStruct()
The local time as a struct tm, for code that already works with the C time functions.
struct tm t = rtc.getTimeStruct();
Serial.println(t.tm_year + 1900);Example: Set the ESP32 clock and print it as a date
On the ESP32-C3-DevKitM-1. It runs in the browser exactly as printed.
#include <ESP32Time.h>
ESP32Time rtc(3600); // an hour ahead of UTC
void setup() {
Serial.begin(115200);
rtc.setTime(30, 24, 15, 17, 1, 2021); // 17 January 2021, 15:24:30
}
void loop() {
Serial.println(rtc.getTime("%A, %B %d %Y %H:%M:%S"));
Serial.println(rtc.getDateTime(true));
Serial.print("epoch ");
Serial.print(rtc.getEpoch());
Serial.print(", hour ");
Serial.print(rtc.getHour());
Serial.print(' ');
Serial.println(rtc.getAmPm());
delay(1000);
}Common errors and how to fix them
getTime() is an hour off from the time I set
setTime() takes UTC and the getters add the offset from the constructor. With ESP32Time rtc(3600), setting 15:24 reads back as 16:24. Either set the UTC time, or construct with no offset if the numbers you set are already local.
The date shows December when it should be January
getMonth() counts from 0, so January is 0. Print getMonth() + 1, or use getTime("%m") or getDate(), which already give the calendar month.
The time goes back to 2021 after every reset
The ESP32’s clock is not battery backed, so a reset or power cut loses it and the library falls back to its default date. Set it from NTP with configTime() at startup, or read it from a DS3231 module.
Questions and answers
Does ESP32Time work with configTime()?
Yes. Both use the same C library clock, so after configTime() syncs over NTP, ESP32Time’s getters return the synced time with no extra code.
Try ESP32Time without installing anything
Open the example, change the sketch, and keep your version in a free account.