nest-observe

Unofficial API for observing Google Nest devices which works with Google authentication

It provides a simple interface to create an event emitter which will stream updates whenever a device in your home changes.

About

This repository contains a proof-of-concept library that uses the https://home.nest.com grpc-web API to observe Nest devices. This is the same API that is used on the app homepage, which comes with a few of benefits:

Access to data using a Google authenticated account (Nest API access was recently removed for migrated accounts)
Access to data from the EU/UK version of the Nest Thermostat E, which is unavailable through the official API

This library was created by examining the https://home.nest.com source code to retrieve protobuf specs for the publically exposed GatewayService used by the app. The library pretends to be a client on the web app to access the api. I have used it here solely for the Observe rpc call, which is a streaming endpoint that pushes new states of devices in your home to the client, other endpoints exist on the service which may allow for updating the state of the home, however this is yet to be explored (feel free to open a PR!).

The endpoint returns a list of 'traits' for each device in the home. This includes information such as current temperature, current humidity, room names, device names, target temperatures, eco modes and more.

Caveats about this library:

This has only been tested in a home using EU/UK versions of the Nest Thermostat E and Heat Link E. While it has been shown to provide access to this data, it would be good to confirm what other devices work with this.
Not all of the trait protobuf specs have been implemented. Please feel free to open am issue/PR to add them, or contact me about my method of extracting the protobuf specs from the source code.

There is still a lot of opportunity for this method of accessing your nest data - please feel free to contribute!

Installation

npm install nest-observe

Usage

Authentication is done using the method outlined by the homebridge-nest library to retrieve the values for issueToken, cookie and apikey. Thankfully you will only need to do this once (note that the other authentication methods on that page are currently unsupported): https://github.com/chrisjshull/homebridge-nest#using-a-google-account

const { authGoogle, observe } = require('nest-observe');

// Use auth details to get JWT token. Returned object contains {token, expiry, refresh}
// where refresh is a function to get a new token object
const token = await authGoogle(issueToken, cookie, apikey);

// Create the observer. Can also be done using promises
const observer = await observe(token.token, {
    protobuf: false, // set true to return protobuf object as value
    debug: false // set true to log a lot more
});

// Event emitted for new updates which include only the new values
observer.on('data', state => {
    console.log('New state:', state);
});

// Event emitted when the streaming is stopped 
observer.on('end', () => {
    console.log('Streaming ended');
});

For each data event, the state is an object which contains mappings of DEVICE/STRUCTURE to values. An example of the state:

{
  "DEVICE_XXXX": {
     "traits": [
       { 
         // Name of the protobuf trait type
         "type": "nest.trait.sensor.TemperatureTrait",

         // Label provided by observe endpoint
         "label": "temperature",

         // Value of the trait (spec is defined in the .proto files)
         "value": {
            "temperatureValue": {
               "temperature": {
                  "value": 19.8700008392334
               }
            }
         }
       },
        // ...  
     ],

     // List of traits which have no corresponding protobuf spec yet
     "ignored": [
       {
          // Name of the protobuf trait type
          "type": "nest.trait.hvac.UtilitySettingsTrait",

          // Base64 encoded message
          "value": "CAEQARgB"
       },
       // ...
     ],
    },
    // more devices and structures...
}

Feedback

There is a lot more we could do with this library and it is still very young and buggy. Please feel free to contribute or contact me!

Acknowledgement

Thanks to https://github.com/chrisjshull/homebridge-nest for the method of authenticating to Google.

Humpheh / nest-observe

readme