particle-dst (community library)
Summary
Name | Value |
---|---|
Name | particle-dst |
Version | 0.1.0 |
Installs | |
License | MIT |
Author | Luca Morandini luca.morandini98@gmail.com |
URL | https://github.com/lucamora/particle-dst |
Repository | https://github.com/lucamora/particle-dst.git |
Download | .tar.gz |
DST switching made simple! Write few lines of code to manually or automatically switch DST all over the world!
Example Build Testing
Device OS Version:
This table is generated from an automated build. Success only indicates that the code compiled successfully.
Library Read Me
This content is provided by the library maintainer and has not been validated or approved.
Particle-dst
DST switching made simple!
What is it?
Particle-dst is a simple Particle library that can be used to switch manually or automatically DST all over the world on Partcle 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)
Desktop IDE (Dev)
How to use it
1) Limits definition
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) Initialization
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) Usage
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 don't 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
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/)
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!
Thanks and happy coding!
Browse Library Files