diff --git a/source/_integrations/nest.markdown b/source/_integrations/nest.markdown index 2b15ffb13de..03603c0c754 100644 --- a/source/_integrations/nest.markdown +++ b/source/_integrations/nest.markdown @@ -64,7 +64,9 @@ 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. -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**. +{% details "Create a Device Access Project [Device Access 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) 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). @@ -80,7 +82,13 @@ For the first phase, you will turn on the API and create the necessary credentia 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. Open a new tab to the [Google API Console](https://console.developers.google.com/apis/credentials). +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 [Cloud Console]" %} + +1. Open a new tab to the [Google API 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. @@ -119,7 +127,11 @@ Project**. Note: This is a different type of project from the Device Access proj 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. ![Screenshot of OAuth Client ID and Client Secret](/images/integrations/nest/oauth_created.png) -1. Now head back to the *Device Access Console* tab and *Add your OAuth client ID* then click **Next**. +{% enddetails %} + +{% details "Link Device Access Authentication [Device Access Console]" %} + +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**. ![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**. @@ -127,6 +139,10 @@ Project**. Note: This is a different type of project from the Device Access proj 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. +{% 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** @@ -135,10 +151,14 @@ Project**. Note: This is a different type of project from the Device Access proj 1. Search for **Smart Device management** and enable the API. ![Screenshot of Search for SDM API](/images/integrations/nest/enable_sdm_api.png) +{% enddetails %} + ## 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. +{% details "Configure Cloud Pub/Sub [Cloud Console]" %} + 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**. @@ -157,9 +177,11 @@ The next phase is to enable the Pub/Sub API by creating a subscription that can 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. +{% enddetails %} + ## Configuration -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. +You now should have everything needed to configure Nest in Home Assistant. Edit your `configuration.yaml` file and populate a `nest` entry in the format of the example configuration below. ```yaml # Example configuration.yaml entry @@ -193,9 +215,25 @@ 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 `configuration.yaml` has a valid `nest` entry, you need to add Nest to your Home Assistant instance via the user interface by using this My button: -1. Using your externally accessible address from the Home Assistant front-end, navigate to **Configuration** then **Integrations**. Click **Add Integration** then locate 'Nest'. +{% my config_flow_start badge domain=page.ha_domain %} + +{% details "Manual configuration steps" %} + +1. Browse to your Home Assistant instance using. +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 _**"Nest"**_ and follow the instructions. + +{% enddetails %} + +The Nest integration setup will walk you through the steps of authorizing +your Home Assistant to access your account and Nest devices. + +{% details "OAuth and Device Authorization steps" %} 1. You should get redirected to Google to choose an account. This should be the same developer account you configured above. @@ -220,6 +258,7 @@ everything, however, you can leave out any feature you do not wish to use with H 1. If all went well, you are ready to go! ![Screenshot of success](/images/integrations/nest/finished.png) +{% enddetails %} ## Troubleshooting @@ -227,34 +266,56 @@ 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. This most likely reason is the *OAuth Consent Screen* is set to *Testing* by default which expires the token after 7 days. Follow the steps above to set it to *Production* to resolve this and reauthorize your integration one more time to get a new token. You may also see this as the error message *invalid_grant: Token has been expired or revoked*. See [Google Identity: Refresh token expiration](https://developers.google.com/identity/protocols/oauth2#expiration) for more reasons on why your token may have expired. +- *Reauthentication required often*: If you are frequently getting logged out, this means your authentication token was revoked by Google likely due to a misconfiguration. + +{% details "Details about reauthentication issues" %} + +- This most likely reason is the *OAuth Consent Screen* is set to *Testing* by default which expires the token after 7 days. +- Follow the steps above to set it to *Production* to resolve this and reauthorize your integration one more time to get a new token. +- You may also see this as the error message *invalid_grant: Token has been expired or revoked*. +- See [Google Identity: Refresh token expiration](https://developers.google.com/identity/protocols/oauth2#expiration) for more reasons on why your token may have expired. + +{% enddetails %} - *Thermostat does not appear or is unavailable* happens due to a bug where the SDM API does return the devices. A common fix get the API to work again is to: - - Restart the Thermostat device. See [How to restart or reset a Nest thermostat](https://support.google.com/googlenest/answer/9247296) for more details. - - In the official Nest app or on https://home.nest.com: Move the Thermostat to a different or fake/temporary room. - - Reload the integration in Home Assistant: Navigate to **Configuration** then **Integrations**, click `...` next to *Nest* and choose **Reload**. + +{% details "How to restart thermostat" %} + + - Restart the Thermostat device. See [How to restart or reset a Nest thermostat](https://support.google.com/googlenest/answer/9247296) for more details. + - In the official Nest app or on https://home.nest.com: Move the Thermostat to a different or fake/temporary room. + - Reload the integration in Home Assistant: Navigate to **Configuration** then **Integrations**, click `...` next to *Nest* and choose **Reload**. + +{% enddetails %} - *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. - *Error 400: redirect_uri_mismatch* means that your OAuth Client ID is not configured to match your Home Assistant URL. - - To resolve this, copy and paste the redirect URI in the error message (`https://:/auth/external/callback`). +{% details "Details about resolving redirect_uri_mismatch" %} - ![Screenshot of success](/images/integrations/nest/redirect_uri_mismatch.png) +- To resolve this, copy and paste the redirect URI in the error message (`https://:/auth/external/callback`). - - Go back to the [API Console](https://console.developers.google.com/apis/credentials) and select your *OAuth 2.0 Client ID*. - - Add the URL to the list of *Authorized redirect URIs* and click **Save** and start the flow over. + ![Screenshot of success](/images/integrations/nest/redirect_uri_mismatch.png) - ![Screenshot of success](/images/integrations/nest/redirect_uris_fix.png) +- Go back to the [API Console](https://console.developers.google.com/apis/credentials) and select your *OAuth 2.0 Client ID*. +- Add the URL to the list of *Authorized redirect URIs* and click **Save** and start the flow over. + + ![Screenshot of success](/images/integrations/nest/redirect_uris_fix.png) + +{% enddetails %} - When configuring the OAuth Client ID redirect URI, you may see an error such as *must end with a public top-level domain (such as .com or .org)* or *must use a valid domain that is a valid top private domain*. This means that you may need to change the URL you use to access Home Assistant in order to access your devices. - - See [Securing](https://www.home-assistant.io/docs/configuration/securing/) Home Assistant for convenient solutions e.g. [Nabu Casa](https://www.nabucasa.com/) or Duck DNS. - - There are subtle [rules](https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation) for what types of URLs are allowed, namely that they must use SSL and 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. +{% details "Details about URL configuration" %} + +- See [Securing](https://www.home-assistant.io/docs/configuration/securing/) Home Assistant for convenient solutions e.g. [Nabu Casa](https://www.nabucasa.com/) or Duck DNS. +- There are subtle [rules](https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation) for what types of URLs are allowed, namely that they must use SSL and 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. + +{% enddetails %} - *Error 403: access_denied* means that you need to visit the [OAuth Consent Screen](https://console.developers.google.com/apis/credentials/consent) and add your Google Account as a *Test User*. @@ -322,7 +383,7 @@ All Google Nest Cam models and the Google Nest Hello Video Doorbell support devi - **Motion detected** - **Person detected** - **Sound detected** -- **Doorbell pressed** *for Google Nest Hello Video Doorbell only* +- **Doorbell pressed** *for Doorbell only* The lower level Pub/Sub subscriber receives events in real time and internally fires `nest_event` events within Home Assistant: @@ -333,7 +394,7 @@ The lower level Pub/Sub subscriber receives events in real time and internally f | Sound detected | [CameraSound](https://developers.google.com/nest/device-access/traits/device/camera-sound#events) | `sound_detected` | | Doorbell pressed | [DoorbellChime](https://developers.google.com/nest/device-access/traits/device/doorbell-chime#events) | `doorbell_chime` | -### Example +## Example This automation will trigger when a `nest_event` event type with a type of `camera_motion` is received from the specified `device_id`. @@ -364,8 +425,7 @@ This section contains instructions for the Legacy [Works with Nest](https://deve New users are not currently able to set up a Works With Nest Developer account. The documentation is preserved here for existing users of the API. -
-Click here to expand documentation for the Legacy Works with Nest API +{% details "Legacy Works with Nest Configuration Steps" %} The Nest integration is the main integration to integrate all [Nest](https://nest.com/) related platforms. To connect Nest, you will have to [sign up for a developer account](https://developers.nest.com/products) and get a `client_id` and `client_secret`. @@ -377,7 +437,7 @@ There is currently support for the following device types within Home Assistant: - [Climate](#climate) - [Sensor](#sensor) -### Setting up developer account +**Setting up developer account** 1. Visit [Nest Developers](https://developers.nest.com/), and sign in. Create an account if you don't have one already. @@ -399,7 +459,7 @@ There is currently support for the following device types within Home Assistant: Connecting to the Nest Developer API requires outbound port 9553 on your firewall. The configuration will fail if this is not accessible. -## Configuration +**Configuration** ```yaml # Example configuration.yaml entry @@ -433,7 +493,7 @@ structure: type: list {% endconfiguration %} -### Service `set_away_mode` +**Service `set_away_mode`** You can use the service `nest/set_away_mode` to set the structure(s) to "Home" or "Away". @@ -466,7 +526,7 @@ script: - Apartment ``` -### Service `set_eta` +**Service `set_eta`** You can use the service `nest/set_eta` to set or update the estimated time of arrival window. Calling this service will automatically set the structure(s) to "Away". Structures must have an associated Nest thermostat in order to use ETA function. @@ -504,7 +564,7 @@ script: - Apartment ``` -### Service `cancel_eta` +**Service `cancel_eta`** You can use the service `nest/cancel_eta` to cancel an existing estimated time of arrival window. Structures must have an associated Nest thermostat in order to use ETA function. @@ -537,13 +597,13 @@ script: - Apartment ``` -### Troubleshooting +**Troubleshooting** - For trouble with the SDM API OAuth authorization flow with Google, see [Troubleshooting](https://developers.google.com/nest/device-access/authorize#troubleshooting) which includes guidance for errors like `redirect_uri_mismatch` where Google needs to know about your external URL. - If you're getting [rickrolled](https://www.youtube.com/watch?v=dQw4w9WgXcQ) by the Legacy API instead of being able to see your Nest cameras, you may not have set up your developer account's permissions correctly. Go back through and make sure you've selected read/write under every category that it's an option. -## Platforms +**Platforms**
@@ -551,7 +611,7 @@ You must have the [Nest component](/integrations/nest/) configured to use the pl
-### Binary Sensor +**Binary Sensor** The `nest` binary sensor platform lets you monitor various states of your [Nest](https://nest.com) devices. @@ -561,7 +621,7 @@ You must have the [Nest component](/integrations/nest/) configured to use these -#### Configuration +**Configuration** To enable binary sensors and customize which sensors are setup, you can extend the [Nest component](/integrations/nest/) configuration in your `configuration.yaml` file with the following settings: @@ -601,7 +661,7 @@ The following conditions are available by device: - person\_detected - sound\_detected -### Camera +**Camera** The `nest` platform allows you to watch still frames from a video stream (not live stream) of your [Nest](https://nest.com/camera/meet-nest-cam/) camera in Home Assistant. @@ -613,7 +673,7 @@ The Legacy API integration allows you to watch still frames from a video stream Nest Camera supports the `camera.turn_on` and `camera.turn_off` services since the 0.75 release. -### Climate +**Climate** The `nest` climate platform lets you control a thermostat from [Nest](https://nest.com). @@ -625,7 +685,7 @@ Please note due to limitations with the European Nest Thermostat E, integration

-### Sensor +**Sensor** The `nest` sensor platform lets you monitor sensors connected to your [Nest](https://nest.com) devices. @@ -635,7 +695,7 @@ The sensors will be setup if the `nest` integration is configured and the requir -#### Configuration +**Configuration** To enable sensors and customize which sensors are setup, you can extend the [Nest component](/integrations/nest/) configuration in your `configuration.yaml` file with the following settings: @@ -675,7 +735,7 @@ The following conditions are available by device: - `color_status`: `gray`, `green`, `yellow` or `red`. Indicates device status by color in the Nest app UI. It is an aggregate condition for battery+smoke+CO states, and reflects the actual color indicators displayed in the Nest app. - Nest Camera: none -### Security State +**Security State**
@@ -701,4 +761,4 @@ A `deter` state is re-evaluated after several minutes and relaxed to `ok` if no The `security_state` automatically switches to `ok` when the structure state is `home`. -
+{% enddetails %}