in iot devices, the timestamp becomes an important attribute of the packet exchanged between the device and the server. therefore, it is necessary to have the correct time on your device at all times. one way is to use an rtc (real time clock) interfaced with your esp32. you can even use esp32's internal rtc. once given a reference time, it can correctly output future timestamps. but how will you get the reference time? one way is to hardcode the current time while programming the esp32. but that is not a neat method. secondly, the rtc is prone to drift and it is a good idea to keep providing it with reference timestamps regularly. in this chapter, we will see how to get the current time from ntp servers, feed it to esp32's internal rtc once, and print future timestamps.

a brief about ntp

ntp stands for network time protocol. it is a protocol for clock synchronization between computer systems. in layperson terms, there is a server sitting somewhere which maintains time accurately. whenever a client requests the current time from the ntp server, it sends back time accurate up to 100s of milliseconds. you can read more about ntp here. for esp32, there is an in−built time library that handles all the communication with the ntp servers. let's explore the use of that library in the code walkthrough below.

code walkthrough

we will use an in−built example for this walkthrough. it can be found in file −> examples −> esp32 −> time −> simpletime. it can also be found on github.

we begin with the inclusion of the wifi and the time libraries.

#include <wifi.h>
#include "time.h"

next, we define some global variables. replace the wifi ssid and password with the corresponding values for your wifi. next, we have defined the url for the ntp server. the gmtoffset_sec refers to the offset in seconds of your timezone from the gmt or the closely related utc. for instance, in india, where the timezone is 5 hours and 30 mins ahead of the utc, the gmtoffset_sec will be (5+0.5)*3600 = 19800.

the daylightoffset_sec is relevant for countries that have daylight savings. it can simply be set to 0 in other countries.

const char* ssid       = "your_ssid";
const char* password   = "your_pass";

const char* ntpserver = "pool.ntp.org";
const long  gmtoffset_sec = 3600;
const int   daylightoffset_sec = 3600;

next, you can see a function printlocaltime(). it simply fetches the local time from the internal rtc and prints it to serial.

void printlocaltime()
{
   struct tm timeinfo;
   if(!getlocaltime(&timeinfo)){
      serial.println("failed to obtain time");
      return;
   }
   serial.println(&timeinfo, "%a, %b %d %y %h:%m:%s");
}

you might be having three questions here −

where is the struct tm defined?
where is the getlocaltime() function defined?
what are the %a, %b, etc. formatters?

the struct tm is defined in the time.h file that we have included at the top. in fact, the time library is not an esp32 specific library. it is an avr library that is compatible to esp32. you can find the source code at here. if you look at the time.h file, you will see the struct tm.

struct tm {
   int8_t   tm_sec; /**< seconds after the minute - [ 0 to 59 ] */
   int8_t   tm_min; /**< minutes after the hour - [ 0 to 59 ] */
   int8_t   tm_hour; /**< hours since midnight - [ 0 to 23 ] */
   int8_t   tm_mday; /**< day of the month - [ 1 to 31 ] */
   int8_t   tm_wday; /**< days since sunday - [ 0 to 6 ] */
   int8_t   tm_mon; /**< months since january - [ 0 to 11 ] */
   int16_t  tm_year; /**< years since 1900 */
   int16_t  tm_yday; /**< days since january 1 - [ 0 to 365 ] */
   int16_t  tm_isdst; /**< daylight saving time flag */
};

now, the getlocaltime function is esp32 specific. it is defined in the esp32−hal−time.c file. it is a part of the arduino core for esp32 and doesn't need a separate include in arduino. you can see the source code here.

now, the meaning of the formatters is given below −

/*
   %a abbreviated weekday name
   %a full weekday name
   %b abbreviated month name
   %b full month name
   %c date and time representation for your locale
   %d day of month as a decimal number (01−31)
   %h hour in 24-hour format (00−23)
   %i hour in 12-hour format (01−12)
   %j day of year as decimal number (001−366)
   %m month as decimal number (01−12)
   %m minute as decimal number (00−59)
   %p current locale's a.m./p.m. indicator for 12−hour clock
   %s second as decimal number (00−59)
   %u week of year as decimal number,  sunday as first day of week (00−51)
   %w weekday as decimal number (0−6; sunday is 0)
   %w week of year as decimal number, monday as first day of week (00−51)
   %x date representation for current locale
   %x time representation for current locale
   %y year without century, as decimal number (00−99)
   %y year with century, as decimal number
   %z %z time-zone name or abbreviation, (no characters if time zone is unknown)
   %% percent sign
   you can include text literals (such as spaces and colons) to make a neater display or for padding between adjoining columns.
   you can suppress the display of leading zeroes  by using the "#" character  (%#d, %#h, %#i, %#j, %#m, %#m, %#s, %#u, %#w, %#w, %#y, %#y)
*/

thus, with our formatting scheme of %a, %b %d %y %h:%m:%s, we can expect the output to be similar to the following: sunday, november 15 2020 14:51:30.

now, coming to the setup and the loop. in the setup, we initialize serial, connect to the internet using our wifi, and configure the internal rtc of esp32 using the configtime() function. as you can see, that function takes in three arguments, the gmtoffset, the daylightoffset and the ntpserver. it will fetch the time from ntpserver in utc, apply the gmtoffset and the daylightoffset locally, and return the output time. this function, like getlocaltime, is defined in the esp32-hal-time.c file. as you can see from the file, tcp/ip protocol is used for fetching time from the ntp server.

once we've obtained the time from the ntp server and fed it to the internal rtc of the esp32, we no longer need wifi. thus, we disconnect the wifi and keep printing time in the loop every second. you can see on the serial monitor that the time gets incremented by one second in every print. this is because the internal rtc of esp32 maintains the time once it got the reference.

void setup()
{
   serial.begin(115200);
  
   //connect to wifi
   serial.printf("connecting to %s ", ssid);
   wifi.begin(ssid, password);
   while (wifi.status() != wl_connected) {
      delay(500);
      serial.print(".");
   }
   serial.println(" connected");
  
   //init and get the time
   configtime(gmtoffset_sec, daylightoffset_sec, ntpserver);
   printlocaltime();

   //disconnect wifi as it's no longer needed
   wifi.disconnect(true);
   wifi.mode(wifi_off);
}
void loop() {
  delay(1000);
  printlocaltime();
}

the serial monitor output will look like −

that's it. you've learned how to get the correct time from the ntp servers and configure your esp32's internal rtc. now, in whatever packets you send to the server, you can add the timestamp.

references

network time protocol - wikipedia

Save or share this article