This Christmas, my super sweet Santa surprised me with the perfect gift: a Nest Thermostat. Not only is the Nest a beautiful piece of fine designed engineering work, it also allows people like you and me to make it even more powerful by using its extensive API. Today was the perfect day to take a small glimpse at this piece of developers candy.
To give the API a quick try, I decided to check out one of the many Node.js Nest wrappers: nest-thermostat. Although there are many alternatives, this one allowed me to get the full nest data object within seconds.
First, let’s install the necessary node.js module:
npm install nest-thermostat
Next, I create a simple script: nest.js with the followig contents:
var nest = require('nest-thermostat').init('michael@mymailadress.com', 'MyNestPassword');
nest.getInfo('MYNESTSERIALNUMBER', function(data) {
console.log(data);
});
And that’s all I need to get a the full data object back … Let’s give it a try by running: node nest.js, the following data shows up:
{
'$version': -3637,
'$timestamp': 1419695984091,
heatpump_setback_active: false,
touched_by: {},
emer_heat_enable: false,
switch_system_off: false,
local_ip: '192.168.0.116',
away_temperature_high: 24.444,
y2_type: 'unknown',
temperature_lock_high_temp: 22.222,
cooling_source: 'electric',
leaf_threshold_cool: 0,
note_codes: [],
fan_cooling_state: false,
heater_source: 'gas',
compressor_lockout_leaf: -17.8,
has_x3_heat: false,
target_humidity_enabled: false,
heat_link_sw_version: '1.1rc2',
heat_x3_source: 'gas',
alt_heat_delivery: 'forced-air',
fan_mode: 'auto',
has_x2_heat: false,
sunlight_correction_active: false,
rssi: 71,
emer_heat_delivery: 'forced-air',
pin_y2_description: 'none',
heatpump_savings: 'off',
humidity_control_lockout_end_time: 0,
filter_reminder_level: 0,
filter_reminder_enabled: false,
capability_level: 4.31,
schedule_learning_reset: false,
has_x2_cool: false,
ob_orientation: 'O',
hvac_pins: 'W1,C,Rh',
cooling_delivery: 'unknown',
range_enable: false,
dual_fuel_breakpoint_override: 'none',
auto_away_enable: true,
lower_safety_temp_enabled: true,
has_fan: false,
dehumidifier_state: false,
nlclient_state: '',
emer_heat_source: 'electric',
heatpump_ready: false,
cooling_x2_delivery: 'unknown',
available_locales: 'en_US,fr_CA,es_US,en_GB,fr_FR,nl_NL',
current_version: '4.3.3',
learning_state: 'initial',
has_fossil_fuel: true,
pin_rh_description: 'power',
pin_ob_description: 'none',
safety_temp_activating_hvac: false,
has_alt_heat: false,
fan_duty_cycle: 3600,
pin_y1_description: 'none',
humidifier_state: false,
gear_threshold_high: 0,
backplate_serial_number: 'XXXXXXXXXXXX',
has_x2_alt_heat: false,
leaf_threshold_heat: 19.89,
heat_x3_delivery: 'in-floor-radiant',
is_on_stand: true,
learning_mode: true,
has_emer_heat: false,
has_aux_heat: false,
aux_heat_source: 'electric',
filter_changed_set_date: 0,
backplate_bsl_info: 'BSL',
sunlight_correction_ready: false,
alt_heat_x2_source: 'gas',
pin_c_description: 'power',
humidifier_type: 'unknown',
pin_w2aux_description: 'none',
humidity_control_lockout_start_time: 0,
sunlight_correction_enabled: true,
country_code: 'NL',
fan_timer_timeout: 0,
target_humidity: 35,
heat_x2_delivery: 'in-floor-radiant',
gear_threshold_low: 0,
lower_safety_temp: 4.444,
heat_link_serial_number: 'XXXXXXXXXXXXX',
last_software_update_utc_secs: 1419542717,
cooling_x2_source: 'electric',
equipment_type: 'electric',
heat_pump_aux_threshold: 10,
alt_heat_x2_delivery: 'forced-air',
heat_pump_comp_threshold: -31.5,
learning_days_completed_cool: 0,
backplate_bsl_version: '2.1',
current_schedule_mode: 'HEAT',
hvac_wires: 'Heat,Common Wire,Rh',
fan_duty_end_time: 0,
leaf: false,
type: 'TBD',
pin_g_description: 'none',
click_sound: 'on',
aux_heat_delivery: 'forced-air',
away_temperature_low_enabled: true,
filter_changed_date: 0,
hvac_safety_shutoff_active: false,
heat_pump_comp_threshold_enabled: false,
preconditioning_ready: true,
has_dehumidifier: false,
heat_link_model: 'Amber-1.5',
fan_cooling_enabled: true,
leaf_away_high: 28.88,
fan_cooling_readiness: 'not ready',
temperature_scale: 'C',
device_locale: 'nl_NL',
preconditioning_active: false,
maint_band_upper: 0.168,
error_code: '',
battery_level: 3.87,
fan_control_state: false,
away_temperature_high_enabled: false,
learning_days_completed_heat: 2,
upper_safety_temp_enabled: false,
pin_star_description: 'none',
preconditioning_enabled: false,
dual_fuel_breakpoint: -1,
current_humidity: 34,
postal_code: '1234AB',
alt_heat_source: 'gas',
backplate_mono_version: '1.0.23',
aux_lockout_leaf: 10,
has_heat_pump: false,
heater_delivery: 'in-floor-radiant',
radiant_control_enabled: true,
auto_away_reset: false,
away_temperature_low: 16,
temperature_lock: false,
has_air_filter: false,
upper_safety_temp: 35,
time_to_target_training: 'training',
dehumidifier_type: 'unknown',
humidity_control_lockout_enabled: false,
target_time_confidence: 0,
fan_timer_duration: 900,
where_id: '00000000-0000-0000-0000-00010000000c',
temperature_lock_low_temp: 20,
pin_w1_description: 'heat',
forced_air: false,
temperature_lock_pin_hash: '',
auto_dehum_enabled: false,
backplate_mono_info: 'TFE (AMBER_BP) 1.0.23 (root@bamboo) 2014-02-03 12:39:22',
star_type: 'unknown',
has_dual_fuel: false,
maint_band_lower: 0.39,
learning_time: 1561,
creation_time: 1419502492178,
has_humidifier: false,
learning_days_completed_range: 0,
dehumidifier_orientation_selected: 'unknown',
leaf_schedule_delta: 1.11,
logging_priority: 'informational',
user_brightness: 'medium',
leaf_away_low: 16.138,
pin_rc_description: 'none',
serial_number: 'XXXXXXXXXXXXXX',
auto_dehum_state: false,
mac_address: 'XXXXXXXXXXX',
heat_x2_source: 'gas',
fan_duty_start_time: 0,
time_to_target: 0,
backplate_model: 'Backplate-3.2',
heat_link_connection: 3,
model_version: 'Display-2.12',
heat_pump_aux_threshold_enabled: true,
ob_persistence: true,
schedules: [],
auto_away: 0,
auto_away_learning: 'training',
hvac_heat_x3_state: false,
compressor_lockout_enabled: false,
hvac_alt_heat_state: false,
target_temperature_type: 'heat',
hvac_heater_state: false,
hvac_emer_heat_state: false,
can_heat: true,
compressor_lockout_timeout: 0,
hvac_cool_x2_state: false,
target_temperature_high: 24,
hvac_aux_heater_state: false,
hvac_heat_x2_state: false,
target_temperature_low: 20,
hvac_ac_state: false,
target_temperature: 20.5,
hvac_fan_state: false,
target_change_pending: false,
name: '',
current_temperature: 20.5,
hvac_alt_heat_x2_state: false,
can_cool: false
}
How about usefull information?
Of course, not all of this is interesting for us, so let’s change our script a bit:
var nest = require('nest-thermostat').init('michael@mymailadress.com', 'MyNestPassword');
nest.getInfo('MYNESTSERIALNUMBER', function(data) {
console.log('Current temperature: ' + data.current_temperature + ' °C');
console.log('Target temperature: ' + data.target_temperature + ' °C');
console.log('Current humidity: ' + data. current_humidity + '%');
});
This gives a more usable result:
Current temperature: 20.44 °C
Target temperature: 20.5 °C
Current humidity: 34%
Which tells me: I should do something about the humidity in my house! If I’m correct, a healthy environment should be somewhere between 40% and 60%.
Anyway, the experiment above shows me how easy it is, to read out the Nest. I think I’ll add the data above to my Magic Mirror.
A bit of … (wait for it) … criticism
Although I like the power of the Nest API, I have one a critical remark: The API is SLOW! I measured the response time of above API-call and it turned out the average response time was around 2 seconds. The reason behind this, is because the Node script doesn’t communicate with the Nest Thermostat directly, but retrieves the data from the Nest servers, where the data is cached.
I my opinion, the approach of my Philips Hue bridge is better: it has a built-in webserver which has it’s own REST API. This way, you stay on your local network (lowering the response times), and you always get the most recent data.
This is probably the same reason why the official Nest App is slow as well. I understand that this solves the issue of local networks that are inaccessible from the outside. But there are better ways to solve this …
Anyway, if you have any fun suggestions on what to built with this API, let me know in the comments down below!
Thank you, Santa! For this perfect gift! :) <3