TimeLib: a date and time kept by the Arduino itself
The Time library, included as TimeLib.h, keeps the date and time in software. You set it once with setTime(), or give it a source with setSyncProvider() (a real-time clock, a GPS or an NTP request), and from then on it counts forward from millis(). hour(), minute(), second(), day(), month(), year() and weekday() read the current time; each also takes a time_t to read a stored one.
Built in on Mokxi: #include <TimeLib.h> and it builds, with nothing to install. Free, and no account needed.
What Time does
Time is held as a time_t, the number of seconds since January 1, 1970 (Unix time), which makes arithmetic easy: add 3600 for an hour, or subtract two times for the gap. makeTime() builds a time_t from a tmElements_t of fields, and breakTime() goes the other way. The helpers dayStr() and monthStr() turn numbers into names.
Without a sync provider the clock is only as good as the board鈥檚 crystal or resonator, and it starts over at power-up. A sync provider is called at start and then every 300 seconds by default; setSyncInterval() changes that.
| Library Manager name | Time |
|---|---|
| Author | Michael Margolis, Paul Stoffregen |
| Include | #include <TimeLib.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <TimeLib.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "Time" by Michael Margolis, Paul Stoffregen from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add Time to lib_deps in PlatformIO. Mokxi follows the calls of release 1.6.1, so a sketch written here builds there too.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
setTime(12, 30, 0, 1, 10, 2026)
Sets the clock: hour, minute, second, day, month, year. setTime(t) takes a time_t instead.
hour()
The current hour, 0 to 23. minute(), second(), day(), month(), year() and weekday() (1 is Sunday) work the same way.
Serial.print(hour());
Serial.print(':');
if (minute() < 10) Serial.print('0');
Serial.println(minute());time_t t = now();
The current time as seconds since 1970. Read it once and pass it to hour(t), minute(t) and friends so every field comes from the same second.
tmElements_t tm;
A time split into Second, Minute, Hour, Wday, Day, Month and Year (counted from 1970).
time_t t = makeTime(tm);
Builds a time_t from the fields in tm.
breakTime(t, tm)
Splits a time_t back into the fields of tm.
setSyncProvider(getRtcTime)
Gives the library a function that returns the true time as a time_t, called at start and every sync interval.
setSyncInterval(60)
How many seconds between calls to the sync provider.
timeStatus()
timeNotSet, timeNeedsSync or timeSet, so the sketch can tell a real time from one that was never set.
adjustTime(3600)
Shifts the clock by that many seconds, for example to apply a time zone by hand.
Example: A clock that keeps time on millis()
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <TimeLib.h>
void printDigits(int digits) {
Serial.print(':');
if (digits < 10) Serial.print('0');
Serial.print(digits);
}
void setup() {
Serial.begin(9600);
setTime(23, 59, 58, 31, 12, 2025); // two seconds to the new year
}
void loop() {
Serial.print(hour());
printDigits(minute());
printDigits(second());
Serial.print(' ');
Serial.print(day());
Serial.print(' ');
Serial.print(monthShortStr(month()));
Serial.print(' ');
Serial.println(year());
delay(1000);
}Common errors and how to fix them
fatal error: Time.h: No such file or directory, or the wrong Time.h is used
The library鈥檚 header is TimeLib.h. Older tutorials include Time.h, which clashes with the C library鈥檚 time.h on systems that ignore case. Change the line to #include <TimeLib.h>.
The clock starts at 00:00:00 January 1, 1970 on every reset
Nothing set the time after power-up. Call setTime() in setup(), or attach a real-time clock with setSyncProvider() so the time comes back after a reset.
The clock gains or loses minutes over a day
Without a sync provider the time is only as good as the board鈥檚 oscillator, and a ceramic resonator can drift a lot. Sync from an RTC module or NTP every few minutes.
Try Time without installing anything
Open the example, change the sketch, and keep your version in a free account.