The Ephemeris docs are now live.
Actions | openHAB
I’m closing this wiki for further edits. Please refer to the above link for the latest docs for Ephemeris.
Besides @glhopital and @cweitkamp I think I’m among the first to use and apply the new Ephemeris capability built into OH. Correct me if I’m wrong, but I believe it is best to use OH 2.5 M4 or later as there were some bugs fixed prior to that milestone release. There are some new features being added as well so upgrading will be recommended as well when the next milestone becomes available.
Anyway, this post is going to be a first cut at documentation for Ephemeris. @Confectrician, I believe this most appropriately would be included on the Actions page, as it is something built into OH and therefore not an add-on and besides configuration, all interaction with it is done through Rule Actions. It’s a lot like the sendHttpXRequest Actions in that respect, but unlike all the rest of the built in Actions, this one requires come configuration. Do you agree? I’d like to know the best place to put this before creating a PR.
I’ll make this a wiki so anyone can contribute.
The below would be a subsection under “Core Actions” on the Actions page.
Ephemeris
Ephemeris is a way to determine what type of day today or a number of days before or after today is. For example, to determine if today is a weekend, a bank holiday, someone’s birthday, trash day, etc.
Rules DSL
-
isWeekend: returns true if today is a weekend -
isWeekend(<offset>): returns true if the day<offset>days from now is the weekend. Use a negative offset to check days in the past.<offset>must be an integer. -
isInDayset("<set>"): returns true if today is in the custom dayset<set>(see below), example,isInDayset("school"). -
isInDayset("<set>", <offset>): returns true if the day<offset>days from now is in the custom dayset<set>. -
isBankHoliday: returns true if today is a bank holiday. -
isBankHoliday(<offset>): returns true if the day<offset>days from now is a bank holiday -
isBankHoliday(<offset>, <file>): returns true if the day<offset>days from now is a bank holiday defined in<file>. -
getBankHolidayName: returns the name of the holiday if today is a bank holiday, null if today is not a bank holiday. -
getBankHolidayName(<offset>): returns the name of the holiday<offset>days from today, null if that day isn’t a bank holiday. -
getBankHolidayName(<offset>, <file>): returns the name of the holiday<offset>days from today defined in the custom list of holidays in the<file>. -
isWeekend(<datetime>): returns true if the passed in date time is a weekend. -
isInDayset("<set>", <datetime>): returns true if the passed in date time is in the custom dayset. -
isBankHoliday(<datetime>): returns true if<datetime>is a bank holiday. -
isBankHoliday(<datetime>, <file>): returns true if<datetime>is a bank holiday defined in<file>. -
getBankHolidayName(<datetime>): returns the name of the holiday on the passed in date time, null if that day is not a holiday. -
getBankHolidayName(<datetime>, <file>): returns the name of the holiday on the passed in date time defined in the custom list of days in<file>: null if that date is not defined in<file>. -
getHolidayDescription(<holiday name>): returns the localized holiday description for the given<holiday name>. -
getDaysUntil(<holiday name>): returns the number of days from today to the next<holiday name> -
getDaysUntil(<datetime>, <holiday name>): returns the number of days between<datetime>and<holiday name>. -
getDaysUntil(<holiday name>, <file>): returns the number of days from today to the next<holiday name>defined in the custom<file>. -
getDaysUntil(<datetime>, <holiday name>, <file>): returns the number of days from<datetime>to <holiday name>defined in the custom<file>. -
getNextBankHoliday: returns the name of the next bank holiday -
getNextBankHoliday(<offset>): returns the name of the next bank holiday after today plus<offset>. -
getNextBankHoliday(<datetime>): returns the name of the next bank holiday after<datetime>. -
getNextBankHoliday(<file>): returns the name of the next bank holiday defined in<file>. -
getNextBankHoliday(<offset>, <file>): returns the name of the next bank holiday after today +<offset>defined in<file>. -
getNextBankHoliday(<datetime>, <file>): returns the name of the next bank holiday after<datetime>defined in<file>.
Scripted Automation:
One must import the Ephemeris Action and then call the above functions using Ephemeris.<function>, for example Ephemeris.getNextBankHoliday().
Configuration:
If your initial installation of openHAB was version 2.5 M4 or later, a default configuration for Ephemeris will exist in $OH_CONF/services/runtime.cfg.
org.openhab.ephemeris:dayset-weekend = [SATURDAY,SUNDAY]
org.openhab.ephemeris:dayset-school = [MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY]
Because upgrades do not replace files in /etc/openhab2, if your initial installation of OH was prior to OH 2.5 M4, you will not have these values in runtime.cfg. It is important that you have at a minimum dayset-weekend defined or the isWeekend Action will generate errors. Therefore you should manually add at least dayset-weekend using one of the two configuration methods described below. If you installed OH after OH 2.5 M4 and need to define new daysets, remove the above two lines from runtime.cfg and add them to ephemeris.cfg as described below along with your new ones. Failure to do this may generate a race condition where sometimes the daysets in runtime.cfg take precedence and other times the ones defined in ephemeris.cfg takes precedence.
PaperUI Configs:
In PaperUI one has the ability to configure which days of the week are considered weekends and set your country, region, and city. If no country is provided the service uses your system default locale settings. Browse to Configuration and System and scroll down to the Ephemeris section. Setting the country, region and optionally city will cause Ephemeris to use the list of bank holidays defined for that location by Jollyday. You can find the XML file for your country here and the localized mapping files that map between the holiday name in the XML and your preferred language are located here.
When filling in the country, region and city, if there isn’t a drop down list for one after choosing the one(s) higher up (e.g. there is no drop down list for city after choosing country and region), leave that field blank. There are no special bank holidays defined by Jollyday for that level.
ephemeris.cfg:
By default Ephemeris supports a weekend dayset and a school dayset. You can define additional daysets or modify the school dayset. If you need to define custom daysets, you must do all your configuration through the ephemeris.cfg file instead of using PaperUI as described above so make sure to redefine the weekend dayset.
Config file location: $OH_CONF/services/ephemeris.cfg.
Fields:
-
country: country to use to get the built in list of bank holidays, uses the standard two letter country code. -
region: uses the appropriate two letter region code. -
dayset-<name>: list of the days of that are in this dayset
If in doubt on what values to use, see the links above to find the XML file for your country, open the XML file, and find the tns:SubConfigurations for your region and use the “hierarchy” value for region.
For example:
country=de
region=nw
dayset-workday=Monday,Tuesday,Wednesday,Thursday,Friday
dayset-weekend=Saturday,Sunday
dayset-trash=Monday
NOTE: if you do not define dayset-weekend, the isWeekend Action will generate errors.
Custom days of the year:
In addition to the ability to define daysets, one can define a custom list of holidays. If you’ve opened the Jollyday XML file for your country already you know what your custom file needs to look like. The following is an example listing some custom days.
<?xml version="1.0" encoding="UTF-8"?>
<tns:Configuration hierarchy="us" description="United States"
xmlns:tns="http://www.example.org/Holiday" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.example.org/Holiday /Holiday.xsd">
<tns:Holidays>
<tns:Fixed month="MARCH" day="20" descriptionPropertiesKey="Rich Birthday" />
<tns:Fixed month="MARCH" day="27" descriptionPropertiesKey="Son's Birthday" />
<tns:Fixed month="JUNE" day="12" descriptionPropertiesKey="Wife's Birthday" />
<tns:Fixed month="DECEMBER" day="27" descriptionPropertiesKey="Anniversary" />
<tns:FixedWeekday which="FIRST" weekday="TUESDAY" month="NOVEMBER" descriptionPropertiesKey="Election Day"/>
</tns:Holidays>
</tns:Configuration>
These should give you enough examples to do almost anything but if you want to dig deeper, look at the xsd that defines the structure of the XML here.
You can place this file anywhere on your file system that OH has access to. Use the full path to the file in your calls to the Actions.
