From 76317604def6d45d3cbb3e98da38f9d1f6ba919c Mon Sep 17 00:00:00 2001 From: Rop Date: Tue, 11 Sep 2018 08:37:05 +0200 Subject: [PATCH] EventsAndOrdinalTime example and little warning about restructuring --- README.md | 18 +++++-- .../EventsAndOrdinalTime.ino | 51 +++++++++++++++++++ keywords.txt | 2 +- library.json | 2 +- library.properties | 2 +- 5 files changed, 67 insertions(+), 8 deletions(-) create mode 100644 examples/EventsAndOrdinalTime/EventsAndOrdinalTime.ino diff --git a/README.md b/README.md index e454d8a..c37f341 100644 --- a/README.md +++ b/README.md @@ -6,21 +6,29 @@ +  + + +| **Major renaming/restructuring still taking place. (The "time" object conflicts on some platforms.)
Please test with it but do not use it in for serious things until a few days from now.** | +|----| + +  + ## A brief history of ezTime -I was working on [M5ez](https://github.com/ropg/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. That was all, I swear. 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. +I was working on [M5ez](https://github.com/ropg/M5ez), an interface library to easily make cool-looking programs for the "[M5Stack](http://m5stack.com/)" ESP32 hardware. The status bar of M5ez needed to display the time. That was all, I swear. I figured I would use [Time](https://github.com/PaulStoffregen/Time), Michael Margolis' and 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. So far, so good. -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 Jack Christensen'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. I figured I would simply get this data from the internet and parse it. +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. It's 2018, my clock would need to know about timezone rules. So I could get Jack Christensen'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. I figured I would simply get this data from the internet and parse it. -And then I wanted 12 or 24 hour time displayed, and thought about various formats for date and time. Wouldn't it be nice to have some function to print formatted time like many programming languages offer them? +Then I wanted 12 or 24 hour time displayed, and thought about various formats for date and time. 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 part of this, it seemed like there had to be a better way. Especially, some way in which all this work would benefit more people. This is how ezTime — the project that was only going to take a few days — came to be. ## ezTime is ... -**self-contained**: It only depends on other libraries to get online, but then it doesn't need other libraries for NTP and timezone data lookups. +**self-contained**: It only depends on other libraries to get online, but then it doesn't need other libraries for NTP and timezone data lookups. (And even networking can be disabled completely if you have another source for time.) **precise**: Unlike other libraries, ezTime does not throw away or mangle the fractional second information from the NTP server. An NTP request to pool.ntp.org only takes 40ms round-trip on home DSL these days, 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. @@ -28,7 +36,7 @@ Overlooking the battlefield after implementing some part of this, it seemed like **eventful**: You can set events to have ezTime execute your own functions at a given time, and delete the events again if you change your mind. -**robust**: It doesn't fail if the timezone api goes away: it can use cached data, which ezTime can store in EEPROM (AVR Arduinos) or NVS (ESP32 through Preferences library). +**robust**: It doesn't fail if the timezone api goes away: it can use cached data, which ezTime can store in EEPROM (AVR Arduinos) or NVS (e.g. ESP32 through Preferences library). **informative**: No need to guess while you're working on something, ezTime can print messages to the serial port at your desired level of detail, telling you about the timezone's daylight savings info it receives or when it gets an NTP update and by how much your internal clock was off, for instance. diff --git a/examples/EventsAndOrdinalTime/EventsAndOrdinalTime.ino b/examples/EventsAndOrdinalTime/EventsAndOrdinalTime.ino new file mode 100644 index 0000000..6fad798 --- /dev/null +++ b/examples/EventsAndOrdinalTime/EventsAndOrdinalTime.ino @@ -0,0 +1,51 @@ +/* + * This sketch prints a message at noon UTC, every second Tuesday of the month. + * Not very useful, but demonstrates events and ordinal time. + */ + +#include +#include + +void setup() { + + Serial.begin(115200); + WiFi.begin("your-ssid", "your-password"); + + time.waitForSync(); + + // Set the event to trigger for the first time + UTC.setEvent( itIsTheSecondTuesday, nextSecondTuesday() ); + +} + +void loop() { + + time.events(); + +} + +void itIsTheSecondTuesday() { + Serial.print(F("It's the second Tuesday: ")); + Serial.println(UTC.dateTime()); + + // The event then sets a new event for the next time + UTC.setEvent( itIsTheSecondTuesday, nextSecondTuesday() ); +} + +time_t nextSecondTuesday() { + + int8_t m = UTC.month(); + int16_t y = UTC.year(); + time_t t = 0; + + while (t <= UTC.now()) { + // Try in current month first, if that has passed, loop once more for next month + t = time.makeOrdinalTime(12, 0, 0, SECOND, TUESDAY, m, y); + m++; + if (m == 13) { + m = 1; + y++; + } + } + return t; +} diff --git a/keywords.txt b/keywords.txt index 3fab814..3e08c5f 100644 --- a/keywords.txt +++ b/keywords.txt @@ -10,7 +10,7 @@ events KEYWORD2 deleteEvent KEYWORD2 breakTime KEYWORD2 makeTime KEYWORD2 -makeUmpteenthTime KEYWORD2 +makeOrdinalTime KEYWORD2 compileTime KEYWORD2 monthString KEYWORD2 dayString KEYWORD2 diff --git a/library.json b/library.json index 355fd61..4538f28 100644 --- a/library.json +++ b/library.json @@ -11,7 +11,7 @@ "type": "git", "url": "https://github.com/ropg/ezTime" }, - "version": "0.7.1", + "version": "0.7.2", "framework": "arduino", "platforms": "*" "build": { diff --git a/library.properties b/library.properties index 715f85a..3b4e800 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=ezTime -version=0.7.1 +version=0.7.2 author=Rop Gonggrijp maintainer=Rop Gonggrijp sentence=ezTime - pronounced "Easy Time" - is a very easy to use Arduino time and date library that provides NTP network time lookups, extensive timezone support, formatted time and date strings, user events, millisecond precision and more.