I was working on M5ez, an interface library to easily make cool-looking programs for the "M5Stack" ESP32 hardware. The status bar of that needed to display the time. I figured I would use [Time](https://github.com/PaulStoffregen/Time), Paul Stoffregen's library to do time things on Arduino. Then I needed to sync that to an NTP server, so I figured I would use [NTPclient](https://github.com/arduino-libraries/NTPClient), one of the existing NTP client libraries. And then I wanted it to show the local time, so I would need some way for the user to set an offset between UTC and local time.
## Some quick examples
So far, so good.
# ezTime: complete documentation
Then I remembered how annoyed I always am when daylight savings time comes or goes, as I have to manually set some of my clocks such as the microwave oven, the clock in the car dashboard, etc etc. My clock would need to know about timezone rules. So I could get JChristensen's [Timezone library](https://github.com/JChristensen/Timezone). But it needs the timezone's rules, like "DST goes into effect on the last Sunday in March at 02:00 local time" told to it, and that seemed a hassle. So I would simply get this data from the internet.
And then I also wanted to print time in various formats. Wouldn't it be nice to have some function to print formatted time like many programming languages offer them?
Overlooking the battlefield after implementing some of this, it seemed like there had to be a better way. Especially, some way in which all this work would benefit more people. I decided to make the mother of all time libraries.
## ezTime is:
**self-contained**: It only depends on core ESP32 libraries (for networking and for storing its cached timezone data in flash). It uses [timezoneapi.io](https://timezoneapi.io/) to get its timezone data.
**precise**: An NTP request to pool.ntp.org only takes 40ms round-trip on my home DSL, so adding sub-second precision to a time library makes sense. ezTime reads the fractional seconds and tries to account for network latency to give you precise time.
## NTP, staying in sync
**backwards compatible**: Anything written for the existing Arduino time library will still work. You simply set which timezone the sketch should be in. (Or have it be in UTC, which is the default.) But you can also refer to the ezTime or Timezone objects directly and use additional power.
**robust**: Doesn't fail if the timezone api goes away. It is built to cache the data for any timezones used. If that server is unreachable it will not initialise new timezones or do a yearly update of the rules, but it will still work on timezones you have already used.
**time-saving**: No more time spent on writing code to print date or time in some nicer way. Print things like "9:20 AM" or "Saturday the 23rd of August 2018" with ease. Prevent display-flicker with minuteChanged() and secondChanged() functions without storing any values to compare.
**`void ezTime.updateNow()`**
**easy to use**: Don't believe it until you see it. Have a look at some examples to see how easy it is to use.
**`timeStatus_t ezTime.timeStatus()`**
### Timezones
**`bool ezTime.queryNTP(String server, time_t &t, unsigned long &measured_at)`**
```
#include<ezTime.h>
#include<WiFi.h>
void setup() {
Serial.begin(115200);
WiFi.begin("your-ssid", "your-password");
ezTime.waitForSync();
**`time_t ezTime.now()`**
Serial.println("UTC: " + UTC.dateTime());
**`void ezTime.breakTime(time_t time, tmElements_t &tm)`**
Timezone myTZ;
**`time_t ezTime.makeTime(tmElements_t &tm)`**
// Anything with a slash in it is interpreted as an official timezone name
Received time: Saturday, 25-Aug-18 14:39:53.674 UTC (internal clock was 1 ms slow)
```
## Getting started
SOON
# ezTime: complete documentation
String urlEncode(String str); // Does what you think it does
String zeropad(uint32_t number, uint8_t length); // Returns number as string of given length, zero-padded on left if needed
String getBetween(String &haystack, String before_needle, String after_needle = ""); // Returns what's between before_needle and after_needle in haystack, or "" if not found. Returns until end of string if after_needle is empty
Rop
7 years ago