[tado] Add channel for PresenceState and support setting HOME/AWAY. Fixes #8826 (#8868)

Signed-off-by: Stefan Profanter <pro@users.noreply.github.com>

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

@@ -3,7 +3,7 @@
 The tado° binding integrates devices from [tado°](https://www.tado.com).
 
 It requires a fully functional tado° installation.
-You can then monitor and control all zone types (Heating, AC, Hot Water) as well as retrieve the HOME/AWAY status of mobile devices.
+You can then monitor and control all zone types (Heating, AC, Hot Water) as well as retrieve the HOME/AWAY status of mobile devices, and setting the HOME/AWAY status of your home.
 
 ## `home` Thing (the Bridge)
 
@@ -24,6 +24,12 @@ Bridge tado:home:demo [ username="mail@example.com", password="secret" ]
 
 Afterwards the discovery will show all zones and mobile devices associated with the user's home.
 
+### Channels
+
+Name | Type | Description | Read/Write
+-|-|-|-|-
+`homePresence` | String | Current presence value of the tado home. `HOME` and `AWAY` can be set | RW
+
 ## `zone` Thing
 
 A *zone* is an area/room of your home.
@@ -143,6 +149,7 @@ Bridge tado:home:demo [ username="mail@example.com", password="secret" ] {
 ## tado.items
 
 ```
+Switch             TADO_PRESENCE_home             "Tado Presence: [MAP(presence.map):%s]"               { channel="tado:home:demo:homePresence" }
 Number:Temperature HEAT_inside_temperature    "Inside Temperature"      { channel="tado:zone:demo:heating:currentTemperature" }
 Number             HEAT_humidity              "Humidity"                { channel="tado:zone:demo:heating:humidity" }
 Number             HEAT_heating_power         "Heating Power"           { channel="tado:zone:demo:heating:heatingPower" }
@@ -179,6 +186,10 @@ Switch             Phone_atHome               "Phone location [MAP(presence.map)
 ```
 sitemap tado label="Tado"
 {
+    Frame label="Status" {
+        Switch item=TADO_PRESENCE_home  icon="presence"
+    }
+
     Frame label="Heating" {
         Text      item=HEAT_inside_temperature
         Text      item=HEAT_humidity

bundles/org.openhab.binding.tado/pom.xml

@@ -18,7 +18,7 @@
     <dependency>
       <groupId>org.openhab.binding.tado</groupId>
       <artifactId>api-client</artifactId>
-      <version>1.3.0</version>
+      <version>1.4.1</version>
       <scope>compile</scope>
     </dependency>
   </dependencies>

bundles/org.openhab.binding.tado/src/main/api/pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>org.openhab.binding.tado</groupId>
 	<artifactId>api-client</artifactId>
-	<version>1.3.0</version>
+	<version>1.4.1</version>
 
 	<properties>
 		<maven.compiler.source>1.8</maven.compiler.source>

bundles/org.openhab.binding.tado/src/main/api/tado-api.yaml

@@ -73,6 +73,62 @@ paths:
         404:
           $ref: "#/responses/NotFound"
 
+  /homes/{home_id}/state:
+    get:
+      operationId: homeState
+      summary: Get state of home
+      tags:
+      - home
+      security:
+      - oauth:
+        - home.details:read
+      description: This will the current presence state of the home (HOME/AWAY).
+      parameters:
+      - $ref: "#/parameters/homeID"
+      responses:
+        200:
+          description: Home State
+          schema:
+            $ref: "#/definitions/HomeState"
+        401:
+          $ref: "#/responses/Unauthorized"
+        403:
+          $ref: "#/responses/AccessDenied"
+        404:
+          $ref: "#/responses/NotFound"
+
+  /homes/{home_id}/presenceLock:
+    put:
+      operationId: updatePresenceLock
+      summary: Set a presence lock state, i.e., HOME or AWAY
+      tags:
+        - home
+      security:
+        - oauth:
+            - home.operation:write
+      description: This will set the presence mode of the home
+      parameters:
+        - $ref: "#/parameters/homeID"
+        - name: json
+          in: body
+          description: The new presence settings.
+          required: true
+          schema:
+            $ref: "#/definitions/HomePresence"
+      responses:
+        200:
+          description: Presence mode successfully updated.
+        400:
+          $ref: "#/responses/BadRequest"
+        401:
+          $ref: "#/responses/Unauthorized"
+        403:
+          $ref: "#/responses/AccessDenied"
+        404:
+          $ref: "#/responses/NotFound"
+        422:
+          $ref: "#/responses/UnprocessableEntity"
+
   /homes/{home_id}/zones:
     get:
       operationId: listZones
@@ -368,6 +424,37 @@ definitions:
     - temperatureUnit
     - awayRadiusInMeters
 
+  HomeState:
+    type: object
+    properties:
+      presence:
+        description: Presence State.
+        $ref: "#/definitions/PresenceState"
+      name:
+        description: User defined name for the home.
+        type: string
+        readOnly: true
+      presenceLocked:
+        description: Not sure what this does..
+        type: boolean
+        readOnly: true
+      showHomePresenceSwitchButton:
+        description: Not sure what this does..
+        type: boolean
+        readOnly: true
+    required:
+      - presence
+      - presenceLocked
+
+  HomePresence:
+    type: object
+    properties:
+      homePresence:
+        description: Presence State.
+        $ref: "#/definitions/PresenceState"
+    required:
+      - homePresence
+
   TadoSystemType:
     description: The system type of the zone.
     type: string
@@ -426,6 +513,13 @@ definitions:
     - 'ON'
     - 'OFF'
 
+  PresenceState:
+    type: string
+    description: Enum to represent presence state.
+    enum:
+    - 'HOME'
+    - 'AWAY'
+
   GenericZoneSetting:
     type: object
     discriminator: type

bundles/org.openhab.binding.tado/src/main/java/org/openhab/binding/tado/internal/TadoBindingConstants.java

@@ -41,6 +41,8 @@ public class TadoBindingConstants {
         FAHRENHEIT
     }
 
+    public static final String CHANNEL_HOME_PRESENCE_MODE = "homePresence";
+
     public static final String CHANNEL_ZONE_CURRENT_TEMPERATURE = "currentTemperature";
     public static final String CHANNEL_ZONE_HUMIDITY = "humidity";
 

bundles/org.openhab.binding.tado/src/main/java/org/openhab/binding/tado/internal/handler/TadoHomeHandler.java

@@ -22,14 +22,19 @@ import org.openhab.binding.tado.internal.api.ApiException;
 import org.openhab.binding.tado.internal.api.HomeApiFactory;
 import org.openhab.binding.tado.internal.api.client.HomeApi;
 import org.openhab.binding.tado.internal.api.model.HomeInfo;
+import org.openhab.binding.tado.internal.api.model.HomePresence;
+import org.openhab.binding.tado.internal.api.model.HomeState;
+import org.openhab.binding.tado.internal.api.model.PresenceState;
 import org.openhab.binding.tado.internal.api.model.User;
 import org.openhab.binding.tado.internal.config.TadoHomeConfig;
+import org.openhab.core.library.types.OnOffType;
 import org.openhab.core.thing.Bridge;
 import org.openhab.core.thing.ChannelUID;
 import org.openhab.core.thing.ThingStatus;
 import org.openhab.core.thing.ThingStatusDetail;
 import org.openhab.core.thing.binding.BaseBridgeHandler;
 import org.openhab.core.types.Command;
+import org.openhab.core.types.RefreshType;
 import org.openhab.core.types.State;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -126,9 +131,44 @@ public class TadoHomeHandler extends BaseBridgeHandler {
         return homeId;
     }
 
+    public HomeState getHomeState() throws IOException, ApiException {
+        HomeApi api = getApi();
+        return api != null ? api.homeState(getHomeId()) : null;
+    }
+
+    public void updateHomeState() {
+        try {
+            updateState(TadoBindingConstants.CHANNEL_HOME_PRESENCE_MODE,
+                    getHomeState().getPresence() == PresenceState.HOME ? OnOffType.ON : OnOffType.OFF);
+        } catch (IOException | ApiException e) {
+            logger.debug("Error accessing tado server: {}", e.getMessage(), e);
+        }
+    }
+
     @Override
     public void handleCommand(ChannelUID channelUID, Command command) {
-        // Nothing to do for a bridge
+        String id = channelUID.getId();
+
+        if (command == RefreshType.REFRESH) {
+            updateHomeState();
+            return;
+        }
+
+        switch (id) {
+            case TadoBindingConstants.CHANNEL_HOME_PRESENCE_MODE:
+                HomePresence presence = new HomePresence();
+                presence.setHomePresence(command.toFullString().toUpperCase().equals("ON")
+                        || command.toFullString().toUpperCase().equals("HOME") ? PresenceState.HOME
+                                : PresenceState.AWAY);
+                try {
+                    api.updatePresenceLock(homeId, presence);
+                } catch (IOException | ApiException e) {
+                    logger.warn("Error setting home presence: {}", e.getMessage(), e);
+                }
+
+                break;
+
+        }
     }
 
     public State getBatteryLowAlarm(long zoneId) {

bundles/org.openhab.binding.tado/src/main/java/org/openhab/binding/tado/internal/handler/TadoZoneHandler.java

@@ -218,6 +218,11 @@ public class TadoZoneHandler extends BaseHomeThingHandler {
     }
 
     private void updateZoneState(boolean forceUpdate) {
+        TadoHomeHandler home = getHomeHandler();
+        if (home != null) {
+            home.updateHomeState();
+        }
+
         // No update during HVAC change debounce
         if (!forceUpdate && scheduledHvacChange != null && !scheduledHvacChange.isDone()) {
             return;
@@ -258,7 +263,6 @@ public class TadoZoneHandler extends BaseHomeThingHandler {
                     "Could not connect to server due to " + e.getMessage());
         }
 
-        TadoHomeHandler home = getHomeHandler();
         if (home != null) {
             updateState(TadoBindingConstants.CHANNEL_ZONE_BATTERY_LOW_ALARM, home.getBatteryLowAlarm(getZoneId()));
         }

bundles/org.openhab.binding.tado/src/main/resources/OH-INF/thing/thing-types.xml

@@ -9,6 +9,10 @@
 		<label>Tado Home</label>
 		<description>The user's tado home</description>
 
+		<channels>
+			<channel typeId="homePresence" id="homePresence"></channel>
+		</channels>
+
 		<config-description>
 			<parameter name="username" type="text" required="true">
 				<label>User Name</label>
@@ -108,6 +112,12 @@
 		</config-description>
 	</thing-type>
 
+	<channel-type id="homePresence">
+		<item-type>Switch</item-type>
+		<label>At Home</label>
+		<description>ON if at home, OFF if away</description>
+	</channel-type>
+
 	<channel-type id="currentTemperature">
 		<item-type>Number:Temperature</item-type>
 		<label>Temperature</label>