Dr. Scott M. Baker

Programming

A python API for the Nest Learning Thermostat

by admin on May.12, 2012, under Programming

I installed one of the nest Nest Thermostats (http://www.nest.com) not so long ago, but there are several things I wanted to automate. In particular, I wanted to be able to schedule the fan to turn on and off periodically to circulate the air in my house. The nest doesn’t have a way to do this, but it does have a WEB interface, so I figured… how hard could it be to interact with the nest?

The Nest and My Hand

Well, turns out it was a little harder than I thought. My initial attempts at peeking at what the Web browser app was doing yielded some insights into the protocol, but not enough. Trying to snoop in the protocol by diverting it through a proxy didn’t work for me (it kept giving network errors when doing this from my iPad). I started looking around the web and came across a few other projects. One was a .net API written by Aaron at WiredPrarie (http://www.wiredprairie.us/blog/index.php/archives/1449). The other was a Siri plugin written in Ruby by Chris Burris (https://github.com/chilitechno/SiriProxy-NestLearningThermostat). Unfortunately neither one did what I needed. The .net API was read only, and the Ruby API lacked anything to do with fan control.

However, Chris’ code was enough to get me poking around the data structures in and short order I had managed to figure out enough of the API to turn the fan on and off (well “on” and “auto” to be more precise). I also added the ability to query status, and the ability to set the target temperature.

The code is hosted on githut at http://github.com/smbaker/pynest. For those unfamiliar with git, you should be able to download the whole package in a ZIP http//github.com/smbaker/pynest/zipball/master.

Let’s look at a sample session:

$ nest.py help
syntax: nest [options] command [command_args]
options:
   --user       ... username on nest.com
   --password
  ... password on nest.com
   --celsius              ... use celsius (the default is farenheit)

commands: temp, fan, show, curtemp, curhumid
    temp     ... set target temperature
    fan [auto|on]         ... set fan state
    show                  ... show everything
    curtemp               ... print current temperature
    curhumid              ... print current humidity

examples:
    nest.py --user joe@user.com --password swordfish temp 73
    nest.py --user joe@user.com --password swordfish fan auto

$ nest.py --user joe@user.com --password swordfish temp 72

$ nest.py --user joe@user.com --password swordfish show
$timestamp......................: 1336793938000
$version........................: -27052532
auto_away.......................: 0
auto_away_enable................: True
auto_away_learning..............: ready
auto_away_reset.................: False
away_temperature_high...........: 24.44444
away_temperature_high_enabled...: False
away_temperature_low............: 10.0
away_temperature_low_enabled....: True
backplate_bsl_info..............: BSL
backplate_bsl_version...........: 1.1
backplate_model.................: Backplate-1.9
backplate_mono_info.............: TFE (BP_DVT) 3.7.3 (ehs@ubuntu) 2012-03-07 10:43:21
backplate_mono_version..........: 3.7.3
backplate_serial_number.........: [redacted]
battery_level...................: 3.864
can_cool........................: True
can_heat........................: True
capability_level................: 2.0
click_sound.....................: on
compressor_lockout_enabled......: False
compressor_lockout_timeout......: 0
creation_time...................: 1332733610873
current_humidity................: 38
current_schedule_mode...........: COOL
current_temperature.............: 20.81
current_version.................: 2.0
equipment_type..................: electric
fan_cooling_readiness...........: ready
fan_cooling_state...............: False
fan_mode........................: auto
forced_air......................: True
has_aux_heat....................: True
has_fan.........................: True
has_heat_pump...................: True
has_x2_heat.....................: False
heat_pump_aux_threshold.........: 4.444443
heat_pump_aux_threshold_enabled.: True
heat_pump_comp_threshold........: -31.5
heat_pump_comp_threshold_enabled: False
hvac_ac_state...................: False
hvac_aux_heater_state...........: False
hvac_fan_state..................: False
hvac_heat_x2_state..............: False
hvac_heater_state...............: False
hvac_pins.......................: Y1,C,Rh,G,OB,Aux
hvac_wires......................: Cool,Fan,Heat Pump OB Shorted,Heat Pump Auxiliary Heat,Common Wire,Rh
leaf............................: False
leaf_away_high..................: 25.109894
leaf_away_low...................: 16.669998
leaf_learning...................: ready
leaf_schedule_delta.............: 1.109985
leaf_threshold_cool.............: 25.109985
leaf_threshold_heat.............: 1000.0
learning_days_completed_cool....: 0
learning_days_completed_heat....: 18
learning_days_completed_range...: 0
learning_mode...................: False
learning_state..................: initial
learning_time...................: 1745
local_ip........................: [like my local IP would have been useful to you?]
lower_safety_temp...............: 7.0
lower_safety_temp_enabled.......: True
mac_address.....................: [redacted]
model_version...................: Diamond-1.12
name............................: Nest
nlclient_state..................:
ob_orientation..................: O
postal_code.....................: [also redacted]
range_enable....................: True
rssi............................: 75.0
schedule_learning_reset.........: False
serial_number...................: [yes, I removed even this from your prying eyes]
switch_preconditioning_control..: False
switch_system_off...............: False
target_change_pending...........: False
target_temperature..............: 21.02611
target_temperature_high.........: 26.66663
target_temperature_low..........: 16.66663
target_temperature_type.........: cool
target_time_confidence..........: 0.0
temperature_lock................: False
temperature_scale...............: F
time_to_target..................: 0
time_to_target_training.........: training
type............................: TBD
upper_safety_temp...............: 35.0
upper_safety_temp_enabled.......: False
user_brightness.................: medium

Now, back to the task at hand. I want my nest to switch it’s fan state to “on” at 11am, and switch it back to “auto” at 7pm. At least that’s a good enough start, perhaps later we can do something fancier, like running it hourly to recirculate the air. This should be as simple as setting up a cron job:

$ crontab -e
0 11 * * * /usr/bin/nest.py --user joe@user.com --password swordfish fan on >/dev/null 2>&1
0 19 * * * /usr/bin/nest.py --user joe@user.com --password swordfish fan auto >/dev/null 2>&1

The above cron entries will turn the fan on at 11:00 every day and back to auto at 19:00 every day.

34 Comments more...

Looking for something?

Use the form below to search the site:

Still not finding what you're looking for? Drop a comment on a post or contact us so we can take care of it!

New Kickstarter Project!

Interested in Nixie Tube projects? Check out my new Nixie Tube Calculator project on Kickstarter.

Copyright Notice

All content on this website is copyright Scott M. Baker and may not be used or reprinted without explicit permission.

Violators will be eaten by a grue.