home-assistant.io/source/_integrations/caldav.markdown

title, description, ha_category, ha_iot_class, ha_release, ha_domain, ha_platforms, ha_integration_type, ha_config_flow

title	description	ha_category	ha_iot_class	ha_release	ha_domain	ha_platforms	ha_integration_type	ha_config_flow
CalDAV	Instructions on how to integrate a WebDav calendar into Home Assistant.	Calendar To-do List	Cloud Polling	0.60	caldav	calendar todo	integration	true

The CalDAV integration allows you to connect your WebDAV calendar to Home Assistant as one of these entity types:

• A calendar entity which can be used to trigger automations based on the start or end of an event using criteria such as the event name or description.
• A todo entity which tracks the number of active items on the to-do list.

The WebDAV entities are updated roughly every 15 minutes.

{% include integrations/config_flow.md %}

During the configuration flow you will be asked for the CalDAV server and credentials for it. An example CalDAV URL is https://caldav.icloud.com/.

This integration was tested against the following systems, but any other complying with the RFC4791 should work:

• Baikal
• iCloud Calendar
• Nextcloud
• Owncloud
• Synology Calendar

Manual configuration

You may also manually add a WebDAV calendar in Home Assistant by adding the following section to your configuration.yaml file. This method does not support to-do lists.

{% details Manual configuration examples %}

# 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

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

# Example configuration.yaml entry for iCloud, calendars will be found automatically
calendar:
  - platform: caldav
    username: !secret userIcloud
    password: !secret passIcloud
    url: https://caldav.icloud.com

All day events are not supported by default when configured using yaml.

The examples below create calendar entities that match specific search criteria.

# 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 entities for the calendar name Agenda: "HomeOffice" and "WarmupFlat" with events matching the regular expression specified in search. In custom calendars, events that last a whole day are taken into account.

Please note that if you use the custom_calendars option, only those calendars will be loaded. You cannot use calendars and custom_calendars in the same configuration.

{% 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. It cannot be used if custom_calender option is used. type: list custom_calendars: required: false description: Details on any custom calendars you want to create. Using this will only load the custom calendars supplied. No other calendars will load. 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 days: required: false description: Number of days for the search for upcoming appointments. default: 1 type: integer verify_ssl: description: Verify the SSL certificate or not. If using self-signed certificates, this usually needs to be set to "False". required: false type: boolean default: true {% endconfiguration %}

{% enddetails %}

Calendar Event Automations

Individual Calendar Events can power automations such as:

• Turn on a light at the start of the event named Front Yard Light
• Send a notification 5 minutes before the start of any event
• Stop the media player 30 minutes after the end of the event named Exercise.

See Calendar Automations for an overview, and read more about Calendar Trigger Variables for the available information you can use in a condition or action such as the event summary, description, location and more.

Calendar Entity Attributes

The calendar entity has additional attributes related to a single next upcoming event.

Using the entity state and attributes is more error prone and less flexible than using Calendar Automations. The calendar entity itself may only track a single upcoming active event and can't handle multiple events with the same start time, or overlapping events.

• 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. This should be in the format of HH:MM or MM. This attribute is not available when configured from the UI.
• 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.

To-do Entity

The todo entity is the number of incomplete items on the to-do list. See the todo integration documentation for details and available services that can be used in automations.

Troubleshooting

{% details "Home Assistant Core Installations" %}

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

{% enddetails %}

{% details "iCloud" %}

You may be required to use app specific passwords to generate a new password for use by Home Assistant to avoid sharing your iCloud account password.

{% enddetails %}