Skip to content

Commit

Permalink
Standardization: Change markup (home-assistant#27921)
Browse files Browse the repository at this point in the history
  • Loading branch information
@c0ffeeca7
c0ffeeca7 authored Jun 22, 2023
1 parent 005b0ca commit 909f72c
Showing 1 changed file with 63 additions and 62 deletions.
125 changes: 63 additions & 62 deletions source/_integrations/google_assistant.markdown
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,17 @@ ha_platforms:
- diagnostics
---

The `google_assistant` integration allows you to control your Home Assistant devices via Google Assistant on your mobile, tablet or Google Home device.
The `google_assistant` integration allows you to control your Home Assistant devices via Google Assistant on your mobile, tablet, or Google Home device.

If you want to send commands to Google Assistant to control devices supported by Google Assistant but not by Home Assistant, or broadcast messages to Google Assistant speakers and displays without interrupting music/video playback, take a look at the [Google Assistant SDK](/integrations/google_assistant_sdk) integration.

## Automatic setup via Home Assistant Cloud

With [Home Assistant Cloud](/cloud/), you can connect your Home Assistant instance in a few simple clicks to Google Assistant. With Home Assistant Cloud you don't have to deal with dynamic DNS, SSL certificates or opening ports on your router. Just log in via the user interface and a secure connection with the cloud will be established. Home Assistant Cloud requires a paid subscription after a 30-day free trial.
With [Home Assistant Cloud](/cloud/), you can connect your Home Assistant instance in a few simple clicks to Google Assistant. With Home Assistant Cloud you don't have to deal with dynamic DNS, SSL certificates, or opening ports on your router. Just log in via the user interface and a secure connection with the cloud will be established. Home Assistant Cloud requires a paid subscription after a 30-day free trial.

For Home Assistant Cloud Users, documentation can be found [here](https://www.nabucasa.com/config/google_assistant/).
For Home Assistant Cloud users, documentation can be found [here](https://www.nabucasa.com/config/google_assistant/).

## Manual setup
## Manual setup (if you don't have Home Assistant Cloud)

The Google Assistant integration (without Home Assistant Cloud) requires a bit more setup than most due to the way Google requires Assistant Apps to be set up.

Expand All @@ -38,60 +38,60 @@ To use Google Assistant, your Home Assistant configuration has to be [externally
### Google Cloud Platform configuration

1. Create a new project in the [Actions on Google console](https://console.actions.google.com/).
1. Click `New Project` and give your project a name.
2. Click on the `Smart Home` card, then click the `Start Building` button.
3. Click `Name your Smart Home action` under `Quick Setup` to give your Action a name - Home Assistant will appear in the Google Home app as `[test] <Action Name>`
4. Click on the `Overview` tab at the top of the page to go back.
5. Click `Build your Action`, then click `Add Action(s)`.
6. Add your Home Assistant URL: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant` in the `Fulfillment URL` box, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / IP address and the port under which your Home Assistant is reachable.
7. Click `Save`.
8. Click the three little dots (more) icon in the upper right corner, select `Project settings`
9. Make note of the `Project ID` that are listed on the `GENERAL` tab of the `Settings` page.
2. `Account linking` is required for your app to interact with Home Assistant.
1. Start by going back to the `Overview` tab.
2. Click on `Setup account linking` under the `Quick Setup` section of the `Overview` page.
3. If asked, leave options as they default `No, I only want to allow account creation on my website` and select `Next`.
4. Then if asked, for the `Linking type` select `OAuth` and `Authorization Code`. Click `Next`
1. Select **New Project** and give your project a name.
2. Select the **Smart Home** card, then select the **Start Building** button.
3. Under **Quick Setup**, select **Name your Smart Home action**. Give your Action a name - Home Assistant will appear in the Google Home app as `[test] <Action Name>`
4. Select the **Overview** tab at the top of the page to go back.
5. Select **Build your Action**, then select **Add Action(s)**.
6. Add your Home Assistant URL: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant` in the **Fulfillment URL** textbox, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / IP address and the port under which your Home Assistant is reachable.
7. Select **Save**.
8. Select the three little dots (more) icon in the upper right corner, select **Project settings**.
9. Make note of the **Project ID** that are listed on the **GENERAL** tab of the **Settings** page.
2. **Account linking** is required for your app to interact with Home Assistant.
1. Start by going back to the **Overview** tab.
2. Select on **Setup account linking** under the **Quick Setup** section of the **Overview** page.
3. If asked, leave options as they default **No, I only want to allow account creation on my website** and select **Next**.
4. Then if asked, for the **Linking type** select **OAuth** and **Authorization Code**. Select **Next**.
5. Enter the following:
1. Client ID: `https://oauth-redirect.googleusercontent.com/r/[YOUR_PROJECT_ID]`. (Replace `[YOUR_PROJECT_ID]` with your project ID from above)
2. Client Secret: Anything you like, Home Assistant doesn't need this field.
3. Authorization URL: `https://[YOUR HOME ASSISTANT URL:PORT]/auth/authorize`. (Replace `[YOUR HOME ASSISTANT URL:PORT]` with your values.)
4. Token URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL:PORT]/auth/token`. (Replace `[YOUR HOME ASSISTANT URL:PORT]` with your values.)
Click `Next`, then `Next` again.
6. In the `Configure your client` `Scopes` textbox, type `email` and click `Add scope`, then type `name` and click `Add scope` again.
7. Do **NOT** check `Google to transmit clientID and secret via HTTP basic auth header`.
8. Click `Next`, then click `Save`
Select **Next**, then **Next** again.
6. In the **Configure your client** **Scopes** textbox, type `email` and select **Add scope**, then type **name** and select **Add scope** again.
7. Do **NOT** check **Google to transmit clientID and secret via HTTP basic auth header**.
8. Select **Next**, then select **Save**.

<img src='/images/integrations/google_assistant/accountlinking.png' alt='Screenshot: Account linking'>

3. Select the `Develop` tab at the top of the page, then in the upper right hand corner select the `Test` button to generate the draft version Test App. If you don't see this option, go to the `Test` tab instead, click on the `Settings` button in the top right below the header, and ensure `On device testing` is enabled (if it isn't, enable it).
3. Select the **Develop** tab at the top of the page, then, in the upper right hand corner, select the **Test** button to generate the draft version Test App. If you don't see this option, go to the **Test** tab instead, select the **Settings** button in the top right below the header, and ensure **On device testing** is enabled (if it isn't, enable it).

4. Go to [Google Cloud Platform](https://console.cloud.google.com/).
1. Go to `Select a project`.
1. Go to **Select a project**.
2. In the window that popped up, select your newly created project from step 1.
3. Go to the menu and select `APIs and Services`and next `Credentials`.
4. In the Credentials view, select `Create credentials` and next `Service account`.
1. `Service account name`: Give your account a self-selected name.
2. Click `Create`.
3. `Select a role`: `Service Accounts` and `Service Account Token Creator`.
4. Click `Continue`.
5. Click on `Done`.
5. Under `Service Accounts` there should now be an account called [name from 4.1]@[projectname].iam.gserviceaccount.com.
3. Go to the menu and select **APIs and Services** and next **Credentials**.
4. In the **Credentials** view, select **Create credentials** and next **Service account**.
1. **Service account name**: Give your account a self-selected name.
2. Select **Create**.
3. **Select a role**: **Service Accounts** and **Service Account Token Creator**.
4. Select **Continue**.
5. Select **Done**.
5. Under **Service Accounts** there should now be an account called [name from 4.1]@[projectname].iam.gserviceaccount.com.
6. Click on the pencil button of that service account.
7. Go to `Keys` and `ADD KEY`.
7. Go to **Keys** and **ADD KEY**.
8. Create a private key, make sure it is in JSON format.
9. This will start a download of a JSON file.
1. Rename the file to `SERVICE_ACCOUNT.JSON`.
2. Add this file to your config-folder. This will be the same folder as your `configuration.yaml`.
12. Go back to [Google Cloud Platform](https://console.cloud.google.com/) and click `Close`.
13. Then click `SAVE`.
14. Go to the `Search products and resources` and search for `Homegraph API` and select it.
12. Go back to [Google Cloud Platform](https://console.cloud.google.com/) and select **Close**.
13. Then select **SAVE**.
14. Go to the **Search products and resources** and search for **Homegraph API** and select it.
15. Enable the HomeGraph API.

5. Add the `google_assistant` integration configuration to your `configuration.yaml` file and restart Home Assistant following the [configuration guide](#yaml-configuration) below.
6. Add services in the Google Home App (note that app versions may be slightly different).
1. Open the Google Home app.
2. Click the `+` button on the top left corner, click `Set up device`, in the "Set up a device" screen click "Works with Google". You should have `[test] <Action Name>` listed under 'Add new'. Selecting that should lead you to a browser to login your Home Assistant instance, then redirect back to a screen where you can set rooms and nicknames for your devices if you wish.
2. Select the `+` button on the top left corner, select **Set up device**. In the **Set up a device** screen, select **Works with Google**. You should have `[test] <Action Name>` listed under **Add new**. Selecting that should lead you to a browser to login your Home Assistant instance, then redirect back to a screen where you can set rooms and nicknames for your devices if you wish.

<div class='note'>

Expand All @@ -104,15 +104,15 @@ If you've added Home Assistant to your phone's home screen, you have to first re
If you want to allow other household users to control the devices:

1. Open the project you created in the [Actions on Google console](https://console.actions.google.com/).
2. Click `Test` on the top of the page, then click `Simulator` located to the page left, then click the three little dots (more) icon in the upper right corner of the console.
3. Click Manage user access. This redirects you to the Google Cloud Platform IAM permissions page.
4. Click ADD at the top of the page.
2. Select **Test** on the top of the page, then select **Simulator** located to the page left, then click the three little dots (more) icon in the upper right corner of the console.
3. Select **Manage user access**. This redirects you to the Google Cloud Platform IAM permissions page.
4. Select **ADD** at the top of the page.
1. Enter the email address of the user you want to add.
2. Click Select a role and choose Project < Viewer.
3. Click SAVE
2. Select **Select a role** and choose **Project** > **Viewer**.
3. Select **SAVE**.
4. Copy and share the Actions project link (`https://console.actions.google.com/project/YOUR_PROJECT_ID/simulator`) with the new user.
5. Have the new user open the link with their own Google account, agree to the Terms of Service popup, then select "Start Testing", select VERSION - Draft in the dropdown, and click "Done".
6. Have the new user go to their `Google Assistant` app to add `[test] your app name` to their account.
5. Have the new user open the link with their own Google account, agree to the Terms of Service popup. Then select **Start Testing**, select **VERSION - Draft** in the dropdown, and select **Done**.
6. Have the new user go to their **Google Assistant** app to add `[test] your app name` to their account.

### Enable Device Sync

Expand All @@ -121,19 +121,19 @@ If you want to support active reporting of state to Google's server (configurati
1. Service Account
1. In the Google Cloud Platform Console, go to the [Create Service account key](https://console.cloud.google.com/iam-admin/serviceaccounts/create) page.
2. At the top left of the page next to "Google Cloud Platform" logo, select your project created in the Actions on Google console. Confirm this by reviewing the project ID and it ensure it matches.
3. From the Service account list, select `CREATE SERVICE ACCOUNT`.
4. In the Service account name field, enter a name.
5. In the Service account ID field, enter an ID.
6. From the Role list, select `Service Accounts` > `Service Account Token Creator`.
7. Click `CONTINUE` and then `DONE`. You are returned to the service account list, and your new account is shown.
8. Click the three dots menu under `Actions` next to your new account, and click `Manage keys`. You are taken to a `Keys` page.
9. Click `ADD KEY` then `Create new key`. Leave the `key type` as `JSON` and click `CREATE`. A JSON file that contains your key downloads to your computer.
3. From the Service account list, select **CREATE SERVICE ACCOUNT**.
4. In the **Service account name** field, enter a name.
5. In the **Service account ID** field, enter an ID.
6. From the **Role** list, select **Service Accounts** > **Service Account Token Creator**.
7. Select **CONTINUE** and then **DONE**. You are returned to the service account list, and your new account is shown.
8. Select the three dots menu under **Actions** next to your new account, and select **Manage keys**. You are taken to a **Keys** page.
9. Select **ADD KEY** then **Create new key**. Leave the **key type** as **JSON** and select **CREATE**. A JSON file that contains your key downloads to your computer.
10. Use the information in this file or the file directly to add to the `service_account` key in the configuration.
11. Click `Close`.
11. Select **Close**.
2. HomeGraph API
1. Go to the [Google API Console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview).
2. At the top left of the page next to "Google Cloud Platform" logo, select your project created in the Actions on Google console. Confirm this by reviewing the project ID and it ensure it matches.
3. Click Enable HomeGraph API.
3. Select **Enable HomeGraph API**.
3. Try "OK Google, sync my devices" - the Google Home app should import your exposed Home Assistant devices and prompt you to assign them to rooms.

### Enable Local Fulfillment
Expand All @@ -143,6 +143,7 @@ Google Assistant devices can send their commands locally to Home Assistant allow
Your Home Assistant instance needs to be connected to the same network as the Google Assistant device that you’re talking to so that it can be discovered via mDNS discovery (UDP broadcasts).

Your Google Assistant devices will still communicate via the internet to:

- Get credentials to establish a local connection.
- Send commands that involve a [secure device](#secure-devices).
- Send commands if local fulfillment fails.
Expand All @@ -158,16 +159,16 @@ For secure remote access, use a reverse proxy such as the {% my supervisor_addon
</div>

1. Open the project you created in the [Actions on Google console](https://console.actions.google.com/).
2. Click `Develop` on the top of the page, then click `Actions` located in the hamburger menu on the top left.
3. Upload `app.js` from [here](https://github.com/NabuCasa/home-assistant-google-assistant-local-sdk/releases/latest) for both Node and Chrome by clicking the `Upload JavaScript files` button.
2. Select **Develop** on the top of the page, then select **Actions** located in the hamburger menu on the top left.
3. Upload `app.js` from [here](https://github.com/NabuCasa/home-assistant-google-assistant-local-sdk/releases/latest) for both Node and Chrome by selecting the **Upload JavaScript files** button.
4. Add device scan configuration:
1. Click `+ New scan config` if no configuration exists
2. Select `MDNS`
3. Set `MDNS service name` to `_home-assistant._tcp.local`
4. Click `Add field`, then under `Select a field` choose `Name`
5. Enter a new `Value` field set to `.*\._home-assistant\._tcp\.local`
5. Check the box `Support local query` under `Add capabilities`.
6. `Save` your changes.
1. Select **+ New scan config** if no configuration exists
2. Select **MDNS**.
3. Set **MDNS service name** to `_home-assistant._tcp.local`
4. Select **Add field**, then under **Select a field**, choose **Name**.
5. Enter a new **Value** field set to `.*\._home-assistant\._tcp\.local`
5. Check the box **Support local query** under **Add capabilities**.
6. Save your changes.
7. Either wait for 30 minutes, or restart all your Google Assistant devices.
8. Restart Home Assistant Core.
9. With a Google Assistant device, try saying "OK Google, sync my devices." This can be helpful to avoid issues, especially if you are enabling local fulfillment sometime after adding cloud Google Assistant support.
Expand Down

0 comments on commit 909f72c

Please sign in to comment.