[tado] Add support for fanLevel, verticalSwing, horizontalSwing, light API

[andrewfg]

Fixes #12160

Background

As described in #12160 the Tado API has been extended for Air Conditioners to support more advanced features. Specifically these devices now support some additional JSON sub-elements as follows..

1. A new fanLevel element providing extended fan speed possibilities compared to the earlier fanspeed element.
2. Two new verticalSwing, horizontalSwing elements providing extended swing possibilities than the earlier swing element.
3. A new light element for controlling the A/C unit panel light.

@Artur-Fedjukevits made a first attempt to support these additional JSON elements; but instead of simply adding support for the new fanLevel, verticalSwing, & horizontalSwing elements, he mistakenly removed support for the prior fanspeed & swing elements. So his solution is not backward compatible with existing older devices.

By contrast, this PR is to add support for the new JSON elements, and still retain support for existing devices without breaking compatibility.

Notes:

1. This PR introduces four new Channel types that correspond to the four new JSON elements.
2. Depending on the brand of A/C unit and its operation mode, (i.e. depending on the capabilities), the choice of possible state option values adapts dynamically.
3. This PR needs to be tested extensively by existing real users of Tado Air Conditioners.

Signed-off-by: Andrew Fiddian-Green software@whitebear.ch

[andrewfg]

Ping @dfrommi for comments..

[andrewfg]

Ping @Pro for comments / testing ..

[andrewfg]

Ping @Timtam for testing (???) ..

[Timtam]

I'm sorry, but I currently don't own an air conditioner, just heating equipment over here.

[Pro]

Ping @Pro for comments / testing ..

Same here, I also do not have an air conditioner to test. Sorry.

[andrewfg]

Adding @hpalne to this thread..

[andrewfg]

@Artur-Fedjukevits and @hpalne : my own Smart AC Controller is old, and my A/C unit is very rudimentary, so I cannot test the new functionality. I can only test that it does not (anymore) break the functionality of older systems. i.e. my testing is only 'old-features-still-working' rather than 'new-features-now-working'. => So I would be most grateful if you could test it from your side. :)

{ PS I am wondering if I could 'trick' Smart AC Controller to think it is connected to a full featured A/C unit.. So perhaps you can tell me your brand of A/C and the model number written on the front or back of its remote control? }

[hpalne]

@andrewfg I can try to test it, just need the compiled jar file.
The A/C unit is installed in our summer house so I don't have the model number. I can post it in the weekend if that would be beneficial?

[andrewfg]

just need the compiled jar file

org.openhab.binding.tado-3.3.0-SNAPSHOT.jar.zip

[andrewfg]

can post it in the weekend

Perfect :)

[andrewfg]

@hpalne see the ReadMe about the Channel names..

https://github.com/openhab/openhab-addons/blob/0d4bf3a2463b4fd493bbd97a5868b6a4383254af/bundles/org.openhab.binding.tado/README.md

[Freeride79]

@andrewfg I have the same issue with the Tado Binding and my LG AC.

2022-03-15 16:54:01.787 [WARN ] [ado.internal.handler.TadoZoneHandler] - Could not apply HVAC change on home 899993 and zone 1: Operation updateZoneOverlay failed with error 422

My issue is that I am totally new to GitHub and I am relatively new to Openhab. So if I want to test the new Binding, what do I have to do? Must i copy the jar file to my raspberry pi? If yes, in which folder? Sorry for being a newbie.

[andrewfg]

@Freeride79 in your OH Settings UI under Bindings, select to uninstall the release version of the Tado binding. Then take the jar file from the zip file two posts above this, and drop it in the 'add-ons' folder on your OH system.

[Artur-Fedjukevits]

just need the compiled jar file

org.openhab.binding.tado-3.3.0-SNAPSHOT.jar.zip

After I replaced the jar file, in my case it starts throwing 422 exception again. First capabilities request in "TadoZoneHandler.java" file on line 216 return this capabilities:

class AirConditioningCapabilities { class GenericZoneCapabilities { type: AIR_CONDITIONING } COOL: class AcModeCapabilities { temperatures: class TemperatureRange { celsius: class IntRange { min: 16 max: 31 step: 1.0 } fahrenheit: class IntRange { min: 61 max: 88 step: 1.0 } } fanSpeeds: null swings: null fanLevels: null horizontalSwings: null verticalSwings: null } HEAT: class AcModeCapabilities { temperatures: class TemperatureRange { celsius: class IntRange { min: 16 max: 31 step: 1.0 } fahrenheit: class IntRange { min: 61 max: 88 step: 1.0 } } fanSpeeds: null swings: null fanLevels: null horizontalSwings: null verticalSwings: null } DRY: class AcModeCapabilities { temperatures: null fanSpeeds: null swings: null fanLevels: null horizontalSwings: null verticalSwings: null } FAN: class AcModeCapabilities { temperatures: null fanSpeeds: null swings: null fanLevels: null horizontalSwings: null verticalSwings: null } AUTO: class AcModeCapabilities { temperatures: class TemperatureRange { celsius: class IntRange { min: 16 max: 31 step: 1.0 } fahrenheit: class IntRange { min: 61 max: 88 step: 1.0 } } fanSpeeds: null swings: null fanLevels: null horizontalSwings: null verticalSwings: null } }

And always when I'm trying to change hvacMode for example, in same file on line 112 get this overlay:

class Overlay { setting: class CoolingZoneSetting { class GenericZoneSetting { type: AIR_CONDITIONING } power: ON mode: HEAT temperature: class TemperatureObject { celsius: 25.0 fahrenheit: null } fanSpeed: null swing: null fanLevel: LEVEL4 verticalSwing: DOWN horizontalSwing: null } termination: class ManualTerminationCondition { class OverlayTerminationCondition { type: MANUAL projectedExpiry: null } } }

I suspect I get 422 exception because we sending unexpected elements even if it is null

[Freeride79]

@andrewfg I replaced also the jar file and got the same error message as before.

2022-03-16 06:47:32.175 [WARN ] [ado.internal.handler.TadoZoneHandler] - Could not apply HVAC change on home 899993 and zone 1: Operation updateZoneOverlay failed with error 422

org.openhab.binding.tado.internal.api.ApiException: Operation updateZoneOverlay failed with error 422
at org.openhab.binding.tado.internal.api.client.HomeApi.updateZoneOverlay(HomeApi.java:625) ~[?:?]
at org.openhab.binding.tado.internal.handler.TadoZoneHandler.setOverlay(TadoZoneHandler.java:114) ~[?:?]
at org.openhab.binding.tado.internal.TadoHvacChange.apply(TadoHvacChange.java:141) ~[?:?]
at org.openhab.binding.tado.internal.handler.TadoZoneHandler.lambda$0(TadoZoneHandler.java:325) ~[?:?]
at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515) [?:?]
at java.util.concurrent.FutureTask.run(FutureTask.java:264) [?:?]
at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:304) [?:?]
at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) [?:?]
at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) [?:?]
at java.lang.Thread.run(Thread.java:829) [?:?]

[andrewfg]

@Artur-Fedjukevits & @Freeride79 many thanks for testing, and apologies that it did not work; normally I would test on my own system, but unfortunately my A/C doesn't have the same features as yours.

So based on your logs, I will write JUnit test module, so I can test without actually having the correct hardware. It might take me a day or two..

[andrewfg]

I have just implemented the following changes..

• The super-set of all of yesterday's changes made variously by @Artur-Fedjukevits and myself.
• Implemented a new Channel for light
• Implemented dynamic State Description Options selection (for UI drop downs) for fanLevel and xxxSwing Channels.

The new JAR is here..
org.openhab.binding.tado-3.3.0-SNAPSHOT.jar.zip

@Freeride79 and @Artur-Fedjukevits can you please confirm the following..

1. Do the fanLevel and xxxSwing Channels still work as before? i.e. no regression from yesterday?
2. Does the light channel now work?
3. For fanLevel and xxxSwing Channels, does the choice of state options shown in UI drop downs, adapt to show only the sub-set of possible values appropriate to the capabilities of your actual A/C unit?
4. Indeed does the choice of values adapt depending on the current operating mode of the A/C?

[Freeride79]

@andrewfg I copied the new JAR to my Openhab and tried to test a little bit.

1. fanlevel and xxxSwing stilll work.

2. light is working now.
   'light' ON:
   
   'light' OFF:
   

3. Drop down
   fan level
   
   vertical swing
   
   horizontal swing
   
   With the swing drop down, I'm not shure if my A/C should have more options.

4. For this question, I have to do further testing

I think it's very important to send the right set of item changes and finalize it with the ZoneOperationMode (in my case Timer) and TimerDuration. If I put those items not at the end of my rule, it does not work.

2022-03-20 09:43:23.153 [DEBUG] [ado.internal.handler.TadoZoneHandler] - Setting overlay of home 899993 and zone 1 with overlay: class Overlay {

setting: class CoolingZoneSetting {

    class GenericZoneSetting {

        type: AIR_CONDITIONING

    }

    power: ON

    mode: HEAT

    temperature: class TemperatureObject {

        celsius: 24.0

        fahrenheit: null

    }

    fanSpeed: null

    swing: null

    light: ON

    fanLevel: LEVEL2

    verticalSwing: ON

    horizontalSwing: OFF

}

termination: class TimerTerminationCondition {

    class OverlayTerminationCondition {

        type: TIMER

        projectedExpiry: null

    }

    durationInSeconds: 36000

    expiry: null

    remainingTimeInSeconds: null

}

}

2022-03-20 09:43:23.533 [DEBUG] [ado.internal.handler.TadoZoneHandler] - Updating state of home 899993 and zone 1

[andrewfg]

@Freeride79 many thanks for the testing. If I understand you correctly, it is basically all now working properly for you??

important to send the right set of item changes and finalize it with the ZoneOperationMode

I think it is actually the other way round i.e. the Operation Mode should be sent first rather than last..

These A/C devices support different capabilities depending on a) whether the Power State is OFF or ON, and b) if the Power State is ON, whether the AC Mode is HEAT, COOL, FAN, DRY, etc. And if you send a command value for (say) a fanLevel that is not in the device's list of capabilities for the current actual Power State and AC Mode, then that command will probably fail.

So the correct sequence is as follows..

1. Send the Power State command e.g. ON
2. Send the AC Mode command e.g. COOL
3. Send the fanLevel (resp. xxxSwing) command e.g. fanLevel = LEVEL2 or horizontalSwing = ON etc.

I would expect that if you do not follow the sequence above, then you will probably get strange or erroneous results.

[andrewfg]

With the swing drop down, I'm not shure if my A/C should have more options.

@Freeride79 according to the logs that you submitted earlier, the swing options for your A/C are only OFF and ON

[andrewfg]

@Artur-Fedjukevits and @Freeride79 if/when you are happy with the functionality, could you kindly go to the ‘Files Changed’ tab on this page, hit the ‘Review Changes’ button on the top right, and ‘Approve’? That will give a signal to the OH Maintainers that they can start the code review prior to merging this PR into OH Main..

[Freeride79]

@Freeride79 many thanks for the testing. If I understand you correctly, it is basically all now working properly for you??

important to send the right set of item changes and finalize it with the ZoneOperationMode

I think it is actually the other way round i.e. the Operation Mode should be sent first rather than last..

These A/C devices support different capabilities depending on a) whether the Power State is OFF or ON, and b) if the Power State is ON, whether the AC Mode is HEAT, COOL, FAN, DRY, etc. And if you send a command value for (say) a fanLevel that is not in the device's list of capabilities for the current actual Power State and AC Mode, then that command will probably fail.

So the correct sequence is as follows..

1. Send the Power State command e.g. ON

2. Send the AC Mode command e.g. COOL

3. Send the fanLevel (resp. xxxSwing) command e.g. fanLevel = LEVEL2 or horizontalSwing = ON etc.

I would expect that if you do not follow the sequence above, then you will probably get strange or erroneous results.

@andrewfg yes, for me everything is working fine! Thank you very much.

Regarding the sequence you are right but I don't send ON to the Power State cause I thougth this is only readable but thats not my point.
I wanted to mention that there is the HVAC mode where I have to adress HEAT, COOL etc. at the beginning and the ZoneOperationMode, were I have to adress Shedule, Manual, Until change or Timer at the End. If I don't send this at the End, it does not work.

[Freeride79]

This works fine with my LG A/C! Thank you very much!

[andrewfg]

works fine with my LG A/C!

Glad to have been able to help. :)

ZoneOperationMode, were I have to address Schedule, Manual, Until change or Timer
If I don't send this at the End, it does not work.

Hmm. Any explicit setting that you make via OpenHAB, or via the App, or by touching the Smart A/C controller itself, implicitly (automatically) switches the operation mode from 'Schedule' to 'Until change'. And, although I did not try it, I think if you then change the operation mode to 'Manual' or 'Timer', the respective overridden setting value is persisted (??). But obviously if you command the operation mode back to 'Schedule' then the overridden setting value is cancelled.

[Artur-Fedjukevits]

Everything working fine!

[andrewfg]

=> This PR is now ready for the formal code review by OH-Maintainers.

[jlaur]

Thanks, looks good. A few minor comments added.

[jlaur]

LGTM - thanks!