Skip to content

Commit 459ea20

Browse files
mnestorLandrash
mnestor
authored and
Landrash
committed
Documentation for Google Calendar component (home-assistant#1403)
* Documentation for Google Calendar component * Fixes from @Landrash
1 parent 4d288c5 commit 459ea20

File tree

2 files changed

+115
-0
lines changed

2 files changed

+115
-0
lines changed

‎source/_components/binary_sensor.google_calendar.markdown

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
layout: page
3+
title: "Google Calendar Event"
4+
description: "Instructions how to use Google Calendars in Home Assistant."
5+
date: 2015-05-08 17:15
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
logo: google_calendar.png
11+
ha_category: Calendar
12+
ha_iot_class: "Cloud Polling"
13+
ha_release: 0.33
14+
---
15+
16+
17+
This platform allows you to connect to your [Google Calendars](https://calendar.google.com) and generate binary sensors. The sensors created can trigger based on any event on the calendar or only for matching events. When you first setup this component it will generate a new configuration file *google_calendars.yaml* that will contain information about all of the calendars you can see.
18+
19+
### {% linkable_title Prerequisites %}
20+
21+
Generate a Client ID and Client Secret on [Google Developers Console](https://console.developers.google.com/start/api?id=calendar).
22+
23+
1. Follow the wizard using the following information.
24+
1. When it gets to the point of asking _Which API are you using?_ just click cancel.
25+
1. Click on the tab 'OAuth consent screen'.
26+
1. Set 'Product name shown to users' to anything you want. We suggest Home-Assistant.
27+
1. Save this page. You don't have to fill out anything else there.
28+
1. Click 'Create credentials' -> OAuth client ID.
29+
1. Set the Application type to 'Other' and give this credential set a name then click Create.
30+
1. Save the client ID and secret as you will need to put these in your configuration.yaml file.
31+
32+
### {% linkable_title Basic Setup %}
33+
34+
To integrate Google Calendar in Home Assistant, add the following section to your `configuration.yaml` file:
35+
36+
```yaml
37+
# Example configuration.yaml entry
38+
google:
39+
client_id: *Value_created_from_steps_above*
40+
client_secret: *Value_created_from_steps_above*
41+
```
42+
43+
Configuration variables:
44+
45+
- **client_id** (*Required*): Use the value you generated in the Prerequisites stage.
46+
- **client_secret** (*Required*): Use the value you generated in the Prerequisites stage.
47+
- **track_new_calendar** (*Optional*): Will automatically generate a binary sensor when a new calendar is detected. The system scans for new calendars on startup. By default this is set to `True`.
48+
49+
The next steps will require you to have Home Assistant running.
50+
51+
After you have it running complete the Google authentication that pops up. It will give you a URL and a code to enter. This will grant your Home Assistant service access to all the Google Calendars that the account you authenticate with can read. This is a Read-Only view of these calendars.
52+
53+
54+
### {% linkable_title Calendar Configuration %}
55+
Editing `google_calendars.yaml`
56+
57+
A basic entry for a single calendar looks like:
58+
59+
```yaml
60+
- cal_id: "***************************@group.calendar.google.com"
61+
entities:
62+
- device_id: test_everything
63+
name: Give me everything
64+
track: true
65+
- cal_id: "***************************@group.calendar.google.com"
66+
entities:
67+
- device_id: test_important
68+
name: Important Stuff
69+
track: true
70+
search: "#Important"
71+
offset: "!!"
72+
- device_id: test_unimportant
73+
name: UnImportant Stuff
74+
track: true
75+
search: "#UnImportant"
76+
```
77+
78+
Variables:
79+
80+
- **cal_id**: The Google generated unique id for this calendar. **DO NOT CHANGE**
81+
82+
- **entities**: Yes, you can have multiple sensors for a calendar!
83+
84+
- **device_id**: (*Required*): The name that all your automations/scripts will use to reference this device.
85+
86+
- **name**: (*Required*): What is the name of your sensor that you'll see in the frontend.
87+
88+
- **track**: (*Required*): Should we create a sensor `True` or ignore it `False`?
89+
90+
- **search**: (*Optional*): If set will only trigger for matched events.
91+
92+
- **offset**: (*Optional*): A set of characters that precede a number in the event title for designating a pre-trigger state change on the sensor. (Default: `!!`)
93+
94+
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. You'll also have a sensor `calendar.test_everything` that will not filter events out and always show the next event available.
95+
96+
But what if you only wanted it to toggle based on all events? Just leave out the *search* parameter.
97+
98+
**Note**: If you use a `#` sign for search then wrap it up. It's better to be safe!
99+
100+
101+
### {% linkable_title Sensor attributes %}
102+
103+
- **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.
104+
105+
- **all_day**: `True`/`False` if this is an all day event. Will be `False` if there is no event found.
106+
107+
- **message**: The event title with the `search` and `offset` values extracted. So in the above example for **offset_reached** the **message** would be set to `Very important meeting`
108+
109+
- **description**: The event description.
110+
111+
- **location**: The event Location.
112+
113+
- **start_time**: Start time of event.
114+
115+
- **end_time**: End time of event.

‎source/images/supported_brands/google_calendar.png

19.2 KB
Loading

0 commit comments

Comments
 (0)