RTI works with Nest Driver

This driver controls and monitors Nest Learning Thermostats™ and Nest Protect™ Smoke + CO Detectors over the internet. An internet connection is required for the driver to work. It also monitors the Home vs Away status of the two structures listed in the account

Revision History
1.0 The initial release of the driver
1.01 Keeps high and low target temps separate, adds gray UI color to Protects, won't send temp changes when stat is off, adds a 'Offline' variable (there was already an event) to stats, adds a configurable timer to hide error messages
1.1 Supports 1.1 of the Nest API: Adds humidity display and notification of Protect manual tests. Changing to this new verison will invalidate the drivers authorization and you will have to reauthorize the driver. See the end of this note for deauthorization instructions
1.2 Adds variables and events for thermostat state (heating/cooling) to the driver. The updated API contains additional changes to the authentications system so that while you will have to reauthorize the driver this time, you should not have to do that for any future changes. The new system allows simple permission granting through the Nest app and only requires it to enable the specific changes in an API update.
1.21 Fixes an issue parsing the new HVAC state variable.
1.22 Fixes an issue using selected variables that can keep the driver from connecting.
1.23 Fixes a problem where after a mode switch the driver would send an extra empty command causing an error message to be displayed
1.24 Fixes a connectivity problem
1.3 Fixes a rate limit issue caused by a Nest upgrade
1.31 Raises the number of allowed thermostats to 40

Configuration

The names of the Structures, as well as the names of the devices to be monitored are entered into the configuration. The current version of the driver requires that devices have unique names, even if located in different structures. In the setup of the Nest devices there is an option to add a label as part of the naming process. This will help keep names unique, as adding a label changes the name of the device as seen by the driver. If you add a label to the Thermostat or Protect it becomes part of the name of device. You must enter the name as it is shown in the app or on the web interface: statName (label)

As the name is the only identifying information returned by the API, changing the name of a Nest device will prevent it from updating the driver or receiving commands.

Authorization (You’re going to want to see the sample file)

The driver cannot access the users account information without authorization. If it is not authorized it will set the "Show Authorization Instructions" flag. This can be used either to pop up the authorization system, or to show a button that allows the user to change to a page that contains all the buttons required to authorize the driver.

Basically the user should go to the web page at http://rticorp.com/nest and follow the instructions to allow the driver to access their thermostats and Protect devices. They will receive a PIN number that needs to be typed in using the keyboard commands in the driver. The PIN number is not case-sensitive.

You will need a keyboard interface in your file somewhere in order to authenticate. The sample file does this on the larger interface but on the phones it simply pops up a message to use the tablets or in-walls to do the authentication.

Rate Limiting of the Driver

(Nest Servers and Internet Control)

This driver does not talk to the devices in the home, it talks to Nest servers. Nest limits the amount of access an ‘app’ can have in an hour so the driver cannot poll and cannot continuously send update commands as the user sweeps the dial. All commands update the variables immediately, but the driver holds onto the commands until no controls have been triggered for 5 seconds and then sends them all at once to the thermostat. You will see this as you adjust the thermostat, adjustments you make in the driver do not actually make it to the thermostat until you stop.

It is definitely possible, by doing repeated changes every 6 seconds, to use up the bandwidth for an account and not be able to make any more changes until enough time goes by to reduce the effective request rate. This is possible, but would be very unusual given the actual frequency of use of most thermostats. If it happens there are two variables, the Error Flag and the Error Text that will both be set. The error text will read 'Too many requests'

Nothing can be done except to wait. The next request that succeeds will clear the flags. The driver will not check to clear it on it's own to avoid just continuing to trigger the rate limit.

Structures

Each Nest account can access devices in two different locations, or 'Structures', as Nest calls them. Each Structure individually keeps track of an Away state which can be either Home, Auto-Away, or Away.

Commands allow you to set the state of the structures and variables exists, both as text and as booleans for the different states of the structures. Nest design guidelines state that you should have a confirmation dialog before any command that changes the state of a structure and the sample files do that. There is an extra state variable available in the driver called Not Home which is true when either Away OR Auto-away are true.

Thermostats
Thermostats have controls for mode (cool, heat, heat-cool, and off) that have matching variables, an overall text based and booleans for each mode. The set points can either be set directly or incremented/decremented. Because the Celsius scale allows you to move set points by half degrees and the math is different, there is a separate set of commands for using Celsius. Version 1.1 of the driver added the ability to read humidity, although the Nest has no controls for humidity.

The Nest API does not provide information on the demand state of the thermostat, it does not tell you whether it is calling for heat or a/c (Driver version 1.2 adds this feature)

Fan Control

The fan cannot be directly controlled but the fan timer can be started and stopped and the driver will show how much time is left to run. The length of the timer is set in the individual thermostat setting in the Nest app so the driver doesn’t immediately know how long the timer will run. It will show the timer as active immediately but the time remaining variable can take 5 to 10 seconds to fill in.

Selected Thermostat
The driver allows for direct control of each thermostat, or if there are several thermostats in the project you can select a thermostat, either directly or from a 2 way list, and then direct all the commands on a page to that thermostat. There is also a set of variables that will change as different thermostats are selected. The sample file uses the selected thermostat extensively. A ‘selected’ thermostat is only the selected thermostat for the device it is selected on. You can even create an interface, duplicate it, and they’ll each get their own version of the selected variable.

Nest Protect Smoke + CO Detectors
Nest Protect devices have no commands, only variables (and events). They have variables for the individual states of the detectors and the overall protector UI color (green, yellow, red) of each Protect. There are also variables for the system-wide UI color.

If there are Protects associated with the Nest account that are not in the file they will still contribute to the global UI state. If an unconfigured Protect goes red the global state will be red, even if the UI shows that all the configured devices are green.

Permission upgrades after driver upgrades
If the new features added to the driver require new information from the Nest Server the Nest app will notify the customer that they need to upgrade the permissions for the RTI app. The new information will not be sent to the driver until that happens

Templates
The Driver uses the following templates:

Thermostat: Nest, Climate
Nest Protect: Nest Protect, Smoke Detector

Nest®, Nest Learning Thermostat™ and the Works with Nest logos are trademarks licensed by Nest Labs, Inc.