| Ecobee.pm |
This module allows MisterHouse to communicate with the public Ecobee API which currently allows interaction with Ecobee's family of thermostats (ecobee3, Smart Si, EMS, EMS Si and white label Carrier Cor and Bryant Housewise). The current version of this module only supports the ecobee3, but can be extended to support the other thermostat models.
Ecobee uses OAuth 2.0 to authorize access to devices associated with your account. The nice thing is that at any point in the future, you can sign into your Ecobee account and revoke any access tokens that you have issued.
To authorize API access for MisterHouse, you will need to perform two steps on the Ecobee website.
First: Sign up as a developer on the Ecobee Developer portal (https://www.ecobee.com/developers/). This steps is required to create the API key used by the application. All thermostats registered with this with this API key (application) will be visible to MisterHouse, so for security reasons, you should create your own application and not use someone elses's API key as they will have access to your thermostats. Once signed up as a developer, the Developer Dashboard becomes available on the consumer portal (https://www.ecobee.com/home/ecobeeLogin.jsp) and can be accessed by selecting DEVELOPER from the three horizontal lines in the upper-right-hand part of the screen. Create a new application. The name must be globally unique, but is arbitrary for how MisterHouse interacts with it. Select Authorization Method ecobee PIN, add any other attributes you desire to include (these are not required), then select Create. Once your application is created, it will be visible in the left-hand part of the screen. Click on this and it will reveal the API key. Copy this string as it is needed in your configuration.
Second: Add the API key string to your mh.private.ini file:
Ecobee_api_key=<API key generated in the previous step>Create an Ecobee instance in the .mht file, or is user code:
.mht file:
CODE, require Ecobee; #noloop
CODE, $ecobee = new Ecobee_Interface(); #noloop
CODE, $ecobee_thermo = new Ecobee_Thermostat('First floor', $ecobee); #noloop
CODE, $thermo_humid = new Ecobee_Thermo_Humidity($ecobee_thermo); #noloop
CODE, $thermo_hvac_status = new Ecobee_Thermo_HVAC_Status($ecobee_thermo); #noloop
CODE, $thermo_mode = new Ecobee_Thermo_Mode($ecobee_thermo); #noloop
CODE, $thermo_climate = new Ecobee_Thermo_Climate($ecobee_thermo); #noloopExplanations of the parameters is contained below in the documentation for each module.
The Ecobee public API is fairly comprehensive and allows access to the majority of the thermostat's features. Since release, Ecobee has been progressively been adding and enhancing features. As such, functionality may change and require updates to this module.
This handles the interaction between the Ecobee API servers and MisterHouse. This is the object that is required. An advanced user could interact with the Ecobee 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 Ecobee_Thermostat and Ecobee_Structure This classes provide more specific support for each of the current Ecobee 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 Ecobee_Thermo_.... These are very specific objects that provide very specific support for individual features on the Ecobee 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.
_list_thermostats()Collects the initial settings and parameters for each device on the Ecobee account.
_get_settings()Gets the current settings, events and program
_get_alerts()Gets the current alerts
_get_groups()Gets the group and grouping data for thermostats
_get_runtime_with_sensors()Gets the runtime and sensor data
_thermostat_summary()Collects the revision numbers from each device on the Ecobee account. Changes to the revision number tell us that something has changed, and we need to request an update.
register($parent, $value)Used to register actions to be run if a specific value changes.
$parent - The parent object on which the value should be monitored
(thermostat, remote sensor, group)
$value - The nested hash to monitor for changes. The assigned value is a
Code Reference to run when the value changes. The code reference
will be passed two arguments, the parameter name and value.print_devices()Prints the name and id of all devices found in the Ecobee account.
get_temp()Returns the temperature of the named temperature sensor registered with the given device (thermostat)
get_humidity()Returns the humidity of the named sensor registered with the given device (thermostat). Currently only the main thermostat device, not the remote sensors have humidity
get_desired_comfort()Returns the given runtime property for desiredX comfort setting. Known properties are:
desiredHeat => Heat desiredCool => Cool desiredHumidity => Humidity desiredDehumidity => Dehumidity desiredFanMode => FanMode
get_setting()Returns the given setting property.
get_alert()Returns either the given alert by the given $id, or all of them if $id is undefined
get_event()Returns either the given event by the given $id, or all of them if $id is undefined
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 Ecobee_Generic. $interface - The Ecobee_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_changed routine.
_delve()Internal function to help populate the monitor_hash with action functions
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
device_id()Returns the device_id of an object.
sensor_id()Returns the sensor_id of an object.
get_value($value)Returns the data contained in value for this device.
This is a high level module for interacting with the Ecobee 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 an Ecobee thermostat instance in the .mht file:
.mht file:
CODE, $ecobee_thermo = new Ecobee_Thermostat('Entryway', $ecobee); #noloopThe arguments:
1. The first argument is the I<the name of the device>.
The name must be the exact verbatim name as listed on the Ecobee
website.
2. The second argument is the interface objectEcobee_Generic
new($name, $interface)Creates a new Ecobee_Generic.
$name - The name of the Thermostat
$interface - The interface objectget_temp()Returns the current ambient temperature.
get_events()Returns the current events.
get_programs()Returns the current programs.
set_hvac_mode($state, $p_setby, $p_response)Sets the mode to $state, must be [heat,auxHeatOnly,cool,auto,off]
set_hold($state, $p_setby, $p_response)Sets a hold for the properties defined in $state. $state format can be either a temperature hold or a climate hold. Temperature holds are in the format temperature_<holdType>_<heatHoldTemp>_<coolHoldTemp> and climate holds are in the format climate_<holdType>_<holdClimateRef>
clear_hold()Clears the current thermostat hold.
This is a very high level module for viewing with the Ecobee Thermostat Humidity value (actualHumidity) 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<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_humid = new Ecobee_Thermo_Humidity($ecobee_thermo); #noloopThe only argument required is the thermostat object.
Ecobee_Generic
This is a very high level module for viewing the Ecobee Thermostat operating status (state). This type of object is often referred to as a child device. It displays the current status (fan, auxHeat1, ventilator, etc) as a vector (bitfield) to convey all the status data as a single state value. The object inherits all of the Generic_Item methods, including c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_hvac_status = new Ecobee_Thermo_HVAC_Status($ecobee_thermo); #noloopThe only argument required is the thermostat object.
Ecobee_Generic
This is a very high level module for interacting with the Ecobee 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 Ecobee_Thermo_Mode($ecobee_thermo); #noloopThe only argument required is the thermostat object.
Ecobee_Generic
This is a very high level module for interacting with the Ecobee Thermostat Climate. This type of object is often referred to as a child device. It displays the climate value of the thermostat either by the active schedule, or by the ClimateRef of an overriding hold. The object inherits all of the Generic_Item methods, including c<state>, c<state_now>, c<tie_event>.
.mht file:
CODE, $thermo_climate = new Ecobee_Thermo_Climate($ecobee_thermo); #noloopThe only argument required is the thermostat object.
Ecobee_Generic
Brian Rudy Originally based on Nest.pm by Kevin Robert Keegan
https://www.ecobee.com/developers/
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.
Hey! The above document had some coding errors, which are explained below:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
=back without =over
| Ecobee.pm |