Arduino library · Network

NTPClient: the time of day from an NTP server

Yes, with limits. You can use the NTPClient library online in Mokxi with nothing to install, and the sketch runs in your browser. Part of it is not simulated, and the notes below say which. The example below, "ESP32 NTP clock on a TM1637 display", runs on the ESP32 DevKit V1.

Built in on Mokxi: #include <NTPClient.h> and it builds, with nothing to install. Free, and no account needed.

What NTPClient does

An ESP8266 or ESP32 has no idea what time it is when it powers up. NTPClient, from the arduino-libraries organization, fixes that by asking a Network Time Protocol server over UDP and keeping the answer: after one successful update() the board can print the hours, minutes and seconds, or hand back the Unix epoch for a logger or a schedule.

You build it on a WiFiUDP object, name a server pool such as pool.ntp.org, give an offset from UTC in seconds and an update interval in milliseconds. Call begin() once WiFi is up and update() in loop(); update() only asks the server again when the interval has passed, so calling it every pass is cheap. forceUpdate() asks right away.

Two gaps surprise people. The library knows nothing about daylight saving, so the offset is fixed until you change it with setTimeOffset(). And the official release has no date function: getFormattedTime() gives HH:MM:SS only, so turn getEpochTime() into a date with gmtime() or TimeLib. In Mokxi there is no UDP and no NTP server, so the time comes from the simulation’s own clock, which starts at 2026-01-01 00:00:00 UTC, and the serial monitor says so.

Library Manager nameNTPClient
AuthorFabrice Weinberg (arduino-libraries)
Include#include <NTPClient.h>
BoardsESP32-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, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi
In the simulatorRuns, with a gap the note below names.

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, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi.

In Mokxi it is built in: #include <NTPClient.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "NTPClient" by Fabrice Weinberg (arduino-libraries) from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add NTPClient to lib_deps in PlatformIO. Mokxi follows the calls of release 3.2.1, so a sketch written here builds there too.

What to know in the simulator: NTP is simulated, so this is not the real current time: the network carries no UDP and cannot reach an NTP server, and the simulation does not know today’s date. An update while the board is on the network sets the simulation’s own clock, 2026-01-01 00:00:00 UTC at power-up plus the seconds since (plus the offset), the same clock configTime() and http://time.mokxi/ give, and the serial monitor says so once.

The calls you will use

In the order a sketch meets them.

NTPClient timeClient(ntpUDP, "pool.ntp.org", 3600, 60000)

Creates the client on a WiFiUDP you declared first, with the server, an offset of 3600 seconds (UTC+1) and a refresh every 60 seconds.

timeClient.begin()

Opens the UDP port. Call it after WiFi.status() reports WL_CONNECTED.

timeClient.update()

Asks the server again only when the update interval has passed, and returns true when the time was refreshed. Put it in loop().

timeClient.forceUpdate()

Asks the server now, whatever the interval, and returns true on an answer. Handy once in setup() so the first reading is right.

timeClient.getFormattedTime()

The local time as a String in HH:MM:SS form, offset included.

timeClient.getEpochTime()

Seconds since 1 January 1970, with the offset added. Pass it to gmtime() or TimeLib for the date.

time_t t = timeClient.getEpochTime();
struct tm *d = gmtime(&t);
Serial.printf("%04d-%02d-%02d\n", d->tm_year + 1900, d->tm_mon + 1, d->tm_mday);

timeClient.getHours()

The hour, 0 to 23. getMinutes() and getSeconds() work the same way, and getDay() gives 0 for Sunday to 6 for Saturday.

timeClient.setTimeOffset(-18000)

Changes the offset in seconds, here UTC-5. Call it again when daylight saving starts or ends.

Example: ESP32 NTP clock on a TM1637 display

On the ESP32 DevKit V1. It runs in the browser exactly as printed.

sketch.ino · ESP32 DevKit V1
/*
 * ESP32 NTP clock: the time of day from the internet on a TM1637 four-digit
 * display, with the colon blinking once a second.
 *
 *   TM1637   CLK -> GPIO 18 (D18), DIO -> GPIO 19 (D19)
 *            VCC -> 3V3, GND -> GND
 *
 * Libraries: NTPClient (arduino-libraries) and TM1637Display (avishorp),
 * both in the Arduino Library Manager.
 *
 * The board joins WiFi, then NTPClient asks an NTP server for the time over
 * UDP and asks again every 10 minutes. Between answers it counts on from
 * millis(), so the display changes every minute without a request.
 *
 * Set UTC_OFFSET to your time zone in seconds: -5 hours is New York in
 * winter (EST), 3600 is Central Europe in winter, 19800 is India. NTP itself
 * knows nothing of time zones or daylight saving: it answers UTC.
 *
 * In Mokxi the network is SIMULATED and reaches no NTP server, so the answer
 * is the simulation's own clock: 2026-01-01 00:00:00 UTC when you press Run,
 * plus the seconds since. With the offset below the display starts at 19:00,
 * New Year's Eve in New York. On a real ESP32 it shows the real time.
 */
#include <WiFi.h>
#include <WiFiUdp.h>
#include <NTPClient.h>
#include <TM1637Display.h>

const char *SSID = "Mokxi-Lab";
const char *PASSWORD = "breadboard";

const long UTC_OFFSET = -5L * 3600;           // seconds; -5 h is EST
const unsigned long RESYNC_MS = 10UL * 60000; // ask the server every 10 minutes

const int CLK_PIN = 18;
const int DIO_PIN = 19;

WiFiUDP ntpUDP;
NTPClient timeClient(ntpUDP, "pool.ntp.org", UTC_OFFSET, RESYNC_MS);
TM1637Display display(CLK_PIN, DIO_PIN);

// "----" while there is no time yet.
const uint8_t DASHES[] = {SEG_G, SEG_G, SEG_G, SEG_G};

int shownMinute = -1;
bool colon = false;
unsigned long ticked = 0;

void setup()
{
    Serial.begin(115200);
    display.setBrightness(5);
    display.setSegments(DASHES);

    Serial.print("Connecting to ");
    Serial.println(SSID);
    WiFi.begin(SSID, PASSWORD);
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }
    Serial.println();
    Serial.print("WiFi connected, IP ");
    Serial.println(WiFi.localIP());

    timeClient.begin();
    while (!timeClient.update()) {
        Serial.println("No answer from the NTP server, trying again");
        delay(1000);
    }
    Serial.print("Time set: ");
    Serial.println(timeClient.getFormattedTime());
}

void loop()
{
    timeClient.update(); // asks the server only when RESYNC_MS has passed

    // Blink the colon: on for half a second, off for half a second.
    unsigned long now = millis();
    if (now - ticked >= 500) {
        ticked = now;
        colon = !colon;
        int hhmm = timeClient.getHours() * 100 + timeClient.getMinutes();
        display.showNumberDecEx(hhmm, colon ? 0b01000000 : 0, true);

        if (timeClient.getMinutes() != shownMinute) {
            shownMinute = timeClient.getMinutes();
            Serial.print("The time is ");
            Serial.println(timeClient.getFormattedTime());
        }
    }
    delay(10);
}

Open it in the editor, wired and ready to run · ESP32 NTP clock on a TM1637 display: the project page

Common errors and how to fix them

The time prints as 00:00:00 or a 1970 date

No answer has arrived yet. Make sure WiFi is connected before begin(), call forceUpdate() in setup() and check isTimeSet() before printing. On a real network, a firewall that blocks UDP port 123 gives the same symptom.

The clock is off by exactly some number of hours

The offset is in seconds, not hours: UTC+2 is 7200, UTC-5 is -18000. NTPClient also ignores daylight saving, so in summer you add the extra 3600 yourself, or use ezTime or the Timezone library to work it out.

'class NTPClient' has no member named 'getFormattedDate'

getFormattedDate() came from a fork (taranais/NTPClient), not the official release this page covers. Use getEpochTime() and convert it with gmtime() or TimeLib’s year(), month() and day() to print the date.

Questions and answers

NTPClient or configTime() on an ESP32?

configTime() is built into the ESP32 and ESP8266 cores, handles time zones through a POSIX string and keeps the C library’s clock in sync on its own. NTPClient is simpler to read and works on any board with a UDP stack.

Why does Mokxi say the time is January 2026?

The simulator cannot reach an NTP server, so update() sets the time from the simulation’s own clock, which starts at 2026-01-01 00:00:00 UTC and counts up from power-on. The code path is the same as on a board.

Try NTPClient without installing anything

Open the example, change the sketch, and keep your version in a free account.