Particle-dst

DST switching made simple!

What is it?

Particle-dst is a simple Particle library that can be easily used to switch manually or automatically DST all over the world on Particle devices!

Installation

Particle-dst is easy to install because it is a normal Particle library.
There are three ways to install this library:

Command Line Interface (CLI)

First of all, go to your project directory:

cd /path/to/your/fantastic/project

Then install the library with the following command:

particle library add particle-dst

Web IDE (Build)

Select your project or create a new one
Click on Libraries in the left sidebar
In the search field type: dst
Select particle-dst
Click on ÌNCLUDE IN PROJECT

Desktop IDE (Dev)

Select your project or create a new one
Click on Browse and manage Particle libraries in the left sidebar
In the search field type: dst
In the particle-dst panel click on Use

Usage

1) Define limits

The library enable and disable DST using two limits that define the beginning and the end dates of DST in your country.
Limits can be created using the specific type provided by the library:

// create the two limits
dst_limit_t beginning;
dst_limit_t end;
// define beginning of DST
beginning.hour = 2;
beginning.day = DST::days::tue;
beginning.month = DST::months::feb;
beginning.occurrence = 2;
// define end of DST
end.hour = 3;
end.day = DST::days::wed;
end.month = DST::months::oct;
end.occurrence = 2;

To define days and months you can use the Particle numbering or you can easily use the enumerators provided by the library. (The values will be converted to the Particle numbering)

beginning.day = DST::days::tue;
// same as
beginning.day = 3; // tuesday

beginning.month = DST::months::feb;
// same as
beginning.months = 2; // february

The occurrence indicates in which week of the target month the DST change.
It could have positive and negative values to indicate if the occurrence is from the beginning or the end of the month:

positive: occurrence from the beginning of the month

negative: occurrence from the end of the month

beginning.occurrence = 1; // first week
beginning.occurrence = -1; // last week

2) Initialize the library

To start using the library, initialize it with the two limits. The last parameter indicates the DST offset in your country.

DST dst;
dst_limit_t beginning;
dst_limit_t end;
void setup() {
  // initialize limits
  // ...
  dst.begin(beginning, end, 1); // DST adds 1 hour
}

3) Use it

There are two methods to use this library: manual mode where the user application has to periodically check if the DST has changed or automatic mode where the library switch DST on its own.

Manual mode

In manual mode the user has to periodically trigger the library to check if DST changed.
To switch DST, simply call one method defined in the library:

bool enabled = dst.check();
// returns true if DST is enabled and false if it is disabled
Serial.printlnf("DST: %s", enabled ? "enabled" : "disabled");

Automatic mode

In automatic mode the library checks every hour if DST is enabled or disabled automatically without the need of any user interaction.
Simply activate the automatic mode passing true to the automatic() method and you’re done!

NOTE: You have to enable the automatic mode after the initialization of the library otherwise it will not work!

dst.begin(beginning, end, 1);
// ...
dst.automatic(true); // enable automatic mode

You can disable the automatic mode whenever you want passing false to the automatic() method:

dst.automatic(false); // disable automatic mode

Other features

Format limits

With particle-dst you can get the timestamp of the beginning and the end of DST in the current year:

int beginning = dst.beginning();
// example: 1487037600
int end = dst.end();
// example: 1507690800

Moreover it is possible to get a formatted string of the limits of the DST in the current year:

char beginning[] = dst.beginning("%a, %d %B @ %R");
// example: Tue, 14 February @ 02:00
char end[] = dst.end("%a, %d %B @ %R");
// example: Wed, 11 October @ 03:00

The library supports all the Particle format strings:

TIME_FORMAT_DEFAULT
TIME_FORMAT_ISO8601_FULL
string based on strftime() (docs: http://www.cplusplus.com/reference/ctime/strftime/)

DST enabled

bool enabled = dst.enabled();

This function returns true if DST is currently enabled and false otherwise.

Time zone

Set the local time zone.

// set time zone to Central European Time
dst.timezone(1);

API

void begin(dst_limit_t beginning_limit, dst_limit_t end_limit, int offset);

bool check();

void automatic(bool enable);

int beginning();

char* beginning(String format);

int end();

char* end(String format);

bool enabled();

void timezone(int zone);

Help me

I’ve tried to develop this library to be easy to use without having to write many lines of code for doing a simple activity.
If you have some suggestions or you found a bug (oh no!), please send me an e-mail at luca.morandini98@gmail.com!

That’s all folks!