[WIP] Ephemeris Documentation

@cweitkamp, how are the days in the school dayset defined? PaperUI only provides the ability to define the days for dayset-weekend and when I look in ephemeris.config in $OH_USERDATA there is no dayset-school defined. I’ve not yet created an ephemeris.cfg file. I think I tried to test for a school dayset when I played with the Actions but now I’m not so sure.

My mistake in a previous thread. Only weekend is required by the bundle.

@rlkoshak Currently a new OH2 installation (OH2.5.M4 or later) will be delivered with the following default configuration in the runtime.cfg inside $OPENHAB_CONF/services/ folder:

org.openhab.ephemeris:dayset-weekend = [SATURDAY,SUNDAY]
org.openhab.ephemeris:dayset-school = [MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY]

dayset-weekend is mandatory to guarantee working isWeekend related methods / actions. dayset-school is optional, because we have no related built-in methods / actions. It can be replaced / extended by any other dayset of ones needs. Additionally there is no proper way to define other daysets via UIs.

I’ve tried it with the example-xml file:

        <tns:Holidays>
            <tns:Fixed month="JANUARY" day="6" descriptionPropertiesKey="EPIPHANY"/>
            <tns:Fixed month="OCTOBER" day="31" descriptionPropertiesKey="REFORMATION_DAY"/>
            <tns:Fixed month="NOVEMBER" day="1" descriptionPropertiesKey="ALL_SAINTS"/>
            <tns:ChristianHoliday type="CORPUS_CHRISTI"/>
        </tns:Holidays>

But both,
Ephemeris.getBankHolidayName(0,’/etc/openhab2/ephemeris/Holidays_de.xml’)
and
Ephemeris.getBankHolidayName(1,’/etc/openhab2/ephemeris/Holidays_de.xml’)
only returns null

Why runtime.cfg instead of ephemeris.cfg?

That’s not a complete XML file. Try:

<?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="JANUARY" day="6" descriptionPropertiesKey="EPIPHANY"/>
            <tns:Fixed month="OCTOBER" day="31" descriptionPropertiesKey="REFORMATION_DAY"/>
            <tns:Fixed month="NOVEMBER" day="1" descriptionPropertiesKey="ALL_SAINTS"/>
            <tns:ChristianHoliday type="CORPUS_CHRISTI"/>
        </tns:Holidays>
</tns:Configuration>

See Failed to install artifact: /var/lib/openhab2/etc/org.openhab.ephemeris.cfg and https://github.com/openhab/openhab-core/issues/1121

OK, so these are just defaults and users are still expected to put their customization in ephemeris.cfg.

What happens when a user creates ephemeris.cfg? Are they required to redefine dayset-weekend, or does ephemeris.cfg only add to what’s in runtime.cfg? I want to make sure the docs are clear about what must be in ephemeris.cfg.

It was just an extract of my file…
this is the full xml:

<?xml version="1.0" encoding="UTF-8"?>
<tns:Configuration hierarchy="de" description="Germany" 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="JANUARY" day="1" descriptionPropertiesKey="NEW_YEAR"/>
        <tns:Fixed month="MAY" day="1" descriptionPropertiesKey="LABOUR_DAY"/>
        <tns:Fixed month="OCTOBER" day="3" validFrom="1990" descriptionPropertiesKey="UNIFICATION_GERMANY"/>
        <tns:Fixed month="DECEMBER" day="25" descriptionPropertiesKey="FIRST_CHRISTMAS_DAY"/>
        <tns:Fixed month="DECEMBER" day="26" descriptionPropertiesKey="SECOND_CHRISTMAS_DAY"/>
        <tns:ChristianHoliday type="GOOD_FRIDAY"/>
        <tns:ChristianHoliday type="EASTER_MONDAY"/>
        <tns:ChristianHoliday type="ASCENSION_DAY"/>
        <tns:ChristianHoliday type="WHIT_MONDAY"/>
    </tns:Holidays>
    <tns:SubConfigurations hierarchy="bw" description="Baden-Württemberg">
        <tns:Holidays>
            <tns:Fixed month="JANUARY" day="6" descriptionPropertiesKey="EPIPHANY"/>
            <tns:Fixed month="OCTOBER" day="31" descriptionPropertiesKey="REFORMATION_DAY"/>
            <tns:Fixed month="NOVEMBER" day="1" descriptionPropertiesKey="ALL_SAINTS"/>
            <tns:ChristianHoliday type="CORPUS_CHRISTI"/>
        </tns:Holidays>
    </tns:SubConfigurations>
</tns:Configuration>

Is the xml-file read on each acces or cached?

You catched it. The xml file is cached upon first read.

And to refresh it’s enough to restart openhab?
Or better rename the xml-file?

Yes, rename the xml file is the easiest while debugging.

    status += ", 'isWeekend': " + Ephemeris.isWeekend
    status += ", 'isBankHoliday': " + Ephemeris.isBankHoliday(0,'/etc/openhab2/ephemeris/Holidays_de2.xml')
    status += ", 'getBankHolidayName': " + Ephemeris.getBankHolidayName(1,'/etc/openhab2/ephemeris/Holidays_de2.xml')
    status += ", 'isInDayset(school)': " + Ephemeris.isInDayset("school")
...
    logInfo("Observation_Check", status)

results in

2019-10-31 16:16:00.017 [INFO ] [thome.model.script.Observation_Check] - {'status': 'OK', 'isWeekend': false, 'isBankHoliday': false, 'getBankHolidayName': null, 'isInDayset(school)': true }

So the Holiday-xml seems to be ignored.

Can you try to remove “subconfigurations” hierarchy tags from your xml ? I have none in mine and it works.

1 Like

Long story short: We used the ephemeris.cfg at the beginning. But because of a bug in the Apache fileinstall we had to move the default configuration to different location.

I guess the same thing like every time. You are able to add an ephemeris.cfg file and it will override existing configurations. But you have to be aware of that the latest edit will win - thus we maybe should recommend to remove the default configuration from runtime.cfg at the time one will add a different config file for Ephemeris service.

How would I go to define shool holiday periods like from 23rd Dec 2019 until 3rd January 2020?
Thanks

From what I can tell so far, the only way to do that is enter a separate entry for each of those days. There is no way that I could find by studying the XSD to define something that stretches across multiple days. Looking at some of the examples and the religious holidays in the schema I notice Jollyday defines a separate entry for each day. There is no way to define a number of days.

It’s also worth noting though, that many religious holidays are also built into Jollyday so even if your country doesn’t give a bank holiday for a given religious holiday, you don’t necessarily need to manually calculate the date yourself. But as with most things like this, you will need to look at the code to verify if the calculation is correct (e.g. Orthodox Christians and Roman Catholic and Protestants calculate the date for Easter differently and I’m not knowledgeable enough to tell if the code handles it correctly).

I’ve updated the docs to cover this rutime.cfg stuff. It strikes me as kind of awkward.

Did anyone consider just having isWeekend return null if there isn’t a weekend dayset? Then we can just say “add a isWeekend dayset to ephemeris.cfg or configure it in PaperUI if that happens.” Then we don’t have to worry at all about runtime.cfg and there is only the two standard ways to config it. Hopefully the UI in OH 3 will let us create daysets that way.

Currently I use Caldav for this

Me too, I thought that would be a good alternative though

I’ve created the PR.

Please add any further comments and edits there.

1 Like