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 15:26:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Change order of nest instructions in fewer steps (#20073)

Browse Source
This commit is contained in:
Allen Porter 2021-10-30 07:35:36 -07:00 committed by GitHub
parent 42cf89b0e9
commit 682ac4f24e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 61 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
source/_integrations/nest.markdown
View File

@ -32,7 +32,7 @@ There is currently support for the following device types within Home Assistant:
- [Sensor](#sensor)
<div class='note'>
This integration supports two Nest APIs: The SDM API (new) accepts new users and requires a US$5 fee. The Legacy Works With Nest API (old) does not accept new users, but the documentation is still available at the bottom of the page for existing users.
The Nest Smart Device Management (SDM) API *requires a US$5 fee*.
</div>
Google applies strict [Redirect URI validation rules](https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation) to keep your login credentials secure. In practice, this means that you must access Home Assistant *over SSL* and a *public top-level domain* when setting up this integration. See the documentation on [Securing](/docs/configuration/securing/) or [Troubleshooting](#troubleshooting), and note that you don't actually need to enable remote access.
@ -62,33 +62,11 @@ The full detailed instructions for account setup are available in the [Device Ac
For the first phase, you will turn on the API and create the necessary credentials to have Home Assistant talk to the Nest API.
{% details "Create a Device Access Project [Device Access Console]" %}
{% details "Create and configure Cloud Project [Cloud Console]" %}
1. First go to the [Device Access Registration](https://developers.google.com/nest/device-access/registration) page. Click on the button **[Go to the Device Access Console](https://console.nest.google.com/device-access/)**.
![Screenshot of Device Access Registration](/images/integrations/nest/device_access.png)
By the end of this section you will have a Cloud Project with the necessary APIs enabled.
1. Check the box to "Accept the Terms of Service" and click **Continue to Payment** where you need to pay a fee (currently US$5).
![Screenshot of accepting terms](/images/integrations/nest/accept_terms.png)
<div class='note'>
It is currently not possible to share/be invited to a home with a G-Suite account. Make sure that you pay the fee with an account that has access to your devices.
</div>
1. Now the "Device Access Console" should be visible. Click on **Create project**.
![Screenshot of creating a project](/images/integrations/nest/create_project.png)
1. Give your Device Access project a name and click **Next**.
![Screenshot of naming a project](/images/integrations/nest/project_name.png)
1. Next you will be asked for an *OAuth client ID*. It is a good idea to go create that now following instructions in the next section in a new browser tab.
{% enddetails %}
{% details "Configure OAuth client_id and client_secret [Cloud Console]" %}
By the end of this section you will have the `client_id` and `client_secret`.
1. Open a new tab to the [Google API Console](https://console.developers.google.com/apis/credentials).
1. Go to the [Google Cloud Console](https://console.developers.google.com/apis/credentials).
1. If this is your first time here, you likely need to create a new Google API project. Click **Create Project** then **New
Project**. Note: This is a different type of project from the Device Access project you are also creating.
@ -96,7 +74,26 @@ Project**. Note: This is a different type of project from the Device Access proj
1. Give your API Project a name then click **Create**. Note: You can ignore the *Project ID* here as Home Assistant does not need it.
1. Click *OAuth consent screen* and make sure you have that configured, otherwise you can do that now...
1. Go to [APIs & Services > Library](https://console.cloud.google.com/apis/library) where you can enable APIs.
1. From the API Library search for [Smart Device management](https://console.cloud.google.com/apis/library/smartdevicemanagement.googleapis.com) and click **Enable**.
![Screenshot of Search for SDM API](/images/integrations/nest/enable_sdm_api.png)
1. From the API Library search for [Cloud Pub/Sub API](https://console.developers.google.com/apis/library/pubsub.googleapis.com) in the Cloud Console and click **Enable**.
You now have a cloud project ready for the next section to configure authentication with OAuth.
{% enddetails %}
{% details "Configure OAuth Consent screen [Cloud Console]" %}
By the end of this section you will have configured the OAuth Consent Screen, needed for giving Home Assistant access to
your cloud project.
1. Go to the [Google API Console](https://console.developers.google.com/apis/credentials).
1. Click [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) and configure it.
![Screenshot of OAuth consent screen creation](/images/integrations/nest/oauth_consent_create.png)
1. Select **External** (the only choice if you are not a G-Suite user) then click **Create**. While you are here, you may click the *Let us know what you think* to give Google's OAuth team any feedback about your experience configuring credentials for self-hosted software. They make regular improvements to this flow and appear to value feedback.
@ -108,10 +105,20 @@ Project**. Note: This is a different type of project from the Device Access proj
1. On the *Test Users* step, you need to add your Google Account (e.g., your @gmail.com address) to the list. Click *Save* on your test account then **Save and Continue** to finish the consent flow.
![Screenshot of OAuth consent screen test users](/images/integrations/nest/oauth_consent_test_users.png)
1. Navigate back to the *OAuth consent screen* and click **Publish App** to set the *Publishing status* is *In Production* and not *Testing*. The warning says your *app will be available to any user with a Google Account* which refers to the fields you entered on the *App Information* screen if someone finds the URL. This does not expose your Google Account or Nest data.
1. Navigate back to the *OAuth consent screen* and click **Publish App** to set the *Publishing status* is **In Production**.
1. Make sure the status is not *Testing*, or you may get logged out every 7 days.
1. The warning says your *app will be available to any user with a Google Account* which refers to the fields you entered on the *App Information* screen if someone finds the URL. This does not expose your Google Account or Nest data.
![Screenshot of OAuth consent screen production status](/images/integrations/nest/oauth_consent_production_status.png)
1. Navigate to the **Credentials** page and click **Create Credentials**.
{% enddetails %}
{% details "Configure OAuth client_id and client_secret [Cloud Console]" %}
By the end of this section you will have the `client_id` and `client_secret` which are needed for later steps.
1. Navigate to the [Credentials](https://console.cloud.google.com/apis/credentials) page and click **Create Credentials**.
![Screenshot of APIs and Services Cloud Console](/images/integrations/nest/create_credentials.png)
1. From the drop-down list select *OAuth client ID*.
@ -124,35 +131,43 @@ Project**. Note: This is a different type of project from the Device Access proj
1. Add **Authorized redirect URIs** for your Home Assistant URL, including the OAuth callback path e.g., `https://<your_home_assistant_url>:<port>/auth/external/callback`. See [Troubleshooting](#troubleshooting) below for more details on the subtle requirements for what kinds of URLs work here.
![Screenshot of creating OAuth credentials](/images/integrations/nest/oauth_redirect_uri.png)
1. You should now be presented with an *OAuth client created* message. Take note of *Your Client ID* and *Your Client Secret* as these are needed for Home Assistant set up.
1. You should now be presented with an *OAuth client created* message. Take note of *Your Client ID* and *Your Client
Secret* as these are needed in later steps.
![Screenshot of OAuth Client ID and Client Secret](/images/integrations/nest/oauth_created.png)
{% enddetails %}
{% details "Link Device Access project_id [Device Access Console]" %}
{% details "Create a Device Access Project [Device Access Console]" %}
By the end of this section you will have a `project_id` as well as the *Topic Name* needed to configure Cloud Pub/Sub.
Now that you have authentication configured, you will create a Nest Device Access Project which *requires a US$5 fee*.
Once completed, you will have a device access `project_id` needed for later steps and the *Topic Name* needed to
configure Pub/Sub.
1. Now head back to the *[Device Access Console](https://console.nest.google.com/device-access/project-list)* tab and *Add your OAuth client ID* then click **Next**.
1. Go to the [Device Access Registration](https://developers.google.com/nest/device-access/registration) page. Click on the button **[Go to the Device Access Console](https://console.nest.google.com/device-access/)**.
![Screenshot of Device Access Registration](/images/integrations/nest/device_access.png)
1. Check the box to "Accept the Terms of Service" and click **Continue to Payment** where you need to pay a fee (currently US$5).
![Screenshot of accepting terms](/images/integrations/nest/accept_terms.png)
<div class='note'>
It is currently not possible to share/be invited to a home with a G-Suite account. Make sure that you pay the fee with an account that has access to your devices.
</div>
1. Now the [Device Access Console](https://console.nest.google.com/device-access/project-list) should be visible. Click on **Create project**.
![Screenshot of creating a project](/images/integrations/nest/create_project.png)
1. Give your Device Access project a name and click **Next**.
![Screenshot of naming a project](/images/integrations/nest/project_name.png)
1. Next you will be asked for an *OAuth client ID* which you created in the previous step and click **Nest**.
![Screenshot of Device Access Console OAuth client ID](/images/integrations/nest/device_access_oauth_client_id.png)
1. Enable Events by clicking on **Enable** and **Create project**.
![Screenshot of enabling events](/images/integrations/nest/enable_events.png)
1. Take note of the *Project ID* as you will it later. At this point you have the `project_id`, `client_id` and `client_secret` configuration options needed for Home Assistant.
1. Also Take note of the *Pub/Sub Topic* which is later entered manually as the *Topic Name* when configuring Pub/Sub in a follow up step.
{% enddetails %}
{% details "Enable Device Access APIs [Cloud Console]" %}
1. Go back to the [Google Cloud Console: API & Services](https://console.developers.google.com/apis/dashboard)
1. Click on **Enable APIs and Services**
![Screenshot of Cloud Console APIs and Services](/images/integrations/nest/enable_api.png)
1. Search for **Smart Device management** and enable the API.
![Screenshot of Search for SDM API](/images/integrations/nest/enable_sdm_api.png)
1. Take note of the *Pub/Sub Topic* which is later entered manually as the *Topic Name* when configuring Pub/Sub in a follow up step.
{% enddetails %}
@ -167,9 +182,6 @@ By the end of this section you will have the `subscriber_id` needed for configur
What is Pub/Sub? You can think of your Nest device as the publisher and your Home Assistant as the subscriber. As your Nest device publishes events like a temperature change or motion event, it notifies your Home Assistant subscriber about
those events so it can record the new value or trigger an automation.
1. Visit [Enable the Cloud Pub/Sub API](https://console.developers.google.com/apis/library/pubsub.googleapis.com) in the Cloud Console and click **Enable**.
1. Go to the [Google Cloud Platform: Pub/Sub: Subscriptions](https://console.cloud.google.com/cloudpubsub/subscription/list) page and click **Create Subscription**.
1. You will need to pick a *Subscription ID*.
@ -279,7 +291,7 @@ everything, however, you can leave out any feature you do not wish to use with H
- Check **Configuration** then **Logs** to see if there are any error messages or misconfigurations then see the error messages below.
- *Reauthentication required often*: If you are frequently getting logged out, this means your authentication token was revoked by Google likely due to a misconfiguration.
- *Reauthentication required often*: If you are getting logged out every 7 days, this means an OAuth Consent Screen misconfiugration or your authentication token was revoked by Google for some other reason.
{% details "Details about reauthentication issues" %}