A FHEM extension to interact with Tado cloud
Latest Update:
29.12.2020:
- Implemented OAuth Authentication (Thanks to Psych160)
- Updated this readme and the module help
The FHEM extension requires two files:
- 98_Tado.pm
- 98_TadoDevice.pm
The extension is build based on the two-tier module concept. The 98_Tado.pm contains the source code to define a Tado device. The Tado device acts like a bridge and manages the communication towards the Tado cloud. The 98_TadoDevice.pm contains the code to define the different TadoDevices. The devices do represent either a physical device represented by a serial number, a so called zone basically representing a room or the weather channel containing the weather data used by Tado to optimize the heating times.
- - Parse the several date information and bring this to local time
- - Add validation on inserted serial numbers
-
Tado implements an interface to the Tado cloud. The plugin can be used to read and write temperature and settings from or to the Tado cloud. The communication is based on the reengineering of the protocol done by Stephen C. Phillips. See his blog for more details. Not all functions are implemented within this FHEM extension. By now the plugin is capable to interact with the so called zones (rooms) and the registered devices. The devices cannot be controlled directly. All interaction - like setting a temperature - must be done via the zone and not the device. This means all configuration like the registration of new devices or the assignment of a device to a room must be done using the Tado app or Tado website directly. Once the configuration is completed this plugin can be used. This device is the 'bridge device' like a HueBridge or a CUL. Per zone or device a dedicated device of type 'TadoDevice' will be created.
- Tado Bridge
- Manages the communication towards the Tado cloud environment and documents the status in several readings like which data was refreshed, when it was rerefershed, etc.
- Overall Presence status Indicates wether at least one mobile device is 'at Home'
- Overall Air Comfort Indicates the air comfort of the whole home.
- Zone (basically a room)
- Temperature Management: Displays the current temperature, allows to set the desired temperature including the Tado modes which can do this manually or automatically
- Zone Air Comfort Indicates the air comfort of the specific room.
- Device
- Connection State: Indicate when the actual device was seen the last time
- Battery Level Indicates the current battery level of the device.
- Find device Output a 'Hi' message on the display to identify the specific device
- Mobile Device<
- Device Configration: Displays information about the device type and the current configuration (view only)
- Presence status Indicates if the specific mobile device is Home or Away.
- Weather
- Displays information about the ouside waether and the solar intensity (cloud source, not actually measured).
- interval
Sets how often the values shall be refreshed. This setting overwrites the value set during define. - start
(Re)starts the automatic refresh. Refresh is autostarted on define but can be stopped using stop command. Using the start command FHEM will start polling again. - stop
Stops the automatic polling used to refresh all values. - presence
Sets the presence value for the whole Tado account. You can set the status to HOME or AWAY and depending on the status all devices will chnange their confiration between home and away mode. If you're using the mobile devices and the Tado premium feature using geofencing to determine home and away status you should not use this function. - home
Gets the home identifier from Tado cloud. The home identifier is required for all further actions towards the Tado cloud. Currently the FHEM extension only supports a single home. If you have more than one home only the first home is loaded.
This function is automatically executed once when a new Tado device is defined. - zones
Every zone in the Tado cloud represents a room. This command gets all zones defined for the current home. Per zone a new FHEM device is created. The device can be used to display and overwrite the current temperatures. This command can always be executed to update the list of defined zones. It will not touch any existing zone but add new zones added since last update.
This function is automatically executed once when a new Tado device is defined. - update
Updates the values of:
- All Tado zones
- The presence status of the whole tado account
- All mobile devices - if attribute generateMobileDevices is set to true
- All devices - if attribute generateDevices is set to true
- The weather device - if attribute generateWeather is set to true
- devices
Fetches all devices from Tado cloud and creates one TadoDevice instance per fetched device. This command will only be executed if the attribute generateDevices is set to yes. If the attribute is set to no or not existing an error message will be displayed and no communication towards Tado will be done. This command can always be executed to update the list of defined devices. It will not touch existing devices but add new ones. Devices will not be updated automatically as there are no values continuously changing. - mobile_devices
Fetches all defined mobile devices from Tado cloud and creates one TadoDevice instance per mobile device. This command will only be executed if the attribute generateMobileDevices is set to yes. If the attribute is set to no or not existing an error message will be displayed and no communication towards Tado will be done. This command can always be executed to update the list of defined mobile devices. It will not touch existing devices but add new ones. - weather
Creates or updates an additional device for the data bridge containing the weather data provided by Tado. This command will only be executed if the attribute generateWeather is set to yes. If the attribute is set to no or not existing an error message will be displayed and no communication towards Tado will be done. - generateDevices
By default the devices are not fetched and displayed in FHEM as they don't offer much functionality. The functionality is handled by the zones not by the devices. But the devices offers an identification function sayHi to show a message on the specific display. If this function is required the Devices can be generated. Therefor the attribute generateDevices must be set to yes
If this attribute is set to no or if the attribute is not existing no devices will be generated.. - generateMobileDevices
By default the mobile devices are not fetched and displayed in FHEM as most users already have a person home recognition. If Tado shall be used to identify if a mobile device is at home this can be done using the mobile devices. In this case the mobile devices can be generated. Therefor the attribute generateMobileDevices must be set to yes
If this attribute is set to no or if the attribute is not existing no mobile devices will be generated.. - generateWeather
By default no weather channel is generated. If you want to use the weather as it is defined by the tado system for your specific environment you must set this attribute. If the attribute generateWeather is set to yes an additional weather channel can be generated.
If this attribute is set to no or if the attribute is not existing no Devices will be generated.. - DeviceCount
Indicates how many devices (hardware devices provided by Tado) are registered in the linked Tado Account.
This reading will only be available / updated if the attribute generateDevices is set to yes. - LastUpdate_Devices
Indicates when the last successful request to update the hardware devices (TadoDevices) was send to the Tado API. his reading will only be available / updated if the attribute generateDevices is set to yes. - HomeID
Unique identifier for your Tado account instance. All devices are linked to your homeID and the homeID required for almost all Tado API requests. - HomeName
Name of your Tado home as you have configured it in your Tado account. - Presence
The current presence status of your home. The status can be HOME or AWAY and is valid for the whole home and all devices and zones linked to this home. The Presence reading can be influences by the set presence command or based on geofencing using mobile devices. - airComfort_freshness
The overall fresh air indicator for your home. Represents a summary of the single indicators per zone / room. - airComfort_lastWindowOpen
Inidcates the last time an open window was detected by Tado to refresh the air within the home. - LastUpdate_AirComfort
Indicates when the last successful request to update the air comfort was send to the Tado API. - LastUpdate_MobileDevices
Indicates when the last successful request to update the mobile devices was send to the Tado API. his reading will only be available / updated if the attribute generateMobileDevices is set to yes. - LastUpdate_Weather
Indicates when the last successful request to update the weather was send to the Tado API. his reading will only be available / updated if the attribute generateWeather is set to yes. - LastUpdate_Zones
Indicates when the last successful request to update the zone / room data was send to the Tado API.
The following features / functionalities are defined by now when using Tado and TadoDevices:
While previous versions of this plugin were using plain authentication encoding the username and the password directly in the URL this version now uses OAuth2 which does a secure authentication and uses security tokens afterwards. This is a huge security improvement. The implementation is based on code written by Philipp (Psycho160). Thanks for sharing.
Define
define <name> Tado <username> <password> <interval>
Example:
define TadoBridge Tado [email protected] somepassword 120
The username and password must match the username and password used on the Tado website. Please be aware that username and password are stored and send as plain text. They are visible in FHEM user interface. It is recommended to create a dedicated user account for the FHEM integration. The Tado extension needs to pull the data from the Tado website. The 'Interval' value defines how often the value is refreshed.
Set
set <name> <option>
The set command just offers very limited options. If can be used to control the refresh mechanism. The plugin only evaluates the command. Any additional information is ignored.
Options:
Get
get <name> <option>
You can get the major information from the Tado cloud.
Options:
Attributes
attr <name> <attribute> <value>
You can change the behaviour of the Tado Device.
Attributes:
Generated Readings/Events:
-
TadoDevice is the implementation of a zone, a device, a mobile device or the weather channel connected to one Tado instance and therefor one tado cloud account. It can only be used in conjunction with a Tado instance (a Tado bridge). The TadoDevice is intended to display the current measurements of a zone or device and allow the interaction. It can be used to set or reset the temperature within a zone or to display a "hi" statement on a physical Tado device. It can also be used to identify which mobile devices are at home. TadoDevices should not be created manually. They are auto generated once a Tado device is defined.
- sayHi
Works on devices only. Sends a request to the a specific physical device. Once the request reaches the device the device displays "HI". Command can be used to identify a physical device. - automatic
Works on zones only. Resets all temperature settings for a zone. The plan defined in the cloud (either by app or browser) will be used to set the temperature - off
Works on zones only. Turns the heating in the specific zone completely off. The setting will be kept until a new temperature is defined via app, browser or FHEM. - temperature
Works on zones only. Sets the temperature for a zone. The setting will be kept until a new temperature is defined via app, browser or FHEM. Value can be off or any numeric value between 4.0 and 25.0 with a precision of 0.1 degree. - temperature-for-60
Works on zones only. Sets the temperature for a zone for 60 minutes only. The temperature will be kept for 60 minutes. Afterwards the zone will fall back to the standard plan defined in app or web. Value definition is like for command set temperature. - temperature-for-90
Works on zones only. Sets the temperature for a zone for 90 minutes only. The temperature will be kept for 90 minutes. Afterwards the zone will fall back to the standard plan defined in app or web. Value definition is like for command set temperature. - temperature-for-120
Works on zones only. Sets the temperature for a zone for 120 minutes only. The temperature will be kept for 120 minutes. Afterwards the zone will fall back to the standard plan defined in app or web. Value definition is like for command set temperature. - temperature-for-180
Works on zones only. Sets the temperature for a zone for 180 minutes only. The temperature will be kept for 180 minutes. Afterwards the zone will fall back to the standard plan defined in app or web. Value definition is like for command set temperature. - temperature-for-240
Works on zones only. Sets the temperature for a zone for 240 minutes only. The temperature will be kept for 240 minutes. Afterwards the zone will fall back to the standard plan defined in app or web. Value definition is like for command set temperature. - temperature-for-300
Works on zones only. Sets the temperature for a zone for 300 minutes only. The temperature will be kept for 300 minutes. Afterwards the zone will fall back to the standard plan defined in app or web. Value definition is like for command set temperature. - Update
This get command is available on zones, weather and mobile devices This call updates the readings of a TadoDevie with the latest values available in the Tado cloud. - earlyStart true|false
When set to true the Tado system starts to heat up before the set heating change. The intention is to reach the target temperature right at the point in time defined. E.g. if you want to change the temperature from 20 degree to 22 degree on 6pm early start would start heating at 5:30pm so the zone is on 22 degree at 6pm. The early start is a feature of Tado. How this is calculated and how early the heating is started is up to Tado. - Basic readings
Contains a list of the basic readings beeing available all the time. This is mainly the status of the room, the actual measured values and the desired values. - date_created
Indicates when this zone was created within the Tado account (not within FHEM). - link
Indicates if the Tado hardware in the specific zone is currently ONLINE or OFFLINE. - tado-mode
Indicates if the heating parameters applied to the specific zone are based on the HOME or the AWAY configuration. - desired-temp
The desired room or water temperature. - measured-temp
The temperature measured by the Tado device in the specific zone / room in °C - measured-temp-fahrenheit
The temperature measured by the Tado device in the specific zone / room in °F - measured-temp-precision
Indicates the precision of the data beeing provided in measured-temp reading. - measured-temp-precision-fahrenheit
Indicates the precision of the data beeing provided in measured-temp-fahrenheit reading. - measured-temp-timestamp
Indicates when the values in measured-temp and measured-temp-fahrenheit were actually measured.
If the connection between the Tado bridge and the Tado webserver is broken values may get aged. This can be identified using this reading. - measured-humidity
The humidity measured by the Tado device in the specific zone / room in % - measured-humidity-timestamp
Indicates when the value in measured-humidity was actually measured.
If the connection between the Tado bridge and the Tado webserver is broken values may get aged. This can be identified using this reading. - heating-percentage
If your heating is capable to run in a more fine grained operation mode than purly ON and OFF and Tado is capable to control the heating on this level, the current heating level in percent is contained in this reading.
Example: If you do have a floor heating the heating temperature is controlled by a valve which can be opened in 10% steps. In this case this reading contains valid values. - heating-percentage-timestamp
Indicates when the value in heating-percentage was actually measured.
If the connection between the Tado bridge and the Tado webserver is broken values may get aged. This can be identified using this reading. - open-window
If tado recognizes an open window within the current zone / room this reading contains the timestamp since when the window is open. If no open window is detected the reading contains the value null - supportsDazzle
Tado dazzle mode shows status changes made via web or mobile app on the Tado device. E.g. if you change the temperature in a zone / room via app, the Tado device displays the new temperature for some seconds so you can check you chnaged the correct device. This reading indicates if the current zone / room and the devices within support dazzle mode. - Scheduled Changes
Tado supports so called intelligent schedules. Within an intelligent schedule certain timeframes are defined and within the timeframes the desired temperature is set. As the intelligent part of the feature Tado documents previous heating cycles and knows the time it takes to heat up. So Tado starts heating before the scheduled date so the room is already at desired temperature when the schedule changes. A zone / room can have different intelligent schedules depending on the tado-mode HOME and AWAY. - nextScheduleChange-start
This reading indicates when the next interval of the schedule will begin. - nextScheduleChange-power
This reading indicates weather the zone will be powered or not on the next change. This could be a heating turned on or a warm water boiler turned to heating mode. - nextScheduleChange-temperature
This reading indicates the desired temperature for the next scheduled change. - Overlay - Manual temperature adjustments
If you manually adjust the temperature for a zone / room either using the Tado device or the Tado app this is calles an override. An override can be temporary and will end after a certain time periode or it is infinite and stays active until it is ended by the user. - overlay-active
This reading indicates if such an override is active (1) or inactive (0). - overlay-desired-temperature
This reading indicates the desired temperature while the overlay is active. - overlay-mode
This reading indicates the mode of the overlay. - overlay-power
This reading indicates if the heating, boiler or AC is turned on while the overlay is active. - overlay-termination-mode
This reading indicates the termination mode currently active. MANUAL indicates the current mode will be active until it is changed by the user and TIMER means it automatically gets disabled once the timer is expired. - overlay-termination-durationInSeconds
This reading indicates how long the overlay will be active in seconds. - overlay-termination-expiry
This reading indicates the date and time when the overlay will expire and Tado will return to automatic operation. - overlay-termination-remainingTimeInSeconds
This reading indicates the remaining time in seconds until the zone / room will be turned back to automatic operation. - Overlay - Manual temperature adjustments
The measured humidity and temperature in a room are evaluated and an air comfort is calculated. The air comfort is provided in english, human readable words for humidity and temperature and by a radar chart visualizing the air comfort. The graph is displayed in the Tado app but cannnot be displayed in FHEM. But you can use the angular and radial values to create your own radar chart. - airComfort_humidityLevel
An english, human readable expression defining the air comfort of your current humidity level. - airComfort_temperatureLevel
An english, human readable expression defining the air comfort of your current temperature level. - airComfort_graph_angular
A radar chart has an angular and a radial axis. This reading contains the numeric value for the angular axis. - airComfort_graph_radial
A radar chart has an angular and a radial axis. This reading contains the numeric value for the radial axis. - batteryState
The state of the battery for the Tado hardware device. - connectionState
The current connection state. - connectionStateLastUpdate
Date and time when the current connection state was registered in the Tado cloud application. - currentFwVersion
The firmware version of the Tado hardware. - inPairingMode
Indicates if a Tado bridge device is in pairing mode and accepts new Tado devices. - device_locale
The languange settings for the device. - device_model
The model or make of the device. - device_os_version
The operating system version of the device. - device_platform
The software platform of the device. - geoTrackingEnabled
Indicates if geofencing is enabled for the device. If geofencing is enabled Tado can switch between the presence modes of HOME and AWAY. To automatically switch you do need a paid premium plan. Otherwise you get a push notification on your mobile and can invoke a status change. - pushNotification_LowBatteryReminder
Indicates if the device will get a push notification if the battery of a Tado device is running low. - pushNotification_awayModeReminder
Indicates if the device will get a push notification if the geofencing detects leaving a fenced area and offers to swicth to AWAY mode. - pushNotification_homeModeReminder
Indicates if the device will get a push notification if the geofencing detects entering a fenced area and offers to swicth to HOME mode. - pushNotification_energySavingsReportReminder
Indicates if the device will get a push notification once a new energy saving report is available in Tado Cloud. - pushNotification_openWindowReminder
Indicates if the device will get a push notification if an open window was detected and offers to temporary turn of the heating. - The Tado weather is not measured using your local devices. Tado is using weather data from a service provider and the address you configured when creating your Tado account to estimate your local weather. There may be internet data of local weather stations or your own weather station providing much more accurate data.
- outsideTemperature
The current outside temperature. - outsideTemperature-timestamp
The timestamp when current outside temperature was updated. - solarIntensity
The current solar intensity - the relative brightness of the sub in % - solarIntensity-timestamp
The timestamp when current solar intensity was updated. - weatherState
An english, human readable text describing the current weather conditions. - weatherState-timestamp
The timestamp when current weather state was updated.
Define
define <name> TadoDevice <TadoId> <IODev=IODeviceId>
Example:
define kitchen TadoDevice 1 IODev=TadoBridge
Normally the define statement should be called by the Tado device. If called manually the TadoId and the IO-Device must be provided. The TadoId is either the zone Id if a zone shall be created or the serial number of a physical device. The IO-Device must be of type Tado.
Set
set <name> <option> <value>
What can be done with the set command is depending on the subtype of the TadoDevice. For all thermostats it is possible to set the temperature using the automatic, temperature and temperature-for options. For all physical devices the sayHi option is available.
Options:
Get
get <name> <option>
The only available get function is called update and can be used to update all readings of the specific TadoDevice.
Options:
Attributes
attr <name> <attribute> <value>
There is one attribute available. It only affects zones.
Attributes:
Generated Readings/Events for subtype zone:
Generated Readings/Events for subtype thermostat and bridge:
Generated Readings/Events for subtype mobile_device:
Generated Readings/Events for subtype weather: