LocalTimeRK (community library)

Summary

Timezone and DST handling for Particle devices

Example Build Testing

Library Read Me

This content is provided by the library maintainer and has not been validated or approved.

LocalTimeRK

Timezone and DST handling for Particle devices

This library is designed for specific local time and daylight saving time scenarios on Particle devices. It is not intended to solve all problems in all situations, however it will work well in certain scenarios:

• Full API docs
• Github repository: https://github.com/rickkas7/LocalTimeRK/
• License: MIT

What it's good for:

• Managing local time, and daylight saving time, if needed, on devices in a known location
• Mostly intended for devices in your own home
• Managing scheduling of tasks at a specific local time
• Displaying local time

What it's not intended for:

• Mobile devices that may change locations
• Customer devices that could be in any timezone

Features

• Timezone configuration using a POSIX timezone rule string
• Does not require network access to determine timezone and daylight saving transitions
• Good for displaying local time, such as on clock-like devices
• Good for scheduling operations at a specific local time. For example, every day at 8:00 AM regardless of timezone and DST
• Support for locations with DST and without DST (timezone only)
• Should work in the southern hemisphere were DST is opposite on the calendar
• Should work in any country as long as a compatible POSIX timezone configuration string can be generated

What is a POSIX timezone configuration?

For the United States east coast, the configuration string is:

EST5EDT,M3.2.0/2:00:00,M11.1.0/2:00:00"

What this means is:

• "EST" is the standard time timezone name
• 5 is the offset from UTC in hours. Actually -5, as the sign is backwards from the way it's normally expressed. And it could be hours and minutes.
• "EDT" is the daylight saving time timezone name
• "M3.2.0" is when DST starts. Month 3 (March), 2nd week, 0 = Sunday
• "2:00:00" transition to DST at 2:00 AM local time
• "M11.1.0" transition back to standard time November, 1st week, on Sunday
• "2:00:00" transition back to standard time at 2:00 AM local time

There are a bunch of supported formats, including for locations that don't have DST (such as Arizona, "MST7") and southern hemisphere where daylight saving is on the opposite part of the year, such as Eastern Australian time used in Sydney, Australia "AEST-10AEDT,M10.1.0/02:00:00,M4.1.0/03:00:00".

Using for scheduling

This library does not modify the Time class timezone! This has the potential to disrupt all sorts of things that depend on Time, and should be avoided. A new class and methods provide access to local time when needed.

Additionally, it's designed to handle scheduling. For example, say you want to perform an operation at 3:00 AM every day, local time. The class can find the UTC time corresponding to this, taking into account timezones and DST changes. Using Time.now() comparisons (at UTC) is fast and efficient. It's also good when you want to store the desired time in EEPROM, retained memory, or the file system.

The library also handles weird transition scenarios that occur on spring forward (in the north hemisphere) where the hour from 2:00 AM local time to 2:59:59 doesn't exist, and in the fall back where the hour from 1:00:00 to 1:59:59 local time occurs twice.

It also handles other common scheduling scenarios:

• Tomorrow (same time)
• Tomorrow (at a specific local time)
• On a specific day of week at a specific time ("every Saturday at 3:00 AM")
• On a day of week with an ordinal ("on the 2nd Saturday of the month")
• On a specific day of month at a specific time
• Also the last day of the month, the second to last day of the month, ...
• On the next weekday (Monday - Friday)
• On the next weekend day (Saturday - Sunday)

Clock Example

There is an example of using the library to use an Adafruit FeatherWing OLED Display 128x32 as a clock.

The display is available at Adafruit. You can find more technical information at Adafruit. The library is available in the Web IDE as oled-wing-adafruit. You can find additional documentation here.

The code example is in the more-examples directory in the Clock directory and is quite simple:

#include "Particle.h"

#include "LocalTimeRK.h"
#include "oled-wing-adafruit.h"

SerialLogHandler logHandler;

SYSTEM_THREAD(ENABLED);

OledWingAdafruit display;

void setup() {
// Set timezone to the Eastern United States
LocalTime::instance().withConfig(LocalTimePosixTimezone("EST5EDT,M3.2.0/2:00:00,M11.1.0/2:00:00"));

display.setup();

display.clearDisplay();
display.display();
}

void loop() {
static unsigned long lastUpdate = 0;
if (millis() - lastUpdate >= 1000 && Time.isValid()) {
lastUpdate = millis();

LocalTimeConvert conv;
conv.withCurrentTime().convert();

// Log.info("local time: %s", conv.format(TIME_FORMAT_ISO8601_FULL).c_str());

// Room for 11 characters at text size 2
display.clearDisplay();
display.setTextColor(WHITE);
display.setTextSize(2);
display.setFont(NULL);
display.setCursor(0, 1);

String msg;

msg = conv.format("%Y-%m-%d"); // 2021-06-07
display.println(msg);

msg = conv.format("%I:%M:%S%p"); // 10:00:00AM
display.println(msg);

display.display();
}
}

(image removed)

Using the library

Configure the timezone

• Determine the POSIX timezone string for your location. For example, the US eastern timezone is shown in the example

• At setup, configure the timezone:

LocalTime::instance().withConfig(LocalTimePosixTimezone("EST5EDT,M3.2.0/2:00:00,M11.1.0/2:00:00"));

Some configuration strings:

Getting the current local time

Use the LocalTimeConvert class like this to get the current time:

LocalTimeConvert conv;
conv.withCurrentTime().convert();

This will initialize the conv object with information about the current local time in the timezone you have configured.

Additional useful LocalTimeConvert methods:

Advanced scheduling

An advanced scheduling mode was added in version 0.0.8. This allows complex schedules such as:

• Every 15 minutes in the hour, between 9:00 AM and 5:00 PM local time, Monday - Friday, except on 2022-03-21
• Every 4 hours of the day starting at 00:00:00 (midnight) other times

This can either be specified in code, or it can be expressed in JSON. JSON allows the schedule to be updating using a Particle.function, for example.

This is a compact representation of that schedule in 77 bytes of JSON data:

[{"mh":15,"y":62,"s":"09:00:00","e":"16:59:59","x":["2022-03-21"]},{"hd":4}]

While scheduling is designed to work with local time, each schedule calculator can optionally have a time zone override, which makes it possible to do some calculations at UTC if you prefer to do that.

Using a schedule

This is the code in examples/2-schedule:

#include "LocalTimeRK.h"

SerialLogHandler logHandler;
SYSTEM_THREAD(ENABLED);

LocalTimeSchedule publishSchedule;

void setup() {
// Set timezone to the Eastern United States
LocalTime::instance().withConfig(LocalTimePosixTimezone("EST5EDT,M3.2.0/2:00:00,M11.1.0/2:00:00"));

// Publish every 5 minutes at :00, :05, :10, ...
publishSchedule.withMinuteOfHour(5);
}

void loop() {
if (publishSchedule.isScheduledTime() && Particle.connected()) {
Particle.publish("testEvent", "scheduled publish!");
}
}

This is a simple example that publishes at :00, :05, :10, .... Note that these are clock times, not rolling times.

Technically you don't need a timezone for this example since it doesn't do any hour-based calculations, but it's set using withConfig() when you need to use one.

The part in loop() tests to see if it's time to publish and then publishes. As shown in the example, if you are not connected to the cloud at the scheduled time, that scheduled time is skipped.

If you reverse the order in the if statement, then if you are not connected to the cloud, it's possible to get publish immediately after reconnecting to the cloud to make up for the one that was missed.

// Allow one out-of-schedule publish to catch up for a missed publish in this order
if (Particle.connected() && publishSchedule.isScheduledTime())

The real benefit is when you start to make more complex schedules, such as:

// Every 15 minutes between 9:00 AM and 5:00 PM local time Monday - Friday
publishSchedule.withMinuteOfHour(15, LocalTimeRange(LocalTimeHMS("09:00:00"), LocalTimeHMS("16:59:59"), LocalTimeRestrictedDate(LocalTimeDayOfWeek::MASK_WEEKDAY)));

// Every hour otherwise
publishSchedule.withMinuteOfHour(60);

You can exclude dates from a schedule. For example, the every 15 minutes on weekdays schedule excludes Monday, April 11, 2022 with this schedule:

publishSchedule.withMinuteOfHour(15, LocalTimeRange(LocalTimeHMS("09:00:00"), LocalTimeHMS("16:59:59"),
LocalTimeRestrictedDate(LocalTimeDayOfWeek::MASK_WEEKDAY, {}, {"2022-04-11"})));
publishSchedule.withMinuteOfHour(60);

LocalTimeSchedule items

LocalTimeSchedule include things like every n minutes, every n hours, as well as day of week and day of month multiples. Each multiple has a type, an increment, in some cases additional data, and a LocalTimeRange that determines when the multiple is used.

LocalTimeRange is itself composed of a TimeRange, and a LocalTimeRestrictedDate. This specifies both the time of day, as well as an optional restriction on the dates it applies. See above for for an explanation of these types.

Minute of hour

This schedule item is used for "every n minutes." For example, if you want to publish an event every 15 minutes.

// PROTOTYPE (class LocalTimeSchedule)
LocalTimeSchedule &withMinuteOfHour(int increment, LocalTimeRange timeRange = LocalTimeRange());

• Minute multiples are relative to the hour, so you typically want to use an increment that 60 is evenly divisible by in order to keep the period constant (2, 3, 4, 5, 6, 10, 12, 15, 20, 30).
• The LocalTimeRange can restrict this to certain hours of the day, and certain days of the week. It can also handle exception dates, both only on date, or to exclude dates.
• The minute of the start of the time range specifies the offset relative to the hour to start the increment from (modulo the increment).
• The second of the start of the time range specifies the second offset.

For example, every 15 minutes all day, at 05:00, 20:00, 35:00, 50:00:

schedule.withMinuteOfHour(15, LocalTimeRange(LocalTimeHMS("00:05:00")));

Every 5 minutes from 9:00 AM to 5:00 PM local time every day:

schedule.withMinuteOfHour(5, LocalTimeRange(LocalTimeHMS("09:00:00"), LocalTimeHMS("16:59:59")))

Every 5 minutes from 9:00 AM to 5:00 PM local time on weekdays (not Saturday or Sunday):

schedule.withMinuteOfHour(5, LocalTimeRange(LocalTimeHMS("09:00:00"), LocalTimeHMS("16:59:59"), LocalTimeRestrictedDate(LocalTimeDayOfWeek::MASK_WEEKDAY)));

In generating from JSON:

Hour of day multiples

This schedule is used for "every n hours." For example, if you want to wake and publish every 4 hours.

// PROTOTYPE (class LocalTimeSchedule)
LocalTimeSchedule &withHourOfDay(int hourMultiple, LocalTimeRange timeRange = LocalTimeRange());

• Hour multiples are relative to the day, so you typically want to use a value that 24 is evenly divisible by (2, 3, 4, 6, 8, 12).
• The LocalTimeRange can restrict this to certain hours of the day, and certain days of the week. It can also handle exception dates, both only on date, or to exclude dates.
• The hour of the start of the time range specifies the offset relative to the day to start the increment from (modulo the increment)
• The minute and second of the start of the time range specifies the minute and second offset

For example, every 2 hours (00:00, 02:00, 04:00) local time.

schedule.withHourOfDay(2);

Every 2 hours, but starting at 01:30 local time (01:30, 03:30, 05:30, ...).

schedule.withHourOfDay(2, LocalTimeRange(LocalTimeHMS("01:30:00"), LocalTimeHMS("23:59:59")));

Every 15 minutes between 9:00 AM and 5:00 PM local time, otherwise every 2 hours (00:00, 02:00, 04:00 local time)

schedule.withMinuteOfHour(15, LocalTimeRange(LocalTimeHMS("09:00:00"), LocalTimeHMS("16:59:59")));
schedule.withHourOfDay(2);

If configuring by JSON:

Day of week of the month

This is used for things like: "Every first Monday of the month," "Every second Tuesday of the month," or "Last Friday of the month."

// PROTOTYPE (class LocalTimeSchedule)
LocalTimeSchedule &withDayOfWeekOfMonth(int dayOfWeek, int instance, LocalTimeRange timeRange = LocalTimeRange());

• The dayOfWeek specifies the day of the week (Sunday = 0, Monday = 1, Tuesday = 2, ..., Saturday = 6).
• The instance specifies which instance (1 = first, 2 = second, ... Or -1 = last, -2 = second to last, ...)
• The LocalTimeRange can restrict this to certain hours of the day, and certain days of the week. It can also handle exception dates, both only on date, or to exclude dates.
• The start of the time range specifies the hour, minute, and second (local time)
• Use a time of day with day of week restriction instead if you want to do "Every Monday"

First Saturday of the month at midnight local time:

schedule.withDayOfWeekOfMonth(LocalTimeDayOfWeek::DAY_SATURDAY, 1);

First Monday of the month at 9:00 AM local time:

schedule.withDayOfWeekOfMonth(LocalTimeDayOfWeek::DAY_MONDAY, 1, LocalTimeHMS("09:00:00"));

Last Friday of the month at 5 PM local time.

schedule.withDayOfWeekOfMonth(LocalTimeDayOfWeek::DAY_FRIDAY, -1, LocalTimeHMS("17:00:00"));

Day of month

This is used for things like "The 1st of the month," "The 15th of the month," or "the last day of the month."

// PROTOTYPE (class LocalTimeSchedule)
LocalTimeSchedule &withDayOfMonth(int dayOfMonth, LocalTimeRange timeRange = LocalTimeRange());

• The dayOfMonth specifies which instance (1 = 1st of the month, 2 = 2nd of the month, ... Or -1 = last day, -2 = second to last day, ...)
• A LocalTimeRange can handle exception dates, both only on date, or to exclude dates.
• The start of the time range specifies the hour, minute, and second (local time)

For example, the 6th of the month at midnight:

schedule.withDayOfMonth(6);

The 6th of the month at 6:00 AM local time:

schedule.withDayOfMonth(6, LocalTimeHMS("06:00"));

The last day of the month at 11:59:59 PM:

schedule.withDayOfMonth(-1, LocalTimeHMS("23:59:59"));

The second to last day of the month:

schedule.withDayOfMonth(-2);

Time schedule

It's also possible to schedule at a specific time in local time. You can specify zero or more LocalTimeHMSRestricted objects, limited by available RAM.

The LocalTimeHMSRestricted is itself composed of a LocalTimeHMS object, for hours minutes and seconds, and a LocalTimeRestrictedDate which can optionally restrict which dates the times re used.

Some ways you can use times:

• "At 17:00:00" every day (local time)
• "At 17:00:00, Monday - Friday"
• "At 09:00:00, Monday - Friday, except for 2022-03-21"
• "At 23:59:59 on 2022-03-31"

// PROTOTYPE (class LocalTimeSchedule)
LocalTimeSchedule &withTime(LocalTimeHMSRestricted hms);
LocalTimeSchedule &withTimes(std::initializer_list<LocalTimeHMSRestricted> timesParam);

At 4:00 AM local time, every day:

schedule.withTime(LocalTimeHMS("04:00"));

At 06:00 and 18:30 (4:30 PM) local time, every day. Note the {} surrounding a list of times.

schedule.withTimes({LocalTimeHMS("06:00"), LocalTimeHMS("18:30")});

At 4:00 AM on weekdays:

schedule.withTime(LocalTimeHMSRestricted("04:00", LocalTimeRestrictedDate(LocalTimeDayOfWeek::MASK_WEEKDAY)));

At midnight (local time) on Saturdays:

schedule.withTime(LocalTimeHMSRestricted("00:00", LocalTimeRestrictedDate(LocalTimeDayOfWeek::MASK_SATURDAY)));

If configuring by JSON:

All methods

LocalTimeHMS

This object holds a hour, minute, and second value (HMS). There are numerous methods to compare time values, and convert the values to other formats.

When converting from string format always use 24-hour clock format; this object does not support AM/PM. Also when converting from strings you can omit the seconds, or even both the minutes and seconds.

Note that hour 24 is never a valid value. Because HMS calculations are always inclusive, the end of the day is 23:59:59. Leap seconds are not supported by the underlying C standard time library.

LocalTimeYMD

This object specifies a year, month, and day. There are numerous methods to compare time values, and convert the values to other formats.

When converting from a string this must always be "YYYY-MM-DD" format, with dashes, and in that order. Other date formats including common but poorly defined United States date formats cannot be used!

LocalTimeRange

A LocalTimeRange is a start time and end time in local time, expressed as LocalTimeHMS objects (hours, minutes, seconds).

Time ranges are inclusive, so the entire day is 00:00:00 to 23:59:59.

The default constructor for LocalTimeRange sets the time range to the entire day.

When converting from JSON:

####### LocalTimeDayOfWeek

A LocalTimeDayOfWeek specifies zero or more days of the week (Sunday, Monday, ...)

Common mask values:

Note that you can combine any mask bits. For example, Monday, Wednesday, Friday is 2 + 8 + 32 = 42,

In JSON, you can only use the numeric mask values, as a decimal number. For example, weekdays Monday - Friday is 62.

LocalTimeRestrictedDate

A LocalTimeRestrictedDate is used for both multiples and times (below). It can have:

• A day of week selection (LocalTimeDayOfWeek), which is a bitmask of days to allow. This makes it easy to specify, for example, weekdays (Monday - Friday).
• A list of dates to allow (vector of LocalTimeYMD)
• A list of dates to exclude (vector of LocalTimeYMD)

Version history

0.1.1 (2023-12-10)

• Added LocalDateTimeRange as a container to hold a UTC time range.

0.1.0 (2023-11-25)

• Added support for LocalTimeRange that crosses midnight (9:00 PM to 5:00 AM, for example).

0.0.9 (2022-04-06)

• Remove automated test from Particle library upload

0.0.8 (2022-04-06)

• Added advanced scheduling modes (JSON scheduling)
• Updated docs

0.0.7 (2022-03-08)

• Added inLocalTimeRange and nextTimeList functions
• Added LocalTimeSchedule

0.0.6 (2022-03-08)

• Added nextMinuteMultiple() and nextTime() functions

0.0.5 (2021-07-08)

• Fixed bug in calculation of negative hour offsets that also included minutes
• Added unit test for Adelaide, Australia

0.0.4 (2021-06-26)

• Added nextDayOrTimeChange

0.0.3 (2021-06-11)

• Remove more-examples code from library

0.0.2 (2021-06-07)

• Add examples

0.0.1 (2021-06-06)

• Initial version

Browse Library Files