ESP32 TFT with LVGL: Digital Clock with Time and Date

In this guide, you’ll learn how to turn your ESP32 and a TFT display into a digital clock that displays time and date. We’ll use the LVGL (Light Versatile Graphics Library) and the WorldTimeAPI to get the current time and date. The ESP32 will be programmed using Arduino IDE.

Are you using a CYD board? Read this guide: ESP32 CYD with LVGL – Digital Clock with Time and Date

Project Overview

In this project, we’ll display the time and date from the WorldTimeAPI on a 2.8-inch ILI9341 TFT LCD Touchscreen (240×320). The time and date will be displayed on text labels.

To get an accurate date and time for your timezone, we’ll use the WorldTimeAPI. To get the time from the API, the ESP32 needs to connect to the internet, so you need to have a router in your surroundings so that the ESP32 can connect to it.

Prerequisites

Before proceeding, make sure you follow the next prerequisites. You must follow all steps, otherwise, your project will not work.

1) Parts Required

For this project, you need the following parts:

• TFT LCD Touchscreen Display – 2.8 inch ILI9341 240×320
• ESP32 board with enough pins to wire the display (for example an ESP32 DOIT V1 board)
• Breadboard
• Jumper wires

2) Install ESP32 Boards in Arduino IDE

We’ll program the ESP32 using Arduino IDE. Make sure you have the ESP32 boards installed. Follow the next tutorial:

• Installing ESP32 Board in Arduino IDE 2 (Windows, Mac OS X, Linux)

3) Get familiar with the ILI9341 TFT LCD Touchscreen Display

The display we’re using in this guide is the 2.8. inch TFT LCD that also comes with a touchscreen. The display communicates via SPI communication protocol and uses the ILI9341 driver. The touchscreen also uses the SPI communication protocol.

The TFT LCD touchscreen also comes with an SD card interface if you need to load files for your specific project. This display is also available with different screen sizes, but we’ll use the one with 240 x 320 pixels).

If this is your first time using this display, make sure to follow our getting started guide:

• ESP32 with LVGL: TFT LCD Touchscreen Display – 2.8 inch ILI9341 240×320 (Arduino IDE)

4) Wire the Display to the ESP32

Wire the TFT LCD and touchscreen pins to the ESP32 GPIOs according to the next table (you must use these exact pins, otherwise the project will not work).

TFT LCD Touchscreen	ESP32
T_IRQ	GPIO 36
T_OUT	GPIO 39
T_DIN	GPIO 32
T_CS	GPIO 33
T_CLK	GPIO 25
SDO(MISO)	GPIO 12
LED	GPIO 21
SCK	GPIO 14
SDI(MOSI)	GPIO 13
D/C	GPIO 2
RESET	EN/RESET
CS	GPIO 15
GND	GND
VCC	5V (or 3.3V)*

* In the VCC pin, you can either use 5V or 3.3V depending if your J1 connection is open or closed (by default it’s usually open as you can see in the figure below).

VCC = 5V | J1=OPEN
VCC = 3.3V | J1=CLOSE

5) Install TFT and LVGL Libraries

LVGL (Light and Versatile Graphics Library) is a free and open-source graphics library that provides a wide range of easy-to-use graphical elements for your microcontroller projects that require a graphical user interface (GUI).

Follow the next tutorial to install and configure the required libraries to use LVGL with the 2.8 inch ILI9341 240×320 TFT LCD Touchscreen using Arduino IDE.

• LVGL with ESP32 TFT LCD Touchscreen Display – 2.8 inch ILI9341 240×320 (Arduino IDE)

6) Install ArduinoJson Library

For this project, you need to install the ArduinoJSON library to handle the JSON response when you make a request to the WorldTimeAPI.

In the Arduino IDE, go to Sketch > Include Library > Manage Libraries. Search for ArduinoJSON and install the library by Benoit Blanchon. We’re using version 7.0.4. We recommend using the same version.

ESP32 TFT Digital Clock: Display Date and Time – Arduino Code

The following code will create two text labels with the current time and date. Before uploading the code to your board, you need to insert your network credentials so that the ESP32 can connect to the internet to get the time and date. You also need to insert your timezone.

/*  Rui Santos & Sara Santos - Random Nerd Tutorials - https://RandomNerdTutorials.com/esp32-cyd-lvgl-digital-clock/  |  https://RandomNerdTutorials.com/esp32-tft-lvgl-digital-clock/
    THIS EXAMPLE WAS TESTED WITH THE FOLLOWING HARDWARE:
    1) ESP32-2432S028R 2.8 inch 240×320 also known as the Cheap Yellow Display (CYD): https://makeradvisor.com/tools/cyd-cheap-yellow-display-esp32-2432s028r/
      SET UP INSTRUCTIONS: https://RandomNerdTutorials.com/cyd-lvgl/
    2) REGULAR ESP32 Dev Board + 2.8 inch 240x320 TFT Display: https://makeradvisor.com/tools/2-8-inch-ili9341-tft-240x320/ and https://makeradvisor.com/tools/esp32-dev-board-wi-fi-bluetooth/
      SET UP INSTRUCTIONS: https://RandomNerdTutorials.com/esp32-tft-lvgl/
    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files.
    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
*/

/*  Install the "lvgl" library version 9.2 by kisvegabor to interface with the TFT Display - https://lvgl.io/
    *** IMPORTANT: lv_conf.h available on the internet will probably NOT work with the examples available at Random Nerd Tutorials ***
    *** YOU MUST USE THE lv_conf.h FILE PROVIDED IN THE LINK BELOW IN ORDER TO USE THE EXAMPLES FROM RANDOM NERD TUTORIALS ***
    FULL INSTRUCTIONS AVAILABLE ON HOW CONFIGURE THE LIBRARY: https://RandomNerdTutorials.com/cyd-lvgl/ or https://RandomNerdTutorials.com/esp32-tft-lvgl/   */
#include <lvgl.h>

/*  Install the "TFT_eSPI" library by Bodmer to interface with the TFT Display - https://github.com/Bodmer/TFT_eSPI
    *** IMPORTANT: User_Setup.h available on the internet will probably NOT work with the examples available at Random Nerd Tutorials ***
    *** YOU MUST USE THE User_Setup.h FILE PROVIDED IN THE LINK BELOW IN ORDER TO USE THE EXAMPLES FROM RANDOM NERD TUTORIALS ***
    FULL INSTRUCTIONS AVAILABLE ON HOW CONFIGURE THE LIBRARY: https://RandomNerdTutorials.com/cyd-lvgl/ or https://RandomNerdTutorials.com/esp32-tft-lvgl/   */
#include <TFT_eSPI.h>

#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

// Replace with your network credentials
const char* ssid = "REPLACE_WITH_YOUR_SSID";
const char* password = "REPLACE_WITH_YOUR_PASSWORD";

// Specify the timezone you want to get the time for: https://worldtimeapi.org/api/timezone
// Timezone example for Portugal: "Europe/Lisbon"
const char* timezone = "Europe/Lisbon";

// Store date and time
String current_date;
String current_time;

// Store hour, minute, second
static int32_t hour;
static int32_t minute;
static int32_t second;
bool sync_time_date = false;

#define SCREEN_WIDTH 240
#define SCREEN_HEIGHT 320

#define DRAW_BUF_SIZE (SCREEN_WIDTH * SCREEN_HEIGHT / 10 * (LV_COLOR_DEPTH / 8))
uint32_t draw_buf[DRAW_BUF_SIZE / 4];

// If logging is enabled, it will inform the user about what is happening in the library
void log_print(lv_log_level_t level, const char * buf) {
  LV_UNUSED(level);
  Serial.println(buf);
  Serial.flush();
}

String format_time(int time) {
  return (time < 10) ? "0" + String(time) : String(time);
}

static lv_obj_t * text_label_time;
static lv_obj_t * text_label_date;

static void timer_cb(lv_timer_t * timer){
  LV_UNUSED(timer);
  second++;
  if(second > 59) {
    second = 0;
    minute++;
    if(minute > 59) {
      minute = 0;
      hour++;
      sync_time_date = true;
      Serial.println(sync_time_date);
      Serial.println("\n\n\n\n\n\n\n\n");
      if(hour > 23) {
        hour = 0;
      }
    }
  }

  String hour_time_f = format_time(hour);
  String minute_time_f = format_time(minute);
  String second_time_f = format_time(second);

  String final_time_str = String(hour_time_f) + ":" + String(minute_time_f) + ":"  + String(second_time_f);
  //Serial.println(final_time_str);
  lv_label_set_text(text_label_time, final_time_str.c_str());
  lv_label_set_text(text_label_date, current_date.c_str());
}

void lv_create_main_gui(void) {
  // Get the time and date from WorldTimeAPI
  while(hour==0 && minute==0 && second==0) {
    get_date_and_time();
  }
  Serial.println("Current Time: " + current_time);
  Serial.println("Current Date: " + current_date);

  lv_timer_t * timer = lv_timer_create(timer_cb, 1000, NULL);
  lv_timer_ready(timer);

  // Create a text label for the time aligned center
  text_label_time = lv_label_create(lv_screen_active());
  lv_label_set_text(text_label_time, "");
  lv_obj_align(text_label_time, LV_ALIGN_CENTER, 0, -30);
  // Set font type and size
  static lv_style_t style_text_label;
  lv_style_init(&style_text_label);
  lv_style_set_text_font(&style_text_label, &lv_font_montserrat_48);
  lv_obj_add_style(text_label_time, &style_text_label, 0);

  // Create a text label for the date aligned center
  text_label_date = lv_label_create(lv_screen_active());
  lv_label_set_text(text_label_date, current_date.c_str());
  lv_obj_align(text_label_date, LV_ALIGN_CENTER, 0, 40);
  // Set font type and size
  static lv_style_t style_text_label2;
  lv_style_init(&style_text_label2);
  lv_style_set_text_font(&style_text_label2, &lv_font_montserrat_30);
  lv_obj_add_style(text_label_date, &style_text_label2, 0); 
  lv_obj_set_style_text_color((lv_obj_t*) text_label_date, lv_palette_main(LV_PALETTE_GREY), 0);
}

void get_date_and_time() {
  if (WiFi.status() == WL_CONNECTED) {
    HTTPClient http;

    // Construct the API endpoint
    String url = String("http://worldtimeapi.org/api/timezone/") + timezone;
    http.begin(url);
    int httpCode = http.GET(); // Make the GET request

    if (httpCode > 0) {
      // Check for the response
      if (httpCode == HTTP_CODE_OK) {
        String payload = http.getString();
        //Serial.println("Time information:");
        //Serial.println(payload);
        // Parse the JSON to extract the time
        JsonDocument doc;
        DeserializationError error = deserializeJson(doc, payload);
        if (!error) {
          const char* datetime = doc["datetime"];          
          // Split the datetime into date and time
          String datetime_str = String(datetime);
          int splitIndex = datetime_str.indexOf('T');
          current_date = datetime_str.substring(0, splitIndex);
          current_time = datetime_str.substring(splitIndex + 1, splitIndex + 9); // Extract time portion
          hour = current_time.substring(0, 2).toInt();
          minute = current_time.substring(3, 5).toInt();
          second = current_time.substring(6, 8).toInt();
        } else {
          Serial.print("deserializeJson() failed: ");
          Serial.println(error.c_str());
        }
      }
    } else {
      Serial.printf("GET request failed, error: %s\n", http.errorToString(httpCode).c_str());
      sync_time_date = true;
    }
    http.end(); // Close connection
  } else {
    Serial.println("Not connected to Wi-Fi");
  }
}

void setup() {
  String LVGL_Arduino = String("LVGL Library Version: ") + lv_version_major() + "." + lv_version_minor() + "." + lv_version_patch();
  Serial.begin(115200);
  Serial.println(LVGL_Arduino);

  // Connect to Wi-Fi
  WiFi.begin(ssid, password);
  Serial.print("Connecting");
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.print("\nConnected to Wi-Fi network with IP Address: ");
  Serial.println(WiFi.localIP());
  
  // Start LVGL
  lv_init();
  // Register print function for debugging
  lv_log_register_print_cb(log_print);

  // Create a display object
  lv_display_t * disp;
  // Initialize the TFT display using the TFT_eSPI library
  disp = lv_tft_espi_create(SCREEN_WIDTH, SCREEN_HEIGHT, draw_buf, sizeof(draw_buf));
  lv_display_set_rotation(disp, LV_DISPLAY_ROTATION_270);
  
  // Function to draw the GUI
  lv_create_main_gui();
}

void loop() {
  // Get the time and date from WorldTimeAPI
  if(sync_time_date) {
    sync_time_date = false;
    get_date_and_time();
    while(hour==0 && minute==0 && second==0) {
      get_date_and_time();
    }
  }
  lv_task_handler();  // let the GUI do its work
  lv_tick_inc(5);     // tell LVGL how much time has passed
  delay(5);           // let this time pass
}

View raw code

How Does the Code Work?

Let’s take a look at how to get time and date from the API and update the text labels with the current values. Alternatively, you can skip to the Demonstration section.

Including Libraries

You need to include the lvgl.h and the TFT_eSPI.h libraries to communicate and display text on the screen.

#include <lvgl.h>
#include <TFT_eSPI.h>

You need to include the WiFi, HTTPClient, and the ArduinoJson libraries to make HTTP requests and handle JSON data.

#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

Insert Your Credentials and Timezone

In the following lines, you must insert your network credentials so that the ESP32 can connect to your router.

const char* ssid = "REPLACE_WITH_YOUR_SSID";
const char* password = "REPLACE_WITH_YOUR_PASSWORD";

Set your timezone in the timezone variable at the beginning of the code (list of all available timezones).

const char* timezone = "Europe/Lisbon";

Declaring Other Variables

Create some auxiliary variables to hold the date and time values.

// Store date and time
String current_date;
String current_time;

// Store hour, minute, second
static int32_t hour;
static int32_t minute;
static int32_t second;
bool sync_time_date = false;

Global Text Labels

We create two global LVGL text label objects, so that we can access them inside all functions later on.

static lv_obj_t * text_label_time;
static lv_obj_t * text_label_date;

setup()

In the setup(), include the following lines for debugging. These will print the version of LVGL that you’re using. You must be using version 9.

String LVGL_Arduino = String("LVGL Library Version: ") + lv_version_major() + "." + lv_version_minor() + "." + lv_version_patch();
Serial.begin(115200);
Serial.println(LVGL_Arduino);

Connect to the Internet

To connect the ESP32 to the internet we use the following code.

// Connect to Wi-Fi
WiFi.begin(ssid, password);
Serial.print("Connecting");
while (WiFi.status() != WL_CONNECTED) {
  delay(500);
  Serial.print(".");
}
Serial.print("\nConnected to Wi-Fi network with IP Address: ");
Serial.println(WiFi.localIP());

Initialize the LVGL Library

Initialize the LVGL Library by calling the lv_init() function in the setup().

// Start LVGL
lv_init();

Register Debugging Function

Register your log_print() function declared previously as a function associated with debugging LVGL.

// Register print function for debugging
lv_log_register_print_cb(log_print);

Create a Display Object

To write to the display, you must create a display object first. You need to do this in all your LVGL sketches. The following lines will create an LVGL display object called disp with the screen width, screen height, and drawing buffer defined earlier.

// Create a display object
lv_display_t * disp;
// Initialize the TFT display using the TFT_eSPI library
disp = lv_tft_espi_create(SCREEN_WIDTH, SCREEN_HEIGHT, draw_buf, sizeof(draw_buf));
lv_display_set_rotation(disp, LV_DISPLAY_ROTATION_270);

Drawing the GUI

The LVGL library works asynchronously. You must call the function to draw on the display in the setup(). Then, everything works with events and callbacks. The code will always be listening for events in the background. When something happens, it will run the callback function associated with the event. You don’t need to check for any events in the loop().

Throughout most of our examples, the function that will draw to the screen will be called lv_create_main_gui(). Then, inside that function, we’ll add the instructions to build the interface.

// Function to draw the GUI
lv_create_main_gui();

get_date_and_time()

When we initialize the screen, we call the get_date_and_time() function to get the latest date and time from the WorldTimeAPI. Then, we store the values in some auxiliary variables that will be used to display them on the screen.

void get_date_and_time() {
  if (WiFi.status() == WL_CONNECTED) {
    HTTPClient http;

    // Construct the API endpoint
    String url = String("http://worldtimeapi.org/api/timezone/") + timezone;
    http.begin(url);
    int httpCode = http.GET(); // Make the GET request

    if (httpCode > 0) {
      // Check for the response
      if (httpCode == HTTP_CODE_OK) {
        String payload = http.getString();
        //Serial.println("Time information:");
        //Serial.println(payload);
        // Parse the JSON to extract the time
        JsonDocument doc;
        DeserializationError error = deserializeJson(doc, payload);
        if (!error) {
          const char* datetime = doc["datetime"];          
          // Split the datetime into date and time
          String datetime_str = String(datetime);
          int splitIndex = datetime_str.indexOf('T');
          current_date = datetime_str.substring(0, splitIndex);
          current_time = datetime_str.substring(splitIndex + 1, splitIndex + 9); // Extract time portion
          hour = current_time.substring(0, 2).toInt();
          minute = current_time.substring(3, 5).toInt();
          second = current_time.substring(6, 8).toInt();
        } else {
          Serial.print("deserializeJson() failed: ");
          Serial.println(error.c_str());
        }
      }
    } else {
      Serial.printf("GET request failed, error: %s\n", http.errorToString(httpCode).c_str());
      sync_time_date = true;
    }
    http.end(); // Close connection
  } else {
    Serial.println("Not connected to Wi-Fi");
  }
}

Preparing the GUI

Before drawing the main GUI, we start by calling the API to get the latest time and date.

void lv_create_main_gui(void) {
  // Get the time and date from WorldTimeAPI
  while(hour==0 && minute==0 && second==0) {
    get_date_and_time();
  }
(...)

Timer

To update the time and date text labels on the screen, we can create an LVGL timer that will run a specific function periodically. In this case, we’ll update it every 1 second. Create an LVGL timer called timer and assign the timer_cb callback function.

lv_timer_t * timer = lv_timer_create(timer_cb, 1000, NULL);
lv_timer_ready(timer);

Time Text Label

To create a text label, we can call the LVGL function lv_label_create() and pass as argument where we want to display the text. We want to add it to the current screen (lv_screen_active()).

// Create a text label for the time aligned center
text_label_time = lv_label_create(lv_screen_active());

After creating the text label, we can set its text by using the lv_label_set_text() function that accepts as arguments the text label we’re referring to and the text we want to add to that label. In our case, we’re setting it to empty at the beginning.

lv_label_set_text(text_label_time, "");

The following lines align the text label. You can use the lv_obj_align() function. Pass as arguments, the LVGL object, the alignment and x and y offsets in pixels.

lv_obj_align(text_label_time, LV_ALIGN_CENTER, 0, -30);

To style our text label, we’ll start by creating an object of type lv_style_t called style_text_label. This kind of object is used to apply styles to LVGL objects.

static lv_style_t style_text_label;

After creating the style, we initialize it using the lv_style_init() function and pass as argument our text label style (style_text_label).

lv_style_init(&style_text_label);

Then, we can set the font type and size using the lv_style_set_text_font() function. We pass as argument the style object we’re referring to and the font type. Finally, we apply the style.

lv_style_set_text_font(&style_text_label, &lv_font_montserrat_48);
lv_obj_add_style(text_label_time, &style_text_label, 0);

Date Text Label

A similar procedure is applied to create the text_label_date.

 // Create a text label for the date aligned center
text_label_date = lv_label_create(lv_screen_active());
lv_label_set_text(text_label_date, current_date.c_str());
lv_obj_align(text_label_date, LV_ALIGN_CENTER, 0, 40);
// Set font type and size
static lv_style_t style_text_label2;
lv_style_init(&style_text_label2);
lv_style_set_text_font(&style_text_label2, &lv_font_montserrat_30);
lv_obj_add_style(text_label_date, &style_text_label2, 0); 
lv_obj_set_style_text_color((lv_obj_t*) text_label_date, lv_palette_main(LV_PALETTE_GREY), 0);

Timer Callback Function

The timer_cb function runs every one second. Each time the callback function runs, we increment one second, every 60 seconds one minute and every 60 minutes one hour.

static void timer_cb(lv_timer_t * timer){
  LV_UNUSED(timer);
  second++;
  if(second > 59) {
    second = 0;
    minute++;
    if(minute > 59) {
      minute = 0;
      hour++;
      sync_time_date = true;
      Serial.println(sync_time_date);
      Serial.println("\n\n\n\n\n\n\n\n");
      if(hour > 23) {
        hour = 0;
      }
    }
  }
(...)

We use these auxiliary variable to prepare the String that will be displayed on the text labels.

String hour_time_f = format_time(hour);
String minute_time_f = format_time(minute);
String second_time_f = format_time(second);

String final_time_str = String(hour_time_f) + ":" + String(minute_time_f) + ":"  + String(second_time_f);

Set the text labels to the current time and date:

lv_label_set_text(text_label_time, final_time_str.c_str());
lv_label_set_text(text_label_date, current_date.c_str());

loop()

In the loop(), you can add any other tasks that you need your ESP32 to do like in any regular Arduino sketch. In our case, we will check if it’s necessary to sync the date and time with the WorldTimeAPI every hour.

void loop() {
  // Get the time and date from WorldTimeAPI
  if(sync_time_date) {
    sync_time_date = false;
    get_date_and_time();
    while(hour==0 && minute==0 && second==0) {
      get_date_and_time();
    }
  }
  lv_task_handler();   // let the GUI do its work
  lv_tick_inc(5);         // tell LVGL how much time has passed
  delay(5);                 // let this time pass
}

Demonstration

Upload the code to your board. Go to Tools > Board and select ESP32 > ESP32 Dev Module. Then, select the right COM port in Tools > Port.

If you see an Error like this: “Sketch too big” during the uploading process, in Arduino IDE go to Tools > Partition scheme > choose anything that has more than 1.4MB APP, for example: “Huge APP (3MB No OTA/1MB SPIFFS“.

Finally, click the upload button.

After a few seconds, the time and date will be displayed on the screen as shown in the picture below.

The ESP32 will not keep the time perfectly with its internal clock. During our tests, after one hour it usually incurs a 20 to 40 seconds delay. Every hour we make a new HTTP request to the WorldTimeAPI to sync the time and date.

Wrapping Up

In this tutorial, you learned to display date and time on a TFT with ESP32 board using the LVGL library.

We hope you found this tutorial useful. We’re preparing more guides about this board, so stay tuned. If you would like to learn more about creating graphical user interfaces using the LVGL library with the ESP32, check out our latest eBook:

• Learn LVGL: Build GUIs for ESP32 Projects (eBook)

Other guides you might like reading:

• LVGL with ESP32 TFT LCD Touchscreen Display – 2.8 inch ILI9341 240×320 (Arduino IDE)
• ESP32 with LVGL: Display DS18B20 Sensor Readings on TFT LCD (Text and Arc)
• ESP32 with TFT: Display Image using LVGL – 2.8 inch ILI9341 240×320 (Arduino)

To learn more about the ESP32, make sure to take a look at our resources:

• Learn ESP32 with Arduino IDE (eBook)
• SMART HOME with Raspberry Pi, ESP32, and ESP8266 eBook
• Free ESP32 Guides and Tutorials