[tado] Add support for fanLevel, verticalSwing, horizontalSwing, light API (#12470)

* [tado] fix issue #12160 (first attempt)
* [tado] code style
* [tado] option descriptors
* [tado] add level5
* [tado] fan level and swing not allowed on heating or hot water
* [tado] warn about possible un-supported state values
* [tado] minor formatting
* [tado] harmonise getter methods for fan and swing state
* [tado] include all options in xml
* [tado] remove 's' from capabilities list names (go figure..)
* [tado] add OFF option
* [tado] add support for light channel, and dynamic channel decriptions
* [tado] tweak ReadMe for more clarity
* [tado] adopt reviewer suggestions

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

bundles/org.openhab.binding.tado/README.md

@@ -27,7 +27,7 @@ Afterwards the discovery will show all zones and mobile devices associated with
 ### Channels
 
 Name | Type | Description | Read/Write
--|-|-|-|-
+-|-|-|-
 `homePresence` | String | Current presence value of the tado home. `HOME` and `AWAY` can be set | RW
 
 ## `zone` Thing
@@ -70,16 +70,34 @@ Name | Type | Description | Read/Write | Zone type
 `acPower` | Switch | Indicates if the Air-Conditioning is Off or On | R | `AC`
 `hvacMode` | String | Active mode, one of `OFF`, `HEAT`, `COOL`, `DRY`, `FAN`, `AUTO` | RW | `HEATING` and `DHW` support `OFF` and `HEAT`, `AC` can support more
 `targetTemperature` | Number:Temperature | Set point | RW | `HEATING`, `AC`, `DHW`
-`fanspeed` | String | Fan speed, one of `AUTO`, `LOW`, `MIDDLE`, `HIGH` | RW | `AC`
-`swing` | Switch | Swing on/off | RW | `AC`
+`fanspeed`<sup>1)</sup> | String | Fan speed, one of `AUTO`, `LOW`, `MIDDLE`, `HIGH` | RW | `AC`
+`fanLevel`<sup>1)</sup> | String | Fan speed, one of <sup>3)</sup> `AUTO`, `SILENT`, `LEVEL1`, `LEVEL2`, `LEVEL3`, `LEVEL4`, `LEVEL5` | RW | `AC`
+`swing`<sup>2)</sup> | Switch | Swing on/off | RW | `AC`
+`verticalSwing`<sup>2)</sup> | String | Vertical swing state, one of <sup>3)</sup> `OFF`, `ON`, `UP`, `MID_UP`, `MID`, `MID_DOWN`, `DOWN`, `AUTO` | RW | `AC`
+`horizontalSwing`<sup>2)</sup> | String | Horizontal swing state, one of <sup>3)</sup> `OFF`, `ON`, `LEFT`, `MID_LEFT`, `MID`, `MID_RIGHT`, `RIGHT`, `AUTO` | RW | `AC`
 `overlayExpiry` | DateTime | End date and time of a timer | R | `HEATING`, `AC`, `DHW`
 `timerDuration` | Number | Timer duration in minutes | RW | `HEATING`, `AC`, `DHW`
 `operationMode` | String | Operation mode the zone is currently in. One of `SCHEDULE` (follow smart schedule), `MANUAL` (override until ended manually), `TIMER` (override for a given time), `UNTIL_CHANGE` (active until next smart schedule block or until AWAY mode becomes active) | RW | `HEATING`, `AC`, `DHW`
 `batteryLowAlarm` | Switch | A control device in the Zone has a low battery (if applicable) | R | Any Zone
 `openWindowDetected` | Switch | An open window has been detected in the Zone | R | Any Zone
+`light` | Switch | State (`ON`, `OFF`) of the control panel light (if applicable) | RW | `AC`
 
 The `RW` items are used to either override the schedule or to return to it (if `hvacMode` is set to `SCHEDULE`).
 
+<sup>1)</sup> Simpler A/C units have fan speed settings in the range [`LOW`, `MIDDLE`, `HIGH`].
+However, more sophisticated devices have settings in the range [`SILENT`, `LEVEL1`, `LEVEL2`, `LEVEL3`, `LEVEL4`].
+So you need to choose the respective channel type name that matches the features of your device.
+
+<sup>2)</sup> Simpler A/C units have a single switch type swing function that is either `ON` or `OFF`.
+However, more sophisticated devices may have either a vertical swing, a horizontal swing, or both, which could also have more complex settings.
+For example the horizontal swing function could simply be `ON` or it could have more complex settings in the range [`LEFT`, `MID_LEFT`, `MID`, `MID_RIGHT`, `RIGHT`].
+So you need to choose the respective channel type name that matches the features of your device.
+
+<sup>3)</sup> The _'one of'_ list contains all possible state values supported within the tado° binding.
+However, in reality different A/C units might only support a **_subset_** of those values.
+And indeed the subset of supported values might depend on the current state of the `acPower` and `hvacMode` channels.
+In that case, if you send a channel command value to an A/C unit which does not (currently) support that particular state value, then openHAB will report a '422' run-time error in the log.
+
 ### Item Command Collection
 
 Item changes are not immediately applied, but instead collected and only when no change is done for 5 seconds (by default - see `hvacChangeDebounce` above), the combined HVAC change is sent to the server.