Mac Home Automation

The XTension caldav plugin lets you link Units in XTension to the existence of an event on your calendar during a certain relative time frame. For example a unit could turn on if an event containing the term “no school” was present on the calendar for tomorrow.

The plugin is compatible with any official CalDAV server and also with Apple’s calendars if you are saving them to iCloud. See the section below on Apple Calendar integration for more information and specific instructions.

As of version 1.0 only the single Unit type is available that will be on if an event exists during the selected time frame and off if it does not. If you need more or different access to the calendar data I can add additional unit types to support that, please let me know.

From the Interface List window create a new Interface and select Caldav Event Plugin from the Device or plugin popup.

Resource Type: Calendars are generally shared as either a straight vCalendar download link or through an actual CalDav server. The plugin supports both types but you have to tell it which your link is to. For an actual CalDav server select that, if your link is a vCalendar file from a regular web server select the vCalendar option.

URL: The URL field should be filled in with the link to the caldav principal base. For Apple Calendars see the next section. The Username and Password fields can be left blank if none is required. NOTE that if you’re using a vCalendar server you will need to encode any necessary user and password into the URL itself and not use the user/password fields. Like: “http://user@password:servername/link”

Generally only a single plugin instance will be necessary for any given server or service. All the calendars that are available to your account will be available to a single instance of the plugin. It is not necessary to create separate instances for each Calendar if they are available to the same account.

This is different also for a straight vCalendar link. In that case the first vCalendar defined in the file is used. If you need to parse longer vCalendar files that may define multiple calendars please let me know as that can be added in a future version.

Update: The Update popup selects how often you wish to update the data. This creates load on the server and should not be set any faster than necessary for your application. Generally every 15 minutes should be fine but for many applications running every hour would be more than sufficient.

Note that the update intervals are calculated from the start of the hour, for example even if you start the plugin at 3 minutes after the hour with an interval set to 5 minutes it will run an update at 5 minutes after, 10 minutes after etc. The same is done for the other intervals. If you select 15 minutes they will run at :00, :15, :30 and :45 after the hour. An initial load is done immediately upon starting up of the interface, but after that they are calculated to fall on the proper intervals.

The Refresh Units Now button will be greyed out until you enable the interface and then it will also enable. If you have made changes to Units or other settings and wish to run an update immediately you can click this button or from a script via the command in the script commands section.

The plugin works great with Apple Calendars as long as you have enabled them to sync to iCloud. The setup process is slightly more involved. The Username field should be your Apple ID but do not put your Apple ID password into the password field. Instead visit https://appleid.apple.com/ (note that if you wish you can type that address into the url field of your browser manually to avoid any fear of possibly being linked to a phishing site or similar) and log in.

Under the Security section and the App-Specific Passwords subheading there is a link to “Generate Password…” clicking on that will let you create a separate app password for this connection which you will enter into the password field in XTension that will allow you access to all the calendars that you have synced to iCloud including those shared with you from other sources.

The URL field for Apple Calendars is always “https://caldav.icloud.com/“ it is not necessary to try to access a specific calendar via the sharing links provided in Calendars and it is also not necessary to set a shared calendar as “public” as this is a direct and authenticated connection to your own iCloud synced calendars.

To link a Unit to the presence of an event on the calendar create a New Unit and assign it to the Interface you created above via the Interface popup. Since there is only a single Unit defined by the plugin at this moment the “Event Presence” Unit type will be selected automatically in the Device popup.

Please also check the Receive Only and Ignore Clicks checkboxes. The Dimmable checkbox should be left unchecked as the presence of an event is a discrete on/off indication and not a value.

Unlike most Units in XTension it is not necessary to create an Address for this unit type. Please leave the Address field blank, but do give the unit a descriptive name.

Enter the calendar name into the Calendar Name field. The search is not case sensitive. You may match all or part of the event name in the Event Name section. The popup will let you select from “Is Exactly, “Contains”, “Starts With” or “Ends With” again the matching is not case sensitive.

The Start Search and End Search fields use a simple relative time description. The start always starts at the moment of midnight on the current day. The format of the string is a number (positive or negate) followed by a suffix denoting the unit. “w” for weeks (the previous or next 7 days, not a week starting specifically on Sunday or Monday) “d” for days, “h” for hours, “m” for minutes and “s” for seconds.

If you wish to see if an event exists today use “0d” as the start field and “1d” as the end field. To see if an event exists tomorrow use “1d” as the start date and “2d” as the end date. To see if an event exists yesterday use “-1d” as the start date and “0d” as the end date.

Any repeating or multi day events are expanded in the query and so you will able to query for multiple day events, all day events as well as timed events that do not last an entire day.

To look for an event existing between 6:00am and 9:00am use “6h” as the start date and “9h” as the end date. The starting position is always the start of the day and not the time that the update is run.

When connecting to a straight vCalendar file the Calendar Name field on the Edit Unit dialog is ignored. Otherwise they function the same.

The plugin currently implements a single scripting command. You can initiate an update via the scripting command refreshnow() used like:

tell xInterface “name you gave the plugin instance above” to refreshnow()

In order to reduce server load and traffic the shortest time frame for updating a calendar is every 5 minutes.

When it is time to refresh the Units only a single query is run for each calendar. All the units listing the same calendar type are scanned and the earliest and latest times they all request are used to create a single query that spans the entire asked for time of all the units. Then the units scan the list to see if the event they are interested is within their selected time frames. This reduces the number of queries that have to be run and increases the speed of getting the data but may create a lot of extra traffic if you have a unit that is looking for for events in the far distant past or the far future.

I created a unit looking for an event named “no school” in my son’s school schedule for today and tomorrow. I am now using that to control the behavior of the wake up script in the morning without my having to always remember to enable or disable it for the next day.

To keep my wife from accidentally muting her pager at bedtime when she is on call I also created a Unit searching her call schedule calendar for “on call” for today. I then used an ESP32 and ePaper display to make her this for her bedside table. It updates as the Unit changes value and since it is an ePaper display it can be on the bedside without making so much light to disrupt anyones sleep. I may update it in the future to display more useful information such as the upcoming weather in the morning or other such things but for the moment it simply displays the monochrome image displayed when she is on call and another that says more happily that she is not if the unit is off.

• The CalDAV plugin was written by James Sentman in January of 2021 and was first included in XTension version 9.4.36.
• The ability to work with straight vCalendar files was added in XTension version 9.4.37