# 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 |
userAgent | Some providers require a specific user agent header. If left empty, the default Jetty header is used. | 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, case insensitive), REGEX (field must match value, completely, dot matches all, usually case sensitive). | 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 |
last_update | DateTime | The time and date of the last successful update of the calendar |
# 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 theAuthorization_Code
field against theauthorizationCode
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 thisAuthorization_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:result_0#title" }
DateTime first_event_at_tomorrow "first at [%1$tT, %1$tY-%1$tm-%1$td]" <calendar> { channel="icalendar:eventfilter:feedd0d0:result_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
# 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).