| Nest.pm |
This module allows MisterHouse to communicate with the public Nest API which currently allows interation with Nest Thermostats and Smoke/CO Detectors.
Nest uses OAuth technology to authorize access to your account. The nice thing is that at any point in the future, you can sign into your Nest account and revoke any access tokens that you have issued.
To start the authorization process, go to the following URL:
https://misterhouse-nest.appspot.com/
Read everything on that page and follow the instructions. At the end of the process, the webpage will provide you with a line to add to your mh.private.ini file. It will be a long line! Copy the entire line and place it in your mh.private.ini file:
Nest_auth_token=<API token from Nest registration>Create a Nest instance in the .mht file, or in user code:
.mht file:
CODE, require Nest; #noloop
CODE, $nest = new Nest_Interface(); #noloop
CODE, $myhouse = new Group(); #noloop
CODE, $nest_thermo = new Nest_Thermostat('Entryway', $nest, 'f'); #noloop
CODE, $nest_thermo_mode = new Nest_Thermo_Mode($nest_thermo); #noloop
CODE, $nest_alarm = new Nest_Smoke_CO_Alarm('Kitchen', $nest); #noloop
CODE, $nest_home = new Nest_Structure('Home', $nest); #noloop
CODE, $myhouse->add($nest_thermo, $nest_thermo_mode, $nest_alarm, $nest_home); #noloopExplanations of the parameters is contained below in the documentation for each module.
Because this module uses the public Nest API, it should provide stable support for a long time. However, by relying on the public API, this module is also limited to supplying only the features currently supported by Nest. Currently some features which are present on the device and the Nest website, such as humidity, are not yet available in the API and as a result are not specifically supported by this module.
The low level commands in this module were written with the exepectation of future additions to the public Nest API. The code should permit advanced users to interact with any future additions to the API without requiring an update to this module.
This module is broken down into a few parts:
This handles the interaction between the Nest API servers and MisterHouse. This is the object that is required. An advanced user could interact with the Nest API solely through this object.
This provides a generic base for building objects that receive data from the interface. This object is inherited by all parent and child objects and in most cases, a user will not need to worry about this object.
These currently include Nest_Smoke_CO_Alarm, Nest_Thermostat, and Nest_Structure. This classes provide more specific support for each of the current Nest type of objects. These objects provide all of the access needed to interact with each of the devices in a user friendly way.
Currently these are named Nest_Thermo_.... These are very specific objects that provide very specific support for individual features on the Nest Thermostats. I have in the past commonly referred to these as child objects. In general, the state of these objects reports the state of a single parameter on the thermostat. A few of the objects also offer writable features that allow changing certain parameters on the thermostat.
This module allows MisterHouse to communicate with the public Nest API which currently allows interation with Nest Thermostats and Smoke/CO Detectors.
Nest uses OAuth technology to authorize access to your account. The nice thing is that at any point in the future, you can sign into your Nest account and revoke any access tokens that you have issued.
To start the authorization process, go to the following URL:
https://misterhouse-nest.appspot.com/
Read everything on that page and follow the instructions. At the end of the process, the webpage will provide you with a line to add to your mh.private.ini file. It will be a long line! Copy the entire line and place it in your mh.private.ini file:
Nest_auth_token=<API token from Nest registration>Create a Nest instance in the .mht file, or in user code:
.mht file:
CODE, require Nest; #noloop
CODE, $nest = new Nest_Interface(); #noloopThis handles the interaction between the Nest API servers and MisterHouse. This is the object that is required. An advanced user could interact with the Nest API solely through this object.
Nest
JSON - Used for encoding/decoding the JSON data
IO::Socket::SSL - SSL Used to establish a secure connection to Nest servers
IO::Socket::INET - Nest uses a RESTful Streaming protocol which requires a
special code setup to keep the HTTP socket constantly open.
IO::Select - Used to manage the HTTP socket
URI::URL - Used for deciphering URLs
HTTP::Response - Used for handling the responses from Nest
HTTP::Request - Used for sending requests to Nestnew($auth, $port_name, $urlCreates a new Nest Interface. The only required parameter is auth, which can also be set using the INI parameter Nest_auth_token.
port_name - defaults to Nest. If you are using multiple Nest Interfaces, I would imagine this to be very rare. Then the subsequent interfaces must have a different port name. You must also change the prefix of the auth INI parameter to match the new port name.
url - I have no idea when this would be used. But if you wanted to use a different url than what Nest provides, maybe for testing or some beta group, then you can provide the url here.
write_data($parent, $value, $data, $url)This is used to write parameters to the Nest servers.
$parent - (alternative) a reference to the parent object (thermostat,
smoke detector, structure) that this data should be written to
$value - The name of the value to write
$data - The data to be written
$url - (alternative) the full url to be written to
Either the parent or the URL must be defined. If the url is defined, it will trump the parent.
Advanced users can use this function to directly write JSON data to Nest. Otherwise it is used by the more user friendly objects.
print_devices()Prints the name and device_id of all devices found in the Nest account.
print_structures()Prints the name and device_id of all structures found in the Nest account.
register($parent, $value, $action)Used to register actions to be run if a specific JSON value changes.
$parent - The parent object on which the value should be monitored
(thermostat, smoke detector, structure)
$value - The parameter to monitor for changes
$action - A Code Reference to run when the json changes. The code reference
will be passed two arguments, the parameter name and value.This is a generic module primarily meant to be inherited by higher level more user friendly modules. The average user should just ignore this module.
Generic_Item
new($interface, $parent, $monitor_hashCreates a new Nest_Generic.
$interface - The Nest_Interface through which this device can be found.
$parent - The parent interface of this object, if not specified the
the parent will be set to Self.
$monitor_hash - A hash ref, {$value => $action}, where $value is the JSON
value that should be monitored with $action equal to the code
reference that should be run on changes. The hash ref can
contain an infinite number of key value pairs. If no action
is specified, it will use the default data_chanted routine.device_id()Returns the device_id of an object.
data_changed()The default action to be called when the JSON data has changed. In most cases we can ignore the value name and just set the state of the child to new_value. More sophisticated children can hijack this method to do more complex tasks.
set_receive()Handles setting the state of the object inside MisterHouse
get_value($value)Returns the JSON data contained in value for this device.
This is a high level module for interacting with the Nest Thermostat. It is generally user friendly and contains many functions which are similar to other thermostat modules.
The state of this object will be the ambient temperature reported by the thermostat. This object does not accept set commands. You can use all of the remaining Generic_Item including c<state>, c<state_now>, c<tie_event> to interact with this object.
Create a Nest thermostat instance in the .mht file:
.mht file:
CODE, $nest_thermo = new Nest_Thermostat('Entryway', $nest, 'f'); #noloopThe arguments:
1. The first argument can be either I<the name of the device> or the I<device id>.
If using the name, this must be the exact verbatim name as listed on the Nest
website. Alternatively, if you want to allow for future name changes without
breaking your installation, you can get the device id using the
L<print_devices()|Nest_Interface::print_devices> routine.
2. The second argument is the interface object
3. The third argument is either [f,c] and denotes the temperature scale you preferNest_Generic
new($name, $interface, $scale)Creates a new Nest_Generic.
$name - The name or device if of the Thermostat
$interface - The interface object
$scale - Either [c,f] denoting your prefered temperature scaleget_temp()Returns the current ambient temperature.
get_heat_sp()Returns the current heat setpoint for the combined heat-cool mode.
get_cool_sp()Returns the current cool setpoint for the combined heat-cool mode.
get_target_sp()Returns the current target setpoint for either the heat or cool mode. The combined heat-cool mode uses its own functions.
get_mode()Return the current mode.
get_fan_state()Return the current fan state.
set_fan_state($state, $p_setby, $p_response)Sets the fan state to $state, must be [true,false].
set_target_temp($state, $p_setby, $p_response)Sets the target temp for the heat or cool mode to $state.
set_target_temp_high($state, $p_setby, $p_response)Sets the heat target temp for the combined heat-cool mode to $state.
set_target_temp_low($state, $p_setby, $p_response)Sets the cool target temp for the combined heat-cool mode to $state.
set_hvac_mode($state, $p_setby, $p_response)Sets the mode to $state, must be [heat,cool,heat-cool,off]
This is a very high level module for interacting with the Nest Thermostat Fan. This type of object is often referred to as a child device. It displays the state of the fan and allows for enabling or disabling it. The object inherits all of the Generic_Item methods, including c<set>, c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_fan = new Nest_Thermo_Fan($nest_thermo); #noloopThe only argument required is the thermostat object.
Nest_Generic
This is a very high level module for interacting with the Nest Thermostat Leaf. This type of object is often referred to as a child device. It displays the state of the leaf. The object inherits all of the Generic_Item methods, including c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_leaf = new Nest_Thermo_Leaf($nest_thermo); #noloopThe only argument required is the thermostat object.
Nest_Generic
This is a very high level module for interacting with the Nest Thermostat Mode. This type of object is often referred to as a child device. It displays the mode of the thermostat and allows for setting the modes. The object inherits all of the Generic_Item methods, including c<set>, c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_mode = new Nest_Thermo_Mode($nest_thermo); #noloopThe only argument required is the thermostat object.
Nest_Generic
This is a very high level module for interacting with the Nest Thermostat Target Temperature. This is used in either the heat or the cool modes. This type of object is often referred to as a child device. It displays the setpoint of the thermostat and allows for setting the temperature. The object inherits all of the Generic_Item methods, including c<set>, c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_param = new Nest_Thermo_Target($nest_thermo); #noloopThe only argument required is the thermostat object.
Nest_Generic
This is a very high level module for interacting with the Nest Thermostat High Target Temperature. This is used only in the heat-cool mode. This type of object is often referred to as a child device. It displays the setpoint of the thermostat and allows for setting the temperature. The object inherits all of the Generic_Item methods, including c<set>, c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_param = new Nest_Thermo_Target_High($nest_thermo); #noloopThe only argument required is the thermostat object.
Nest_Generic
This is a very high level module for interacting with the Nest Thermostat Low Target Temperature. This is used only in the heat-cool mode. This type of object is often referred to as a child device. It displays the setpoint of the thermostat and allows for setting the temperature. The object inherits all of the Generic_Item methods, including c<set>, c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_param = new Nest_Thermo_Target_Low($nest_thermo); #noloopThe only argument required is the thermostat object.
Nest_Generic
This is a very high level module for interacting with the Nest Thermostat High Away Target Temperature. This type of object is often referred to as a child device. It displays the setpoint of the thermostat and but cannot be changed. The object inherits all of the Generic_Item methods, including c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_param = new Nest_Thermo_Away_High($nest_thermo); #noloopThe only argument required is the thermostat object.
Nest_Generic
This is a very high level module for interacting with the Nest Thermostat High Away Target Temperature. This type of object is often referred to as a child device. It displays the setpoint of the thermostat and but cannot be changed. The object inherits all of the Generic_Item methods, including c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_param = new Nest_Thermo_Away_Low($nest_thermo); #noloopThe only argument required is the thermostat object.
Nest_Generic
This is a high level module for interacting with the Nest Smoke Alarm. It is generally user friendly.
The state of this object will be the combined state of both the CO and smoke alarm plus the battery state. If everything it OK the state will be OK. Any emergency state will be listed first, followed by a warning state, followed by a battery health warning. You CANNOT set the state of this object, as the detector is a read only device. You can use all of the the Generic_Item methods, including c<set>, c<state>, c<state_now>, c<tie_event> to interact with this object.
Create a Nest smoke alarm instance in the .mht file:
.mht file:
CODE, $nest_alarm = new Nest_Smoke_CO_Alarm('Kitchen', $nest); #noloopThe arguments:
1. The first argument can be either I<the name of the device> or the I<device id>.
If using the name, this must be the exact verbatim name as listed on the Nest
website. Alternatively, if you want to allow for future name changes without
breaking your installation, you can get the device id using the
L<print_devices()|Nest_Interface::print_devices> routine.
2. The second argument is the interface objectNest_Generic
new($name, $interface)Creates a new Nest_Generic.
$name - The name or device if of the Thermostat
$interface - The interface objectget_co()Returns the carbon monoxide alarm state. [ok,warning,emergency]
get_smoke()Returns the smoke alarm state. [ok,warning,emergency]
get_battery()Returns the detector battery health. [ok,replace]
This is a high level module for interacting with the Nest Structure object. It is generally user friendly.
The state of this object will be set to the home/away state of the structure. You can use all of the the Generic_Item methods, including c<set>, c<state>, c<state_now>, c<tie_event> to interact with this object.
Create a Nest structure instance in the .mht file:
.mht file:
CODE, $nest_home = new Nest_Structure('Home', $nest); #noloopThe arguments:
1. The first argument can be either I<the name of the structure> or the I<structure id>.
If using the name, this must be the exact verbatim name as listed on the Nest
website. Alternatively, if you want to allow for future name changes without
breaking your installation, you can get the device id using the
L<print_structures()|Nest_Interface::print_structures> routine.
2. The second argument is the interface objectNest_Generic
new($name, $interface)Creates a new Nest_Generic.
$name - The name or device if of the Thermostat
$interface - The interface objectget_away_status()Returns the state of the structure. [home,away]
set_away_status($state, $p_setby, $p_response)Sets the state of the structure. $State must be [home,away]. This will cause all devices inside this structure to change to the set state.
Kevin Robert Keegan
http://developer.nest.com/
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
| Nest.pm |