Gotado

https://pkg.go.dev/github.com/gonzolino/gotado
Admin
Gotado is a Go client library for the tado° Web API, enabling programmatic control of tado° smart...
Tokens:39,427
Snippets:523
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Usage of Token Refresh Callback

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Demonstrates how to set up an OAuth2 config, get a device access token, define a callback for token refresh, and create a tado client with the callback.

```go
config := gotado.AuthConfig(clientID, "offline_access")
token, _ := config.DeviceAccessToken(ctx, deviceAuth)

callback := func(newToken *oauth2.Token) {
    // Save token to encrypted storage
    log.Println("Token refreshed, saving to disk")
    SaveTokenToFile(newToken)
}

tado := gotado.NewWithTokenRefreshCallback(ctx, config, token, callback)

```

--------------------------------

### Install gotado Package

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Install the gotado package using the go get command. This command fetches and installs the package and its dependencies.

```bash
go get github.com/gonzolino/gotado

```

--------------------------------

### Installation Structure

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Holds information about a tado° hardware installation, including ID, type, revision, state, and associated devices.

```go
type Installation struct {
	ID       int32    `json:"id"`
	Type     string   `json:"type"`
	Revision int32    `json:"revision"`
	State    string   `json:"state"`
	Devices  []Device `json:"devices"`
}
```

--------------------------------

### Enable Early Start

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Enables the early start feature for a given zone. Requires client, user home, and zone details.

```go
func EnableEarlyStart(client *Client, userHome *UserHome, zone *Zone) error
```

--------------------------------

### GetInstallations

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Lists all hardware installations associated with a given tado° home.

```APIDOC
## GetInstallations

### Description
Lists all installations in the given home.

### Method
GET

### Endpoint
`/homes/{homeId}/installations`

### Parameters
#### Path Parameters
- **homeId** (int) - Required - The ID of the home to list installations for.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **id** (int32) - The unique identifier for the installation.
- **type** (string) - The type of installation (e.g., 'TADO_WINTER_V3').
- **revision** (int32) - The revision number of the installation configuration.
- **state** (string) - The current state of the installation.
- **devices** (array) - A list of devices associated with the installation.

#### Response Example
```json
[
  {
    "id": 12345,
    "type": "TADO_WINTER_V3",
    "revision": 1,
    "state": "ACTIVE",
    "devices": [
      {
        "type": "TADO_WINTER_V3",
        "revision": 1,
        "state": "ACTIVE"
      }
    ]
  }
]
```
```

--------------------------------

### GetInstallations Method for Home

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves a list of all installations within a specific home.

```go
func (h *Home) GetInstallations(ctx context.Context) ([]*Installation, error)
```

--------------------------------

### GetInstallations

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves a list of installations associated with the user's home.

```APIDOC
## GetInstallations

### Description
Retrieves a list of installations associated with the user's home.

### Function Signature
func GetInstallations(client *Client, userHome *UserHome) ([]*Installation, error)
```

--------------------------------

### GetEarlyStart

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Checks if the early start feature is enabled for the zone. Early start helps to reach the desired temperature by the scheduled time.

```APIDOC
## GetEarlyStart

### Description
Checks if the early start feature is enabled for the zone. Early start optimizes heating to reach the target temperature by the scheduled time.

### Method
GET

### Endpoint
/zones/{zoneId}/earlyStart

### Parameters
#### Path Parameters
- **zoneId** (int): The ID of the zone to check early start status for.

### Response
#### Success Response (200)
- **earlyStartEnabled** (bool): True if early start is enabled, false otherwise.

#### Error Response (4xx/5xx)
- **error** (string): Description of the error.
```

--------------------------------

### EnableEarlyStart

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Enables the early start feature for a zone.

```APIDOC
## EnableEarlyStart

### Description
Enables the early start feature for a zone.

### Function Signature
func EnableEarlyStart(client *Client, userHome *UserHome, zone *Zone) error
```

--------------------------------

### Check Early Start Enabled

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Checks if early start is enabled for a given zone. Returns a boolean and an error. Requires client, user home, and zone details.

```go
func IsEarlyStartEnabled(client *Client, userHome *UserHome, zone *Zone) (bool, error)
```

--------------------------------

### GetInstallations Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Lists all hardware installations associated with a given tado° home. Requires a client and user home object.

```go
func GetInstallations(client *Client, userHome *UserHome) ([]*Installation, error)
```

--------------------------------

### EarlyStart Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Controls the early start feature for tado° heating. When enabled, tado° ensures a set temperature is reached at the block's start.

```go
type EarlyStart struct {
	Enabled bool `json:"enabled"`
}
```

--------------------------------

### Get Users Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Lists all users and their associated mobile devices for a given home. Requires a client and user home.

```go
func GetUsers(client *Client, userHome *UserHome) ([]*User, error)
```

--------------------------------

### Check Early Start Status

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Checks if the early start feature is enabled for the zone. Early start can help pre-heat the zone before a scheduled time.

```go
func (z *Zone) GetEarlyStart(ctx context.Context) (bool, error)
```

--------------------------------

### Set Zone Early Start

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Enables or disables the early start feature for a zone. Early start allows the system to begin heating sooner to reach the target temperature by the scheduled time.

```go
func (z *Zone) SetEarlyStart(ctx context.Context, earlyStart bool) error
```

--------------------------------

### Get User and Home Information

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieve the current user's information and then fetch details about a specific home. This demonstrates basic API calls after client initialization.

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

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

```

--------------------------------

### Get Away Configuration

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Fetches the away configuration settings for the zone. This allows checking or applying settings relevant when the zone is unoccupied.

```go
func (z *Zone) GetAwayConfiguration(ctx context.Context) (*AwayConfiguration, error)
```

--------------------------------

### Get Devices in Zone

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Lists all devices associated with the zone. This is useful for inventorying hardware within a specific zone.

```go
func (z *Zone) GetDevices(ctx context.Context) ([]*Device, error)
```

--------------------------------

### Get Timetables Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Lists all available schedule timetables for a specified zone. Requires a client, user home, and zone.

```go
func GetTimetables(client *Client, userHome *UserHome, zone *Zone) ([]*ScheduleTimetable, error)
```

--------------------------------

### Get Open Window Detection Settings

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the current settings for open window detection. Use this to check the configuration and status of this feature.

```go
func (z *Zone) GetOpenWindowDetection(ctx context.Context) (*OpenWindowDetection, error)
```

--------------------------------

### Get Home by Name

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves a specific home associated with the user by its name.

```go
func (u *User) GetHome(ctx context.Context, name string) (*Home, error)
```

--------------------------------

### Disable Early Start

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Disables the early start feature for a given zone. Requires client, user home, and zone details.

```go
func DisableEarlyStart(client *Client, userHome *UserHome, zone *Zone) error
```

--------------------------------

### SetEarlyStart

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Enables or disables the early start feature for a zone's heating schedule. Requires a boolean value and returns an error.

```APIDOC
## SetEarlyStart

### Description
Enables or disables the early start feature for the zone's heating schedule.

### Method
(Implicitly a method call on a Zone object, not an HTTP endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **earlyStart** (bool) - Required - `true` to enable early start, `false` to disable.

### Request Example
```go
err := zone.SetEarlyStart(ctx, true)
```

### Response
#### Success Response
No explicit return value on success, only an error.

#### Response Example
`nil` (if successful)
```

--------------------------------

### Get Weather Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves current weather information at the specified home's location. Requires a client and user home.

```go
func GetWeather(client *Client, userHome *UserHome) (*Weather, error)
```

--------------------------------

### DisableEarlyStart

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Disables the early start feature for a zone.

```APIDOC
## DisableEarlyStart

### Description
Disables the early start feature for a zone.

### Function Signature
func DisableEarlyStart(client *Client, userHome *UserHome, zone *Zone) error
```

--------------------------------

### IsEarlyStartEnabled

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Checks if the early start feature is enabled for a zone.

```APIDOC
## IsEarlyStartEnabled

### Description
Checks if the early start feature is enabled for a zone.

### Function Signature
func IsEarlyStartEnabled(client *Client, userHome *UserHome, zone *Zone) (bool, error)
```

--------------------------------

### Get Away Configuration

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves the current away configuration for a given zone. Requires client, user home, and zone details. Returns the configuration or an error.

```go
func GetAwayConfiguration(client *Client, userHome *UserHome, zone *Zone) (*AwayConfiguration, error)
```

--------------------------------

### Get Zones Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves information about all zones within a specified user home using the provided client. Returns a slice of Zone pointers and an error if the operation fails.

```go
func GetZones(client *Client, userHome *UserHome) ([]*Zone, error)
```

--------------------------------

### Get Current User Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves information about the currently authenticated user. Requires only a client.

```go
func GetMe(client *Client) (*User, error)
```

--------------------------------

### Get Zone Capabilities

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the capabilities of the zone. This helps in understanding what features and settings are supported by the specific zone.

```go
func (z *Zone) GetCapabilities(ctx context.Context) (*ZoneCapabilities, error)
```

--------------------------------

### Get Home Information

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Fetch details about a specific home associated with the user. Requires the client and a home object, typically obtained from the user information.

```go
home, err := gotado.GetHome(client, &user.Homes[0])
fmt.Printf("Home Address:\n%s\n%s %s\n", *home.Address.AddressLine1, *home.Address.ZipCode, *home.Address.City)

```

--------------------------------

### Get Device Temperature Offset

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the temperature offset settings for a given tado° device.

```go
func (d *Device) GetTemperatureOffset(ctx context.Context) (float32, error)
```

--------------------------------

### MobileDevice Structure

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Represents a mobile device with the tado° app installed, including its name, ID, settings, location, and metadata.

```go
type MobileDevice struct {
	Name           string                `json:"name"`
	ID             int32                 `json:"id"`
	Settings       MobileDeviceSettings  `json:"settings"`
	Location       *MobileDeviceLocation `json:"location"`
	DeviceMetadata MobileDeviceMetadata  `json:"deviceMetadata"`
}
```

--------------------------------

### Get Authenticated User Information

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves information about the authenticated user.

```go
func (t *Tado) Me(ctx context.Context) (*User, error)
```

--------------------------------

### Get Zone Schedule for All Weekdays

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves a heating schedule where the same schedule applies to all days of the week. Use for uniform heating needs.

```go
func (z *Zone) ScheduleMonToSun(ctx context.Context) (*HeatingSchedule, error)
```

--------------------------------

### Get User Information

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieve the current user's information using the authenticated client. This is a basic API call to fetch user details.

```go
user, err := gotado.GetMe(client)
fmt.Printf("User Email: %s\n", user.Email)

```

--------------------------------

### Get Zone Schedule for All Days

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the heating schedule where each day of the week has a distinct schedule. Use when daily schedules vary.

```go
func (z *Zone) ScheduleAllDays(ctx context.Context) (*HeatingSchedule, error)
```

--------------------------------

### Get Zone Schedule Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves the heating schedule for a specified zone. Requires a client, user home, zone, and timetable as input.

```go
func GetSchedule(client *Client, userHome *UserHome, zone *Zone, timetable *ScheduleTimetable) ([]*ScheduleBlock, error)
```

--------------------------------

### Get Zone Capabilities Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Fetches the capabilities for a specific tado° zone. Requires a client, user home, and the zone object. Added in v0.3.0.

```go
func GetZoneCapabilities(client *Client, userHome *UserHome, zone *Zone) (*ZoneCapabilities, error)
```

--------------------------------

### Client.WithCredentials

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Creates a new client instance with provided credentials.

```APIDOC
## Client.WithCredentials

### Description
Creates a new client instance with provided credentials.

### Function Signature
func (c *Client) WithCredentials(ctx context.Context, username, password string) (*Client, error)
```

--------------------------------

### Initiate Open Window Mode

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Puts the zone into open window mode. This function should be called after an open window has been detected by tado°.

```go
func (z *Zone) OpenWindow(ctx context.Context) error
```

--------------------------------

### New Tado client constructor

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Creates a new tado client instance. Requires a context, an oauth2 configuration, and an oauth2 token.

```go
func New(ctx context.Context, config *oauth2.Config, token *oauth2.Token) *Tado
```

--------------------------------

### SetHeatingOn

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Turns on the heating in the zone and sets a target temperature. The temperature unit should match the home's configured unit (Celsius or Fahrenheit).

```APIDOC
## SetHeatingOn

### Description
Turns on the heating in the zone. The temperature should use the unit configured for the home.

### Method
POST

### Endpoint
/zones/{zoneId}/heating/on

### Parameters
#### Path Parameters
- **zoneId** (string) - Required - The ID of the zone to turn on heating for.

#### Request Body
- **temperature** (float64) - Required - The target temperature.
```

--------------------------------

### GetDevices Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves a list of all devices within a specified user home. Requires a client and user home object.

```go
func GetDevices(client *Client, userHome *UserHome) ([]*Device, error)
```

--------------------------------

### SetHeatingOn

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Turns on the heating for a zone to a specified temperature. Requires a temperature value and returns an error.

```APIDOC
## SetHeatingOn

### Description
Turns on the heating for the zone to a specified target temperature.

### Method
(Implicitly a method call on a Zone object, not an HTTP endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **temperature** (float64) - Required - The target temperature to set.

### Request Example
```go
err := zone.SetHeatingOn(ctx, 21.0)
```

### Response
#### Success Response
No explicit return value on success, only an error.

#### Response Example
`nil` (if successful)
```

--------------------------------

### ZoneStateNextTimeBlock Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Indicates the start time of the next time block for a Tado° zone.

```go
type ZoneStateNextTimeBlock struct {
	Start time.Time `json:"start"`
}
```

--------------------------------

### Create Authenticated Tado Client

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Initialize an authenticated client for the tado° API. Requires client ID, client secret, username, and password. Ensure you have these credentials before proceeding.

```go
client, err := gotado.NewClient("cliendId", "clientSecret").WithCredentials(context.TODO(), "username", "password")

```

--------------------------------

### Get Schedule Time Blocks

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves all time blocks associated with a specific schedule.

```APIDOC
## Get Schedule Time Blocks

### Description
Retrieves all time blocks of the schedule.

### Method
`GetTimeBlocks`

### Parameters
- **ctx** (context.Context) - The context for the request.

### Returns
- **([]*ScheduleTimeBlock, error)** - A slice of ScheduleTimeBlock pointers and an error if the operation fails.
```

--------------------------------

### ZoneStateNextScheduledChange Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Holds the start time and settings for the next scheduled change in a Tado° zone.

```go
type ZoneStateNextScheduledChange struct {
	Start   time.Time    `json:"start"`
	Setting *ZoneSetting `json:"setting"`
}
```

--------------------------------

### AwayConfigurationSetting Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Holds the specific settings for an away configuration, including type, power, and optional temperature settings.

```go
type AwayConfigurationSetting struct {
	Type        string                               `json:"type"`
	Power       string                               `json:"power"`
	Temperature *AwayConfigurationSettingTemperature `json:"temperature,omitempty"`
}
```

--------------------------------

### Client.Do

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Executes an HTTP request and returns the response.

```APIDOC
## Client.Do

### Description
Executes an HTTP request and returns the response.

### Function Signature
func (c *Client) Do(req *http.Request) (*http.Response, error)
```

--------------------------------

### New Mock ConfigInterface

Source: https://pkg.go.dev/github.com/gonzolino/gotado/internal/oauth2

Creates a new mock instance of MockConfigInterface for testing purposes.

```go
func NewMockConfigInterface(ctrl *gomock.Controller) *MockConfigInterface
```

--------------------------------

### SetAwayPreheatOff

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Turns off preheating before arrival for the zone. Tado° will only start heating after arrival. To re-enable preheating, use SetAwayPreheatComfortLevel().

```APIDOC
## SetAwayPreheatOff

### Description
Turns off preheat before arrival. Tado° will only start heating after arrival. To turn preheating back on, use SetAwayPreheatComfortLevel().

### Method
DELETE

### Endpoint
/zones/{zoneId}/awayConfiguration/preheat

### Parameters
#### Path Parameters
- **zoneId** (string) - Required - The ID of the zone to turn off preheating for.
```

--------------------------------

### Client.WithCredentials Method

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Sets credentials and scopes for the tado° API client. Returns a new client instance with updated credentials.

```go
func (c *Client) WithCredentials(ctx context.Context, username, password string) (*Client, error)
```

--------------------------------

### Home Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Represents a tado° equipped home. Contains details like home ID, name, timezone, and various configuration settings.

```go
type Home struct {
	ID              int32  `json:"id"`
	Name            string `json:"name"`
	DateTimeZone    string `json:"dateTimeZone"`
	DateCreated     string `json:"dateCreated"`
	TemperatureUnit string `json:"temperatureUnit"`
	// TODO partner missing
	SimpleSmartScheduleEnabled bool                  `json:"simpleSmartScheduleEnabled"`
	AwayRadiusInmeters         float32               `json:"awayRadiusInMeters"`
	InstallationCompleted      bool                  `json:"installationCompleted"`
	IncidentDetection          HomeIncidentDetection `json:"incidentDetection"`
	AutoAssistFreeTrialEnabled bool                  `json:"autoAssistFreeTrialEnabled"`
	Skills                     []string              `json:"skills"`
	ChristmasModeEnabled       bool                  `json:"christmasModeEnabled"`
	ShowAutoAssistReminders    bool                  `json:"showAutoAssistReminders"`
	ContactDetails             HomeContactDetails    `json:"contactDetails"`
	Address                    HomeAddress           `json:"address"`
	Geolocation                HomeGeolocation       `json:"geolocation"`
	ConsentGrantSkippable      bool                  `json:"consentGrantSkippable"`
}
```

--------------------------------

### Tado Constructor

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Constructors for creating a Tado client instance.

```APIDOC
## Tado Constructor

### New

Creates a new Tado client instance.

### Method
constructor

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.
- **config** (*oauth2.Config) - Required - The OAuth2 configuration.
- **token** (*oauth2.Token) - Required - The OAuth2 token.

### Response
#### Success Response (200)
- **tado** (*Tado) - A pointer to the Tado client instance.

### NewWithTokenRefreshCallback

Creates a new Tado client instance with a token refresh callback.

### Method
constructor

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.
- **config** (*oauth2.Config) - Required - The OAuth2 configuration.
- **token** (*oauth2.Token) - Required - The OAuth2 token.
- **callback** (TokenRefreshCallback) - Required - The token refresh callback function.

### Response
#### Success Response (200)
- **tado** (*Tado) - A pointer to the Tado client instance.
```

--------------------------------

### OpenWindow

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Puts the zone into open window mode. This should only be called after an open window has been detected by the tado° system.

```APIDOC
## OpenWindow

### Description
Puts the zone into open window mode. This action should be taken after an open window has been detected by the tado° system.

### Method
POST

### Endpoint
/zones/{zoneId}/openWindow

### Parameters
#### Path Parameters
- **zoneId** (int): The ID of the zone to put into open window mode.

#### Request Body
None

### Response
#### Success Response (204)
No content, indicating the operation was successful.

#### Error Response (4xx/5xx)
- **error** (string): Description of the error.
```

--------------------------------

### Set Window Open

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Marks the window in a specified zone as open. This function assumes window open detection has already occurred. Requires client, user home, and zone details.

```go
func SetWindowOpen(client *Client, userHome *UserHome, zone *Zone) error
```

--------------------------------

### New Tado Client

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Creates a new tado client instance with the provided OAuth2 configuration and token.

```APIDOC
## New Tado Client

### Description
Creates a new tado client.

### Function Signature
`func New(ctx context.Context, config *oauth2.Config, token *oauth2.Token) *Tado`

### Parameters
- **ctx** (context.Context) - The context for the request.
- **config** (*oauth2.Config) - The OAuth2 configuration.
- **token** (*oauth2.Token) - The OAuth2 token.

### Returns
- **(*Tado)** - A pointer to the newly created Tado client.
```

--------------------------------

### NewClient

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Creates a new tado° client instance. This is the entry point for interacting with the API.

```APIDOC
## NewClient

### Description
Creates a new tado° client instance. This is the entry point for interacting with the API.

### Signature
```go
func NewClient(clientID, clientSecret string) *Client
```

### Parameters
* **clientID** (string) - The client ID for authentication.
* **clientSecret** (string) - The client secret for authentication.

### Returns
* (*Client) - A pointer to the initialized tado° client.
```

--------------------------------

### Get Zone State

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the current state of the zone, including temperature, humidity, and operational status. This is essential for real-time monitoring.

```go
func (z *Zone) GetState(ctx context.Context) (*ZoneState, error)
```

--------------------------------

### Device Authentication Flow

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Demonstrates the device authentication flow using OAuth 2.0. This involves obtaining a device authorization, prompting the user to visit a verification URI, and then retrieving an access token.

```go
ctx := context.Background()
config := gotado.AuthConfig(clientID)

deviceAuth, err := config.DeviceAuth(ctx)

// The user must visit the verification URI and authenticate with his personal credentials.
// Afterwards an access token will be generated.
fmt.Printf("To authenticate, visit %s\n", deviceAuth.VerificationURIComplete)

token, err := config.DeviceAccessToken(ctx, deviceAuth)

```

--------------------------------

### Mock Client Method

Source: https://pkg.go.dev/github.com/gonzolino/gotado/internal/oauth2

Mocks the base Client method of the ConfigInterface for testing.

```go
func (m *MockConfigInterface) Client(ctx context.Context, t *oauth2.Token) *http.Client
```

--------------------------------

### Get Dazzle Mode Settings

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the current dazzle mode settings for the zone. Use this to check if dazzle mode is active and its configuration.

```go
func (z *Zone) GetDazzleMode(ctx context.Context) (*ZoneDazzleMode, error)
```

--------------------------------

### Set Zone Overlay Heating On Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Turns on heating for a specified tado° zone to a target temperature. The temperature unit should match the home's configuration. Returns the resulting overlay or an error. Added in v0.2.0.

```go
func SetZoneOverlayHeatingOn(client *Client, userHome *UserHome, zone *Zone, temperature float64) (*ZoneOverlay, error)
```

--------------------------------

### Get Active Schedule Timetable

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the currently active schedule timetable for the zone. This is useful for understanding the zone's heating plan.

```go
func (z *Zone) GetActiveScheduleTimetable(ctx context.Context) (*ScheduleTimetable, error)
```

--------------------------------

### GetHome Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves detailed information about a specific tado° home. Requires a client and user home object.

```go
func GetHome(client *Client, userHome *UserHome) (*Home, error)
```

--------------------------------

### Get Active Timetable Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves the currently active schedule timetable for a given zone. Requires a client, user home, and zone.

```go
func GetActiveTimetable(client *Client, userHome *UserHome, zone *Zone) (*ScheduleTimetable, error)
```

--------------------------------

### GetMobileDevices Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Lists all mobile devices linked to a specific tado° home. Requires a client and user home object.

```go
func GetMobileDevices(client *Client, userHome *UserHome) ([]*MobileDevice, error)
```

--------------------------------

### Device Methods

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Methods for interacting with individual devices, including retrieving and setting temperature offsets.

```APIDOC
## Device Methods

### GetTemperatureOffset

Retrieves the temperature offset for a device.

### Method
GET

### Endpoint
(Not specified, typically relative to a device ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **temperatureOffset** (float32) - The current temperature offset.
- **error** (error) - An error if the operation fails.

### SetTemperatureOffset

Sets the temperature offset for a device.

### Method
PUT

### Endpoint
(Not specified, typically relative to a device ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.
- **temperatureOffset** (float32) - Required - The desired temperature offset.

### Response
#### Success Response (200)
- **error** (error) - An error if the operation fails.
```

--------------------------------

### Set Away Temperature

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Sets a manual temperature for a zone when the house is empty. Requires client, user home, zone, and temperature.

```go
func SetAwayTemperature(client *Client, userHome *UserHome, zone *Zone, temperature float64) error
```

--------------------------------

### MobileDevice Struct Definition

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Represents a mobile device with the tado° app installed. Includes device name, ID, settings, location, and metadata. Some fields are unexported.

```go
type MobileDevice struct {
	Name           string                `json:"name"`
	ID             int32                 `json:"id"`
	Settings       MobileDeviceSettings  `json:"settings"`
	Location       *MobileDeviceLocation `json:"location"`
	DeviceMetadata MobileDeviceMetadata  `json:"deviceMetadata"`
	// contains filtered or unexported fields
}
```

--------------------------------

### Get Zone Schedule for Weekdays and Weekends

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves a heating schedule with a uniform schedule for Monday-Friday and separate schedules for Saturday and Sunday. Use for typical work-week/weekend variations.

```go
func (z *Zone) ScheduleMonToFriSatSun(ctx context.Context) (*HeatingSchedule, error)
```

--------------------------------

### GetZoneStates Function Signature

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Returns the current states of all zones within the home. This function was added in v2.1.1 and requires a context.

```go
func (h *Home) GetZoneStates(ctx context.Context) (*ZoneStates, error)
```

--------------------------------

### Get Heating Schedule

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the complete active heating schedule for the zone, including the active timetable and all time blocks. This provides a comprehensive view of the heating plan.

```go
func (z *Zone) GetHeatingSchedule(ctx context.Context) (*HeatingSchedule, error)
```

--------------------------------

### Define User Structure

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Represents a tado° user, including their name, email, username, ID, associated homes, locale, and mobile devices.

```go
type User struct {
	Name          string         `json:"name"`
	Email         string         `json:"email"`
	Username      string         `json:"username"`
	ID            string         `json:"id"`
	Homes         []UserHome     `json:"homes"`
	Locale        string         `json:"locale"`
	MobileDevices []MobileDevice `json:"mobileDevices"`
}
```

--------------------------------

### Get Manual Control Termination Condition

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the condition that determines how long manual control remains active after a tado° device was controlled manually. This helps in understanding override behavior.

```go
func (z *Zone) GetManualControlTerminationCondition(ctx context.Context) (*ZoneOverlayTermination, error)
```

--------------------------------

### Client.WithTimeout

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Creates a new client instance with a specified timeout.

```APIDOC
## Client.WithTimeout

### Description
Creates a new client instance with a specified timeout.

### Function Signature
func (c *Client) WithTimeout(timeout time.Duration) *Client
```

--------------------------------

### GetZones Function Signature

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves information about all zones configured in the home. A context is necessary for this API call.

```go
func (h *Home) GetZones(ctx context.Context) ([]*Zone, error)
```

--------------------------------

### Set Mobile Device Settings

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Updates the settings of a given mobile device. Requires client, user home, mobile device, and new settings.

```go
func SetMobileDeviceSettings(client *Client, userHome *UserHome, mobileDevice *MobileDevice, settings MobileDeviceSettings) error
```

--------------------------------

### Turn On Zone Heating

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Turns on the heating for a zone to a specified temperature. Ensure the temperature unit matches the home's configuration.

```go
func (z *Zone) SetHeatingOn(ctx context.Context, temperature float64) error
```

--------------------------------

### GetDevices Method for Home

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves a list of all devices associated with a specific home.

```go
func (h *Home) GetDevices(ctx context.Context) ([]*Device, error)
```

--------------------------------

### Client.WithTimeout Method

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Configures the tado° client with a specific timeout for HTTP requests. Returns the client instance with the timeout applied.

```go
func (c *Client) WithTimeout(timeout time.Duration) *Client
```

--------------------------------

### Home Methods

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Methods for retrieving information about the home, including devices, users, and weather.

```APIDOC
## Home Methods

### GetDevices

Retrieves a list of all devices within the home.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **devices** ([]*Device) - A slice of Device pointers.
- **error** (error) - An error if the operation fails.

### GetInstallations

Retrieves a list of installations associated with the home.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **installations** ([]*Installation) - A slice of Installation pointers.
- **error** (error) - An error if the operation fails.

### GetMobileDevices

Retrieves a list of mobile devices associated with the home.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **mobileDevices** ([]*MobileDevice) - A slice of MobileDevice pointers.
- **error** (error) - An error if the operation fails.

### GetState

Retrieves the current state of the home.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **homeState** (*HomeState) - A pointer to the HomeState.
- **error** (error) - An error if the operation fails.

### GetUsers

Retrieves a list of users associated with the home.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **users** ([]*User) - A slice of User pointers.
- **error** (error) - An error if the operation fails.

### GetWeather

Retrieves the current weather information for the home's location.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **weather** (*Weather) - A pointer to the Weather information.
- **error** (error) - An error if the operation fails.

### GetZone

Retrieves a specific zone within the home by its name.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.
- **name** (string) - Required - The name of the zone.

### Response
#### Success Response (200)
- **zone** (*Zone) - A pointer to the Zone.
- **error** (error) - An error if the operation fails.

### GetZoneStates

Retrieves the states of all zones within the home.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **zoneStates** (*ZoneStates) - A pointer to the ZoneStates.
- **error** (error) - An error if the operation fails.

### GetZones

Retrieves a list of all zones within the home.

### Method
GET

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **zones** ([]*Zone) - A slice of Zone pointers.
- **error** (error) - An error if the operation fails.

### SetPresenceAuto

Sets the home presence mode to automatic.

### Method
PUT

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **error** (error) - An error if the operation fails.

### SetPresenceAway

Sets the home presence mode to away.

### Method
PUT

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **error** (error) - An error if the operation fails.

### SetPresenceHome

Sets the home presence mode to home.

### Method
PUT

### Endpoint
(Not specified, typically relative to a home ID)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for the request.

### Response
#### Success Response (200)
- **error** (error) - An error if the operation fails.
```

--------------------------------

### DeviceCharacteristics Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Lists the capabilities of a tado° device.

```go
type DeviceCharacteristics struct {
	Capabilities []string `json:"capabilities"`
}
```

--------------------------------

### NewClient Function

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Creates a new instance of the tado° API client. Requires client ID and client secret for authentication.

```go
func NewClient(clientID, clientSecret string) *Client
```

--------------------------------

### ZoneSetting Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Represents the setting configuration for a zone, including its type, power state, and temperature.

```go
type ZoneSetting struct {
	Type        ZoneType                `json:"type"`
	Power       Power                   `json:"power"`
	Temperature *ZoneSettingTemperature `json:"temperature"`
}
```

--------------------------------

### Enable Open Window Detection with Timeout

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Enables open window detection and sets a heating timeout duration in seconds after an open window is detected. This allows for custom behavior during detected open windows.

```go
func (z *Zone) EnableOpenWindowDetection(ctx context.Context, timeout int32) error
```

--------------------------------

### GetState

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the current state of the home, including information like current temperature, humidity, and system mode.

```APIDOC
## GetState

### Description
Retrieves the current state of the home.

### Method
GET

### Endpoint
/homes/{homeId}/state

### Parameters
#### Path Parameters
- **homeId** (int32) - Required - The unique identifier for the home.

### Response
#### Success Response (200)
- **homeState** (HomeState) - An object containing the current state of the home.

#### Response Example
```json
{
  "homeState": {
    "temperature": {
      "celsius": 21.0,
      "fahrenheit": 69.8
    },
    "mode": "HOME",
    "isPartyModeEnabled": false,
    "isWinterModeEnabled": false,
    "isAwayModeEnabled": false
  }
}
```
```

--------------------------------

### User Structure

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Represents a tado° user, including their name, email, ID, homes, locale, and mobile devices.

```go
type User struct {
	Name          string         `json:"name"`
	Email         string         `json:"email"`
	Username      string         `json:"username"`
	ID            string         `json:"id"`
	Homes         []UserHome     `json:"homes"`
	Locale        string         `json:"locale"`
	MobileDevices []MobileDevice `json:"mobileDevices"`
	// contains filtered or unexported fields
}
```

--------------------------------

### GetZoneStates

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Returns information about the states of all zones in the home.

```APIDOC
## GetZoneStates

### Description
Returns information about the states of all zones in the home.

### Method
GET

### Endpoint
/zones/states

### Parameters
#### Query Parameters
- **ctx** (context.Context) - Required - The context for the request.

### Response
#### Success Response (200)
- **zoneStates** (*ZoneStates) - Information about the states of all zones.
```

--------------------------------

### Set Away Configuration

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Sets a custom away configuration for a given zone. Requires client, user home, zone, and away configuration details.

```go
func SetAwayConfiguration(client *Client, userHome *UserHome, zone *Zone, awayConfig *AwayConfiguration) error
```

--------------------------------

### Create gotado Client

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Create a new gotado client instance using the provided context, authentication configuration, and token. This client is used to interact with the tado° API.

```go
tado := gotado.New(ctx, config, token)

```

--------------------------------

### GetUsers Function Signature

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves a list of all users and their associated mobile devices within a home. This function requires a context for the request.

```go
func (h *Home) GetUsers(ctx context.Context) ([]*User, error)
```

--------------------------------

### Zone Capabilities Structure

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Defines the capabilities of a zone, including its type and whether temperature can be set. Used to understand device limitations.

```go
type ZoneCapabilities struct {
	Type              ZoneType                      `json:"type"`
	CanSetTemperature *bool                         `json:"canSetTemperature,omitempty"`
	Temperatures      *ZoneCapabilitiesTemperatures `json:"temperatures,omitempty"`
}
```

--------------------------------

### SetWindowOpen

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Sets the window state to open for a zone.

```APIDOC
## SetWindowOpen

### Description
Sets the window state to open for a zone.

### Function Signature
func SetWindowOpen(client *Client, userHome *UserHome, zone *Zone) error
```

--------------------------------

### Client Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado

The tado° API client structure. Use this to authenticate and make requests to the tado° API.

```go
type Client struct {
	// ClientID specifies the client ID to use for authentication
	ClientID string
	// ClientSecret specifies the client secret to use for authentication
	ClientSecret string
	// contains filtered or unexported fields
}
```

--------------------------------

### Client.Do Method

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Sends an HTTP request to the tado° API. This method is part of the Client and handles request execution.

```go
func (c *Client) Do(req *http.Request) (*http.Response, error)
```

--------------------------------

### GetState Method for Home

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the current state of a specific home.

```go
func (h *Home) GetState(ctx context.Context) (*HomeState, error)
```

--------------------------------

### Create Token Refresh Callback Source

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Creates a TokenSource that calls a callback on token refresh. Useful for tado°'s short-lived tokens and refresh token rotation.

```go
func NewCallbackTokenSource(src oauth2.TokenSource, callback TokenRefreshCallback, initialToken ...*oauth2.Token) oauth2.TokenSource
```

--------------------------------

### GetZoneCapabilities

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Fetches the specific capabilities of a given Tado° zone, such as temperature control limits and supported modes.

```APIDOC
## GetZoneCapabilities

### Description
Returns the capabilities of the given zone.

### Method
GET

### Endpoint
/zones/{zoneId}/capabilities

### Parameters
#### Path Parameters
- **zoneId** (int32) - Required - The ID of the zone.

#### Query Parameters
- **client** (*Client) - Required - The API client instance.
- **userHome** (*UserHome) - Required - The user's home object.
- **zone** (*Zone) - Required - The zone object for which to retrieve capabilities.

### Response
#### Success Response (200)
- **ZoneCapabilities** - An object containing the capabilities of the zone.

#### Response Example
```json
{
  "type": "RADIATOR",
  "canSetTemperature": true,
  "temperatures": {
    "celsius": {
      "min": 5,
      "max": 25,
      "step": 0.5
    },
    "fahrenheit": {
      "min": 41,
      "max": 77,
      "step": 1.0
    }
  }
}
```
```

--------------------------------

### GetZone Function Signature

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves information about a specific zone within the home, identified by its name. The function requires a context and the zone's name.

```go
func (h *Home) GetZone(ctx context.Context, name string) (*Zone, error)
```

--------------------------------

### GetDevices

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Lists all devices associated with the zone. This can include thermostats, sensors, and other tado° devices within that zone.

```APIDOC
## GetDevices

### Description
Lists all devices within the specified zone. This includes thermostats, sensors, and other connected tado° devices.

### Method
GET

### Endpoint
/zones/{zoneId}/devices

### Parameters
#### Path Parameters
- **zoneId** (int): The ID of the zone to list devices for.

### Response
#### Success Response (200)
- **devices** ([]*Device): A list of Device objects representing the devices in the zone.

#### Error Response (4xx/5xx)
- **error** (string): Description of the error.
```

--------------------------------

### GetCapabilities

Source: https://pkg.go.dev/github.com/gonzolino/gotado/v2

Retrieves the capabilities of the zone. This indicates what features and functionalities the zone supports.

```APIDOC
## GetCapabilities

### Description
Retrieves the capabilities of the zone. This information details the features and functionalities supported by this specific zone.

### Method
GET

### Endpoint
/zones/{zoneId}/capabilities

### Parameters
#### Path Parameters
- **zoneId** (int): The ID of the zone to retrieve capabilities for.

### Response
#### Success Response (200)
- **capabilities** (*ZoneCapabilities): An object detailing the zone's capabilities.

#### Error Response (4xx/5xx)
- **error** (string): Description of the error.
```

--------------------------------

### AwayConfiguration Struct

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Defines the structure for away configuration settings, including type, auto-adjust, comfort level, and specific settings. Comfort level must be 0, 50, or 100.

```go
type AwayConfiguration struct {
	Type       string `json:"type"`
	AutoAdjust bool   `json:"autoAdjust"`
	// Comfort Level must be 0 (Eco), 50 (Balanced) or 100 (Comfort)
	ComfortLevel int32                     `json:"comfortLevel"`
	Setting      *AwayConfigurationSetting `json:"setting"`
}
```

--------------------------------

### Client.Request Method

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Performs a generic HTTP request to the tado° API. Supports different HTTP methods and request bodies.

```go
func (c *Client) Request(method, url string, body io.Reader) (*http.Response, error)
```

--------------------------------

### Client.Request

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Makes an HTTP request with a specified method, URL, and optional body.

```APIDOC
## Client.Request

### Description
Makes an HTTP request with a specified method, URL, and optional body.

### Function Signature
func (c *Client) Request(method, url string, body io.Reader) (*http.Response, error)
```

--------------------------------

### GetAwayConfiguration

Source: https://pkg.go.dev/github.com/gonzolino/gotado

Retrieves the away configuration for a zone.

```APIDOC
## GetAwayConfiguration

### Description
Retrieves the away configuration for a zone.

### Function Signature
func GetAwayConfiguration(client *Client, userHome *UserHome, zone *Zone) (*AwayConfiguration, error)
```
Tokens:
Raw