[netatmo] Rework room actions (#12870)

* [netatmo] Rework room actions
* Clarify what thermostat modes can be used for the action

Fix #12836

Signed-off-by: Laurent Garnier <lg.hc@free.fr>

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

@@ -574,10 +574,10 @@ Person things are automatically created in discovery process for all known perso
 All these channels except at-home are read only.
 
 
-# Configuration Examples
+## Configuration Examples
 
 
-## things/netatmo.things
+### things/netatmo.things
 
 ```
 Bridge netatmo:account:home "Netatmo Account" [clientId="xxxxx", clientSecret="yyyy", refreshToken="zzzzz"] {
@@ -596,7 +596,7 @@ Bridge netatmo:account:home "Netatmo Account" [clientId="xxxxx", clientSecret="y
 ```
 
 
-## Sample configuration of live-stream-url channels:
+### Sample configuration of live-stream-url channels:
 
 ```
         ....
@@ -609,7 +609,7 @@ Bridge netatmo:account:home "Netatmo Account" [clientId="xxxxx", clientSecret="y
 ```
 
 
-## items/netatmo.items
+### items/netatmo.items
 
 ```
 # Indoor Module
@@ -648,7 +648,7 @@ Number:Length        Rain_Hour                         "Rain Last Hour [%.1f %un
 Number:Length        Rain_Today                        "Rain Today [%.1f %unit%]"                                   <rain>             { channel = "netatmo:rain:home:inside:rainModule:rain#sum-24"}
 ```
 
-## sitemaps/netatmo.sitemap
+### sitemaps/netatmo.sitemap
 
 ```
 sitemap netatmo label="Netatmo" {
@@ -696,26 +696,74 @@ sitemap netatmo label="Netatmo" {
 }
 ```
 
+## Rule Actions
 
-# Sample data
+Multiple actions are supported by this binding. In classic rules these are accessible as shown in this example (adjust getActions with your ThingId):
+
+Example
+
+```
+ val actions = getActions("netatmo","netatmo:room:home:home:livingroom")
+ if(null === actions) {
+        logInfo("actions", "Actions not found, check thing ID")
+        return
+ }
+```
+
+### setThermRoomTempSetpoint(temp,endtime)
+
+Sends a temperature setpoint (and switch to manual mode) to the thermostat for a room with an end time.
+
+Parameters:
+
+| Name    | Description                                                          |
+|---------|----------------------------------------------------------------------|
+| temp    | The temperature setpoint.                                            |
+| endtime | Time the setpoint should end (Local Unix time in seconds).           |
+
+Example:
+
+```
+actions.setThermRoomTempSetpoint(19.0, 1654387205)
+```
+
+### setThermRoomModeSetpoint(mode,endtime)
+
+Sends a mode to the thermostat for a room with an optional end time.
+
+Parameters:
+
+| Name    | Description                                                          |
+|---------|----------------------------------------------------------------------|
+| mode    | The mode to set: MANUAL, MAX or HOME.                                |
+| endtime | Time the setpoint should end (Local Unix time in seconds).           |
+
+Example:
+
+```
+actions.setThermRoomModeSetpoint("MANUAL", 1654387205)
+actions.setThermRoomModeSetpoint("HOME", null)
+```
+
+## Sample data
 
 If you want to evaluate this binding but have not got a Netatmo station yourself
 yet, you can search on the web for a publicly shared weather station.
 
 
-# Icons
+## Icons
 
 The following icons are used by original Netatmo web app:
 
 
-## Modules
+### Modules
 
 - https://my.netatmo.com/images/my/app/module_int.png
 - https://my.netatmo.com/images/my/app/module_ext.png
 - https://my.netatmo.com/images/my/app/module_rain.png
 
 
-## Battery status
+### Battery status
 
 - https://my.netatmo.com/images/my/app/battery_verylow.png
 - https://my.netatmo.com/images/my/app/battery_low.png
@@ -724,7 +772,7 @@ The following icons are used by original Netatmo web app:
 - https://my.netatmo.com/images/my/app/battery_full.png
 
 
-## Signal status
+### Signal status
 
 - https://my.netatmo.com/images/my/app/signal_verylow.png
 - https://my.netatmo.com/images/my/app/signal_low.png
@@ -733,7 +781,7 @@ The following icons are used by original Netatmo web app:
 - https://my.netatmo.com/images/my/app/signal_full.png
 
 
-## Wifi status
+### Wifi status
 
 - https://my.netatmo.com/images/my/app/wifi_low.png
 - https://my.netatmo.com/images/my/app/wifi_medium.png

bundles/org.openhab.binding.netatmo/src/main/java/org/openhab/binding/netatmo/internal/action/RoomActions.java

@@ -14,6 +14,7 @@ package org.openhab.binding.netatmo.internal.action;
 
 import java.util.Optional;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
@@ -61,90 +62,68 @@ public class RoomActions implements ThingActions {
         return (ThingHandler) handler;
     }
 
-    /**
+    @RuleAction(label = "@text/actionSetThermRoomTempSetpointLabel", description = "@text/actionSetThermRoomTempSetpointDesc")
-     * The setThermpoint room thing action
+    public void setThermRoomTempSetpoint(
-     */
+            @ActionInput(name = "temp", label = "@text/actionInputSetpointLabel", description = "@text/actionInputSetpointDesc") @Nullable Double temp,
-    @RuleAction(label = "@text/actionLabel", description = "@text/actionDesc")
-    public void setThermpoint(
-            @ActionInput(name = "setpoint", label = "@text/actionInputSetpointLabel", description = "@text/actionInputSetpointDesc") @Nullable Double temp,
             @ActionInput(name = "endtime", label = "@text/actionInputEndtimeLabel", description = "@text/actionInputEndtimeDesc") @Nullable Long endTime) {
-        setThermpoint(temp, endTime, "MANUAL");
+        CommonInterface roomHandler = handler;
+        if (roomHandler == null) {
+            logger.info("Handler not set for room thing actions.");
+            return;
+        } else if (temp == null) {
+            logger.info("Temperature is required, action ignored");
+            return;
+        } else if (endTime == null) {
+            logger.info("Temperature provided but no endtime given, action ignored");
+            return;
+        }
+        energy.ifPresent(cap -> cap.setRoomThermTemp(roomHandler.getId(), temp, endTime, SetpointMode.MANUAL));
     }
 
-    @RuleAction(label = "@text/actionLabel", description = "@text/actionDesc")
+    @RuleAction(label = "@text/actionSetThermRoomModeSetpointLabel", description = "@text/actionSetThermRoomModeSetpointDesc")
-    public void seThermpoint(
+    public void setThermRoomModeSetpoint(
             @ActionInput(name = "mode", label = "@text/actionInputModeLabel", description = "@text/actionInputModeDesc") @Nullable String mode,
             @ActionInput(name = "endtime", label = "@text/actionInputEndtimeLabel", description = "@text/actionInputEndtimeDesc") @Nullable Long endTime) {
-        setThermpoint(null, endTime, mode);
+        CommonInterface roomHandler = handler;
+        if (roomHandler == null) {
+            logger.info("Handler not set for room thing actions.");
+            return;
+        } else if (mode == null) {
+            logger.info("Mode is required, action ignored");
+            return;
         }
 
-    @RuleAction(label = "@text/actionLabel", description = "@text/actionDesc")
-    public void setThermpoint(
-            @ActionInput(name = "setpoint", label = "@text/actionInputSetpointLabel", description = "@text/actionInputSetpointDesc") @Nullable Double temp,
-            @ActionInput(name = "endtime", label = "@text/actionInputEndtimeLabel", description = "@text/actionInputEndtimeDesc") @Nullable Long endTime,
-            @ActionInput(name = "mode", label = "@text/actionInputModeLabel", description = "@text/actionInputModeDesc") @Nullable String mode) {
-        CommonInterface roomHandler = handler;
-        if (roomHandler != null) {
-            String roomId = roomHandler.getId();
         SetpointMode targetMode = SetpointMode.UNKNOWN;
-            Long targetEndTime = endTime;
-            Double targetTemp = temp;
-            if (mode != null) {
         try {
             targetMode = SetpointMode.valueOf(mode);
             if (!ALLOWED_MODES.contains(targetMode)) {
-                        logger.info("Mode can only be MAX, HOME or MANUAL for a room");
+                logger.info("Mode can only be {} for a room",
+                        ALLOWED_MODES.stream().map(s -> s.name()).collect(Collectors.joining(", ")));
                 return;
             }
         } catch (IllegalArgumentException e) {
             logger.info("Invalid mode passed : {} - {}", mode, e.getMessage());
             return;
         }
-            }
+
-            if (temp != null) {
+        Long targetEndTime = endTime;
-                logger.debug("Temperature provided, mode forced to MANUAL.");
-                targetMode = SetpointMode.MANUAL;
-                if (targetEndTime == null) {
-                    logger.info("Temperature provided but no endtime given, action ignored");
-                    return;
-                }
-            } else {
         if (SetpointMode.HOME.equals(targetMode)) {
             targetEndTime = 0L;
-                    targetTemp = 0.0;
+        } else if (targetEndTime == null) {
-                } else {
+            logger.info("No endtime given, action ignored");
-                    logger.info("mode is required if no temperature setpoint provided");
             return;
         }
-            }
 
-            try {
-                double setpointTemp = targetTemp != null ? targetTemp : 0;
         long setpointEnd = targetEndTime;
         SetpointMode setpointMode = targetMode;
-                energy.ifPresent(cap -> cap.setRoomThermTemp(roomId, setpointTemp, setpointEnd, setpointMode));
+        energy.ifPresent(cap -> cap.setRoomThermTemp(roomHandler.getId(), 0, setpointEnd, setpointMode));
-            } catch (IllegalArgumentException e) {
-                logger.debug("Ignoring setRoomThermpoint command due to illegal argument exception: {}",
-                        e.getMessage());
-            }
-        } else {
-            logger.info("Handler not set for room thing actions.");
-        }
     }
 
-    /**
+    public static void setThermRoomTempSetpoint(ThingActions actions, @Nullable Double temp, @Nullable Long endTime) {
-     * Static setThermpoint method for Rules DSL backward compatibility
+        ((RoomActions) actions).setThermRoomTempSetpoint(temp, endTime);
-     */
-    public static void setThermpoint(ThingActions actions, @Nullable Double temp, @Nullable Long endTime,
-            @Nullable String mode) {
-        ((RoomActions) actions).setThermpoint(temp, endTime, mode);
     }
 
-    public static void setThermpoint(ThingActions actions, @Nullable Double temp, @Nullable Long endTime) {
+    public static void setThermRoomModeSetpoint(ThingActions actions, @Nullable String mode, @Nullable Long endTime) {
-        setThermpoint(actions, temp, endTime, null);
+        ((RoomActions) actions).setThermRoomModeSetpoint(mode, endTime);
-    }
-
-    public static void setThermpoint(ThingActions actions, @Nullable String mode, @Nullable Long endTime) {
-        setThermpoint(actions, null, endTime, mode);
     }
 }

bundles/org.openhab.binding.netatmo/src/main/resources/OH-INF/i18n/netatmo.properties

@@ -398,11 +398,13 @@ request-time-out = Request timed out - will attempt reconnection later
 
 # actions
 
+actionSetThermRoomTempSetpointLabel = send temperature setpoint to the thermostat for a room
+actionSetThermRoomTempSetpointDesc = Sends a temperature setpoint (and switch to manual mode) to the thermostat for a room with an end time.
 actionInputSetpointLabel = Setpoint
-actionInputSetpointDesc = The temperature setpoint
+actionInputSetpointDesc = The temperature setpoint.
 actionInputEndtimeLabel = Endtime
-actionInputEndtimeDesc = Time the setpoint should end
+actionInputEndtimeDesc = Time the setpoint should end (Local Unix time in seconds).
+actionSetThermRoomModeSetpointLabel = send mode to the thermostat for a room
+actionSetThermRoomModeSetpointDesc = Sends a mode to the thermostat for a room with an optional end time.
 actionInputModeLabel = Mode
-actionInputModeDesc = The mode to set: MANUAL, SCHEDULE or FG (Frost-Guard)
+actionInputModeDesc = The mode to set: MANUAL, MAX or HOME.
-actionLabel = send a set room thermpoint command
-actionDesc = Send set room thermpoint command with endtime.