Python API and command line tool for the Nest™ Thermostat

Installation

[sudo] pip install python-nest

Usage

Module

You can import the module as nest.

importnestusername='joe@user.com'password='swordfish'napi=nest.Nest(username, password)
forstructureinnapi.structures:
print'Structure %s'%structure.nameprint' Away: %s'%structure.awayprint' Devices:'fordeviceinstructure.devices:
print' Device: %s'%device.nameprint' Temp: %0.1f'%device.temperature# Access advanced structure properties:forstructureinnapi.structures:
print'Structure : %s'%structure.nameprint' Postal Code : %s'%structure.postal_codeprint' Country : %s'%structure.country_codeprint' dr_reminder_enabled : %s'%structure.dr_reminder_enabledprint' emergency_contact_description : %s'%structure.emergency_contact_descriptionprint' emergency_contact_type : %s'%structure.emergency_contact_typeprint' emergency_contact_phone : %s'%structure.emergency_contact_phoneprint' enhanced_auto_away_enabled : %s'%structure.enhanced_auto_away_enabledprint' eta_preconditioning_active : %s'%structure.eta_preconditioning_activeprint' house_type : %s'%structure.house_typeprint' hvac_safety_shutoff_enabled : %s'%structure.hvac_safety_shutoff_enabledprint' num_thermostats : %s'%structure.num_thermostatsprint' measurement_scale : %s'%structure.measurement_scaleprint' renovation_date : %s'%structure.renovation_dateprint' structure_area : %s'%structure.structure_area# Access advanced device properties:fordeviceinstructure.devices:
print' Device: %s'%device.nameprint' Where: %s'%device.whereprint' Mode : %s'%device.modeprint' Fan : %s'%device.fanprint' Temp : %0.1fC'%device.temperatureprint' Humidity : %0.1f%%'%device.humidityprint' Target : %0.1fC'%device.targetprint' Away Heat: %0.1fC'%device.away_temperature[0]
print' Away Cool: %0.1fC'%device.away_temperature[1]
print' Eco : %s'%device.ecoprint' hvac_ac_state : %s'%device.hvac_ac_stateprint' hvac_cool_x2_state : %s'%device.hvac_cool_x2_stateprint' hvac_heater_state : %s'%device.hvac_heater_stateprint' hvac_aux_heater_state : %s'%device.hvac_aux_heater_stateprint' hvac_heat_x2_state : %s'%device.hvac_heat_x2_stateprint' hvac_heat_x3_state : %s'%device.hvac_heat_x3_stateprint' hvac_alt_heat_state : %s'%device.hvac_alt_heat_stateprint' hvac_alt_heat_x2_state: %s'%device.hvac_alt_heat_x2_stateprint' hvac_emer_heat_state : %s'%device.hvac_emer_heat_stateprint' online : %s'%device.onlineprint' last_ip : %s'%device.last_ipprint' local_ip : %s'%device.local_ipprint' last_connection : %s'%device.last_connectionprint' error_code : %s'%device.error_codeprint' battery_level : %s'%device.battery_level# The Nest object can also be used as a context managerwithnest.Nest(username, password) asnapi:
fordeviceinnapi.devices:
device.temperature=23# Weather data is also available under structure or device# The api is the same from eitherstructure=napi.structures[0]
time_str=structure.weather.current.datetime.strftime('%Y-%m-%d %H:%M:%S')
print'Current Weather at %s:'%time_strprint' Condition: %s'%structure.weather.current.conditionprint' Temperature: %s'%structure.weather.current.temperatureprint' Humidity: %s'%structure.weather.current.humidityprint' Wind Dir: %s'%structure.weather.current.wind.directionprint' Wind Azimuth: %s'%structure.weather.current.wind.azimuthprint' Wind Speed: %s'%structure.weather.current.wind.kph# NOTE: Hourly forecasts do not contain a "contidion" its value is `None`# Wind Speed is likwise `None` as its generally not reportedprint'Hourly Forcast:'forfinstructure.weather.hourly:
print' %s:'%f.datetime.strftime('%Y-%m-%d %H:%M:%S')
print' Temperature: %s'%f.temperatureprint' Humidity: %s'%f.humidityprint' Wind Dir: %s'%f.wind.directionprint' Wind Azimuth: %s'%f.wind.azimuth# NOTE: Daily forecasts temperature is a tuple of (low, high)print'Daily Forcast:'forfinstructure.weather.daily:
print' %s:'%f.datetime.strftime('%Y-%m-%d %H:%M:%S')
print' Condition: %s'%structure.weather.current.conditionprint' Low: %s'%f.temperature[0]
print' High: %s'%f.temperature[1]
print' Humidity: %s'%f.humidityprint' Wind Dir: %s'%f.wind.directionprint' Wind Azimuth: %s'%f.wind.azimuthprint' Wind Speed: %s'%structure.weather.current.wind.kph# NOTE: By default all datetime objects are timezone unaware (UTC)# By passing `local_time=True` to the `Nest` object datetime objects# will be converted to the timezone reported by nest. If the `pytz`# module is installed those timezone objects are used, else one is# synthesized from the nest datanapi=nest.Nest(username, password, local_time=True)
printnapi.structures[0].weather.current.datetime.tzinfo

In the API all temperature values are in degrees celsius. Helper functions for conversion are in the utils module:

fromnestimportutilsasnest_utilstemp=23.5fahrenheit=nest_utils.c_to_f(temp)
temp==nest_utils.f_to_c(fahrenheit)

The utils function use decimal.Decimal to ensure precision.

For "advanced" usage such as token caching, use the source, luke!

Command line

usage: nest [-h] [--conf FILE] [--token-cache TOKEN_CACHE_FILE] [-t TOKEN]
[-u USER] [-p PASSWORD] [-c] [-s SERIAL] [-i INDEX]
{temp,fan,mode,away,target,humid,target_hum,show} ...
Command line interface to Nest™ Thermostats
positional arguments:
{temp,fan,mode,away,target,humid,target_hum,show}
commandhelp
temp show/set temperature
fan set fan "on" or "auto"
mode show/set current mode
away show/set current away status
target show current temp target
humid show current humidity
target_hum show/set target humidity
specify target humidity value or auto to auto-select a
humidity based on outside temp
show show everything
optional arguments:
-h, --help show this help message and exit
--conf FILE config file (default ~/.config/nest/config)
--token-cache TOKEN_CACHE_FILE
auth access token
-t TOKEN, --token TOKEN
auth access token cache file
-u USER, --user USER username for nest.com
-p PASSWORD, --password PASSWORD
password for nest.com
-c, --celsius use celsius instead of farenheit
-s SERIAL, --serial SERIAL
optional, specify serial number of nest thermostat to
talk to
-i INDEX, --index INDEX
optional, specify index number of nest to talk to
examples:
# If your nest is not in range mode
nest --user joe@user.com --password swordfish temp 73
# If your nest is in range mode
nest --user joe@user.com --password swordfish temp 66 73
nest --user joe@user.com --password swordfish fan --auto
nest --user joe@user.com --password swordfish target_hum 35

A configuration file can also be specified to prevent username/password repitition.

[DEFAULT]user = joe@user.com
password = swordfish
token_cache = ~/.config/nest/cache

The [DEFAULT] section may also be named [nest] for convience.

History

This module was originally a fork of nest_thermostat <https://github.com/FiloSottile/nest_thermostat> which was a fork of pynest <https://github.com/smbaker/pynest