iCalendar Binding

This binding is intended to use a web-based iCal calendar as an event trigger or presence switch. It implements several channels that indicate the current calendar event and upcoming calendar events. Furthermore it is possible to embed command tags in the calendar event description in order to issue commands directly to other items in the system, without the need to create special rules.

Supported Things

The primary thing type is the calendar. It is based on a single iCalendar file and implemented as bridge. There can be multiple things having different properties representing different calendars.

Each calendar can have event filters which allow to get multiple events, maybe filtered by additional criteria. Time based filtering is done by each event's start.

Thing Configuration

Configuration for calendar

Each calendar thing requires the following configuration parameters:

parameter name	description	optional
url	The URL of an iCal Calendar to be used as a source of events.	mandatory
refreshTime	The frequency in minutes with which the calendar gets refreshed from the source.	mandatory
username	The username for pulling the calendar. If set, the binding pulls the calendar using basic auth. Only valid in combination with password.	optional
password	The password for pulling the calendar. If set, the binding pulls the calendar using basic auth. Only valid in combination with username.	optional
maxSize	The maximum size of the iCal-file in Mebibytes.	mandatory (default available)
authorizationCode	The authorization code to permit the execution of embedded command tags. If set, the binding checks that the authorization code in the command tag matches before executing any commands.	optional

Configuration for eventfilter

Each eventfilter thing requires a bridge of type calendar and has following configuration options:

parameter name	description	optional
maxEvents	The count of expected results.	mandatory
refreshTime	The frequency in minutes the channels get refreshed.	mandatory (default available)
datetimeUnit	A unit for time settings in this filter. Valid values: MINUTE, HOUR, DAY and WEEK.	optional (required for time-based filtering)
datetimeStart	The start of the time frame where to search for events relative to current time. Combined with datetimeUnit.	optional
datetimeEnd	The end of the time frame where to search for events relative to current time. Combined with datetimeUnit. The value must be greater than datetimeStart to get results.	optional
datetimeRound	Whether to round the datetimes of start and end down to the earlier time unit. Example if set: current time is 13:00, timeunit is set to DAY. Resulting search will start and end at 0:00.	optional
textEventField	A field to filter the events text-based. Valid values: SUMMARY, DESCRIPTION, COMMENT, CONTACT and LOCATION (as described in RFC 5545).	optional/required for text-based filtering
textEventValue	The text to filter events with.	optional
textValueType	The type of the text to filter with. Valid values: TEXT (field must contain value), REGEX (field must match value, completely, dot matches all, case insensetive).	optional/required for text-based filtering

Channels

Channels for calendar

The channels of calendar describe the current and the next forthcoming event. They are all read-only.

Channel	Type	Description
current_presence	Switch	Current presence of an event, ON if there is currently an event, OFF otherwise
current_title	String	Title of a currently present event
current_start	DateTime	Start of a currently present event
current_end	DateTime	End of a currently present event
next_title	String	Title of the next event
next_start	DateTime	Start of the next event
next_end	DateTime	End of the next event

Channels for eventfilter

The channels of eventfilter are generated using following scheme, all are read-only.

Channel-scheme	Type	Description
result_<no>#begin	DateTime	The begin of an event
result_<no>#end	DateTime	The end of an event
result_<no>#title	String	The title of an event

The scheme replaces <no> by the results index, beginning at 0. An eventfilter having maxEvents set to 3 will have following channels:

• result_0#begin
• result_0#end
• result_0#title
• result_1#begin
• result_1#end
• result_1#title
• result_2#begin
• result_2#end
• result_2#title

Command Tags

Each calendar event may include one or more command tags in its description text. These command tags are used to issue commands directly to other items in the system when the event begins or ends. A command tag must consist of at least three fields. A fourth field is optional. The syntax is as follows:

	BEGIN:Item_Name:New_State_Value
	BEGIN:Item_Name:New_State_Value:Authorization_Code
	END:Item_Name:New_State_Value
	END:Item_Name:New_State_Value:Authorization_Code

The first field must be either BEGIN or END. If it is BEGIN then the command will be executed at the beginning of the calendar event. If it is END then the command will be executed at the end of the calendar event. A calendar event may contain multiple BEGIN or END tags. If an event contains both BEGIN and END tags, the item is (say) to be turned ON at the beginning of an event and turned OFF again at the end of the event.

The Item_Name field must be the name of an item.

The New_State_Value is the state value that will be sent to the item. It must be a value which is compatible with the item type. See openHAB Core definitions for command types (opens new window) for valid types and formats.

The Authorization_Code may optionally be used as follows:

• When the thing configuration parameter authorizationCode is not blank, the binding will compare the Authorization_Code field against the authorizationCode configuration parameter, and it will only execute the command if the two strings are the same.

• When the thing configuration parameter authorizationCode is blank, the binding will NOT check this Authorization_Code field, and so it will always execute the command.

Full Example

All required information must be provided in the thing definition, either via UI or in the .things file..

Bridge icalendar:calendar:deadbeef    "My calendar" @ "Internet" [ url="http://example.org/calendar.ical", refreshTime=60 ]
Thing  icalendar:eventfilter:feedd0d0 "Tomorrows events" (icalendar:calendar:deadbeef) [ maxEvents=1, datetimeUnit="DAY", datetimeStart=1, datetimeEnd=2, datetimeRound=true ]

Link the channels as usual to items:

String   current_event_name        "current event [%s]"                       <calendar> { channel="icalendar:calendar:deadbeef:current_title" }
DateTime current_event_until       "current until [%1$tT, %1$tY-%1$tm-%1$td]" <calendar> { channel="icalendar:calendar:deadbeef:current_end" }
String   next_event_name           "next event [%s]"                          <calendar> { channel="icalendar:calendar:deadbeef:next_title" }
DateTime next_event_at             "next at [%1$tT, %1$tY-%1$tm-%1$td]"       <calendar> { channel="icalendar:calendar:deadbeef:next_start" }
String   first_event_name_tomorrow "first event [%s]"                         <calendar> { channel="icalendar:eventfilter:feedd0d0:event_0#title" }
DateTime first_event_at_tomorrow   "first at [%1$tT, %1$tY-%1$tm-%1$td]"      <calendar> { channel="icalendar:eventfilter:feedd0d0:event_0#begin" }

Sitemap just showing the current event and the beginning of the next:

sitemap local label="My Calendar Sitemap" {
    Frame label="events" {
        Text item=current_event_name label="current event [%s]"
        Text item=current_event_until label="current until [%1$tT, %1$tY-%1$tm-%1$td]"
        Text item=next_event_name label="next event [%s]"
        Text item=next_event_at label="next at [%1$tT, %1$tY-%1$tm-%1$td]"
    }
    Frame label="tomorrow" {
        Text item=first_event_name_tomorrow
        Text item=first_event_at_tomorrow
    }
}

Command tags in a calendar event (in the case that configuration parameter authorizationCode equals abc):

BEGIN:Calendar_Test_Temperature:12.3°C:abc
END:Calendar_Test_Temperature:23.4°F:abc

Command tags in a calendar event (in the case that configuration parameter authorizationCode is not set):

BEGIN:Calendar_Test_Switch:ON
END:Calendar_Test_Switch:OFF

Notes for Nextcloud

The url should be: https://<URL_TO_SERVER>/remote.php/dav/calendars/<username>/<calendar_name>?export, so the ?export is important to get an ical file from the calendar. Username and password for the nextcloud account have to be set as well.

Breaking changes

In OH3 calendar was changed from Thing to Bridge. You need to recreate calendars (or replace Thing by Bridge in your .things file).

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)