diff --git a/CODEOWNERS b/CODEOWNERS index e5234c4e3a90a..8d822b0713129 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -41,6 +41,7 @@ /bundles/org.openhab.binding.doorbird/ @mhilbush /bundles/org.openhab.binding.dscalarm/ @RSStephens /bundles/org.openhab.binding.dsmr/ @Hilbrand +/bundles/org.openhab.binding.ecobee/ @mhilbush /bundles/org.openhab.binding.dwdpollenflug/ @DerOetzi /bundles/org.openhab.binding.dwdunwetter/ @limdul79 /bundles/org.openhab.binding.elerotransmitterstick/ @vbier diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml index 6651a6083287f..95fc584e5afac 100644 --- a/bom/openhab-addons/pom.xml +++ b/bom/openhab-addons/pom.xml @@ -204,6 +204,11 @@ org.openhab.binding.dwdunwetter ${project.version} + + org.openhab.addons.bundles + org.openhab.binding.ecobee + ${project.version} + org.openhab.addons.bundles org.openhab.binding.elerotransmitterstick diff --git a/bundles/org.openhab.binding.ecobee/.classpath b/bundles/org.openhab.binding.ecobee/.classpath new file mode 100644 index 0000000000000..a5d95095ccaaf --- /dev/null +++ b/bundles/org.openhab.binding.ecobee/.classpath @@ -0,0 +1,32 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/bundles/org.openhab.binding.ecobee/.project b/bundles/org.openhab.binding.ecobee/.project new file mode 100644 index 0000000000000..d785eb7799fd4 --- /dev/null +++ b/bundles/org.openhab.binding.ecobee/.project @@ -0,0 +1,23 @@ + + + org.openhab.binding.ecobee + + + + + + org.eclipse.jdt.core.javabuilder + + + + + org.eclipse.m2e.core.maven2Builder + + + + + + org.eclipse.jdt.core.javanature + org.eclipse.m2e.core.maven2Nature + + diff --git a/bundles/org.openhab.binding.ecobee/NOTICE b/bundles/org.openhab.binding.ecobee/NOTICE new file mode 100644 index 0000000000000..38d625e349232 --- /dev/null +++ b/bundles/org.openhab.binding.ecobee/NOTICE @@ -0,0 +1,13 @@ +This content is produced and maintained by the openHAB project. + +* Project home: https://www.openhab.org + +== Declared Project Licenses + +This program and the accompanying materials are made available under the terms +of the Eclipse Public License 2.0 which is available at +https://www.eclipse.org/legal/epl-2.0/. + +== Source Code + +https://github.com/openhab/openhab-addons diff --git a/bundles/org.openhab.binding.ecobee/README.md b/bundles/org.openhab.binding.ecobee/README.md new file mode 100644 index 0000000000000..20d0ed2e698e7 --- /dev/null +++ b/bundles/org.openhab.binding.ecobee/README.md @@ -0,0 +1,1252 @@ +# Ecobee Binding + +[Ecobee Inc.](https://www.ecobee.com/) of Toronto, Canada, sells a range of Wi-Fi +enabled thermostats, principally in the Americas. +This binding communicates with the +[Ecobee API](https://www.ecobee.com/home/developer/api/introduction/index.shtml) over a secure, +RESTful API to Ecobee's servers. +Monitoring ambient temperature and humidity, changing HVAC mode, changing heat or cool setpoints, +changing the backlight intensity, and even sending textual messages to one or a group of thermostats, +can be accomplished through this binding. + +## Supported Things + +The following thing types are supported: + +| Thing | ID | Description | +|----------------|-----------------|--------------| +| Account | account | Represents an Ecobee account. Manages all communication with the Ecobee API. | +| Thermostat | thermostat | Represents a physical Ecobee thermostat associated with the Ecobee Account. | +| Remote Sensor | sensor | Represents an Ecobee remote sensor that is associated with an Ecobee Thermostat. Also represents the internal sensor of an Ecobee Thermostat. | + +## Discovery + +Once an Account has been set up, and the API key has been authorized, Thermostats and Remote +Sensors will be discovered automatically. +First, the thermostats will be added to the inbox. +Then, once a Thermostat thing has been created, the Remote Sensors associated with that +thermostat will be added to the inbox. +The binding will detect the capabilities (e.g. temperature, humidity, occupancy) supported by the +sensor, and then dynamically create channels for those capabilities. + +## Authorization + +After you have installed the binding, and have created the Account thing with a valid API key, +the binding will try to get information about your thermostats from the Ecobee web service. +When this happens, the binding will determine that it has not yet been authorized by the Ecobee web service. + +At this point the binding will retrieve a four-character PIN code from the Ecobee web service. +The binding will mark the Account thing OFFLINE with a detailed status message that contains the +PIN code needed to complete the authorization. +The PIN code will be valid for 9 minutes. +The status message will look something like this. + +``` +Enter PIN 'RVLA' in MyApps. PIN expires in 9 minutes. +``` + +To complete the authorization, the PIN code must be entered into the Ecobee **My Apps** settings in your account at ecobee.com. +This will authorize the binding to work with the thermostats associated with your Ecobee account. +Once authorization is complete, the binding will retrieve information about the available thermostats, +and add those thermostats to the inbox. + +## Thing Configuration + +### Ecobee Account + +The following configuration parameters are available on the Ecobee Account: + +| Parameter | Type |Required/Optional | Description | +|-------------------------|------------|------------------|-------------| +| apiKey | String | Required | This is the Ecobee API key, which is needed to authorize the binding with the Ecobee servers. | +| refreshIntervalNormal | Integer | Required | Specifies the interval in seconds with which the Ecobee data will be updated under normal operation. | +| refreshIntervalQuick | Integer | Required | Specifies the interval in seconds with which the Ecobee data will be updated after sending an update or executing a function. | +| apiTimeout | Integer | Required | Time in seconds to allow an API request against the Ecobee servers to complete. | +| discoveryEnabled | Switch | Required | Specifies whether the binding should auto-discover thermostats and remote sensors. | +| discoveryInterval | Integer | Optional | Specifies time interval in seconds in which the binding will attempt to discover thermostats. | + +### Ecobee Thermostat + +The following configuration parameters are available on the Ecobee Thermostat: + +| Parameter | Required/Optional | Description | +|-------------------------|-------------------|-------------| +| thermostatId | Required | This is the ID that is assigned to a thermostat by Ecobee. This parameter is used for all communication with Ecobee involving this thermostat. | + +### Ecobee Remote Sensor + +The following configuration parameters are available on the Ecobee Remote Sensor: + +| Parameter | Required/Optional | Description | +|-------------------------|-------------------|-------------| +| sensorId | Required | This is the ID that is assigned to a remote and/or internal sensor by Ecobee. | + +## Channels + +### Thermostat Channels + +The following channels are available on the Ecobee Thermostat. + +| Group | Channel | Type | ReadWrite | Description | +|-------|---------|------|-----------|--------------| +| info | identifier | String | | Identifier | +| info | name | String | yes | Name | +| info | thermostatRev | String | | Thermostat Rev | +| info | isRegistered | Switch | | Is Registered | +| info | modelNumber | String | | Model Number | +| info | brand | String | | Brand | +| info | features | String | | Features | +| info | lastModified | DateTime | | Last Modified | +| info | thermostatTime | DateTime | | Thermostat Time | +|||||| +| equipmentStatus | equipmentStatus | String | | Equipment Status | +|||||| +| program | currentClimateRef | String | | Current Climate Ref | +|||||| +| runtime | runtimeRev | String | | Runtime Rev | +| runtime | connected | Switch | | Connected | +| runtime | firstConnected | DateTime | | First Connected | +| runtime | connectDateTime | DateTime | | Connected Date Time | +| runtime | disconnectDateTime | DateTime | | Disconnected Date Timee | +| runtime | lastModified | DateTime | | Last Modified | +| runtime | lastStatusModified | DateTime | | Last Status Modified | +| runtime | runtimeDate | String | | Runtime Date | +| runtime | runtimeInterval | Number | | Runtime Interval | +| runtime | actualTemperature | Number:Temperature | | Actual Temperature | +| runtime | actualHumidity | Number:Dimensionless | | Actual Humidity | +| runtime | rawTemperature | Number:Temperature | | Raw Temperature | +| runtime | showIconMode | Number | | Show Icon Mode | +| runtime | desiredHeat | Number:Temperature | | Desired Heat | +| runtime | desiredCool | Number:Temperature | | Desired Cool | +| runtime | desiredHumidity | Number:Dimensionless | | Desired Humidity | +| runtime | desiredDehumidity | Number:Dimensionless | | Desired Dehumidity | +| runtime | desiredFanMode | String | | Desired Fan Mode | +| runtime | desiredHeatRangeLow | Number:Temperature | | Desired Heat Range Low | +| runtime | desiredHeatRangeHigh | Number:Temperature | | Desired Heat Range High | +| runtime | desiredCoolRangeLow | Number:Temperature | | Desired Cool Range Low | +| runtime | desiredCoolRangeHigh | Number:Temperature | | Desired Cool Range High | +|||||| +| settings | hvacMode | String | yes | HVAC Mode | +| settings | lastServiceDate | String | yes | Last Service Date | +| settings | serviceRemindMe | Switch | yes | Service Remind Me | +| settings | monthsBetweenService | Number | yes | Months Between Service | +| settings | remindMeDate | String | yes | Remind Me Date | +| settings | vent | String | yes | Vent | +| settings | ventilatorMinOnTime | Number | yes | Ventilator Min On Time | +| settings | serviceRemindTechnician | Switch | yes | Service Remind Technician | +| settings | eiLocation | String | yes | EI Location | +| settings | coldTempAlert | Number:Temperature | yes | Cold Temp Alert | +| settings | coldTempAlertEnabled | Switch | yes | Cold Temp Alert Enabled | +| settings | hotTempAlert | Number:Temperature | yes | Hot Temp Alert | +| settings | hotTempAlertEnabled | Switch | yes | Hot Temp Alert Enabled | +| settings | coolStages | Number | | Cool Stages | +| settings | heatStages | Number | | Heat Stages | +| settings | maxSetBack | Number | yes | Max Set Back | +| settings | maxSetForward | Number | yes | Max Set Forward | +| settings | quickSaveSetBack | Number | yes | Quick Save Set Back | +| settings | quickSaveSetForward | Number | yes | Quick Save Set Forward | +| settings | hasHeatPump | Switch | | Has Heat Pump | +| settings | hasForcedAir | Switch | | Has Forced Air | +| settings | hasBoiler | Switch | | Has Boiler | +| settings | hasHumidifier | Switch | | Has Humidifier | +| settings | hasElectric | Switch | | Has Electric | +| settings | hasDehumidifier | Switch | | Has Dehumidifier | +| settings | hasErv | Switch | | Has ERV | +| settings | hasHrv | Switch | | Has HRV | +| settings | condensationAvoid | Switch | yes | Condensation Avoid | +| settings | useCelsius | Switch | yes | Use Celsius | +| settings | useTimeFormat12 | Switch | yes | Use Time Format 12 | +| settings | locale | String | yes | Locale | +| settings | humidity | String | yes | Humidity | +| settings | humidifierMode | String | yes | Humidifier Mode | +| settings | backlightOnIntensity | Number | yes | Backlight On Intensity | +| settings | backlightSleepIntensity | Number | yes | Backlight Sleep Intensity | +| settings | backlightOffTime | Number | yes | Backlight Off Time | +| settings | soundTickVolume | Number | yes | Sound Tick Volume | +| settings | soundAlertVolume | Number | yes | Sound Alert Volume | +| settings | compressorProtectionMinTime | Number | yes | Compressor Protection Min Time | +| settings | compressorProtectionMinTemp | Number:Temperature | yes | Compressor Protection Min Temp | +| settings | stage1HeatingDifferentialTemp | Number | yes | Stage 1 Heating Differential Temp | +| settings | stage1CoolingDifferentialTemp | Number | yes | Stage 1 Cooling Differential Temp | +| settings | stage1HeatingDissipationTime | Number | yes | Stage 1 Heating Dissipation Time | +| settings | stage1CoolingDissipationTime | Number | yes | Stage 1 Cooling Dissipation Time | +| settings | heatPumpReversalOnCool | Switch | yes | Heat Pump Reversal On Cool | +| settings | fanControlRequired | Switch | yes | Fan Control Required | +| settings | fanMinOnTime | Number | yes | Fan Min On Time | +| settings | heatCoolMinDelta | Number | yes | Heat Cool Min Delta | +| settings | tempCorrection | Number | yes | Temp Correction | +| settings | holdAction | String | yes | Hold Action | +| settings | heatPumpGroundWater | Switch | | Heat Pump Ground Water | +| settings | dehumidifierMode | String | yes | Dehumidifier Mode | +| settings | dehumidifierLevel | Number | yes | Dehumidifier Level | +| settings | dehumidifyWithAC | Switch | yes | Dehumidify With AC | +| settings | dehumidifyOvercoolOffset | Number | yes | Dehumidify Overcool Effect | +| settings | autoHeatCoolFeatureEnabled | Switch | yes | Auto Heat Cool Feature Enabled | +| settings | wifiOfflineAlert | Switch | yes | WiFi Offline Alert | +| settings | heatMinTemp | Number:Temperature | | Heat Min Temp | +| settings | heatMaxTemp | Number:Temperature | | Heat Max Temp | +| settings | coolMinTemp | Number:Temperature | | Cool Min Temp | +| settings | coolMaxTemp | Number:Temperature | | Cool Max Temp | +| settings | heatRangeHigh | Number:Temperature | yes | Heat Range High | +| settings | heatRangeLow | Number:Temperature | yes | Heat Range Low | +| settings | coolRangeHigh | Number:Temperature | yes | Cool Range High | +| settings | coolRangeLow | Number:Temperature | yes | Cool Range Low | +| settings | userAccessCode | String | | User Access Code | +| settings | userAccessSetting | Number | | User Access Settings | +| settings | auxRuntimeAlert | Number | yes | Aux Runtime Alert | +| settings | auxOutdoorTempAlert | Number:Temperature | yes | Aux Outdoor Temp Alert | +| settings | auxMaxOutdoorTemp | Number:Temperature | yes | Aux Max Outdoor Temp | +| settings | auxRuntimeAlertNotify | Switch | yes | Aux Runtime Alert Notify | +| settings | auxOutdoorTempAlertNotify | Switch | yes | Aux Outdoor Temp Alert Notify | +| settings | auxRuntimeAlertNotifyTechnician | Switch | yes | Aux Runtime Alert Notify Technician | +| settings | auxOutdoorTempAlertNotifyTechnician | Switch | yes | Aux Outdoor Temp Alert Notify Technician | +| settings | disablePreHeating | Switch | yes | Disable Pre Heating | +| settings | disablePreCooling | Switch | yes | Disable Pre Cooling | +| settings | installerCodeRequired | Switch | yes | Installer Code Required | +| settings | drAccept | String | yes | DR Accept | +| settings | isRentalProperty | Switch | yes | Is Rental Property | +| settings | useZoneController | Switch | yes | Use Zone Controller | +| settings | randomStartDelayCool | Number | yes | Random Start Delay Cool | +| settings | randomStartDelayHeat | Number | yes | Random Start Delay Heat | +| settings | humidityHighAlert | Number:Dimensionless | yes | Humidity High Alert | +| settings | humidityLowAlert | Number:Dimensionless | yes | Humidity Low Alert | +| settings | disableHeatPumpAlerts | Switch | yes | Disable Heat Pump Alerts | +| settings | disableAlertsOnIdt | Switch | yes | Disable Alerts On IDT | +| settings | humidityAlertNotify | Switch | yes | Humidity Alert Notify | +| settings | humidityAlertNotifyTechnician | Switch | yes | Humidity Alert Notify Technician | +| settings | tempAlertNotify | Switch | yes | Temp Alert Notify | +| settings | tempAlertNotifyTechnician | Switch | yes | Temp Alert Notify Technician | +| settings | monthlyElectricityBillLimit | Number | yes | Monthly Electricity Bill Limit | +| settings | enableElectricityBillAlert | Switch | yes | Enable Electricity Bill Alert | +| settings | enableProjectedElectricityBillAlert | Switch | yes | Enable Projected Electricity Bill Alert | +| settings | electricityBillingDayOfMonth | Number | yes | Electricity Billing Day Of Month | +| settings | electricityBillCycleMonths | Number | yes | Electricity Bill Cycle Months | +| settings | electricityBillStartMonth | Number | yes | Electricity Bill Start Month | +| settings | ventilatorMinOnTimeHome | Number | yes | Ventilator Min On Time Home | +| settings | ventilatorMinOnTimeAway | Number | yes | Ventilator Min On Time Away | +| settings | backlightOffDuringSleep | Switch | yes | Backlight Off During Sleep | +| settings | autoAway | Switch | yes | Auto Away | +| settings | smartCirculation | Switch | yes | Smart Circulation | +| settings | followMeComfort | Switch | yes | Follow Me Comfort | +| settings | ventilatorType | String | | Ventilator Type | +| settings | isVentilatorTimerOn | Switch | yes | Is Ventilator Timer On | +| settings | ventilatorOffDateTime | String | | Ventilator Off Date Time | +| settings | hasUVFilter | Switch | yes | Has UV Filter | +| settings | coolingLockout | Switch | yes | Cooling Lockout | +| settings | ventilatorFreeCooling | Switch | yes | Ventilator Free Cooling | +| settings | dehumidifyWhenHeating | Switch | yes | Dehumidify When Heating | +| settings | ventilatorDehumidify | Switch | yes | Ventilator Dehumidify | +| settings | groupRef | String | yes | Group Ref | +| settings | groupName | String | yes | Group Name | +| settings | groupSetting | Number | yes | Group Setting | +|||||| +| alerts | acknowledgeRef | String | | Acknowledge Ref | +| alerts | date | String | | Date | +| alerts | time | String | | Time | +| alerts | severity | String | | Severity | +| alerts | text | String | | Text | +| alerts | number | Number | | Number | +| alerts | type | String | | Type | +| alerts | isOperatorAlert | Switch | | Is Operator Alert | +| alerts | reminder | String | | Reminder | +| alerts | showIdt | Switch | | Show IDT | +| alerts | showWeb | Switch | | Show Web | +| alerts | sendEmail | Switch | | Send Email | +| alerts | acknowledgement | String | | Acknowledgement | +| alerts | remindMeLater | Switch | | Remind Me Later | +| alerts | thermostatIdentifier | String | | Thermostat Identifier | +| alerts | notificationType | String | | Notification Type | +|||||| +| events | name | String | | Event Name | +| events | type | String | | Event Type | +| events | running | Switch | | Event is Running | +| events | startDate | String | | Event Start Date | +| events | startTime | String | | Event Start Time | +| events | endDate | String | | Event End Date | +| events | endTime | String | | Event End Time | +| events | isOccupied | Switch | | Is Occupied | +| events | isCoolOff | Switch | | Is Cool Off | +| events | isHeatOff | Switch | | Is Heat Off | +| events | coolHoldTemp | Number:Temperature | | Cool Hold Temp | +| events | heatHoldTemp | Number:Temperature | | Heat Hold Temp | +| events | fan | String | | Fan | +| events | vent | String | | Vent | +| events | ventilatorMinOnTime | Number | | Ventilator Min On Time | +| events | isOptional | Switch | | Is Optional | +| events | isTemperatureRelative | Switch | | Is Temperature Relative | +| events | coolRelativeTemp | Number | | Cool Relative Temp | +| events | heatRelativeTemp | Number | | Heat Relative Temp | +| events | isTemperatureAbsolute | Switch | | Is Temperature Absolute | +| events | dutyCyclePercentage | Number | | Duty Cycle Percentage | +| events | fanMinOnTime | Number | | Fan Min On Time | +| events | occupiedSensorActive | Switch | | Occupied Sensor Active | +| events | unoccupiedSensorActive | Switch | | Unoccupied Sensor Active | +| events | drRampUpTemp | Number | | DR Ramp Up Temp | +| events | drRampUpTime | Number | | DR Ramp Up Time | +| events | linkRef | String | | Link Ref | +| events | holdClimateRef | String | | Hold Climate Ref | +|||||| +| weather | timestamp | DateTime | | Timestamp | +| weather | weatherStation | String | | Weather Station | +| weather | weatherSymbol | Number | | Symbol | +| weather | weatherSymbolText | String | | Symbol Text | +|||||| +| forecast0..9 | dateTime | DateTime | | Date Time | +| forecast0..9 | condition | String | | Condition | +| forecast0..9 | temperature | Number:Temperature | | Temperature | +| forecast0..9 | pressure | Number:Pressure | | Pressure | +| forecast0..9 | relativeHumidity | Number:Dimensionless | | Relative Humidity | +| forecast0..9 | dewpoint | Number:Temperature | | Dewpoint | +| forecast0..9 | visibility | Number | | Visibility | +| forecast0..9 | windSpeed | Number:Speed | | Wind Speed | +| forecast0..9 | windGust | Number:Speed | | Wind Gust | +| forecast0..9 | windDirection | String | | Wind Direction | +| forecast0..9 | windBearing | Number:Angle | | Wind Bearing | +| forecast0..9 | pop | Number:Dimensionless | | Probability of Precipitation | +| forecast0..9 | tempHigh | Number:Temperature | | High Temperature | +| forecast0..9 | tempLow | Number:Temperature | | Low Temperature | +| forecast0..9 | sky | Number | | Sky | +| forecast0..9 | skyText | String | | Sky Text | +|||||| +| location | timeZoneOffsetMinutes | Number | | Time Zone Offset Minutes | +| location | timeZone | String | yes | Time Zone | +| location | isDaylightSaving | Switch | | Is Daylight Saving | +| location | streetAddress | String | yes | Street Address | +| location | city | String | yes | City | +| location | provinceState | String | yes | Province/State | +| location | country | String | yes | Country | +| location | postalCode | String | yes | Postal Code | +| location | phoneNumber | String | yes | Phone Number | +| location | mapCoordinates | Location | yes | Thermostat Location | +|||||| +| houseDetails | style | String | yes | Style | +| houseDetails | size | Number | yes | Size | +| houseDetails | numberOfFloors | Number | yes | Number of Floors | +| houseDetails | numberOfRooms | Number | yes | Number of Rooms | +| houseDetails | numberOfOccupants | Number | yes | Number of Occupants | +| houseDetails | age | Number | yes | Age | +| houseDetails | windowEfficiency | Number | yes | Window Efficiency | +|||||| +| management | administrativeContact | String | | Administrative Contact | +| management | billingContact | String | | Billing Contact | +| management | name | String | | Name | +| management | phone | String | | Phone | +| management | email | String | | Email | +| management | web | String | | Web | +| management | showAlertIdt | Switch | | Show Alert Idt | +| management | showAlertWeb | Switch | | Show Alert Web | +|||||| +| technician | contractorRef | String | | Contractor Ref | +| technician | name | String | | Name | +| technician | phone | String | | Phone | +| technician | streetAddress | String | | Street Address | +| technician | city | String | | City | +| technician | provinceState | String | yes | Province/State | +| technician | country | String | | Country | +| technician | postalCode | String | | Postal Code | +| technician | email | String | | Email | +| technician | web | String | | Web | +|||||| +| version | thermostatFirmwareVersion | String | | Firmware Version | + +### Remote Sensor Channels + +The following channels are available on the Ecobee Remote Sensor. + +| Channel | Type | ReadWrite | Description | +|--------------|----------|-------------|--------------| +| id | String | | Sensor ID assigned by thermostat | +| name | String | | Name given to the remote sensor by the user | +| type | String | | The type of sensor | +| code | String | | The unique 4-digit alphanumeric sensor code | +| inUse | Switch | | Indicates whether the remote sensor is currently in use by a comfort setting | + +Some or all of the following Remote Sensor channels will be added dynamically depending on the capabilities of the sensor. + +| Channel | Type | ReadWrite | Description | +|--------------|-----------------------|-----------|--------------| +| temperature | Number:Temperature | | Temperature reported by the sensor | +| humidity | Number:Dimensionless | | Humidity reported by the sensor | +| occupancy | Switch | | Occupancy status reported by the sensor | +| co2 | String | | CO2 reported by the sensor | +| dryContact | String | | Dry contact status reported by the sensor | +| adc | String | | ADC reported by the sensor | + +## Thing Actions + +### Acknowledge + +The acknowledge function allows an alert to be acknowledged by specifying the alert's acknowledgement ref. + +##### acknowledge - acknowledge an alert + +```java +boolean acknowledge(String ackRef, String ackType, Boolean remindMeLater) +``` + +``` +Parameters: +ackRef - The acknowledge ref of alert. +ackType - The type of acknowledgement. Valid values: accept, decline, defer, unacknowledged. +remindMeLater - Whether to remind at a later date, if this is a defer acknowledgement. + +Returns - true if the operation was successful, false otherwise +``` + +### Control Plug + +Control the on/off state of a plug by setting a hold on the plug. +Creates a hold for the on or off state of the plug for the specified duration. +Note that an event is created regardless of whether the program is in the same state as the requested state. + +##### controlPlug - Control the on/off state of a plug + +```java +boolean controlPlug(String plugName, String plugState, Date startDateTime, Date endDateTime, String holdType, Number holdHours) +``` + +``` +Parameters: +plugName - Name of plug to be controlled. +plugState - State to which plug should be set (on, off, resume). +startDateTime - Start time for which the plug state should be applied. +endDateTime - End time for which the plug state should be applied. +holdType - Type of hold that should be applied (dateTime, nextTransityion, indefinite, holdHours). +holdHours - Number of hours for which the plug state should be applied. + +Returns - true if the operation was successful, false otherwise +``` + +### Create Vacation + +If the start/end date/times are not provided for the vacation event, +the vacation event will begin immediately and last 14 days. +If both the coolHoldTemp and heatHoldTemp parameters provided to this function have the same value, +and the Thermostat is in auto mode, then the two values will be adjusted during processing to be +separated by the value stored in thermostat.settings.heatCoolMinDelta. + +##### createVacation - Create a vacation event on the thermostat + +```java +boolean createVacation(String name, QuantityType coolHoldTemp, QuantityType heatHoldTemp, Date startDateTime, Date endDateTime, String fan, Number fanMinOnTime) +``` + +``` +Parameters: +name - The vacation event name. It must be unique. +coolHoldTemp - The temperature to set the cool vacation hold at. +heatHoldTemp - The temperature to set the heat vacation hold at. +startDateTime - The start date/time. +endDateTime - The end date/time. +fan - The fan mode during the vacation. Values: auto, on Default: auto +fanMinOnTime - The minimum number of minutes to run the fan each hour. Range: 0-60, Default: 0 + +Returns - true if the operation was successful, false otherwise +``` + +### Delete Vacation + +The delete vacation function deletes a vacation event from a thermostat. +This is the only way to cancel a vacation event. +This method is able to remove vacation events not yet started and scheduled in the future. + +##### deleteVacation - delete a vacation event from a thermostat + +```java +boolean deleteVacation(String name) +``` + +``` +Parameters: +name - Name of vacation to be deleted. + +Returns - true if the operation was successful, false otherwise +``` + +### Reset Preferences + +The reset preferences function sets all of the user configurable settings back +to the factory default values. +This function call will not only reset the top level thermostat settings such +as hvacMode, lastServiceDate and vent, but also all of the user configurable +fields of the thermostat.settings and thermostat.program objects. +Note that this does not reset all values. +For example, the installer settings and wifi details remain untouched. + +##### resetPreferences - Sets all user configurable settings back to factory defaults + +```java +boolean resetPreferences() +``` + +``` +Returns - true if the operation was successful, false otherwise +``` + +### Resume program + +The resume program function removes the currently running event providing the event +is not a mandatory demand response event. +If resumeAll parameter is not set, top active event is removed from the stack and +the thermostat resumes its program, or enters the next event in the stack if one exists. +If resumeAll parameter set to true, the function resumes all events and returns the thermostat to its program. + +##### resumeProgram - Remove the currently running event + +```java +boolean resumeProgram(Boolean resumeAll) +``` + +``` +Parameters: +resumeAll - Indicates if the thermostat should be resumed to next event (false) or to its program (true). + +Returns - true if the operation was successful, false otherwise +``` + +### Send Message + +The send message function allows an alert message to be sent to the thermostat. +The message properties are same as those of the Alert Object. + +##### - sendMessage - Send a message to a thermostat + +```java +boolean sendMessage(String text) +``` + +``` +Parameters: +text - Text of message to be sent to the thermostat. + +Returns - true if the operation was successful, false otherwise +``` + +### Set Hold + +The set hold function sets the thermostat into a hold with the specified temperature. +Creates a hold for the specified duration. +Note that an event is created regardless of whether the program is in the same state as the requested state. + +There is also support for creating a hold by passing a holdClimateRef request parameter/value pair to this function. +When an existing and valid Climate.climateRef value is passed to this function, the coolHoldTemp, +heatHoldTemp and fan mode from that Climate are used in the creation of the hold event. +The values from that Climate will take precedence over any coolHoldTemp, heatHoldTemp and fan mode +parameters passed into this function separately. + +To resume from a hold and return to the program, use the `resumeProgram` function. + +##### setHold - Set an indefinite hold using the supplied coolHoldTemp and heatHoldTemp + +```java +boolean setHold(QuantityType coolHoldTemp, QuantityType heatHoldTemp) +``` + +``` +Parameters: +coolHoldTemp - The temperature to set the cool hold at. +heatHoldTemp - The temperature to set the heat hold at. + +Returns - true if the operation was successful, false otherwise +``` + +##### setHold - Set a hold using the supplied cool and heat temperatures that lasts for the specified number of hours + +```java +boolean setHold(QuantityType coolHoldTemp, QuantityType heatHoldTemp, Number holdHours) +``` + +``` +Parameters: +coolHoldTemp - The temperature to set the cool hold at. +heatHoldTemp - The temperature to set the heat hold at. +holdHours - Duration of hold. + +Returns - true if the operation was successful, false otherwise +``` + +##### setHold - Set an indefinite hold using the supplied climate ref + +```java +boolean setHold(String climateRef) +``` + +``` +Parameters: +climateRef - Climate to be applied to thermostat (e.g. home, away). + +Returns - true if the operation was successful, false otherwise +``` + +##### setHold - Set a hold using the supplied climate ref that lasts for the specified number of hours + +```java +boolean setHold(String climateRef, Number holdHours) +``` + +``` +Parameters: +climateRef - Climate to be applied to thermostat (e.g. home, away). +holdHours - Duration of hold. + +Returns - true if the operation was successful, false otherwise +``` + +##### setHold + +```java +boolean setHold(QuantityType coolHoldTemp, QuantityType heatHoldTemp, String holdClimateRef, Date startDateTime, Date endDateTime, String holdType, Number holdHours) +``` + +``` +Parameters: +coolHoldTemp - The temperature to set the cool hold at. +heatHoldTemp - The temperature to set the heat hold at. +holdClimateRef - Climate to be applied to thermostat (e.g. home, away). +startDateTime - The start date/time of the hold. +endDateTime - The end date/time of the hold. +holdType - The hold duration type. Valid values: dateTime, nextTransition, indefinite, holdHours. +holdHours - Duration of hold. + +Returns - true if the operation was successful, false otherwise +``` + +##### setHold + +```java +boolean setHold(Map params, String holdType, Number holdHours, Date startDateTime, Date endDateTime) + +Parameters: +params - The map of hold parameters. +holdType - The hold duration type. Valid values: dateTime, nextTransition, indefinite, holdHours. +holdHours - Duration of hold. +startDateTime - The start date/time of the hold. +endDateTime - The end date/time of the hold. + +Returns - true if the operation was successful, false otherwise +``` + +### Set Occupied + +The set occupied function may only be used by EMS thermostats. +The function switches a thermostat from occupied mode to unoccupied, or vice versa. +If used on a Smart thermostat, the function will throw an error. +Switch occupancy events are treated as Holds. +There may only be one Switch Occupancy at one time, and the new event will replace any previous event. + +Note that an occupancy event is created regardless what the program on the thermostat is set to. +For example, if the program is currently unoccupied and you set occupied=false, an occupancy event +will be created using the heat/cool settings of the unoccupied program climate. +If your intent is to go back to the program and remove the occupancy event, use resumeProgram instead. + +##### setOccupied - + +```java +boolean setOccupied(Boolean occupied, Date startDateTime, Date endDateTime, String holdType, Number holdHours) +``` + +``` +Parameters: +occupied - The climate to use for the temperature, occupied (true) or unoccupied (false). +holdType - The hold duration type. Valid values: dateTime, nextTransition, indefinite, holdHours. +holdHours - Duration of hold. +startDateTime - The start date/time. +endDateTime - The end date/time. + +Returns - true if the operation was successful, false otherwise +``` + +### Update Sensor + +The update sensor function allows the caller to update the name of an ecobee3 remote sensor. + +Each ecobee3 remote sensor "enclosure" contains two distinct sensors types temperature and occupancy. +Only one of the sensors is required in the request. +Both of the sensors' names will be updated to ensure consistency as they are part of the +same remote sensor enclosure. +This also reflects accurately what happens on the Thermostat itself. + +##### updateSensor - Update the name of a sensor + +```java +boolean updateSensor(String name, String deviceId, String sensorId) +``` + +``` +Parameters: +name - The updated name to give the sensor. Has a max length of 32, but shorter is recommended. +deviceId - The deviceId for the sensor, typically this indicates the enclosure and corresponds to the ThermostatRemoteSensor.id field. For example: rs:100 +sensorId - The idendifier for the sensor within the enclosure. Corresponds to the RemoteSensorCapability.id. For example: 1 + +Returns - true if the operation was successful, false otherwise +``` + +### Get Alerts + +##### getAlerts - Get the list of alerts + +```java +String getAlerts() +``` + +``` +Returns - A JSON string representing the array of alerts for the thermostat, or null if there are no alerts. +``` + +### Get Events + +##### getEvents - Get the list of events + +```java +String getEvents() +``` + +``` +Returns - A JSON string representing the array of events for the thermostat, or null if there are no events. +``` + +### Get Climates + +##### getClimates - Get the list of climates configured on this thermostat + +```java +String getClimates() +``` + +``` +Returns - A JSON string representing the array of climates for the thermostat. +``` + +## Full Example + +### Things + +``` +Bridge ecobee:account:account "Ecobee Account" [ apiKey="kjafhd4YTiucye48yn498n94c8ufn49", refreshIntervalNormal=30, refreshIntervalQuick=5, apiTimeout=20, discoveryEnabled=false ] { + Bridge thermostat 32122305166 "Ecobee First Floor Thermostat" [ thermostatId="32122305166" ] { + Thing sensor ei-0 "Ecobee Sensor Thermostat" [ sensorId="ei:0" ] { + Channels: + Type sensorTemperature : temperature [ ] + Type sensorHumidity : humidity [ ] + Type sensorOccupancy : occupancy [ ] + } + Thing sensor rs-101 "Ecobee Sensor Room 1" [ sensorId="rs:101" ] { + Channels: + Type sensorTemperature : temperature [ ] + Type sensorOccupancy : occupancy [ ] + } + Thing sensor rs-100 "Ecobee Sensor Room 2" [ sensorId="rs:100" ] { + Channels: + Type sensorTemperature : temperature [ ] + Type sensorOccupancy : occupancy [ ] + } + } + Bridge thermostat 385421394655 "Ecobee Upstairs Thermostat" [ thermostatId="385421394655" ] { + } +} +``` + +### Items + +``` +Group gInfo "Information" +Group gRuntime "Runtime" +Group gEquipmentStatus "Equipment Status" +Group gSettings "Settings" +Group gProgram "Program" +Group gAlert "First Alert in Alert List" +Group gEvent "Currently Running Event" +Group gWeather "Weather Forecast" +Group gVersion "Version" +Group gLocation "Location" +Group gHouseDetails "House Details" +Group gManagement "Management" +Group gTechnician "Technician" +Group gThermostatSensor "Thermostat Sensor" +Group gRoom1Sensor "Room 1 Sensor" +Group gRoom2Sensor "Room 2 Sensor" + +// Info group +String Info_Identifier "Thermostat Identifier [%s]" (gInfo) { channel="ecobee:thermostat:account:729318833078:info#identifier" } +String Info_Name "Thermostat Name [%s]" (gInfo) { channel="ecobee:thermostat:account:729318833078:info#name" } +String Info_ThermostatRev "Thermostat Rev [%s]" (gInfo) { channel="ecobee:thermostat:account:729318833078:info#thermostatRev" } +Switch Info_IsRegistered "Is Registered [%s]" (gInfo) { channel="ecobee:thermostat:account:729318833078:info#isRegistered" } +String Info_ModelNumber "Model Number [%s]" (gInfo) { channel="ecobee:thermostat:account:729318833078:info#modelNumber" } +String Info_Brand "Brand [%s]" (gInfo) { channel="ecobee:thermostat:account:729318833078:info#brand" } +String Info_Features "Features [%s]" (gInfo) { channel="ecobee:thermostat:account:729318833078:info#features" } +DateTime Info_LastModified "Last Modified [%1$tA, %1$tm/%1$td/%1$tY %1$tl:%1$tM %1$tp]"