home-assistant.io/source/_components/calendar.caldav.markdown

layout, title, description, date, sidebar, comments, sharing, footer, ha_category, ha_iot_class, ha_release

layout	title	description	date	sidebar	comments	sharing	footer	ha_category	ha_iot_class	ha_release
page	CalDav	Instructions on how to integrate a WebDav calendar into Home Assistant.	2017-11-27 23:14	true	false	true	true	Calendar	Cloud Polling	0.60

The caldav platform allows you to connect to your WebDav calendar and generate binary sensors. A different sensor will be created for each individual calendar, or you can specify custom calendars which match a criteria you define (more on that below). These sensors will be on if you have an on going event in that calendar or off if the event is later in time, or if there is no event at all. The WebDav calendar get updated roughly every 15 minutes.

{% linkable_title Prerequisites %}

You need to have a CalDav server and credentials for it. This component was tested against Baikal but any component complying with the RFC4791 should work. Nextcloud and Owncloud work fine.

You might need some additional system packages to compile the Python caldav library. On a Debian based system, install them by:

$ sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev

{% linkable_title Basic Setup %}

To integrate a WebDav calendar in Home Assistant, add the following section to your configuration.yaml file:

# Example configuration.yaml entry for baikal
calendar:
  - platform: caldav
    username: john.doe@test.com
    password: !secret caldav
    url: https://baikal.my-server.net/cal.php/calendars/john.doe@test.com/default

# Example configuration.yaml entry for nextcloud, calendars will be found automatically
calendar:
  - platform: caldav
    username: john.doe
    password: !secret caldav
    url: https://nextcloud.example.com/remote.php/dav

This example will generate default binary sensors for each calendar you have in your account. Those calendars will be on when there is an ongoing event and off if not. Events that last a whole day are ignored in those calendars. You have to setup custom calendars in order to take them into account or for advanced event filtering.

{% linkable_title Custom calendars %}

You have the possibility to create multiple binary sensors for events that match certain conditions.

# Example configuration.yaml entry
calendar:
  - platform: caldav
    username: john.doe@test.com
    password: !secret caldav
    url: https://baikal.my-server.net/cal.php/calendars/john.doe@test.com/default
    custom_calendars:
      - name: 'HomeOffice'
        calendar: 'Agenda'
        search: 'HomeOffice'
      - name: 'WarmupFlat'
        calendar: 'Agenda'
        search: 'Warmup'

This will create two binary sensors for the calendar name Agenda: "HomeOffice" and "WarmupFlat". Those sensors will be on if there is an ongoing event matching the regular expression specified in search. In custom calendars, events that last a whole day are taken into account.

Please note that when you configure custom calendars, the default ones are not created anymore.

{% configuration %} url: required: true description: The full URL to your calendars. type: string username: required: false description: Username for authentication. type: string password: required: false description: Password for authentication. type: string calendars: required: false description: List of the calendars to filter. Empty or absent means no filtering, i.e. all calendars will be added. type: list custom_calendars: required: false description: Details on any custom binary sensor calendars you want to create. type: list keys: name: required: true description: The name of your custom calendar. type: string calendar: required: true description: The source calendar to search on. type: string search: required: true description: Regular expression for filtering the events based on the content of their summary, description or location. type: string {% endconfiguration %}

{% linkable_title Sensor attributes %}

• offset_reached: If set in the event title and parsed out will be on/off once the offset in the title in minutes is reached. So the title Very important meeting !!-10 would trigger this attribute to be on 10 minutes before the event starts.
• all_day: True/False if this is an all day event. Will be False if there is no event found.
• message: The event title with the search values extracted. So in the above example for offset_reached the message would be set to Very important meeting
• description: The event description.
• location: The event Location.
• start_time: Start time of event.
• end_time: End time of event.

{% linkable_title Examples %}

All events of the calendars "private" and "holidays". Note that all day events are not included.

# Example configuration.yaml entry for nextcloud
calendar:
  - platform: caldav
    url: https://nextcloud.example.com/remote.php/dav
    username: 'me'
    password: !secret caldav
    calendars:
      - private
      - holidays

Full example with automation to wake up to music if not holiday. Prerequisite: you have a calendar named "work" where you create calendar entries containing "Holiday".

Custom calendar names are built from the main calendar + name of the custom calendar.

# configuration.yaml
calendar:
  - platform: caldav
    url: https://nextcloud.example.com/remote.php/dav
    username: 'me'
    password: !secret caldav
    custom_calendars:
      - name: holiday
        calendar: work
        search: 'Holiday'

# automations.yaml
- id: wakeup
  alias: worktime wakeup
  trigger:
    platform: time
    at: 06:40:00
  action:
  - service: media_player.media_play
    entity_id: media_player.bedroom
  condition:
  - condition: state
    entity_id: calendar.work_holiday
    state: 'off'