diff --git a/source/_integrations/nest.markdown b/source/_integrations/nest.markdown
index 7c4d4592114..08ff9f05e7b 100644
--- a/source/_integrations/nest.markdown
+++ b/source/_integrations/nest.markdown
@@ -25,7 +25,7 @@ There is currently support for the following device types within Home Assistant:
- [Sensor](#sensor)
-This integration continues to support the Legacy Works With Nest API which is not accepting new users. The documentation for this API is at the bottom of this page so existing users can keep using it.
+This integration supports two Nest APIs. The SDM API is the new primary API that accepts new users. The Legacy Works With Nest API is not accepting new users, but the documentation still exists at the bottom of the page so existing users can keep using it.
## Overview: Supported Devices
@@ -45,36 +45,86 @@ You are in control of the information and capabilities exposed to Home Assistant
Others devices like Smoke and CO Alarms or Security systems are not currently
supported by the SDM API.
-## Account Setup
+The full detailed instructions for account setup are available in the [Device Access Registration](https://developers.google.com/nest/device-access/registration) Quick Start Guide. The instructions below are included to make this complex setup process a bit easier to follow.
-You will need to follow the instructions in [Device Access Registration](https://developers.google.com/nest/device-access/registration) to authorize access to your devices. Follow these steps in the Quick Start Guide:
+## Device Access Registration
-- Accept the Terms of Service.
-- Pay a fee (currently US$5).
-- [Register for Device Access](https://developers.google.com/nest/device-access/get-started#register_for_device_access) to get a `project_id`.
-- [Set up Google Cloud Platform](https://developers.google.com/nest/device-access/get-started#set_up_google_cloud_platform) and enable the
- API
-- Authorize your Google Account and create OAuth credentials to get a `client_id` and `client_secret`.
-- Configure *Authorized redirect URIs* with the URL you use to access Home Assistant including the path for the OAuth callback , e.g. `https://:/auth/external/callback` (also see `redirect_url_mismatch` troubleshooting below)
+For the first phase, you will turn on the API and create the necessary credentials to have Home Assistant talk to the Nest API.
-
-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.
-
+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**.
+ 
-Then you need to configure a Pub/Sub subscriber following the SDM API Event instructions under [Device Access: Events](https://developers.google.com/nest/device-access/api/events) though not using a service account. The basic
-steps are:
+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).
+ 
-- [Enable events](https://developers.google.com/nest/device-access/subscribe-to-events#enable_events) in the [Device Access Console](https://console.nest.google.com/device-access/project-list) which creates a Pub/Sub topic.
-- [Enable the Cloud Pub/Sub API](https://console.developers.google.com/apis/library/pubsub.googleapis.com) in the Cloud Console.
-- [Create a Pub/Sub subscription](https://console.cloud.google.com/cloudpubsub/subscription/list) in the Google Cloud Platform console. Make sure to create a pull subscription and get a `subscriber_id` ("Subscription name" in Google Cloud Console). The *Topic name* should match the topic name in the device access console.
+
+ 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.
+
-Follow all of the instructions in [Device Access: Quick Start Guide](https://developers.google.com/nest/device-access/get-started) carefully as it is easy to make a configuration mistake that is difficult to debug. It is recommended to exercise the entire guide, including the command to test out the API, to make sure that it is working before configuring Home Assistant.
+1. Now the "Device Access Console" should be visible. Click on **Create project**.
+ 
-When you get to the steps about configuring events make sure to follow guide under [Events](https://developers.google.com/nest/device-access/api/events) that configures the [Pub/Sub subscription](https://console.cloud.google.com/cloudpubsub/subscription/list) from the Google Cloud console. Make sure to use the *topic name* from the device access console and a unique subscription ID in the cloud console. Note the message retention is how long messages will queue while offline, so keep that short (e.g., under an hour) to avoid a potentially large backlog of updates.
+1. Give your project a name and click **Next**.
+ 
+
+1. Next you will be asked for an *OAuth client ID*. It is a good idea to go create that now. Open a new tab to the [Google Cloud Console](https://console.developers.google.com/apis/credentials) **Credentials** page and click **Create
+Credentials**.
+ 
+
+1. From the drop-down list select *OAuth client ID*.
+ 
+
+1. Pick a name for your credential.
+
+1. Add **Authorized redirect URIs** for your Home Assistant URL, including the OAuth callback path e.g., `https://:/auth/external/callback`. See [Troubleshooting](#troubleshooting) below for more details on the subtle requirements for what kinds of URLs work here.
+ 
+
+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. Now head back to the *Device Access Console* tab and *Add your OAuth client ID* then click **Next**.
+ 
+
+1. Enable Events by clicking on **Enable** and **Create project**.
+ 
+
+1. Take note of the *Project ID* as you will need it later. At this point you have the `project_id`, `client_id` and `client_secret` configuration options needed for Home Assistant.
+
+1. At this point you should have a `Project ID`, `OAuth Client ID`, and an `OAuth Secret`.
+
+1. Go back to the [Google Cloud Console: API & Services](https://console.developers.google.com/apis/dashboard)
+
+1. Click on **Enable APIs and Services**
+ 
+
+1. Search for **Smart Device management** and enable the API.
+ 
+
+## Pub/Sub subscriber setup
+
+The next phase is to enable the Pub/Sub API by creating a subscription that can keep Home Assistant informed of events or device changes in near real-time. See [Device Access: Events](https://developers.google.com/nest/device-access/api/events) for the full detailed instructions.
+
+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*.
+ 
+
+1. The *Topic name* should match the topic name in your project in the [Device Access Console](https://console.nest.google.com/device-access/) and typically looks like `projects/sdm-prod/topics/EXAMPLE`.
+ 
+
+1. Select **Pull** as the *Delivery Type*.
+
+1. Lower the message retention duration to be something short (e.g., 10 minutes or under an hour) to avoid a large backlog of updates when Home Assistant is turned off.
+
+1. Leave the rest of the defaults and click **Create**.
+
+1. Once created, copy the *Subscription name* which you will want to hold on to as your `subscriber_id` for configuring Home Assistant. This typically looks like `projects/MY-CLOUD-ID/subscriptions/EXAMPLE`. Don't confuse *Subscription name* with *Topic name* since they look similar.
## Configuration
-```yaml
+Congratulations, you now should have everything you need to configure Home Assistant. Edit your `configuration.yaml` file and populate a `nest` entry in the format of the example [Configuration](#configuration) below.
```yaml
# Example configuration.yaml entry
@@ -108,21 +158,40 @@ subscriber_id:
## Device Setup
-Once your developer account is set up and you have a valid `nest` entry in `configuration.yaml` , you need to connect devices with the following steps:
+Once your developer account is set up and you have a valid `nest` entry in `configuration.yaml`, you need to connect devices with the following steps:
+
+1. From the Home Assistant front-end, navigate to **Configuration** then *Integrations**. Under **Set up a new integration** locate 'Nest'.
-1. From the Home Assistant front-end, navigate to **Configuration** then **Integrations**. Under **Set up a new integration** locate 'Nest'.
1. You should get redirected to Google to choose an account. This should be the same developer account you configured above.
+
1. The *Google Nest permissions* screen will allow you to choose which devices to configure. You can leave out any device that you do not wish to use with Home Assistant.
-1. You will get redirected back to another account selection page.
+ 
+
+1. You will get redirected back to another account selection page. See [Troubleshooting](#troubleshooting) below if you get a `redirect_uri_mismatch` error.
+
+1. Then you will be asked to grant access to additional permissions. Click *Allow*.
+ 
+ 
+
1. Confirm you want to allow persistent access to Home Assistant.
+ 
+
+1. If all went well, you are ready to go!
+ 
+
## Troubleshooting
- For general trouble with the SDM API OAuth authorization flow with Google, see [Troubleshooting](https://developers.google.com/nest/device-access/authorize#troubleshooting).
-- *Error 500: redirect_url_mismatch* means that you need visit the [GCP credentials](https://console.developers.google.com/apis/credentials) page and modify your OAuth2.0 Client ID to add the correct Home Asssitant callback URL. The error message tells you the exact URL that needs to be added, including any ports or paths like `/auth/external/callback` path. See [Redirect uri mismatch](https://developers.google.com/nest/device-access/authorize#redirect_uri_mismatch) for more details.
+- *Error 500: redirect_uri_mismatch* means that you need to visit the [GCP credentials](https://console.developers.google.com/apis/credentials) page and modify your OAuth2.0 Client ID to add the correct Home Assistant callback URL. The error message tells you the exact URL that needs to be added, including any ports or paths like `/auth/external/callback` path. See [Redirect URI mismatch](https://developers.google.com/nest/device-access/authorize#redirect_uri_mismatch) for more details.
-- *No devices or entities are created* if the SDM API is not returning any devices for the authorized account. Double double check that GCP is configured correctly to [Enable the API](https://developers.google.com/nest/device-access/get-started#set_up_google_cloud_platform) and authorize at least one device in the OAuth setup flow. If you have trouble here, then you may want to walk through the [Get Started: Device Access](https://developers.google.com/nest/device-access/get-started) guide again and issue commands directly against the API until you successfully get back devices.
+ - A convienent solution is to use [Nabu Casa](https://www.nabucasa.com/)
+ - There are subtle rules for what types of URLs are allowed, namely that they must use a publicly known hostname, though your Home Assistant ports do not need to be exposed to the internet.
+ - You can use any publicly known hostname you own
+ - As a hack, you can use hosts tricks to temporarily assign a public hostname to your Home Assistant IP address.
+
+- *No devices or entities are created* if the SDM API is not returning any devices for the authorized account. Double-check that GCP is configured correctly to [Enable the API](https://developers.google.com/nest/device-access/get-started#set_up_google_cloud_platform) and authorize at least one device in the OAuth setup flow. If you have trouble here, then you may want to walk through the Google instructions and issue commands directly against the API until you successfully get back the devices.
- *Not receiving updates* typically means a problem with the subscriber configuration. Changes for things like sensors or thermostat temperature set points should be instantly published to a topic and received by the Home Assistant susbcriber when everything is configured correctly.
diff --git a/source/images/integrations/nest/accept_terms.png b/source/images/integrations/nest/accept_terms.png
new file mode 100644
index 00000000000..16516c60e4f
Binary files /dev/null and b/source/images/integrations/nest/accept_terms.png differ
diff --git a/source/images/integrations/nest/create_credentials.png b/source/images/integrations/nest/create_credentials.png
new file mode 100644
index 00000000000..45e4a5ebb55
Binary files /dev/null and b/source/images/integrations/nest/create_credentials.png differ
diff --git a/source/images/integrations/nest/create_project.png b/source/images/integrations/nest/create_project.png
new file mode 100644
index 00000000000..b03d5d3ca47
Binary files /dev/null and b/source/images/integrations/nest/create_project.png differ
diff --git a/source/images/integrations/nest/create_subscription.png b/source/images/integrations/nest/create_subscription.png
new file mode 100644
index 00000000000..354846780dc
Binary files /dev/null and b/source/images/integrations/nest/create_subscription.png differ
diff --git a/source/images/integrations/nest/device_access.png b/source/images/integrations/nest/device_access.png
new file mode 100644
index 00000000000..aefcd5f128e
Binary files /dev/null and b/source/images/integrations/nest/device_access.png differ
diff --git a/source/images/integrations/nest/device_access_oauth_client_id.png b/source/images/integrations/nest/device_access_oauth_client_id.png
new file mode 100644
index 00000000000..9b7465d89c4
Binary files /dev/null and b/source/images/integrations/nest/device_access_oauth_client_id.png differ
diff --git a/source/images/integrations/nest/device_access_pubsub_topic.png b/source/images/integrations/nest/device_access_pubsub_topic.png
new file mode 100644
index 00000000000..34d045b8222
Binary files /dev/null and b/source/images/integrations/nest/device_access_pubsub_topic.png differ
diff --git a/source/images/integrations/nest/enable_api.png b/source/images/integrations/nest/enable_api.png
new file mode 100644
index 00000000000..24df886fc19
Binary files /dev/null and b/source/images/integrations/nest/enable_api.png differ
diff --git a/source/images/integrations/nest/enable_events.png b/source/images/integrations/nest/enable_events.png
new file mode 100644
index 00000000000..bf2883b61f9
Binary files /dev/null and b/source/images/integrations/nest/enable_events.png differ
diff --git a/source/images/integrations/nest/enable_sdm_api.png b/source/images/integrations/nest/enable_sdm_api.png
new file mode 100644
index 00000000000..67b7ed91868
Binary files /dev/null and b/source/images/integrations/nest/enable_sdm_api.png differ
diff --git a/source/images/integrations/nest/finished.png b/source/images/integrations/nest/finished.png
new file mode 100644
index 00000000000..f6380374c70
Binary files /dev/null and b/source/images/integrations/nest/finished.png differ
diff --git a/source/images/integrations/nest/oauth_approve.png b/source/images/integrations/nest/oauth_approve.png
new file mode 100644
index 00000000000..8741d5e8ed4
Binary files /dev/null and b/source/images/integrations/nest/oauth_approve.png differ
diff --git a/source/images/integrations/nest/oauth_client_id.png b/source/images/integrations/nest/oauth_client_id.png
new file mode 100644
index 00000000000..66e4ab38ac6
Binary files /dev/null and b/source/images/integrations/nest/oauth_client_id.png differ
diff --git a/source/images/integrations/nest/oauth_confirm.png b/source/images/integrations/nest/oauth_confirm.png
new file mode 100644
index 00000000000..caf847371d7
Binary files /dev/null and b/source/images/integrations/nest/oauth_confirm.png differ
diff --git a/source/images/integrations/nest/oauth_created.png b/source/images/integrations/nest/oauth_created.png
new file mode 100644
index 00000000000..8696ee7f64f
Binary files /dev/null and b/source/images/integrations/nest/oauth_created.png differ
diff --git a/source/images/integrations/nest/oauth_grant1.png b/source/images/integrations/nest/oauth_grant1.png
new file mode 100644
index 00000000000..520fdf47fd9
Binary files /dev/null and b/source/images/integrations/nest/oauth_grant1.png differ
diff --git a/source/images/integrations/nest/oauth_grant2.png b/source/images/integrations/nest/oauth_grant2.png
new file mode 100644
index 00000000000..75ba05a7630
Binary files /dev/null and b/source/images/integrations/nest/oauth_grant2.png differ
diff --git a/source/images/integrations/nest/oauth_redirect_uri.png b/source/images/integrations/nest/oauth_redirect_uri.png
new file mode 100644
index 00000000000..739e3cc94d6
Binary files /dev/null and b/source/images/integrations/nest/oauth_redirect_uri.png differ
diff --git a/source/images/integrations/nest/project_name.png b/source/images/integrations/nest/project_name.png
new file mode 100644
index 00000000000..015478bebf1
Binary files /dev/null and b/source/images/integrations/nest/project_name.png differ