![](\"https://github.com/homebridge-plugins/homebridge-tado/blob/latest/images/tado_logo.png?raw=true\"){kind=logo}
\n\n \n
![\"CustomUI\"](\"https://i.ibb.co/tL955Lg/hb-tadoplatform-ui-test.gif\")
\n\n_(In the section below you can find more information about the functions.)_\n \n## Non Config Ui X User?\n\nThe plugin can also work without config ui x or a custom ui. If you want the config.json auto-fill feature, you have to put the following part in your config.json. This will generate a ready to use config.json with all options disabled except thermostats. After the first start, this user will get ``\"reconfigure\": false``. If you want to refresh a home, just enable ``\"reconfigure\"`` for the user and restart homebridge. If you want to add an another home, add the user credentials (username) to the array. The Plugin can handle multiple accounts. \n\n**Note:**\n\nIf you on HOOBS, you need to reboot the HOOBS server to get your first start config changes instead of restarting Homebridge/HOOBS service.\n\n```\n{\n \"bridge\": {\n ...\n },\n \"accessories\": [\n ...\n ],\n \"platforms\": [\n {\n \"name\": \"TadoPlatform\",\n \"platform\": \"TadoPlatform\",\n \"debug\": false,\n \"user\": [\n {\n \"username\": \"mail@example.com\"\n }\n ]\n }\n ]\n}\n```\nSee [Example Config](https://github.com/homebridge-plugins/homebridge-tado/blob/latest/example-config.json) for more details\n\n## Configuration\n\n## Authentication\n\nThis plugin implements the tado-supported authentication using the [Device Code Grant Flow](https://support.tado.com/en/articles/8565472-how-do-i-authenticate-to-access-the-rest-api).\n\nDuring the initial setup, the plugin will prompt you to open a specific URL in your web browser. You will then be asked to log in with your tado account and grant access to the new device. Once this process has been completed successfully, the plugin automatically handles all subsequent authentication tasks, including secure token storage, token refresh, and renewal. This ensures continuous access to the tado API v2 without further user interaction.\n\n### Custom API Configuration\n\nFor advanced use cases, the plugin allows overriding the default tado API endpoint by specifying a custom API URL through the `tadoApiUrl` parameter within each home configuration.\n\nAdditionally, it is possible to disable the built-in authentication flow entirely by setting the `skipAuth` parameter to `true`. When enabled, all API requests will be sent without an authentication token.\n\n**Important:** Use `skipAuth` only if you are certain that your setup does not require token-based authentication. Improper use may result in limited or failed communication with the tado API.\n\nFor further details and configuration examples, refer to the related discussion: \n[homebridge-tado issue #176 – Authentication Options](https://github.com/homebridge-plugins/homebridge-tado/issues/176#issuecomment-3419839118)\n\n## Polling Behavior Configuration\n\nTo better control API usage and reduce unnecessary load, the plugin provides additional polling-related options:\n\nWhen `addJitter` is enabled, a random ±10% jitter is applied to the polling interval.\n\nThe setting `nightPolling` optionally defines a longer polling interval during nighttime hours (00:00–06:00, local time). This reduces overnight API activity while maintaining normal polling behavior during the day.\n\n## Thermostat\n\nEach zone in the config.json with ``\"type\": \"HEATING\"`` and ``\"easyMode\": false`` is exposed to Apple Home as a thermostat accessory with the following features:\n\n- Current Mode: OFF | COOLING | HEATING | AUTO\n- Target Mode: OFF | HEATING | AUTO\n- Curent Temperature\n- Target Temperature\n- Built-in humidity sensor\n- Separate Humidity (if ``\"separateHumidity\": true``)\n- Separate Temperature Sensor (if ``\"separateTemperature\": true``)\n- Battery state (if ``noBattery: false``)\n- Delay Switch characteristic with timer (if ``\"delaySwitch\": true``)\n\n**Delay Switch**\nThe Delay Switch (characteristic) can be used for eg. if you have an automation with `Open Window => Thermostat Off / Close Window => Thermostat On` and you want avoid multiple state changes, u can set ``\"delaySwitch\": true``in your config and change the timer (in seconds) via a third party app. If setted correctly, the thermostat will wait eg 60 seconds before switching to ON. It can also be used for own automations if you need a switch that turns off automatically after the given perioswithout affecting your thermostats (``\"autoOffDelay\": true``)\n\n**Mode / Mode Timer**\n``mode`` for the commands to be sent with. can be 'MANUAL' for manual control until ended by the user, 'AUTO' for manual control until next schedule change in tado° app OR 'TIMER' for manual control until timer ends. ``modeTimer`` for the ``MANUAL`` mode in minutes.\n\nEach zone in the config.json with ``type: HEATING`` and ``easyMode: true`` is exposed to Apple Home as a HeaterCooler accessory with the features as above and some minor changes:\n\n- Active: ON | OFF\n- Target Mode: HEATING\n\nYou can also adjust the minimum temperature step ``\"minStep\"``, minimum temperature value ``\"minValue\"`` or maximum temperature value ``\"maxValue\"`` via config.json. \n\n- **minValue**: By default, HEATING devices, also this plugin, supports a minValue of 5° Celsius / 41° Fahrenheit. If your device has a different minValue, you can set it up here. (Incorrect minValue may cause problems!)\n- **maxValue**: By default, HEATING devices, also this plugin, supports a maxValue of 25° Celsius / 77° Fahrenheit by default. If your device has a different minValue, you can set it up here. (Incorrect maxValue may cause problems!)\n- **minStep**: Minimum step for temperature adjustment. (Default: 1, must be between 0 - 1)\n\n```\n\"homes\": [\n {\n \"zones\": [\n {\n \"active\": true,\n \"id\": 32,\n \"name\": \"Living Room\",\n \"type\": \"HEATING\",\n \"mode\": \"MANUAL\",\n \"modeTimer\": 30,\n \"delaySwitch\": true,\n \"autoOffDelay\": false,\n \"openWindowSensor\": true,\n \"openWindowSwitch\": false,\n \"separateTemperature\": false,\n \"separateHumidity\": true,\n \"mode\": \"MANUAL\",\n \"modeTimer\": 30,\n \"minValue\": 5,\n \"maxValue\": 25,\n \"minStep\": 0.5,\n \"easyMode\": false,\n \"noBattery\": false\n }\n ...\n ]\n }\n ...\n]\n```\n\n#### Open Window:\n\nEach zone with ``\"type\": \"HEATING\"`` also has the possibility to display \"OpenWindow\" contact sensors or switches in Apple Home with the following features:\n\n- Switch to enable disable open window for the zone or trigger the open window state of the zone\n- Contact sensor to show the open window state\n\n```\n\"homes\": [\n {\n \"zones\": [\n {\n \"active\": true,\n \"name\": \"Living Room\",\n \"type\": \"HEATING\",\n \"mode\": \"AUTO\"\n \"openWindowSensor\": true,\n \"openWindowSwitch\": true\n ...\n }\n ...\n ]\n }\n ...\n]\n```\n\n## Air Conditioning\n\nEach zone in the config.json with `\"type\": \"AIR_CONDITIONING\"` is exposed to Apple Home as a HeaterCooler accessory with the following features:\n\n- Current Mode: OFF | IDLE | HEATING | COOLING\n- Target Mode: OFF | HEATING | COOLING | AUTO\n- Current Temperature\n- Target Temperature (Heating/Cooling with CoolingThresholdTemperature support)\n- Built-in humidity sensor\n- Separate Humidity (if `\"separateHumidity\": true`)\n- Separate Temperature Sensor (if `\"separateTemperature\": true`)\n- Battery state (if `\"noBattery\": false`)\n- Delay Switch characteristic with timer (if `\"delaySwitch\": true`)\n\n**AC-Specific Features**\nAir conditioning zones support both heating and cooling modes with dedicated cooling threshold temperature control. Fan speed and swing controls are handled through the tado app, while Apple Home integration focuses on temperature and mode control for optimal compatibility. Note that the RotationSpeed characteristic is not supported for AC units.\n\n**Mode / Mode Timer**\n`mode` for the commands to be sent with. can be 'MANUAL' for manual control until ended by the user, 'AUTO' for manual control until next schedule change in tado° app OR 'TIMER' for manual control until timer ends. `modeTimer` for the `MANUAL` mode in minutes.\n\nYou can also adjust the minimum temperature step `\"minStep\"`, minimum temperature value `\"minValue\"` or maximum temperature value `\"maxValue\"` via config.json if needed.\n\n- **minStep**: Minimum step for temperature adjustment. (Default: 1, must be between 0 - 1)\n\n```json\n\"homes\": [\n {\n \"zones\": [\n {\n \"active\": true,\n \"id\": 45,\n \"name\": \"Living Room AC\",\n \"type\": \"AIR_CONDITIONING\",\n \"mode\": \"MANUAL\",\n \"modeTimer\": 30,\n \"delaySwitch\": true,\n \"autoOffDelay\": false,\n \"separateTemperature\": false,\n \"separateHumidity\": true,\n \"minStep\": 1,\n \"noBattery\": false\n }\n ...\n ]\n }\n ...\n]\n```\n\n## Hot Water\n\nEach zone in the config.json with ``\"type\": HOT_WATER`` and ``\"boilerTempSupport\": false`` is exposed to Apple Home as a switch (``\"accTypeBoiler: \"SWITCH\"``) or faucet (``\"accTypeBoiler: \"FAUCET\"``) accessory with the following features:\n\n- Active: ON | OFF\n\nEach zone in the config.json with ``type: HOT_WATER`` and ``boilerTempSupport: true`` is exposed to Apple Home as a HeaterCooler accessory with the following features:\n\n- Current Mode: OFF | ON\n- Target Mode: OFF | ON\n- Curent Temperature\n- Target Temperature\n- Separate Temperature Sensor (if ``separateTemperature: true``)\n\nYou can also adjust the minimum temperature step ``\"minStep\"``, minimum temperature value ``\"minValue\"`` or maximum temperature value ``\"maxValue\"`` via config.json. \n\n- **minValue**: By default, HOT WATER devices, also this plugin, supports a minValue of 30° Celsius / 86° Fahrenheit. If your device has a different minValue, you can set it up here. (Incorrect minValue may cause problems!)\n- **maxValue**: By default, HOT WATER devices, also this plugin, supports a maxValue of 65° Celsius / 149° Fahrenheit by default. If your device has a different minValue, you can set it up here. (Incorrect maxValue may cause problems!)\n- **minStep**: Minimum step for temperature adjustment. (Default: 1, must be between 0 - 1)\n\n```\n\"homes\": [\n {\n \"zones\": [\n {\n \"active\": true,\n \"id\": 1,\n \"name\": \"Bathroom\",\n \"type\": \"HOT_WATER\",\n \"mode\": \"MANUAL\",\n \"modeTimer\": 30,\n \"minValue\": 30,\n \"maxValue\": 65,\n \"minStep\": 1,\n \"separateTemperature\": true,\n \"boilerTempSupport\": false,\n \"accTypeBoiler\": \"SWITCH\"\n }\n ...\n ]\n }\n ...\n]\n```\n\n## Presence\n\nEach user or anyone sensor in the config.json is exposed to Apple Home as a occupancy (``\"accType: \"OCCUPANCY\"``) or motion (``\"accType: \"MOTION\"``) accessory. \n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": {\n \"anyone\": true,\n \"accTypeAnyone\": \"MOTION\",\n \"user\": [\n {\n \"active\": true,\n \"name\": \"Buddy 1\",\n \"accType\": \"MOTION\"\n },\n {\n \"active\": true,\n \"name\": \"Buddy 2\",\n \"accType\": \"OCCUPANCY\"\n }\n ]\n }\n ...\n }\n]\n```\n\n## Weather\n\nWeather settings allow you to display a sensor for temperature, a light bulb (```\"accTypeSolarIntensity\": \"LIGHTBULB\"```) or light sensor (```\"accTypeSolarIntensity\": \"SENSOR\"```) for sun intensity in Apple Home.\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": {\n \"temperatureSensor\": true,\n \"solarIntensity\": true,\n \"accTypeSolarIntensity\": \"LIGHTBULB\"\n }\n ...\n }\n ...\n]\n```\n\n```\n\"homes\": [\n {\n \"geolocation\": {\n \"longitude\": \"10.1234567\",\n \"latitude\": \"23.4567890\"\n },\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... }\n ...\n }\n ...\n]\n```\n\n## Special Settings\n\n### Prefer Siri Temperature\n\nThe `preferSiriTemperature` parameter controls how the plugin interprets combined **state + temperature** updates received from Apple Home. It was introduced in version **v8.6.0** to address inconsistent behavior between **Siri commands** and **Apple Home scenes**.\n\n**Background**\n\nApple Home and Siri both send temperature and state changes simultaneously — especially if a thermostat is currently turned off.\nPrior to this improvement, the plugin always switched thermostats to **AUTO** mode when a state update to AUTO and a temperature update was received simultaneously, which occasionally led to conflicts and unexpected behaviour. With `preferSiriTemperature`, users can fine-tune how these combined updates are handled, allowing a more predictable and user-friendly experience depending on whether they primarily use **Siri voice control** or **Apple Home scenes**.\n\n**Configuration**\n\nTo enable this behavior, add the parameter to your configuration:\n\n```json\n\"preferSiriTemperature\": true\n```\n\nThis option changes how combined state + temperature updates are interpreted:\n\n| Situation | Apple Home sends | Default behavior | With `preferSiriTemperature: true` |\n|------------|----------------|------------------|------------------------------------|\n| Siri: “Set to 7 °C” (while off) | `AUTO + 7 °C` | Switches to Auto | Only sets temperature to 7 °C |\n| Scene: “Auto 21 °C” | `AUTO + 21 °C` | Switches to Auto | Only sets temperature to 21 °C |\n| Scene: “Auto 5 °C” | `AUTO + 5 °C` | Switches to Auto | Switches to Auto *(fallback)* |\n\n- By default, the plugin behaves as it did prior to v8.4.0, maintaining full compatibility with existing automations and Apple Home scenes.\n- If you frequently control your thermostats via Siri, enabling `preferSiriTemperature` may provide a smoother and more natural experience.\n- If your setup relies heavily on scenes or automations, leaving this option disabled is recommended to preserve predictable mode transitions.\n\n## Extras\n\n### Central Switch\nShows a switch accessory with additional switches in Apple Home which mimics the \"Boost\" and \"Turnoff\" switch from tado. It also shows the Heater Running information as a custom characteristic for the month (in hours) and it shows also how many thermostats are in auto, manual or off mode. Its also possible to show a dummy switch withiun the central switch for eg. automation purposes.\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... },\n \"extras\": {\n \"centralSwitch\": true,\n \"runningInformation\": true\n }\n ...\n }\n ...\n]\n```\n\n#### Boost Switch\nShows a switch accessory in Apple Home (added to central switch) which mimics the \"Boost\" switch from tado and switches all heaters to max temperature. \n_Note: Central Switch needs to be truned on._\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... },\n \"extras\": {\n \"centralSwitch\": true,\n \"boostSwitch\": true\n }\n ...\n }\n ...\n]\n```\n\n#### Shedule Switch\nShows a switch accessory in Apple Home (added to central switch) which mimics the \"Shedule\" switch from tado and switches all heaters to their default shedule\n_Note: Central Switch needs to be truned on._\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... },\n \"extras\": {\n \"centralSwitch\": true,\n \"sheduleSwitch\": true\n }\n ...\n }\n ...\n]\n```\n\n#### Turnoff Switch\nShows a switch accessory in Apple Home (added to central switch) which mimics the \"Turn Off\" switch from tado and switches all heaters off\n_Note: Central Switch needs to be truned on._\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... },\n \"extras\": {\n \"centralSwitch\": true,\n \"turnoffSwitch\": true\n }\n ...\n }\n ...\n]\n```\n\n\n#### Dummy Switch\nShows a dummy switch accessory in Apple Home (added to central switch) without any functions. Can be used for eg automation purposes.\n_Note: Central Switch needs to be truned on._\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... },\n \"extras\": {\n \"centralSwitch\": true,\n \"dummySwitch\": true\n }\n ...\n }\n ...\n]\n```\n\n### Presence Lock\nShows a switch with to sub switchs within the main accessory (``\"accTypePresenceLock\": \"SWITCH\"``) or security (``\"accTypePresenceLock\": \"ALARM\"``) accessory in Apple Home with following features: HOME | AWAY | DISABLED\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... },\n \"extras\": {\n \"presenceLock\": true,\n \"accTypePresenceLock\": \"SWITCH\"\n }\n ...\n }\n ...\n]\n```\n\n### Child Lock\nEach device with ``\"type\": \"HEATING\"`` and child lock support can be exposed to Apple Home as a \"sub\" switch to the main switch accessory which can show you if child lock is enabled or you can also enable/disable child lock.\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... },\n \"extras\": {\n \"childLockSwitches\": [\n {\n \"active\": true,\n \"name\": \"Living Room Heater\",\n \"serialNumber\": \"VA1234567890\"\n },\n {\n \"active\": true,\n \"name\": \"Sleeping Room Heater\",\n \"serialNumber\": \"VA1234567890\"\n }\n ]\n }\n ...\n }\n ...\n]\n```\n\n## Telegram\n\nYou can set up the notifier to get a Telegram notification with customized messages and markdown capability when user arrives/leaves or open window detection triggers. Before you can use the \"Telegram Notification\" functionality, you need to set up a bot. Here you can find more information: [Setup Telegram Bot](https://github.com/SeydX/homebridge-fritz-platform/blob/master/docs/Telegram.md)\n\n**Hint:**\nTo better customize the messages, special characters can be set so that the plugin replaces them.\n\n**@** character will be replaced by the Accessory name\n\n**%** character will be replaced by the house name\n\n```\n\"homes\": [\n {\n \"zones\": [ ... ],\n \"extras\": { ... },\n \"presence\": { ... },\n \"weather\": { ... },\n \"telegram\": {\n \"active\": true,\n \"token\": \"136373846:HKAHEVbsuwxl0uCSIi8kdFJsheköjezz72525\",\n \"chatID\": \"-123456789\",\n \"messages\": {\n \"presence\": {\n \"user_in\": \"%: Welcome @\",\n \"user_out\": \"%: Bye Bye @\",\n \"anyone_in\": \"%: Anyone at home.\",\n \"anyone_out\": \"%: Nobody at home.\"\n },\n \"openWindow\": {\n \"opened\": \"%: Open Window activated from @!\",\n \"closed\": \"%: Open Window deactivated from @!\"\n }\n }\n }\n }\n ...\n]\n```\n\n## Supported clients\n\nThis plugin has been verified to work with the latest versions of:\n\n* Apple Home (Apple HomeKit)\n* 3rd party apps like Elgato Eve\n* Homebridge\n\n## tado X Compatibility\n\n**tado X devices are not supported.**\n\nThe new generation of tado X devices uses a completely different API endpoint (`https://hops.tado.com`) and communication methods that are not compatible with the existing tado API (`https://my.tado.com/api/v2`) used by this plugin.\n\nSupporting tado X devices would require a full integration of the new API, which is currently **not planned** due to the significant development effort involved.\n\nFor more technical details about the tado X API, see:\n- [tado X – API differences (wiki)](https://github.com/kritsel/tado-openapispec-v2/wiki/tado-X) \n- [Swagger documentation](https://kritsel.github.io/tado-openapispec-v2/swagger.html#/) \n- [Postman collection & additional resources](https://github.com/gedhi/tadox-postman-collection?tab=readme-ov-file#additional-resources)\n\nIf you are using tado X devices, please note that this plugin will **not be able to control or display** those devices at the moment.\n\n## Contributing\n\nYou can contribute to this homebridge plugin in following ways:\n\n- [Report issues](https://github.com/homebridge-plugins/homebridge-tado/issues) and help verify fixes as they are checked in.\n- Review the [source code changes](https://github.com/homebridge-plugins/homebridge-tado/pulls).\n- Contribute bug fixes.\n- Contribute changes to extend the capabilities\n\nPull requests are accepted.\n\n## Troubleshooting\n\nIf you have any issues with the plugin, you can enable the debug mode, which will provide some additional information. This might be useful for debugging issues. Open your config.json and set ``\"debug\": true``\n\n## Disclaimer\n\nAll product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.","readmeFilename":"README.md"}