Nest


The nest integration allows you to integrate your Google Nest devices in Home Assistant. This integration uses the Smart Device Management API and Google’s Cloud Pubsub to efficiently listen for changes in device state or other events.

There is currently support for the following device types within Home Assistant:

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.

Google applies strict Redirect URI validation rules 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 or Troubleshooting, and note that you don’t actually need to enable remote access.

Overview: Supported Devices

Home Assistant is integrated with the following devices through the SDM API:

  • Thermostat Devices
    • Every thermostat is exposed as a climate entity
    • A Temperature sensor entity. Note: Additional Nest Temperature Sensors are not supported by the SDM API.
    • A Humidity sensor entity.
    • Example devices: All Google Nest Thermostat models
  • Display, Camera, and Doorbell Devices
    • The camera live stream is available as a camera entity
    • Device Triggers for use in automations such as Person detected, Motion detected and Doorbell pressed
    • Example devices: All Google Nest Cam models, Google Nest Hello Video Doorbell, Google Nest Hub Max

You are in control of the information and capabilities exposed to Home Assistant. You can authorize a single device, multiple devices, or different levels of functionality such as motion events, live streams, for any particular device. The integration is flexible enough to adapt based on what you allow.

Others devices like Smoke and CO Alarms or Security systems are not currently supported by the SDM API.

The full detailed instructions for account setup are available in the Device Access Registration Quick Start Guide. The instructions below are included to make this complex setup process a bit easier to follow.

Device Access Registration

For the first phase, you will turn on the API and create the necessary credentials to have Home Assistant talk to the Nest API.

Create a Device Access Project [Device Access Console]
Configure OAuth client_id and client_secret [Cloud Console]
Link Device Access project_id [Device Access Console]
Enable Device Access APIs [Cloud Console]

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 for the full detailed instructions.

Configure Cloud Pub/Sub subscriber_id [Cloud Console]

Configuration

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.

# Example configuration.yaml entry
nest:
  client_id: CLIENT_ID
  client_secret: CLIENT_SECRET
  # "Project ID" in the Device Access Console
  project_id: PROJECT_ID
  # Provide the full path exactly as shown under "Subscription name" in Google Cloud Console
  subscriber_id: projects/project-label-22ee1/subscriptions/SUBSCRIBER_ID

Configuration Variables

client_id string Required

Your Device Access or Nest developer client ID.

client_secret string Required

Your Device Access or Nest developer client secret.

project_id string (Optional)

Your Device Access Project ID. This enables the SDM API.

subscriber_id string (Optional)

Full path for the Pub/sub Subscription ID used to receive events. This is required to use the SDM API. Enter this exactly as it appears under “Subscription name” in the Pub/Sub console.

Device Setup

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:

Manual configuration steps

The Nest integration setup will walk you through the steps of authorizing your Home Assistant to access your account and Nest devices.

OAuth and Device Authorization steps

Troubleshooting

  • For general trouble with the SDM API OAuth authorization flow with Google, see Troubleshooting.

  • 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.

Details about reauthentication issues
  • 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:
How to restart thermostat
  • 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 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.

Details about resolving redirect_uri_mismatch
  • 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.
Details about URL configuration
  • Error 403: access_denied means that you need to visit the OAuth Consent Screen and add your Google Account as a Test User.

  • Error: invalid_client no application name means the OAuth Consent Screen has not been fully configured for the project. Enter the required fields (App Name, Support Email, Developer Email) and leave everything else as default.

  • Subscriber error: Subscription misconfigured. Expected subscriber_id to match… means that the configuration.yaml has an incorrect subscriber_id field. Re-enter the Subscription Name which looks like projects/project-label-22ee1/subscriptions/SUBSCRIBER_ID. Make sure this is not the Topic name.

  • Subscriber error: Subscription misconfigured. Expected topic name to match … means that the topic name in the Google Cloud Console was entered incorrectly. The topic name comes from the Device Console and must start with projects/sdm-prod/topics/. It is easy to make the mistake of creating a new topic rather than manually entering the right topic name.

  • 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 subscriber when everything is configured correctly.

  • You can see stats about your subscriber in the Cloud Console which includes counts of messages published by your devices, and how many have been acknowledged by your Home Assistant subscriber. You can also View Messages to see examples of published. Many old unacknowledged messages indicate the subscriber is not receiving the messages and working properly or not connected at all. Double check the subscriber_id matches the Subscription Name

  • To aid in diagnosing subscriber problems or camera stream issues it may help to turn up verbose logging by adding some or all of these to your configuration.yaml depending on where you are having trouble:


logger:
  default: info
  logs:
    homeassistant.components.nest: debug
    homeassistant.components.nest.climate_sdm: debug
    homeassistant.components.nest.camera_sdm: debug
    homeassistant.components.nest.sensor_sdm: debug
    homeassistant.helpers.config_entry_flow: debug
    homeassistant.helpers.config_entry_oauth2_flow: debug
    google_nest_sdm: debug
    google_nest_sdm.device: debug
    google_nest_sdm.device_manager: debug
    google_nest_sdm.google_nest_subscriber: debug
    google_nest_sdm.event: debug
    google.cloud.pubsub_v1: debug

Camera

All Google Nest Cam models, Google Nest Hello Video Doorbell, Google Nest Hub Max expose a CameraLiveStream via the SDM API, which returns a RTSP live stream which can be viewed from Home Assistant.

Given a camera named Front Yard then the camera is created with a name such as camera.front_yard.

Climate

All Google Nest Thermostat models are exposed as a climate entity that use the Thermostat Traits in the SDM API. State changes to the thermostat are reported to Home Assistant through the Cloud Pubsub subscriber.

Given a thermostat named Upstairs then the climate entity is created with a name such as climate.upstairs

Sensor

All Google Nest Thermostat models have traits exposed from the SDM API. The initial values of the sensors are fetched on startup, then updated regularly using the Cloud Pubsub subscriber. The following traits are supported with sensors:

Given a thermostat named Upstairs then sensors are created with names such as sensor.upstairs_temperature or sensor.upstairs_humidity.

Automation and Device Triggers

The Nest integration makes device triggers available to enable automation in Home Assistant. You should review the Automating Home Assistant getting started guide on automations or the Automation documentation for full details.

Screenshot Device Triggers

All Google Nest Cam models and the Google Nest Hello Video Doorbell support device triggers:

  • Motion detected
  • Person detected
  • Sound detected
  • 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:

Device Trigger Pub/Sub Event nest_event
Motion detected CameraMotion motion_detected
Person detected CameraPerson person_detected
Sound detected CameraSound sound_detected
Doorbell pressed DoorbellChime doorbell_chime

Example

This automation will trigger when a nest_event event type with a type of camera_motion is received from the specified device_id.

alias: "motion alert"
trigger:
  - platform: event
    event_type: nest_event
    event_data:
      device_id: YOUR_DEVICE_ID
      type: camera_motion
action:
  - service: notify.mobile_app_pixel_2
    data:
      title: motion detected
      message: front door motion detected
      data:
        image: /api/camera_proxy/camera.front_door

The action in this section uses the Android Companion App and the camera proxy to send a notification with a snapshot from the camera.

Legacy Works With Nest API

This section contains instructions for the Legacy Works with Nest API.

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.
Legacy Works with Nest Configuration Steps