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-19 07:17:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update google calendar documentation for yaml deprecation (#22844)

Browse Source 
* Update google calendar documentation for yaml deprecation

* Small doc adjustments

* Fix typo

* Apply suggestions from code review

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

* Add 'note warning' to configuration instructions

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Allen Porter 2022-05-22 14:29:26 -07:00 committed by GitHub
parent 55aa6061ce
commit 05f3af07cb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 73 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

231
source/_integrations/google.markdown
View File

@ -43,64 +43,9 @@ This section explains how to generate a Client ID and Client Secret on
{% enddetails %} {% enddetails %}
{% include integrations/config_flow.md %}
## Configuration The integration setup will next give you instructions to enter the Application Credentials (OAuth Client ID and Client Secret) and authorize Home Assistant to access your account and Calendars.
To integrate Google Calendar in Home Assistant,
add the following section to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
google:
client_id: YOUR_CLIENT_ID
client_secret: YOUR_CLIENT_SECRET
```
{% configuration %}
client_id:
description: Use the client ID you generated in the Prerequisites stage.
required: true
type: string
client_secret:
description: Use the client secret you generated in the Prerequisites stage.
required: true
type: string
track_new_calendar:
description: >
Will automatically generate a binary sensor when a new calendar
is detected. The system scans for new calendars only on startup.
required: false
type: boolean
default: true
calendar_access:
description: >
Determines the level of access that Home Assistant will request when
connecting to calendars. This can be `read_only` or `read_write`.
required: false
type: string
default: read_write
{% endconfiguration %}
Then make sure to restart Home Assistant under _**Server Controls**_.
{% my server_controls badge %}
After that, you need to add Google Calendars *Integration*.
{% my config_flow_start badge domain=page.ha_domain %}
{% details "Manual configuration steps" %}
1. Browse to your Home Assistant instance.
1. In the sidebar click on _**{% my config icon %}**_.
1. From the configuration menu select: _**{% my integrations icon %}**_.
1. In the bottom right, click on the
_**{% my config_flow_start icon domain=page.ha_domain %}**_ button.
1. From the list, search and select _**"Google Calendars"**_ and follow the instructions.
{% enddetails %}
The integration setup will next give you instructions on how to authorize Home Assistant to access your account and Calendars.
{% details "OAuth and Device Authorization steps" %} {% details "OAuth and Device Authorization steps" %}
@ -136,49 +81,88 @@ to all the Google Calendars available to your linked account.
If the setup process fails and you see an error message such as *Authentication code expired, please try again* you may want to try the flow again. You may also check the logs for additional error messages that may indicate a misconfiguration such as an invalid client id or secret. If the setup process fails and you see an error message such as *Authentication code expired, please try again* you may want to try the flow again. You may also check the logs for additional error messages that may indicate a misconfiguration such as an invalid client id or secret.
## Calendar Configuration ## Calendar Entities
The integration will discover new calendars and write them into a configuration file `google_calendars.yaml` in your configuration directory. The configuration file can let you control which calendars appear, or set up more elaborate event matching criteria. Each Google Calendar from *My Calendars* ([more info](https://support.google.com/calendar/answer/37095)) is represented as a [calendar](/integrations/calendar) entity in Home Assistant.
A basic entry for a single calendar looks like: For example, your calendar named *Personal* is created as entity `calendar.personal`. You may rename an entity, or disable any entities which you don't need.
```yaml ## Calendar Event Automations
- cal_id: "*****@group.calendar.google.com"
entities:
- device_id: test_everything
name: Give me everything
track: true
```
From this, we will get a binary sensor `calendar.test_everything` triggered by any event on the calendar and will show the next 10 events on the 'Calendar' dashboard. Individual Calendar *Events* are what powering automations such as:
A bit more elaborate configuration: * 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*.
```yaml 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.
- cal_id: "*****@group.calendar.google.com"
entities:
- device_id: test_unimportant
name: UnImportant Stuff
track: true
search: "#UnImportant"
- device_id: test_important
name: Important Stuff
track: true
search: "#Important"
offset: "!!"
```
From this we will end up with the binary sensors `calendar.test_unimportant` and `calendar.test_important` which will toggle themselves on/off based on events on the same calendar that match the search value set for each. ## Calendar Entity Attributes
`calendar.test_unimportant` will toggle for events whose title contain '#UnImportant'
`calendar.test_important` will toggle for events whose title contain '#Important'. By using the offset variable an event title containing "#Important !!-10" will toggle the sensor 10 minutes before the event starts.
<div class='note warning'> The calendar entity has additional attributes related to a single next upcoming event.
If you use a `#` sign for `search` then wrap the whole search term in quotes. <div class='note'>
Otherwise everything following the hash sign would be considered a YAML comment.
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> </div>
{% details "Attributes" %}
- **all_day**: `true`/`false` if this is an all day event. Will be `false` if there is no event found.
- **message**: The event summary.
- **description**: The event description.
- **location**: The event location.
- **start_time**: Start time of event.
- **end_time**: End time of event.
{% enddetails %}
### Service `google.add_event`
You can use the service `google.add_event` to create a new calendar event in a calendar. Calendar id's can be found in the file `google_calendars.yaml`. All dates and times are in your local time, the integration gets your time zone from your `configuration.yaml` file.
{% details "Add Event Service details" %}
<div class='note'>
This will only be available if you have given Home Assistant `read-write` access in configuration options.
</div>
| Service data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | --------|
| `calendar_id` | no | The id of the calendar you want. | *****@group.calendar.google.com
| `summary` | no | Acts as the title of the event. | Bowling
| `description` | yes | The description of the event. | Birthday bowling
| `start_date_time` | yes | The date and time the event should start. | 2019-03-10 20:00:00
| `end_date_time` | yes | The date and time the event should end. | 2019-03-10 23:00:00
| `start_date` | yes | The date the whole day event should start. | 2019-03-10
| `end_date` | yes | The date the whole day event should end. | 2019-03-11
| `in` | yes | Days or weeks that you want to create the event in. | "days": 2
<div class='note'>
You either use `start_date_time` and `end_date_time`, or `start_date` and `end_date`, or `in`.
</div>
{% enddetails %}
## More Configuration
{% details "More Configuration" %}
<div class='note warning'>
It is not recommended to new users to use these settings as they are not
compatible with other Home Assistant features, but this documentation is available
for existing users.
</div>
The integration will discover new calendars and write them into a configuration file `google_calendars.yaml` in your configuration directory that can allow for additional configuration.
{% configuration %} {% configuration %}
cal_id: cal_id:
description: The Google *generated* unique id for this calendar. description: The Google *generated* unique id for this calendar.
@ -200,11 +184,6 @@ entities:
description: What is the name of your sensor that you'll see in the frontend. description: What is the name of your sensor that you'll see in the frontend.
required: true required: true
type: string type: string
track:
description: "Should we create a sensor `true` or ignore it `false`?"
required: true
type: boolean
default: true
search: search:
description: If set will only trigger for matched events. description: If set will only trigger for matched events.
required: false required: false
@ -224,68 +203,4 @@ entities:
default: true default: true
{% endconfiguration %} {% endconfiguration %}
### Calendar 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 #Important !!-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 `offset` value extracted. So in the above example for **offset_reached** the **message** would be set to `Very important meeting #Important`
- **description**: The event description.
- **location**: The event Location.
- **start_time**: Start time of event.
- **end_time**: End time of event.
### Service `google.add_event`
You can use the service `google.add_event` to create a new calendar event in a calendar. Calendar id's can be found in the file `google_calendars.yaml`. All dates and times are in your local time, the integration gets your time zone from your `configuration.yaml` file.
<div class='note'>
This will only be available if you have given Home Assistant `read-write` access (see `calendar_access`).
</div>
| Service data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | --------|
| `calendar_id` | no | The id of the calendar you want. | *****@group.calendar.google.com
| `summary` | no | Acts as the title of the event. | Bowling
| `description` | yes | The description of the event. | Birthday bowling
| `start_date_time` | yes | The date and time the event should start. | 2019-03-10 20:00:00
| `end_date_time` | yes | The date and time the event should end. | 2019-03-10 23:00:00
| `start_date` | yes | The date the whole day event should start. | 2019-03-10
| `end_date` | yes | The date the whole day event should end. | 2019-03-11
| `in` | yes | Days or weeks that you want to create the event in. | "days": 2
<div class='note'>
You either use `start_date_time` and `end_date_time`, or `start_date` and `end_date`, or `in`.
</div>
## Using calendar in automations
A calendar can be used as an external scheduler for special events or reoccurring events instead of hardcoding them in automations. The calendar entry must have a duration greater than 1 minute. Events that are 0 minutes long will not trigger the automation.
Trigger as soon as an event starts:
```yaml
trigger:
platform: state
entity_id: calendar.calendar_name
to: "on"
```
By using specific text in the event title, you can set conditions to initiate particular automation flows on designated events while other events will be ignored.
For example, the actions following this condition will only be executed for events named 'vacation':
{% raw %}
```yaml
condition:
- condition: state
entity_id: calendar.calendar_name
state: vacation
attribute: message
```
{% endraw %}