Zone on/off via TadoLocal is not persistent because TadoLocal commands are handled as overlays

[Bekkie]

I was puzzled for a while about why zone switching on and off was not behaving as expected.

What I found is that TadoLocal commands appear to be handled by Tado as overlays. Because of that, switching a zone off is not permanent: depending on the Tado manual-mode setting, the zone returns to the SMART schedule when the next time block starts, when a timer expires, or according to the app’s manual control configuration.

This is a problem for my use case, where I use TadoLocal for per-user geofencing. For example:

• if one of my kids is away, I switch off heating in that specific room
• if everyone is away, I also switch off the living room

Since my kids are often away for a full day or longer, their rooms should stay off for that whole period.

There is a second related issue: switching a room on again via TadoLocal does not restore the SMART schedule. Instead, it seems to restore the latest temperature target (set by schedule or manual). Then, depending on the Tado app’s manual timer setting, SMART schedule resumes after the configured timeout, at the next timer block, or never.

Expected behavior

• Switching a zone off should optionally support a persistent off mode
• Switching a zone on/auto should optionally support returning directly to SMART schedule

Current behavior

• Zone off is implemented as an overlay, so it is temporary
• Zone on restores the previous manual target rather than returning to SMART schedule

Proposal

It would be very useful and quite straightforward to implement persistent off and back to auto/SMART schedule functionality via the Tado Cloud API.

Cloud API examples

Switch off permanently for one zone
PUT https://my.tado.com/api/v2/homes/{home_id}/zones/{zone_id}/overlay?ngsw-bypass=true

Payload:

{
  "termination": { "typeSkillBasedApp": "MANUAL" },
  "setting": {
    "type": "HEATING",
    "power": "OFF",
    "temperature": null
  }
}

Switch off permanently for all zones
PUT https://my.tado.com/api/v2/homes/{home_id}/overlay?ngsw-bypass=true

Payload:

{
  "overlays": [
    {
      "overlay": {
        "setting": { "power": "OFF", "type": "HEATING" },
        "termination": { "typeSkillBasedApp": "MANUAL" }
      },
      "room": 1
    },
    {
      "overlay": {
        "setting": { "power": "OFF", "type": "HEATING" },
        "termination": { "typeSkillBasedApp": "MANUAL" }
      },
      "room": 2
    },
    {
      "overlay": {
        "setting": { "power": "OFF", "type": "HEATING" },
        "termination": { "typeSkillBasedApp": "MANUAL" }
      },
      "room": 3
    },
    {
      "overlay": {
        "setting": { "power": "OFF", "type": "HEATING" },
        "termination": { "typeSkillBasedApp": "MANUAL" }
      },
      "room": 4
    }
  ]
}

Return one room to SMART schedule
DELETE https://my.tado.com/api/v2/homes/{home_id}/zones/{zone_id}/overlay?ngsw-bypass=true

Return all rooms to SMART schedule
DELETE https://my.tado.com/api/v2/homes/{home_id}/overlay?rooms=1,2,3,4&ngsw-bypass=true

note: not sure what "?ngsw-bypass=true" does

Possible API design options

Option 1: add dedicated routes

PUT /zones/schedule/off
PUT /zones/schedule/auto
PUT /zones/{zone_id}/schedule/off
PUT /zones/{zone_id}/schedule/auto

Option 2: extend existing zone switching with a cloud parameter

Examples:

/zones/3/set?temperature=-1&cloudcall=true   -> send to cloud instead of HomeKit
/zones/3/set?temperature=0&cloudcall=true    -> send to cloud instead of HomeKit
/zones/3/set?temperature=12&cloudcall=true   -> cloud call ignored

I understand this would require a cloud API call, so it may not fit the original local-only design. Still, for geofencing and longer absences, persistent off / return-to-auto behavior would be very useful.

Any thoughts on this topic?

[rhuijben]

I would just make it an option on the existing set... For my usecases not setting it works fine... Otherwise we would have to add new endpoints for each future option. It should also work with the local schedule work that is now merged.

(persistent is probably a better name than cloudcall, as it may also interact with local schedules)

I follow the schedule most of the time, but disable zones that I don't need at the time, so I would like a way to 'not do this'... but I'm not sure if that should stay the default in all cases.

The cloud api also has some points where a new schedule overrides older cases. And for the knobs itself there are some settings on how they should behave (time; new schedule block, etc.) We should probably move some of this to proper per zone settings... with perhaps an easy way to set the default behavior for all zones.

Advanced clients can ask for specific behavior... but the other options are probably home/zone defined.

[Bekkie]

I would just make it an option on the existing set... For my usecases not setting it works fine... Otherwise we would have to add new endpoints for each future option. It should also work with the local schedule work that is now merged.

Do you referer this PR #22, this is still open with a merge conflict and failing test cases...

(persistent is probably a better name than cloudcall, as it may also interact with local schedules)

Agree

I follow the schedule most of the time, but disable zones that I don't need at the time, so I would like a way to 'not do this'... but I'm not sure if that should stay the default in all cases.

The current behaviour should be the default indeed.

The cloud api also has some points where a new schedule overrides older cases. And for the knobs itself there are some settings on how they should behave (time; new schedule block, etc.) We should probably move some of this to proper per zone settings... with perhaps an easy way to set the default behavior for all zones.

This is also what is configured in the Tado app, is not all visible to TadoLocal. Especially the difference between off, auto and and manual mode. TadoLocal only sees heating: on or off.

Advanced clients can ask for specific behavior... but the other options are probably home/zone defined.

Something like this?

Settings per zone to change:

PUT /zone/{zone_id}

{
  "name": "str",
  "zone_id": "int",
  "leader_device_id": "int",
  "order_id": "int", 
  "window_open_time": "int",  
  "window_rest_time": "int",
} 

PUT /xxxx/?
Settings per home:

{
   "history_retention": "int",     // keep history for x days
   "hvac_schedule_mode": {"none", "local", "tadosmart"},  // Use local heatmode [0/1], schedule or send to cloud
}

[Bekkie]

Added per 1.1.2 release