Items Nest

Nest

SYNOPSIS

This module allows MisterHouse to communicate with the public Nest API which currently allows interaction with Nest Thermostats and Smoke/CO Detectors.

CONFIGURATION

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.

INI PARAMETERS

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:

Items.mht

Defined in items.mht as

  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); #noloop

Explanations of the parameters is contained below in the documentation for each module.

OVERVIEW

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 expectation 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:

NEST_INTERFACE 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.
NEST_GENERIC 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.
PARENT ITEMS 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.
CHILD ITEMS 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.

Nest_Interface

SYNOPSIS

This module allows MisterHouse to communicate with the public Nest API which currently allows interaction with Nest Thermostats and Smoke/CO Detectors.

CONFIGURATION

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.

INI PARAMETERS

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>

Items.mht

Create a Nest instance in the .mht file, or in user code:

  CODE, require Nest; #noloop 
  CODE, $nest = new Nest_Interface(); #noloop

DESCRIPTION

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.

INHERITS

Nest

DEPENDENCIES

  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 Nest

METHODS

Method	Description
`new($auth, $port_name, $url`	Creates 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<br/>`$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.
`client_version()`	Prints the MisterHouse Client Version. Client version of 2 is required for humidity and `hvac_state`. Returns -1 if unknown version, or if the data hasn't been parsed yet

Nest_Generic

SYNOPSIS

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.

INHERITS

Generic_Item

METHODS

Method	Description
`new($interface, $parent, $monitor_hash)`	Creates a new Nest_Generic. `$interface - The Nest_Interface through which this device can be found.<br/>`$parent `- The parent interface of this object, if not specified the parent will be set to Self.<br/>`$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_changed` 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.

Nest_Thermostat

SYNOPSIS

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, c<state_now>, c<tie_event> to interact with this object.

CONFIGURATION

Items.mht

Create a Nest thermostat instance in the .mht file:

#
CODE, $nest_thermo = new Nest_Thermostat('Entryway', $nest, 'f'); #noloop

The arguments:

The first argument can be either I or the I. 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.
The second argument is the interface object
The third argument is either [f,c] and denotes the temperature scale you prefer

INHERITS

Nest_Generic

METHODS

Method	Description
`new($name, $interface, $scale)`	Creates a new Nest_Generic. `$name - The name or device if of the Thermostat<br/>`$interface `- The interface object<br/>`$scale `- Either`[c,f]` denoting your preferred temperature scale
`get_temp()`	Returns the current ambient temperature.
`get_heat_sp()`	Returns the current heat set-point for the combined heat-cool mode.
`get_cool_sp()`	Returns the current cool set-point for the combined heat-cool mode.
`get_target_sp()`	Returns the current target set-point 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].
`get_humidity()`	Return the current humidity value.
`get_hvac_state()`	Return the current thermostat state (heating, cooling, off).
`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]

Nest_Thermo_Fan

SYNOPSIS

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, c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

CODE, $thermo_fan = new Nest_Thermo_Fan($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_Leaf

SYNOPSIS

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, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_leaf = new Nest_Thermo_Leaf($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_Humidity

SYNOPSIS

This is a very high level module for viewing with the Nest Thermostat Humidity value. This type of object is often referred to as a child device. It displays the current humidity. The object inherits all of the Generic_Item methods, including c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_humid = new Nest_Thermo_Humidity($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_HVAC_State

SYNOPSIS

This is a very high level module for viewing the Nest Thermostat operating state. This type of object is often referred to as a child device. It displays the current status (heating, cooling, off). The object inherits all of the Generic_Item methods, including c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_hvac_state = new Nest_Thermo_HVAC_State($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_Mode

SYNOPSIS

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, c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_mode = new Nest_Thermo_Mode($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_Target

SYNOPSIS

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 set-point of the thermostat and allows for setting the temperature. The object inherits all of the Generic_Item methods, including c, c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_param = new Nest_Thermo_Target($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_Target_High

SYNOPSIS

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 set-point of the thermostat and allows for setting the temperature. The object inherits all of the Generic_Item methods, including c, c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_param = new Nest_Thermo_Target_High($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_Target_Low

SYNOPSIS

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 set-point of the thermostat and allows for setting the temperature. The object inherits all of the Generic_Item methods, including c, c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_param = new Nest_Thermo_Target_Low($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_Away_High

SYNOPSIS

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 set-point of the thermostat and but cannot be changed. The object inherits all of the Generic_Item methods, including c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_param = new Nest_Thermo_Away_High($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Thermo_Away_Low

SYNOPSIS

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 set-point of the thermostat and but cannot be changed. The object inherits all of the Generic_Item methods, including c, c<state_now>, c<tie_event>.

CONFIGURATION

Items.mht

Defined in items.mht as

  CODE, $thermo_param = new Nest_Thermo_Away_Low($nest_thermo); #noloop

The only argument required is the thermostat object.

INHERITS

Nest_Generic

Nest_Smoke_CO_Alarm

SYNOPSIS

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, c, c<state_now>, c<tie_event> to interact with this object.

CONFIGURATION

Items.mht

Create a Nest smoke alarm instance in the .mht file:

  CODE, $nest_alarm = new Nest_Smoke_CO_Alarm('Kitchen', $nest); #noloop

The arguments:

The first argument can be either I or the I. 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.
The second argument is the interface object

INHERITS

Nest_Generic

METHODS

Method	Description
`new($name, $interface)`	Creates a new Nest_Generic. `$name` - The name or device if of the Thermostat `$interface` - The interface object
`get_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]

Nest_Structure

SYNOPSIS

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, c, c<state_now>, c<tie_event> to interact with this object.

CONFIGURATION

Items.mht

Create a Nest structure instance in the .mht file:

  CODE, $nest_home = new Nest_Structure('Home', $nest); #noloop

The arguments:

The first argument can be either I or the I. 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.
The second argument is the interface object

INHERITS

Nest_Generic

METHODS

Method	Description
`new($name, $interface)`	Creates a new Nest_Generic. `$name` - The name or device if of the Thermostat `$interface` - The interface object
`get_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.

AUTHOR

Kevin Robert Keegan