1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
# PyTado -- Pythonize your central heating
[](https://github.com/wmalgadey/PyTado/actions/workflows/lint-and-test-matrix.yml)
[](https://github.com/wmalgadey/PyTado/actions/workflows/publish-to-pypi.yml)
[](https://badge.fury.io/py/python-tado)
[](https://codecov.io/github/wmalgadey/PyTado)
[![Open in Dev Containers][devcontainer-shield]][devcontainer]
PyTado is a Python module implementing an interface to the Tado web API. It allows a user to interact with their
Tado heating system for the purposes of monitoring or controlling their heating system, beyond what Tado themselves
currently offer.
It is hoped that this module might be used by those who wish to tweak their Tado systems, and further optimise their
heating setups.
---
Original author: Chris Jewell <chrism0dwk@gmail.com>
Licence: GPL v3
Copyright: Chris Jewell 2016-2018
## Disclaimer
Besides owning a Tado system, I have no connection with the Tado company themselves. PyTado was created for my own use,
and for others who may wish to experiment with personal Internet of Things systems. I receive no help (financial or
otherwise) from Tado, and have no business interest with them. This software is provided without warranty, according to
the GNU Public Licence version 3, and should therefore not be used where it may endanger life, financial stakes, or
cause discomfort and inconvenience to others.
## Usage
As of the 15th of March 2025, Tado has updated their OAuth2 authentication flow. It will now use the device flow, instead of a username/password flow. This means that the user will have to authenticate the device using a browser, and then enter the code that is displayed on the browser into the terminal.
PyTado handles this as following:
1. The `_login_device_flow()` will be invoked at the initialization of a PyTado object. This will start the device flow and will return a URL and a code that the user will have to enter in the browser. The URL can be obtained via the method `device_verification_url()`. Or, when in debug mode, the URL will be printed. Alternatively, you can use the `device_activation_status()` method to check if the device has been activated. It returns three statuses: `NOT_STARTED`, `PENDING`, and `COMPLETED`. Wait to invoke the `device_activation()` method until the status is `PENDING`.
2. Once the URL is obtained, the user will have to enter the code that is displayed on the browser into the terminal. By default, the URL has the `user_code` attached, for the ease of going trough the flow. At this point, run the method `device_activation()`. It will poll every five seconds to see if the flow has been completed. If the flow has been completed, the method will return a token that will be used for all further requests. It will timeout after five minutes.
3. Once the token has been obtained, the user can use the PyTado object to interact with the Tado API. The token will be stored in the `Tado` object, and will be used for all further requests. The token will be refreshed automatically when it expires.
The `device_verification_url()` will be reset to `None` and the `device_activation_status()` will return `COMPLETED`.
### Screenshots of the device flow
### How to not authenticate the device again
It is possible to save the refresh token and reuse to skip the next login.
The following code will use the `refresh_token` file to save the refresh-token after login, and load the refresh-token if you create the Tado interface class again.
If the file doesn't exists, the webbrowser is started and the device authentication url is automatically opened. You can activate the device in the browser. When you restart the program, the refresh-token is reused and no webbrowser will be opened.
```python
import webbrowser # only needed for direct web browser access
from PyTado.interface.interface import Tado
tado = Tado(token_file_path="/var/tado/refresh_token")
status = tado.device_activation_status()
if status == "PENDING":
url = tado.device_verification_url()
webbrowser.open_new_tab(url)
tado.device_activation()
status = tado.device_activation_status()
if status == "COMPLETED":
print("Login successful")
else:
print(f"Login status is {status}")
```
## Example code
```python
"""Example client for PyTado"""
from PyTado.interface.interface import Tado
def main() -> None:
"""Retrieve all zones, once successfully logged in"""
tado = Tado()
print("Device activation status: ", tado.device_activation_status())
print("Device verification URL: ", tado.device_verification_url())
print("Starting device activation")
tado.device_activation()
print("Device activation status: ", tado.device_activation_status())
zones = tado.get_zones()
print(zones)
if __name__ == "__main__":
main()
```
Note: For developers, there is an `example.py` script in `examples/` which is configured to fetch data from your account.
You can then invoke `python examples/example.py`.
## Contributing
We are very open to the community's contributions - be it a quick fix of a typo, or a completely new feature!
You don't need to be a Python expert to provide meaningful improvements. To learn how to get started, check out our
[Contributor Guidelines](https://github.com/wmalgadey/econnect-python/blob/main/CONTRIBUTING.md) first, and ask for help
in [GitHub Discussions](https://github.com/wmalgadey/PyTado/discussions) if you have questions.
## Development
We welcome external contributions, even though the project was initially intended for personal use. If you think some
parts could be exposed with a more generic interface, please open a [GitHub issue](https://github.com/wmalgadey/PyTado/issues)
to discuss your suggestion.
### Setting up a devcontainer
The easiest way to start, is by opening a CodeSpace here on GitHub, or by using
the [Dev Container][devcontainer] feature of Visual Studio Code.
[![Open in Dev Containers][devcontainer-shield]][devcontainer]
### Dev Environment
To contribute to this repository, you should first clone your fork and then setup your development environment. Clone
your repository as follows (replace yourusername with your GitHub account name):
```bash
git clone https://github.com/yourusername/PyTado.git
cd PyTado
```
Then, to create your development environment and install the project with its dependencies, execute the following
commands in your terminal:
```bash
# Create and activate a new virtual environment
python3 -m venv venv
source venv/bin/activate
# install all dependencies
poetry install
# Install pre-commit hooks
poetry run pre-commit install
```
### Coding Guidelines
To maintain a consistent codebase, we utilize [black][1]. Consistency is crucial as it helps readability, reduces errors,
and facilitates collaboration among developers.
To ensure that every commit adheres to our coding standards, we've integrated [pre-commit hooks][2]. These hooks
automatically run `black` before each commit, ensuring that all code changes are automatically checked and formatted.
For details on how to set up your development environment to make use of these hooks, please refer to the
[Development][3] section of our documentation.
[1]: https://github.com/ambv/black
[2]: https://pre-commit.com/
[3]: https://github.com/wmalgadey/PyTado#development
### Testing
Ensuring the robustness and reliability of our code is paramount. Therefore, all contributions must include at least one
test to verify the intended behavior.
To run tests locally, execute the test suite using `pytest` with the following command:
```bash
pytest tests/ --cov --cov-branch -vv
```
---
A message from the original author:
> This software is at a purely experimental stage. If you're interested and can write Python, clone the Github repo,
> drop me a line, and get involved!
>
> Best wishes and a warm winter to all!
>
> Chris Jewell
[devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
[devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/wmalgadey/PyTado
|
