diff --git a/source/_integrations/google.markdown b/source/_integrations/google.markdown index a0c83e5adac..d14f5bb1138 100644 --- a/source/_integrations/google.markdown +++ b/source/_integrations/google.markdown @@ -43,64 +43,9 @@ This section explains how to generate a Client ID and Client Secret on {% enddetails %} +{% include integrations/config_flow.md %} -## Configuration - -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. +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. {% 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. -## 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 -- cal_id: "*****@group.calendar.google.com" - entities: - - device_id: test_everything - name: Give me everything - track: true -``` +## Calendar Event Automations -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 -- 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: "!!" -``` +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. -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.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. +## Calendar Entity Attributes -
+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. -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.
+ +{% 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" %} + +
+ +This will only be available if you have given Home Assistant `read-write` access in configuration options. + +
+ +| 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 + +
+ +You either use `start_date_time` and `end_date_time`, or `start_date` and `end_date`, or `in`. + +
+ +{% enddetails %} + +## More Configuration + + +{% details "More Configuration" %} + +
+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. +
+ +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 %} cal_id: 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. required: true type: string - track: - description: "Should we create a sensor `true` or ignore it `false`?" - required: true - type: boolean - default: true search: description: If set will only trigger for matched events. required: false @@ -224,68 +203,4 @@ entities: default: true {% endconfiguration %} -### Calendar 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 #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. - -
- -This will only be available if you have given Home Assistant `read-write` access (see `calendar_access`). - -
- -| 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 - -
- -You either use `start_date_time` and `end_date_time`, or `start_date` and `end_date`, or `in`. - -
- -## 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 %} +{% enddetails %}