robertogallea / restado

PHP and Laravel library for managing Tado system

Restado

PHP and Laravel library for managing Tado system

This package provides a simple interface towards the public Tado Thermostat System API. It wraps the web methods available for authenticating users and retrieve information from the local devices.

The package is also integrated within Laravel.

Since the API is currently officially undocumented, if you are aware of methods missing in this library, please inform me!

1. Installation
2. Updating
3. Configuration
4. Usage
5. Supported Methods
6. Issues, Questions and Pull Requests

1. Installation

1. Require the package using composer:

   composer require robertogallea/restado
   

2. Add the service provider to the providers in config/app.php:

   Laravel 5.5 uses Package Auto-Discovery, so doesn't require you to manually add the ServiceProvider

   Robertogallea\Restado\RestadoServiceProvider::class,

3. Add the alias to the aliases in config/app.php:

   'Restado' => Robertogallea\Restado\Facades\Restado::class,    

4. Add the following variables to your .env file

   TADO_CLIENT_ID=<TADO_APP_ID>       // defaults to public-api-preview
   TADO_SECRET=<TADO_APP_SECRET_KEY>  // defaults to 4HJGRffVR8xb3XdEUQpjgZ1VplJi6Xgw                                                      
   TADO_USER=<TADO_USER>
   TADO_PASS=<TADO_PASSWORD>
   TADO_HOME_ID=<TADO_HOME_ID>

2. Updating

1. To update this package, update the composer package:

   composer update robertogallea/restado

3. Configuration

1. To use Restado, no further configuration is required. However, if you wish to tweak with config, publish the relative configuration file using the command

php artisan vendor:publish --provider="Robertogallea\Restado\RestadoServiceProvider" --tag=config

4. Usage

To use this package you should use the method of the Restado facade.

1. Obtain a valid token for your session:

   $access_token = Restado::authorize();

2. Use a method to get the related information, for example:

   $me = Restado::me($access_token);

each method returns an object containing the data from the server. Currently the API is not officially documented, the only reference I found is at this page: http://blog.scphillips.com/posts/2017/01/the-tado-api-v2/

5. Supported Methods

Currently these methods are supported:

Authorisation

• authorize();
• me($access_token);

Home and device data

• getHome($access_token);
• setHome($access_token, $settings);
• getHomeWeather($access_token);
• getHomeDevices($access_token);
• getHomeInstallations($access_token);
• getHomeUsers($access_token);
• setDazzle($access_token, $zone_id, $setting);

Mobile devices

• getHomeMobileDevices($access_token);
• deleteHomeMobileDevice(token, $mobile_device_id);
• getHomeMobileDeviceSettings($access_token, $mobile_device_id);
• setHomeMobileDeviceSettings($access_token, $mobile_device_id, $settings);
• identifyDevice($access_token, $device_id);
• getAppUsersRelativePositions($access_token);

Home zones

• getHomeZones($access_token);
• getHomeZoneState($access_token, $zone_id);
• getHomeZoneStates($access_token, $home_id);
• getHomeZoneDayReport($access_token, $zone_id, $date);
• getHomeZoneCapabilities($access_token, $zone_id);
• getHomeZoneEarlyStart($access_token, $zone_id);
• setHomeZoneEarlyStart($access_token, $zone_id, $settings);
• getHomeZoneOverlay($access_token, $zone_id);
• setHomeZoneOverlay($access_token, $zone_id, $settings);
• deleteHomeZoneOverlay($access_token, $zone_id);
• getHomeZoneScheduleActiveTimetable($access_token, $zone_id);
• setHomeZoneScheduleActiveTimetable($access_token, $zone_id, $settings);
• getHomeZoneScheduleAway($access_token, $zone_id);
• setHomeZoneScheduleAway($access_token, $zone_id, $settings);
• getHomeZoneScheduleTimetableBlocks($access_token, $zone_id, $timetable_id, $pattern=null);
• setHomeZoneScheduleTimetableBlocks($access_token, $zone_id, $timetable_id, $pattern, $settings);

Temperature offset

• getTemperatureOffset($access_token, $device_id);
• setTemperatureOffset($access_token, $device_id, $settings);

Open window detection

• setOpenWindowDetection($access_token, $zone_id, $settings);

Presence detection

• isAnyoneAtHome($access_token);
• getPresenceLock($access_token);
• setPresenceLock($access_token, $settings);

Energy IQ & savings reports

• deleteEnergyIQMeterReading($access_token, $reading_id);
• addEnergyIQMeterReading($access_token, $settings);
• updateEnergyIQTariff($access_token, $settings);
• getEnergyIQMeterReadings($access_token);
• getEnergyIQTariff($access_token);
• getEnergyIQ($access_token);
• getEnergySavingsReport($access_token, $year, $month, $country_code);

To request an energy savings report via getEnergySavingsReport, you're required to pass a three-letter country code in accordance with ISO 3166-1 alpha-3

6. Issues, Questions and Pull Requests

You can report issues and ask questions in the issues section. Please start your issue with ISSUE: and your question with QUESTION:

If you have a question, check the closed issues first.

To submit a Pull Request, please fork this repository, create a new branch and commit your new/updated code in there. Then open a Pull Request from your new branch. Refer to this guide for more info.

restado's Issues

switch to new tado authentication server

tado is discontinuing the old OAuth2 endpoints at my.tado.com. Starting March 2019, authentication will require retrieving access and refresh tokens from auth.tado.com. The client public-api-preview can be used as is (with the same client secret) on the new endpoint.

The new authentication will also be a standard OAuth2 system, but will use JWT as a format for refresh tokens. So be aware that this will increase the size of the refresh tokens.

Additionally, the new endpoints implement refresh token rotation. A new refresh token is issued with every access token refresh response. The previous refresh token is invalidated.

Issue with 'Required options not defined: urlAuthorize, urlAccessToken, urlResourceOwnerDetails'

When following the instructions, I get the following error:

When I add the following code to the getProvider method, I get an Invalid Scope error:

'urlAuthorize' => 'https://my.tado.com/oauth/token', 
'urlAccessToken' => 'https://my.tado.com/oauth/token', 
'urlResourceOwnerDetails' => null,

Then adding 'scope' => 'home.user', to the authorize method (below password), it seems to be working again.

New API route: zoneStates (plural)

Hello and thank you very much for your API! :)

I noticed that it is now possible to get all zone states with a single request by using the following route:

'https://my.tado.com/api/v2/homes/' . $home_id . '/zoneStates',

This way one does not have to send a request for each room which is very useful.

I added the following function to Restado.php:

/**
    * @param $access_token
    * @param $home_id
    * @return mixed
    */
   public function getHomeZoneStates($access_token, $home_id) {
       $provider = $this->getProvider();

       $request = $provider->getAuthenticatedRequest(
           'GET',
           'https://my.tado.com/api/v2/homes/' . $home_id . '/zoneStates',
           $access_token
       );
       $client = new \GuzzleHttp\Client();
       $response = $client->send($request);
       return json_decode($response->getBody());
   }

Could you include it in your repository?