EcoAdaptor for Nest

Background

A Customer Application can interact with the Arrayent Connect Cloud and the Arrayent EcoAdaptor for Nest via an Application SDK (for iOS or Android) or by accessing Arrayent’s Web APIs directly. Application Developers should be familiar with how to read and write attributes from the Arrayent Connect Cloud and be familiar with the Arrayent Alert Engine. For an overview of the Arrayent Web APIs, please see the online documentation Web Service API Reference. For a general overview of Arrayent Cloud Alerts, read the Alerts Guide. Arrayent Cloud Alerts consists of a set of triggers defined for a device that will cause an action if a certain attribute value meets a specific criteria. For example, a trigger can be defined such that if the attribute representing the Nest structure home/away status is equal to ‘home’, then the Arrayent Cloud Alert can send an attribute update to the Arrayent Device associated to the same user account. This attribute update can command the Arrayent Device to perform some action based on the change in the Home/Away status.

Assumptions

This document assumes the following:

1. Developer is familiar with the Arrayent API.
2. Developer is familiar with the Nest data model. (See Nest data model <https://developer.nest.com/documentation/api-reference).

Prerequisites

Nest Structures Overview

A Nest User Account may have at most two structures defined. A Nest Structure is synonymous to a user’s home. Therefore a user may have at most two ‘homes’ defined, typically a primary residence and a vacation residence. Nest Devices (Thermostats, Protects, etc) are associated with a particular structure. This is logical since a Thermostat or Protect is physically located in just one of the two possible user homes. Arrayent’s Nest User Account Data Model represents all possible Nest Structure that a user may have. If a Nest Structure is not in use, then the attribute value associated with that Nest Structure is left blank. The attribute names in the Arrayent Data Model for a Nest Structure looks like the following example:

d.structures[1].a.away
d.structures[2].a.away

The above example illustrates the two possible structures a user may have. Each one of the attributes may have a value indicating the Home/Away state for the structure. Arrayent applies an index to the attribute name to differentiate between the two structure attributes. d.structures[1].a.away represents the Home/Away status of structure 1, and d.structures[2].a.away represents the Home/Away status of structure 2. But index values 1 and 2 are arbitrary Arrayent-assigned indexes. To obtain a mapping of the Arrayent-assigned Nest Structure Index to the Nest Structure Identifier, call the GET largestrings API on the EcoAdaptor. The largestrings API takes two parameters, an Arrayent user security token and the id of the Nest Virtual device on the Arrayent’s user account. Sample largestrings API:

https://example.arrayent.com:8081/ecoadaptors/largestrings?secToken=1234-abcd&id=5678

Return value:

{
  "labels": {
    "Albert's Office": "yv0MKPfnpbP8WP2EGPKpviGr4xJyd3rzagYV6niscawAM3TeEjSdpw",
    "Albert's Home": "O3RvyQDBopx4Tx7qToKHsMyF5jwZ9AnJ06qydu2e5XKc86c-h6hkMA"
  },
  "identifiers": {
    "yv0MKPfnpbP8WP2EGPKpviGr4xJyd3rzagYV6niscawAM3TeEjSdpw": [
      "1"
    ],
    "ivbUNOPk-JbavyqnfjgvNeMx2Nrb3s7F": [
      "1",
      "thermostats",
      "Bedroom (FF64)",
      "yv0MKPfnpbP8WP2EGPKpviGr4xJyd3rzagYV6niscawAM3TeEjSdpw"
    ],
    "O3RvyQDBopx4Tx7qToKHsMyF5jwZ9AnJ06qydu2e5XKc86c-h6hkMA": [
      "2"
    ],
    "ivbUNOPk-JYV-F1lJya3FeMx2Nrb3s7F": [
      "1",
      "thermostats",
      "Basement (C84B)",
      "O3RvyQDBopx4Tx7qToKHsMyF5jwZ9AnJ06qydu2e5XKc86c-h6hkMA"
    ]
  }
}

The largestrings API returns a JSON mapping of Nest IDs to Arrayent Index values. The “labels” tag will provide a mapping between the Nest Structure Friendly Names and the Nest Structure IDs. The “identifiers” tags will then provide a mapping between the Nest Structure IDs and the Arrayent Index IDs used in the Arrayent Nest User Data Model attribute names.

Nest Devices Overview

Each Nest Structure may contain up to 20 Nest Thermostats and 18 Nest Protects. Arrayent’s Nest User Account Data Model represents all possible Nest Devices that a user may have within each Nest Structure. If a Nest Device is not populated in the Nest Structure, then the attribute value associated with that Nest Device is left blank. The attribute names in the Arrayent Data Model for a Nest Device looks like the following example:

d.structures[1].d.smokeCoAlarms[1].co_alarm_state
d.structures[1].d.thermostats[2].has_fan

The first example, d.structures[1].d.smokeCoAlarms[1].co_alarm_state, represents the Carbon Monoxide alarm state for the first Nest Protect in Nest Structure 1. The second example, d.structures[1].d.thermostats[2].has_fan, represents the presence of a fan in the second Nest Thermostat in Nest Structure 1. To obtain a mapping between the Arrayent device index used in the attribute names and the Nest Device IDs, use the GET largestrings EcoAdaptor API.

Arrayent Nest Device Attribute Overview

The following table describes the set of Arrayent Attributes representing the overall status of a Nest User account. The attribute names uses the variable X, where X represents the Nest Structure index used by Arrayent (1 or 2).

The following table describes the set of Arrayent Attributes representing the status of an individual Nest Device in the Nest User account. The attribute names uses the variable X and Y, where X represents the Nest Structure index used by Arrayent (1 or 2) and Y represents the Nest Device index used by Arrayent (1-20 for Nest Thermostats, 1-18 for Nest Protects).

Detailed Nest Account and Arrayent Account Federation Flow

The best description of how to federate is found in https://developer.nest.com/documentation/cloud/how-to-auth A brief description of the steps required to work with Arrayent are:

1. The application redirects the end user to the Nest cloud and using the client_id obtained from Nest do a GET on the URL specified in the Authorization URL in the client page for the application. For example:

   GET https://home.nest.com/login/oauth2?client_id=XXXX&state=STATE.
   

   This will prompt the end user to enter his/her Nest credentials to authorize the application to work with Nest. A brief description of what the application will do with Nest is displayed as a reminder to the end user. If the end user authorizes the application to work with Nest, Nest cloud will respond with the redirect_URI and a temporary code in the form of:

   REDIRECT_URI?code="yyyyy"&state=STATE
   

1. The application must capture the REDIRECT and extract the “code” out of it and then submit to the Access token URL as specified in the client page for the application. For example:

   POST https://api.home.nest.com/oauth2/access_token?code=STRING&client_id=XXXX&client_secret=YYYY&grant_type=authorization_code
   

2. This will respond with something like:

   {
    "access_token": "c.FmDPkzyzaQe...",
    "expires_in": 315569260
   }
   

3. Using the value from access_token, Application must POST this value to Arrayent cloud to federate between the end user Arrayent account and the end user Nest account.
   1. If using Web APIs:

      POST https://example.arrayent.com:8081/ecoadaptors/federatedtokens?secToken=923-4987123&anEcosystemName=Nest&anAccessToken=c.FmDPkzyzaQe
      

      If successful Arrayent returns the deviceId of the Nest Virtual Device created in the Arrayent Connect Cloud to represent the Nest account. For example:

      { "DeviceId": "201338848" }
      

   2. If using Application SDK (Android/iOS) developers:
      1. First initialize Application SDK with URL for Arrayent’s Nest EcoAdapter. This URL will be provided by Arrayent. Call Arrayent Application SDK’s setEcoCloudUrl() method with Arrayent’s Nest Adapter URL. Note: In iOS this is in the AppEngine class and in Android, this is in the Arrayent class.
      2. Call Arrayent Application SDK’s updateFederatedToken() method with the Access Token obtained from Nest. See appendix for more details.
4. Obtain the Arrayent DeviceId for the Nest Account. You may have captured the Arrayent DeviceId for the Nest account in the previous step, but you may wish to obtain it again in future login sessions:
   1. Obtain the deviceId for Nest device
      1. If using Web APIs – call Arrayent getDeviceListThe getDeviceList Web API will return something list this:

         <devList>
          <devId>201338848</devId>
          <devName>Nest13724_1</devName>
          <typeId>384</typeId>
          <sleepMode>SHORT</sleepMode>
          <appID>1124</appID>
          <userID>13724</userID>
         </devList>
         

      2. If using Application SDK’s call getDevices() method to obtain the list of devices associated to user account.
   2. If the Nest User Account device is present, move on to next step.
   3. If the Nest User Account device is not present, inform user that an error occurred.
5. Customer App defines Arrayent Cloud Alerts to perform Arrayent Device actions based on changes in Nest Home/Away state.
   1. Use Arrayent APIs to create an Arrayent Alert and pass in a valid alert definition.
   2. In iOS, the AlertInfo object describes the alert definition
   3. In Android, the TriggerConfig object describes the alert definition.
   4. See appendix for more details.

Home/Away State Change Causes Device State Change

When Nest updates the Home/Away state in their cloud, the Nest Structure attribute change will show up in the Arrayent Nest Data Model. The change will show up in either attribute d.structures[1].a.away or attribute d.structures[2].a.away, depending on the Nest Structure. To have this Nest state change perform an action on a Device, define an ‘Attribute Alert’ so that the update of the Home/Away attribute in the Arrayent Nest Data Model will trigger a corresponding attribute update on the Device. For example, let’s assume we have a simple Device with attribute setled1 that accepts two possible values, 0 for off and 1 for on. In this example, we’ll want to turn the led on when Nest reports Home/Away status is ‘home’ and turn the led off when when Nest reports Home/Away status is ‘away’ or ‘auto-away’. In order to satisfy this use case, we’ll call Arrayent’s addTrigger API to define an Attribute Alert. The addTrigger takes a series of parameters that defines alerts in general. For the specific use case of interacting with the Arrayent Nest Data Model, the following parameters should be set:

Turn On Nest Fan Based On User Action

error: <errormsg>, <badvalue>, <timestamp>

error:Cannot change fan_timer_active while structure is away, true, 2015-09-18 12:51:05.917

Nest Access Tokens

Arrayent Device Attributes

Alerts

For details on the Arrayent Application SDK Alert methods, please consult the Application SDK Documentation.

For a summary of the details, please see the following online documentation for Android and for iOS. You may require credentials to access these portals, please contact your Arrayent team for access.