tado

README

tado

Basic Go API for Tado thermostats.

Authors

• Christophe Lambin

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Documentation

Overview

Package tado provides an API Client for the Tadoº smart thermostat devices

Using this package typically involves creating an APIClient as follows:

client := tado.APIClient{
   HTTPClient: &http.Client{},
   Username: "your-tado-username",
   Password: "your-tado-password",
}

Once a client has been created, you can query tado.com for information about your different Tado devices. Currently the following three APIs are supported:

GetZones:         get the different zones (rooms) defined in your home
GetZoneInfo:      get metrics for a specified zone in your home
GetWeatherInfo:   get overall weather information
GetMobileDevices: get status of each registered mobile device

Index

• type API
• type APIClient
  • func (client *APIClient) DeleteZoneOverlay(ctx context.Context, zoneID int) error
  • func (client *APIClient) GetMobileDevices(ctx context.Context) ([]MobileDevice, error)
  • func (client *APIClient) GetWeatherInfo(ctx context.Context) (weatherInfo WeatherInfo, err error)
  • func (client *APIClient) GetZoneInfo(ctx context.Context, zoneID int) (ZoneInfo, error)
  • func (client *APIClient) GetZones(ctx context.Context) ([]Zone, error)
  • func (client *APIClient) SetZoneOverlay(ctx context.Context, zoneID int, temperature float64) error
• type ConnectionState
• type Device
  • func (device *Device) String() string
• type MobileDevice
  • func (mobileDevice *MobileDevice) String() string
• type MobileDeviceLocation
• type MobileDeviceSettings
• type Percentage
• type Temperature
• type Value
• type WeatherInfo
  • func (weatherInfo *WeatherInfo) String() string
• type Zone
  • func (zone Zone) String() string
• type ZoneInfo
  • func (zoneInfo *ZoneInfo) String() string
• type ZoneInfoActivityDataPoints
• type ZoneInfoOpenWindow
• type ZoneInfoOverlay
  • func (overlay *ZoneInfoOverlay) String() string
• type ZoneInfoOverlaySetting
  • func (setting *ZoneInfoOverlaySetting) String() string
• type ZoneInfoOverlayTermination
• type ZoneInfoSensorDataPoints
• type ZoneInfoSetting

Types

type API

type API interface {
	GetZones() (context.Context, []Zone, error)
	GetZoneInfo(context.Context, int) (ZoneInfo, error)
	GetWeatherInfo() (context.Context, WeatherInfo, error)
	GetMobileDevices() (context.Context, []MobileDevice, error)
	SetZoneOverlay(context.Context, int, float64) error
	DeleteZoneOverlay(context.Context, int) error
}

API for the Tado APIClient. Used to mock the API during unit testing

type APIClient

type APIClient struct {
	HTTPClient   *http.Client
	Username     string
	Password     string
	ClientSecret string
	AccessToken  string

	Expires      time.Time
	RefreshToken string
	HomeID       int
	// contains filtered or unexported fields
}

APIClient represents a Tado API client.

Basic example to create a Tado API client:

client := tado.APIClient{
   HTTPClient: &http.Client{},
   Username: "your-tado-username",
   Password: "your-tado-password",
}

If the default Client Secret does not work, you can provide your own secret:

client := tado.APIClient{
   HTTPClient:    &http.Client{},
   Username:     "your-tado-username",
   Password:     "your-tado-password",
   ClientSecret: "your-client-secret",
}

where your-client-secret can be found by visiting https://my.tado.com/webapp/env.js after logging in to my.tado.com

func (*APIClient) DeleteZoneOverlay

func (client *APIClient) DeleteZoneOverlay(ctx context.Context, zoneID int) error

DeleteZoneOverlay deletes the overlay (manual temperature setting) for the specified ZoneID

func (*APIClient) GetMobileDevices

func (client *APIClient) GetMobileDevices(ctx context.Context) ([]MobileDevice, error)

GetMobileDevices retrieves the status of all registered mobile devices.

func (*APIClient) GetWeatherInfo

func (client *APIClient) GetWeatherInfo(ctx context.Context) (weatherInfo WeatherInfo, err error)

GetWeatherInfo retrieves weather information for the user's Home.

func (*APIClient) GetZoneInfo

func (client *APIClient) GetZoneInfo(ctx context.Context, zoneID int) (ZoneInfo, error)

GetZoneInfo gets the info for the specified ZoneID

func (*APIClient) GetZones

func (client *APIClient) GetZones(ctx context.Context) ([]Zone, error)

GetZones retrieves the different Zones configured for the user's Home ID

func (*APIClient) SetZoneOverlay

func (client *APIClient) SetZoneOverlay(ctx context.Context, zoneID int, temperature float64) error

SetZoneOverlay sets an overlay (manual temperature setting) for the specified ZoneID

type ConnectionState

type ConnectionState struct {
	Value     bool      `json:"value"`
	Timestamp time.Time `json:"timeStamp"`
}

ConnectionState contains the connection state of a Tado device

type Device

type Device struct {
	DeviceType      string          `json:"deviceType"`
	Firmware        string          `json:"currentFwVersion"`
	ConnectionState ConnectionState `json:"connectionState"`
	BatteryState    string          `json:"batteryState"`
}

Device contains attributes of a Tado device

func (*Device) String

func (device *Device) String() string

String serializes a Device into a string. Used for logging

type MobileDevice

type MobileDevice struct {
	ID       int                  `json:"id"`
	Name     string               `json:"name"`
	Settings MobileDeviceSettings `json:"settings"`
	Location MobileDeviceLocation `json:"location"`
}

MobileDevice contains the response to /api/v2/homes/<HomeID>/mobileDevices

func (*MobileDevice) String

func (mobileDevice *MobileDevice) String() string

String serializes a MobileDevice into a string. Used for logging.

type MobileDeviceLocation

type MobileDeviceLocation struct {
	Stale  bool `json:"stale"`
	AtHome bool `json:"atHome"`
}

MobileDeviceLocation is a sub-structure of MobileDevice

type MobileDeviceSettings

type MobileDeviceSettings struct {
	GeoTrackingEnabled bool `json:"geoTrackingEnabled"`
}

MobileDeviceSettings is a sub-structure of MobileDevice

type Percentage

type Percentage struct {
	Percentage float64 `json:"percentage"`
}

Percentage contains a percentage (0-100%)

type Temperature

type Temperature struct {
	Celsius float64 `json:"celsius"`
}

Temperature contains a temperature in degrees Celsius

type Value

type Value struct {
	Value string `json:"value"`
}

Value contains a string value

type WeatherInfo

type WeatherInfo struct {
	OutsideTemperature Temperature `json:"outsideTemperature"`
	SolarIntensity     Percentage  `json:"solarIntensity"`
	WeatherState       Value       `json:"weatherState"`
}

WeatherInfo contains the response to /api/v2/homes/<HomeID>/weather

This structure provides the following key information:

OutsideTemperature.Celsius:  outside temperate, in degrees Celsius
SolarIntensity.Percentage:   solar intensity (0-100%)
WeatherState.Value:          string describing current weather (list TBD)

func (*WeatherInfo) String

func (weatherInfo *WeatherInfo) String() string

String converts WeatherInfo to a loggable string

type Zone

type Zone struct {
	ID      int      `json:"id"`
	Name    string   `json:"name"`
	Devices []Device `json:"devices"`
}

Zone contains the response to /api/v2/homes/<HomeID>/zones

func (Zone) String

func (zone Zone) String() string

String serializes a Zone into a string. Used for logging

type ZoneInfo

type ZoneInfo struct {
	Setting            ZoneInfoSetting            `json:"setting"`
	ActivityDataPoints ZoneInfoActivityDataPoints `json:"activityDataPoints"`
	SensorDataPoints   ZoneInfoSensorDataPoints   `json:"sensorDataPoints"`
	OpenWindow         ZoneInfoOpenWindow         `json:"openwindow,omitempty"`
	Overlay            ZoneInfoOverlay            `json:"overlay,omitempty"`
}

ZoneInfo contains the response to /api/v2/homes/<HomeID>/zones/<zoneID>/state

This structure provides the following key information:

Setting.Power:                              power state of the specified zone (0-1)
Temperature.Celsius:                        target temperature for the zone, in degrees Celsius
OpenWindow.DurationInSeconds:               how long an open window has been detected in seconds
ActivityDataPoints.HeatingPower.Percentage: heating power for the zone (0-100%)
SensorDataPoints.Temperature.Celsius:       current temperature, in degrees Celsius
SensorDataPoints.Humidity.Percentage:       humidity (0-100%)

func (*ZoneInfo) String

func (zoneInfo *ZoneInfo) String() string

String serializes a ZoneInfo into a string. Used for logging.

type ZoneInfoActivityDataPoints

type ZoneInfoActivityDataPoints struct {
	HeatingPower Percentage `json:"heatingPower"`
}

ZoneInfoActivityDataPoints contains the zone's heating info

type ZoneInfoOpenWindow

type ZoneInfoOpenWindow struct {
	DetectedTime           time.Time `json:"detectedTime"`
	DurationInSeconds      int       `json:"durationInSeconds"`
	Expiry                 time.Time `json:"expiry"`
	RemainingTimeInSeconds int       `json:"remainingTimeInSeconds"`
}

ZoneInfoOpenWindow contains info on an open window. Only set if a window is open

type ZoneInfoOverlay

type ZoneInfoOverlay struct {
	Type        string                     `json:"type"`
	Setting     ZoneInfoOverlaySetting     `json:"setting"`
	Termination ZoneInfoOverlayTermination `json:"termination"`
}

ZoneInfoOverlay contains the zone's manual settings

func (*ZoneInfoOverlay) String

func (overlay *ZoneInfoOverlay) String() string

String serializes a ZoneInfoOverlay into a string. Used for logging.

type ZoneInfoOverlaySetting

type ZoneInfoOverlaySetting struct {
	Type        string      `json:"type"`
	Power       string      `json:"power"`
	Temperature Temperature `json:"temperature"`
}

ZoneInfoOverlaySetting contains the zone's overlay settings

func (*ZoneInfoOverlaySetting) String

func (setting *ZoneInfoOverlaySetting) String() string

String serializes a ZoneInfoOverlaySetting into a string. Used for logging.

type ZoneInfoOverlayTermination

type ZoneInfoOverlayTermination struct {
	Type          string `json:"type"`
	RemainingTime int    `json:"remainingTimeInSeconds,omitempty"`
}

ZoneInfoOverlayTermination contains the termination parameters for the zone's overlay

type ZoneInfoSensorDataPoints

type ZoneInfoSensorDataPoints struct {
	Temperature Temperature `json:"insideTemperature"`
	Humidity    Percentage  `json:"humidity"`
}

ZoneInfoSensorDataPoints contains the zone's current temperature & humidity

type ZoneInfoSetting

type ZoneInfoSetting struct {
	Power       string      `json:"power"`
	Temperature Temperature `json:"temperature"`
}

ZoneInfoSetting contains the zone's current power & target temperature