gonzolino / gotado

Go client for the tado° Web API

gotado

Go client for the tado° Web API. Still in early development, so only a subset of the API functionality is implemented.

Installation

Install gotado with go get:

go get github.com/gonzolino/gotado

Then you can import "github.com/gonzolino/gotado" in your packages. Have a look at the examples directory to see example code.

Usage

Authentication

Besides your tado° username and password you need a clientId and clientSecret to authenticate with the tado° API. One way to get those is to grab them from https://my.tado.com/webapp/env.js.

Getting Started

Get started by creating a client object:

tado := gotado.New("cliendId", "clientSecret")

With the client you can authenticate and start using the gotado functions:

me, err := tado.Me(ctx, "username", "password")
fmt.Printf("User Email: %s\n", me.Email)

home, err := me.GetHome(client, "My Home Name")
fmt.Printf("Home Address:\n%s\n%s %s\n", *home.Address.AddressLine1, *home.Address.ZipCode, *home.Address.City)

Just have a look at the package documentation to learn more about whats possible.

Contributing

Please feel free to submit issues and/or pull requests if you discover bugs or missing features.

gotado's Issues

Add functions to control early start

Add functions to control whether tado should ensure that a set temperature is reached when a block starts.

The relevant API endpoint is: https://my.tado.com/api/v2/homes/{homeID}/zones/{zoneID}/earlyStart. The endpoint allows GET and PUT requests. The content of the PUT request for updates should be '{"enabled": true|false}'.

Create unit tests for all functions

Besides a few exceptions, most functions are currently lacking proper unit tests.

All functions should be properly covered by unit tests.

Add function to read zone capabilities

Endpoint /api/v2/homes/<homeID>/zones/<zoneID>/capabilities gives information about the capabilities of a zone, such as the min and max temperature the thermostats in a zone support.

Add a function to read these capabilities.

Sketch stable package interface

we need to come up with a clean and stable interface for the gotado package.

A set of blackbox tests should be written to "codify" how the interface should look like and how it should work. As soon as this is in place the existing functions can be converted to the new stable interface

Update README.md for new package interface

Examples etc. in the README need to be updated for the new package interface.

Add functions to read data about tado° environment

Support the following read-only endpoints to gather information about a tado° environment:

• /api/v2/homes/\<homeID>/weather
• /api/v2/homes/\<homeID>/devices
• /api/v2/homes/\<homeID>/installations
• /api/v2/homes/\<homeID>/mobileDevices
• /api/v2/homes/\<homeID>/users

Introduce proper error type

All errors currently returned by gotado are just plain errors. We need a proper error type for gotado that contains the error message, but also the http status code of the tado API. Errors should also properly wrap the underlying error.

Manage default overlay for a zone

API endpoint https://my.tado.com/api/v2/homes/<homeid>/zones/<zoneid>/defaultOverlay allows to manage the default overlay of a zone.

Investigate what exactly can be controlled here via API and implement corresponding function (or create follow-up issues).

Set temperature offset for device

Getting the temperature offset is implemented at https://github.com/gonzolino/gotado/blob/main/device.go.

A put request to the same endpoint allows setting the offset.

Manage dazzle mode for a zone

API endpoint https://my.tado.com/api/v2/homes/<homeid>/zones/<zoneid>/dazzle allows to enable/disable dazzle mode for a zone.

Implement Get/Set function, or use Enable/Disable functions instead of Set.

Support Tado overlays

The Tado API allows to set "overlays" for zones. These overlays can be used for manual control of the heating temperature.

gotado should support getting, setting and deleting overlays for zones.

Manage open window detection for a zone

The API endpoint https://my.tado.com/api/v2/homes/<homeid>/zones/<zoneid>/openWindowDetection allows to enable and disable open window detection in a zone as well as setting the timeout.

The payload should look like this:

{
  enabled: true,
  timeoutInSeconds: 900
}

Get and Set function should be implemented for this (Set function might be splitted into Enable/Disable functions and a SetTimeout function).

Add sponsor button

Add a sponsor button to the repo.

See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository for more information

Evaluate possibility to manage schedules

Tado API should allow managing the schedule of zones. Evaluate if it is possible to add support to gotado.

Add functions to control mobile device settings

The API endpoint /api/v2/homes/<homeID>/mobileDevices/<deviceID>/settings allows to GET or PUT settings such as geo-tracking or push notifications for mobile devices.

Add functions to read and write those settings.

Add functions to control the away config

Add functions to control the away configuration of a zone

The API endpoint is https://my.tado.com/api/v2/homes/{homeID}/zones/{zoneID}/schedule/awayConfiguration. For updates, the PUT request content should look something like

{
  "type": "HEATING",
  "setting": null,
  "autoAdjust": true,
  "comfortLevel": 0
}

Add constants

Add constants for tado API parameters that only allow a defined set of values.

Add functions to control geofencing

Add functions to set the geofencing to AWAY or HOME.

Geofencing can be controlled with a PUT request to the following API endpoint: https://my.tado.com/api/v2/homes/{homeID}/presenceLock. The content of the PUT request should be '{"homePresence": "AWAY|HOME"}'. A DELETE request to the same endpoint returns geofencing into AUTO mode.

Replace deprecated `strings.Title` function in errors.go

strings.Title has been deprecated since Go 1.18 and an alternative has been available since Go 1.0: The rule Title uses for word boundaries does not handle Unicode punctuation properly. Use golang.org/x/text/cases instead. (SA1019)

Assignees: @gonzolino
Labels: