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

Update nest documentation with Device Access program / SDM API information (#14855)

Browse Source 
Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Allen Porter 2020-10-21 04:14:29 -07:00 committed by GitHub
parent ccde398289
commit ed283402c0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 84 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
source/_integrations/nest.markdown
View File

@ -15,34 +15,57 @@ ha_codeowners:
ha_domain: nest
---
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`.
The `nest` integration allows you to access all supported [Google Nest](https://store.google.com/us/category/connected_home?) devices. There are two APIs:
1. New [Device Access](https://developers.google.com/nest/device-access) program and [Smart Device Management](https://developers.google.com/nest/device-access/api) (SDM) API.
1. Legacy [Works With Nest](https://developers.nest.com/) API. This API does not accept new users, but existing users can keep using it.
<div class='note warning'>
The two APIs support different features and devices. The SDM API integration is currently under development and does not yet support everything in the API either.
</div>
There is currently support for the following device types within Home Assistant:
- [Binary Sensor](#binary-sensor)
- [Camera](#camera)
- [Climate](#climate)
- [Sensor](#sensor)
- [Binary Sensor](#binary-sensor) (Legacy API Only)
- [Camera](#camera) (Legacy API Only)
- [Climate](#climate) (Legacy API Only)
- [Sensor](#sensor) (Both APIs)
### Setting up developer account
## Device Access: Developer Account Setup
You will need to follow the instructions in [Device Access Registration](https://developers.google.com/nest/device-access/registration), which includes the following steps in the
Quick Start Guide:
- Accept the Terms of Service.
- Pay a fee (currently US$5).
- Register in the Device Access Console to get a `project_id`.
- Authorize your Google Account and create OAuth credentials to get a `client_id` and `client_secret`.
- Enable pubsub events in the Device Access Console (creates a topic).
- Create a pull subscription to get a `subscription_id`.
Additionally, Home Assistant must be configured with a URL (e.g., external exposed [`http`](/integrations/http/), Nabu Casa, etc). When setting up the OAuth credentials, make sure the Home Assistant URL is in the list of *Authorized redirect URIs*, so the redirect back to Home Assistant can get an OAuth authorization code.
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.
It may be easiest to create a [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 name. 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.
## Works With Nest: Developer Account Setup (Legacy)
<div class='note warning'>
New users are not currently able to set up a Works With Nest Developer account due to the change announced by Google. We will reach out to Nest to see if we can become a partner so that users joining Home Assistant after [August 2019](/blog/2019/05/08/nest-data-bye-bye/) can still use Nest. In the future we will add documentation on how to setup a Works With Google account and configure your Nest integration.
New users cannot set up a "Works With Nest Developer" account and instead should use the Device Access program. The instructions below only apply if you already have an account.
</div>
1. Visit [Nest Developers](https://developers.nest.com/), and sign in. Create an account if you don't have one already.
2. Fill in account details:
* The "Company Information" can be anything. We recommend using your name.
3. Submit changes
4. Click "[Products](https://developers.nest.com/products)" at top of page.
4. Click "[Products](https://developers.nest.com/products)" at the top of page.
5. Click "[Create New Product](https://developers.nest.com/products/new)"
6. Fill in details:
* Product name must be unique. We recommend [email] - Home Assistant.
* The description, users, URLs can all be anything you want.
* Leave the "Redirect URI" Field blank
7. For permissions check every box and if it's an option select the read/write option. Note: there are important permissions under the "Other Permissions" category. If you are only adding a thermostat, do not just select the permissions under "Thermostat". You still need to check the boxes under "Other Permissions" in order to give you access to features like away mode, ETA, structure read/write, and postal code.
7. For permissions, check every box and if it's an option, select the read/write option. Note: there are important permissions under the "Other Permissions" category. If you are only adding a thermostat, do not just select the permissions under "Thermostat". You still need to check the boxes under "Other Permissions" to give you access to features like away mode, ETA, structure read/write, and postal code.
* The description requires a specific format to be accepted.
* Use "[Home Assistant] [Edit] [For Home Automation]" as the description as it is not super important.
8. Click "Create Product"
@ -51,13 +74,16 @@ 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
nest:
client_id: CLIENT_ID
client_secret: CLIENT_SECRET
# Fields required by Device Access (SDM) API. Otherwise, use legacy API.
project_id: PROJECT_ID
subscriber_id: SUBSCRIBER_ID
```
```yaml
@ -72,20 +98,43 @@ nest:
{% configuration %}
client_id:
description: Your Nest developer client ID.
description: Your Device Access or Nest developer client ID.
required: true
type: string
client_secret:
description: Your Nest developer client secret.
description: Your Device Access or Nest developer client secret.
required: true
type: string
project_id:
description: Your Device Access project_id. This enables the SDM API.
required: false
type: string
subscription_id:
description: Your Pub/sub subscription_id used to receive events. This is required to use the SDM API.
type: string
required: false
structure:
description: The structure or structures you would like to include devices from. If not specified, this will include all structures in your Nest account.
description: The structure or structures you would like to include devices from. If not specified, this will include all structures in your Nest account. Not currently supported by the SDM API.
required: false
type: list
{% endconfiguration %}
### Service `set_away_mode`
## Device Setup (SDM API)
Once your developer account is set up and `nest` has been configured, 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 'Google Nest Device Access'.
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.
1. You will get redirected back to another account selection page.
1. Confirm you want to allow persistent access to Home Assistant.
## Services (Legacy API Only)
They Legacy API supports additional services for home/away/eta that are not
supported by the SDM API.
### Service `set_away_mode` (Legacy API Only)
You can use the service `nest/set_away_mode` to set the structure(s) to "Home" or "Away".
@ -118,7 +167,7 @@ script:
- Apartment
```
### Service `set_eta`
### Service `set_eta` (Legacy API Only)
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.
@ -156,7 +205,7 @@ script:
- Apartment
```
### Service `cancel_eta`
### Service `cancel_eta` (Legacy API Only)
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.
@ -189,7 +238,7 @@ script:
- Apartment
```
### Troubleshooting
## Troubleshooting (Legacy API Only)
- If you're getting [rickrolled](https://www.youtube.com/watch?v=dQw4w9WgXcQ) 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.
@ -201,17 +250,17 @@ You must have the [Nest component](/integrations/nest/) configured to use the pl
</div>
## Binary Sensor
### Binary Sensor (Legacy API Only)
The `nest` binary sensor platform lets you monitor various states of your [Nest](https://nest.com) devices.
<div class='note'>
You must have the [Nest component](/integrations/nest/) configured to use these sensors. The binary sensors will be setup if the `nest` integration is configured and the required configuration for the `nest binary sensor` is set.
You must have the [Nest component](/integrations/nest/) configured to use these sensors. The binary sensors will be set up if the `nest` integration is configured and the required configuration for the `nest binary sensor` is set.
</div>
## 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:
@ -224,7 +273,7 @@ nest:
- 'target'
```
By default all binary sensors for your available Nest devices will be monitored. Leave `monitored_conditions` blank to disable all binary sensors for the [Nest component](/integrations/nest/).
By default, all binary sensors for your available Nest devices will be monitored. Leave `monitored_conditions` blank to disable all binary sensors for the [Nest component](/integrations/nest/).
{% configuration %}
monitored_conditions:
@ -251,19 +300,19 @@ The following conditions are available by device:
- person\_detected
- sound\_detected
## Camera
### Camera (Legacy API Only)
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.
<div class='note'>
The `nest` camera will automatically be setup when you do.
The `nest` camera will automatically be set up when you do.
</div>
Nest Camera supports the `camera.turn_on` and `camera.turn_off` services since the 0.75 release.
## Climate
### Climate (Legacy API Only)
The `nest` climate platform lets you control a thermostat from [Nest](https://nest.com).
@ -275,17 +324,18 @@ Please note due to limitations with the European Nest Thermostat E, integration
<img src='/images/screenshots/nest-thermostat-card.png' />
</p>
## Sensor
### Sensor
The `nest` sensor platform lets you monitor sensors connected to your [Nest](https://nest.com) devices.
The `nest` sensor platform lets you monitor sensors connected to your [Nest](https://nest.com) devices. The SDM API supports these sensor traits:
- [Temperature](https://developers.google.com/nest/device-access/traits/device/temperature)
- [Humidity](https://developers.google.com/nest/device-access/traits/device/humidity)
<div class='note'>
The sensors will be setup if the `nest` integration is configured and the required configuration for the `nest sensor` is set.
The SDM API will monitor all devices automatically once configured. The Legacy API has additional configuration for `nest sensor`.
</div>
## 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:
@ -298,7 +348,7 @@ nest:
- 'target'
```
By default all sensors for your available Nest devices will be monitored. Leave `monitored_conditions` blank to disable all sensors for the [Nest component](/integrations/nest/).
By default all, sensors for your available Nest devices will be monitored. Leave `monitored_conditions` blank to disable all sensors for the [Nest component](/integrations/nest/).
{% configuration %}
monitored_conditions:
@ -325,7 +375,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 (Legacy Only)
<div class='note warning'>