pytadolog 1.0.0

CSV logger for PyTado

pytadolog is a Python module which extends the python-tado package so that data can be logged from the Tado web API to a local CSV file.

Installation

Note about PyTado

This package requires python-tado to query the TADO web API, however development of the main package appears to have stalled. There are a number of forks available on PyPI with different APIs and varying aliases (python-tadoac, python-tado (PyPI), pytado). This package was developed with python-tado v0.2.9 cloned directly from GitHub, it has been tested to be compatible with commit 00a9ab1.

Therefore, before installing pytadolog you must first install the correct version of pytado. This can be achieved using the package manager pip as below:

pip install git+https://[e-mail]/chrism0dwk/PyTado.git@00a9ab12569e84a5537c2a0517c3a6b5cbb9d535

pip can then be used to install pytadolog.

pip install pytadolog

Usage

pytadolog includes a helpful console script and can easily be invoked with:

>>> tadolog

Commandline arguments can also be provided to customise pytadolog. These can be explored using:

>>> tadolog -h

usage: __main__.py [-h] [-o OUTDIR] [--update-period UPDATE_PERIOD]
                   [--last-day LAST_DAY] [-m]

optional arguments:
  -h, --help            show this help message and exit
  -o OUTDIR, --outdir OUTDIR
                        path to output directory
  --update-period UPDATE_PERIOD
                        time in seconds between updates
  --last-day LAST_DAY   last day of week as 3 letter string
  --disable-multiproc   use single process for web query and csv saving
  -d, --debug           log debugging statements to file
  -v, --verbose         log info statements to file

CSV conversion

This package includes a handy script to convert created CSV files to Excel files. Conversion requires openpyxl to be installed. The script can be invoked from the console using:

>>> csv2excel path/to/csv

Again, console arguments can be passed to the script to customise execution:

>>> csv2excel -h

usage: csv2excel [-h] [-o OUTPATH] [--dropna] input

positional arguments:
  input                 path to csv to convert

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPATH, --outpath OUTPATH
                        path to output xlsx
  --dropna              drop NaN values in xlsx

Other methods for launching pytadolog

The package can be invoked using the main() method of the package:

>>> python -m pytadolog
Alternatively the class can be imported into Python and started explicitly:

```python
from pytadolog import TadoLogger


with TadoLogger() as tl:
    tl.start()  # Starts logging to CSV

Using the context manager ensures that scheduled events are cleaned up when the process is terminated. This can be handled explicitly by calling the close() method:

from pytadolog import TadoLogger


tl = TadoLogger()
try:
    tl.start()  # Starts logging to CSV
except KeyboardInterrupt:
    tl.close()  # Cancels scheduled events

Output

pytadolog creates a CSV file containing weather data for the registered home and set temperature, heating power, measured temperature and relative humidity of each zone in the home. This is structured using a pandas MultiIndex. The CSV is updated at the update_period which defaults to 30s as this is the fastest Tado queries connected devices. By default the CSVs will be stored in home/Documents/TadoLogs

The CSV will be structured like this:

Zone	We ather	We ather	We ather	Livin groom	Livin groom	Livin groom	Livin groom	Livin groom	Hall	Hall	Hall	Hall	Hall
Var iable	Ou tside Temp (°C)	Solar Int. (%)	We ather	Temp (°C)	R.H. (%)	Set Temp (°C)	He ating Power (%)	Open W indow	Temp (°C)	R.H. (%)	Set Temp (°C)	He ating Power (%)	Open W indow
2021- 02-20 19: 03:30	13.33	0.0	NI GHT_C LOUDY	23.88	45.0	20.0	0.0	FALSE	18.56	58.4	13.0	0.0	FALSE
2021- 02-20 19: 04:00	13.33	0.0	NI GHT_C LOUDY	23.88	45.0	20.0	0.0	FALSE	18.56	58.4	13.0	0.0	FALSE
2021- 02-20 19: 04:30	13.33	0.0	NI GHT_C LOUDY	23.88	45.0	20.0	0.0	FALSE	18.56	58.4	13.0	0.0	FALSE

pytadolog will also generate a logfile to track progress. This is stored in a logs/ subdirectory in the output directory, i.e. home/Documents/TadoLogs/logs by default.

Tado credentials

pytadolog uses keyring to store the Tado log in credentials securely using the operating system’s default keyring service.

From the keyring README:

These recommended keyring backends are supported:

• macOS Keychain

• Freedesktop Secret Service supports many DE including GNOME (requires secretstorage)

• KDE4 & KDE5 KWallet (requires dbus)

• Windows Credential Locker

Other keyring implementations are available through Third-Party Backends.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

[Black](https://black.readthedocs.io/) is used to format all Python files.

A GitHub action is set-up to automatically build and publish tagged releases to the [PyPI](https://pypi.org/project/pytadolog/) repository. All pushes to the master branch are built and published to the [TestPyPI](https://test.pypi.org/project/pytadolog/) repository.

License

MIT