search

chrisjshull / homebridge-nest

Nest plugin for HomeBridge
688 stars 109 forks source link

readme

homebridge-nest

verified-by-homebridge Discord

Nest plug-in for Homebridge using the native Nest API. See what's new in release 4.6.9.

Integrate your Nest Thermostat, Temperature Sensors, Nest Protect, and Nest x Yale Lock devices into your HomeKit system. Both Nest Accounts (pre-August 2019) and Google Accounts are supported.

Currently, homebridge-nest supports all Nest Thermostat, Protect, and Nest x Yale Lock models, including the EU/UK model of the Thermostat E with Heat Link and the October 2020 model Nest Thermostat with mirror display.

We do not support the discontinued Nest Secure system. We also do not support cameras - but for that, there is the excellent homebridge-nest-cam plug-in.

Starling Home Hub

If you want a plug-and-play Nest integration solution, check out Starling Home Hub. It's a little box that connects to your home router, so you'll be up and running in minutes without needing to set up a Homebridge server, manually edit configuration files, or worry about authentication tokens. Starling Home Hub also supports Nest Cameras (including the August 2021 battery-powered models) and Nest Secure (Guard and Detects).

If you want a DIY solution, then read on, as homebridge-nest is for you!

Installation

  1. Install homebridge using: npm install -g homebridge
  2. Install this plug-in using: npm install -g homebridge-nest
  3. Update your configuration file. See example config.json snippet below.

Configuration

Configuration sample (edit ~/.homebridge/config.json):

"platforms": [
        {
            "platform": "Nest",
            "options": [ "HomeAway.Disable" ],
            "access_token": "your Nest Account access token"
        }
    ],

Required fields when using a Nest Account with an access token: (see below for set-up info)

Required fields when using a Google Account with a refresh token: (see below for set-up info)

Required fields when using a Google Account with cookies: (see below for set-up info)

Optional fields:

Using a Nest Account

To use a Nest Account with homebridge-nest, you will need to obtain an access token from the Nest web app. (Note - no Nest developer account is required.) Simply go to https://home.nest.com in your browser and log in. Once that's done, go to https://home.nest.com/session in your browser, and you will see a long string that looks like this:

{"2fa_state":"not_enrolled","access_token":"XXX","email":"...","expires_in":"...", ...}

Simply set "access_token" in your config.json file under the "platform": "Nest" entry to the value of access_token near the start of the string (the XXX), which will be a long sequence of letters, numbers and punctuation beginning with b. There may be other keys labelled access_token further along in the string - please ignore these.

Do not log out of home.nest.com, as this will invalidate your credentials. Just close the browser tab.

Using a Google Account

Google Accounts (mandatory for new Nest devices after August 2019, with an optional migration for earlier accounts) are fully supported.

(Note: the plug-in used to support two ways to authenticate with Google, the refresh token method and the cookies method. The refresh token method no longer works due to Google-side changes in October 2022, so now we only document the cookies method.)

Using the cookies method, Google Accounts are configured using the "googleAuth" object in config.json, which contains two fields, "issueToken" and "cookies", which looks like this:

      "platform": "Nest",
      "googleAuth": {
        "issueToken": "https://accounts.google.com/o/oauth2/iframerpc?action=issueToken...",
        "cookies": "OCAK=TOMPYI3cCPAt...; SID=ogftnk...; HSID=ApXSR...; ...; SIDCC=AN0-TYt..."
      },

The values of "issueToken" and "cookies" are specific to your Google Account. To get them, follow these steps (only needs to be done once, as long as you stay logged into your Google Account).

  1. Open a Chrome browser tab in Incognito Mode (or clear your cache).
  2. Open Developer Tools (View/Developer/Developer Tools).
  3. Click on 'Network' tab. Make sure 'Preserve Log' is checked.
  4. In the 'Filter' box, enter issueToken
  5. Go to home.nest.com, and click 'Sign in with Google'. Log into your account.
  6. One network call (beginning with iframerpc) will appear in the Dev Tools window. Click on it.
  7. In the Headers tab, under General, copy the entire Request URL (beginning with https://accounts.google.com). This is your "issueToken" in config.json.
  8. In the 'Filter' box, enter oauth2/iframe
  9. Several network calls will appear in the Dev Tools window. Click on the last iframe call.
  10. In the Headers tab, under Request Headers, copy the entire cookie (include the whole string which is several lines long and has many field/value pairs - do not include the cookie: name). This is your "cookies" in config.json.
  11. Do not log out of home.nest.com, as this will invalidate your credentials. Just close the browser tab.

HomeKit Accessory Types

Home

Nest Thermostat (+ Temperature Sensors)

Nest Protect

Nest x Yale Lock

Feature Options

Set "options" in config.json to an array of strings chosen from the following to customise feature options:

By default, options set apply to all devices. To set an option for a specific device only, add .device_id to the corresponding option, where device_id is shown in the Homebridge logs, or in HomeKit itself as Serial Number in the Settings page for your device. For example, to disable one specific thermostat with serial number 09AC01AC31180349, add "Thermostat.Disable.09AC01AC31180349" to the "options" array.

Things to try with Siri

Donate to Support homebridge-nest

homebridge-nest is a labour of love. It's provided under the ISC licence and is completely free to do whatever you want with. But if you'd like to show your appreciation for its continued development, please consider clicking here to make a small donation or, even better, send me a thank-you card:

Adrian Cable
PO Box 370365
Montara, CA 94037

I appreciate your feedback and support in whatever form!