jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-18 23:06:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Caldav configuration flow documentation (#29677)

Browse Source 
* Refresh caldav documentation for configuration from the UI

* Apply suggestions from code review

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Remove mention of binary sensor

---------

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Allen Porter 2023-11-04 16:52:13 -07:00 committed by GitHub
parent c7f6ae7b10
commit e306f2c5b4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 51 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
source/_integrations/caldav.markdown
View File

@ -11,25 +11,24 @@ ha_platforms:
ha_integration_type: integration ha_integration_type: integration
--- ---
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. The CalDAV integration allows you to connect your WebDAV calendar to Home Assistant.
Each calendar is a [calendar](/integrations/calendar) entity which can be used
to trigger automations based on the the start or end of an event using criteria
such as the event name or description. The WebDAV calendar is updated roughly
every 15 minutes.
## Prerequisites {% include integrations/config_flow.md %}
You need to have a CalDAV server and credentials for it. This integration was tested against [Baikal](https://sabre.io/baikal/) but any integration complying with the RFC4791 should work. [Nextcloud](https://nextcloud.com/) and [Owncloud](https://owncloud.org/) work fine. During the configuraiton flow you will be asked for the CalDAV server and credentials
for it. An example CalDAV URL is `https://caldav.icloud.com/`.
{% details "Notes for Home Assistant Core Installations" %} This integration was tested against [iCloud Calendar](https://www.icloud.com/calendar/), [Nextcloud](https://nextcloud.com/), [Owncloud](https://owncloud.org/), [Baikal](https://sabre.io/baikal/). Any integration complying with the RFC4791 should work.
You might need some additional system packages to compile the Python CalDAV library. On a Debian based system, install them by: ## Manual Configuration
```bash You may also manually add a WebDAV calendar in Home Assistant by adding the following section to your `configuration.yaml` file:
sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev
```
{% enddetails %} {% details Manual configuration examples %}
## Basic Setup
To integrate a WebDAV calendar in Home Assistant, add the following section to your `configuration.yaml` file:
```yaml ```yaml
# Example configuration.yaml entry for baikal # Example configuration.yaml entry for baikal
@ -67,11 +66,9 @@ calendar:
url: https://caldav.icloud.com url: https://caldav.icloud.com
``` ```
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. All day events are not supported by default when configured using yaml.
## Custom calendars The examples below create calendar entities that match specific search criteria.
You have the possibility to create multiple binary sensors for events that match certain conditions.
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
@ -89,7 +86,7 @@ calendar:
search: "Warmup" 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. 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. 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.
@ -112,7 +109,7 @@ calendars:
type: list type: list
custom_calendars: custom_calendars:
required: false required: false
description: Details on any custom binary sensor calendars you want to create. Using this will only load the custom calendars supplied. No other calendars will load. 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 type: list
keys: keys:
name: name:
@ -139,9 +136,30 @@ verify_ssl:
default: true default: true
{% endconfiguration %} {% endconfiguration %}
## Sensor attributes {% enddetails %}
- **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`.
## 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](/integrations/calendar#automation) for an overview, and read more about [Calendar Trigger Variables](/docs/automation/templating/#calendar) 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.
<div class='note'>
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.
</div>
- **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. - **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 - **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. - **description**: The event description.
@ -149,53 +167,22 @@ verify_ssl:
- **start_time**: Start time of event. - **start_time**: Start time of event.
- **end_time**: End time of event. - **end_time**: End time of event.
## Examples ## Troubleshooting
All events of the calendars "private" and "holidays". Note that all day events are not included. {% details "Home Assistant Core Installations" %}
```yaml You might need some additional system packages to compile the Python CalDAV library. On a Debian based system, install them by:
# Example configuration.yaml entry for nextcloud
calendar: ```bash
- platform: caldav sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev
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". {% enddetails %}
Custom calendar names are built from the main calendar + name of the custom calendar. Using the option of `'.*'` will load all calendar events. {% details "iCloud" %}
```yaml You may be required to use [app specific passwords](https://support.apple.com/en-us/102654)
# configuration.yaml to generate a new password for use by Home Assistant to avoid sharing your iCloud account
calendar: password.
- platform: caldav
url: https://nextcloud.example.com/remote.php/dav
username: "me"
password: !secret caldav
custom_calendars:
- name: holiday
calendar: work
search: "Holiday"
- name: vacation
calendar: vacation
search: ".*"
# automations.yaml {% enddetails %}
- id: wakeup
alias: "worktime wakeup"
trigger:
platform: time
at: "06:40:00"
action:
- service: media_player.media_play
target:
entity_id: media_player.bedroom
condition:
- condition: state
entity_id: calendar.work_holiday
state: "off"
```