git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2023 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.nest.internal.sdm.dto;
  14
  15 import static java.util.Map.entry;
  16
  17 import java.math.BigDecimal;
  18 import java.time.Duration;
  19 import java.time.ZonedDateTime;
  20 import java.util.LinkedHashMap;
  21 import java.util.Map;
  22 import java.util.Map.Entry;
  23
  24 import org.openhab.binding.nest.internal.sdm.dto.SDMTraits.SDMFanTimerMode;
  25 import org.openhab.binding.nest.internal.sdm.dto.SDMTraits.SDMThermostatEcoMode;
  26 import org.openhab.binding.nest.internal.sdm.dto.SDMTraits.SDMThermostatMode;
  27
  28 /**
  29  * The {@link SDMCommands} provides classes used for mapping all SDM REST API device command requests and responses.
  30  *
  31  * @author Wouter Born - Initial contribution
  32  *
  33  * @see <a href="https://developers.google.com/nest/device-access/reference/rest/v1/enterprises.devices/executeCommand">
  34  *      https://developers.google.com/nest/device-access/reference/rest/v1/enterprises.devices/executeCommand</a>
  35  */
  36 public class SDMCommands {
  37
  38     /**
  39      * Command request parent.
  40      */
  41     public abstract static class SDMCommandRequest<T extends SDMCommandResponse> {
  42         private final String command;
  43         private final Map<String, Object> params = new LinkedHashMap<>();
  44
  45         @SafeVarargs
  46         private SDMCommandRequest(String command, Entry<String, Object>... params) {
  47             this.command = command;
  48             for (Entry<String, Object> param : params) {
  49                 this.params.put(param.getKey(), param.getValue());
  50             }
  51         }
  52
  53         public String getCommand() {
  54             return command;
  55         }
  56
  57         public Map<String, Object> getParams() {
  58             return params;
  59         }
  60
  61         @SuppressWarnings("unchecked")
  62         public Class<T> getResponseClass() {
  63             return (Class<T>) SDMCommandResponse.class;
  64         }
  65     }
  66
  67     /**
  68      * Command response parent. This class is also used for responses without additional data.
  69      */
  70     public static class SDMCommandResponse {
  71     }
  72
  73     // CameraEventImage trait commands
  74
  75     /**
  76      * Generates a download URL for the image related to a camera event.
  77      */
  78     public static class SDMGenerateCameraImageRequest extends SDMCommandRequest<SDMGenerateCameraImageResponse> {
  79
  80         /**
  81          * Event images expire 30 seconds after the event is published. Make sure to download the image prior to
  82          * expiration.
  83          */
  84         public static final Duration EVENT_IMAGE_VALIDITY = Duration.ofSeconds(30);
  85
  86         /**
  87          * @param eventId ID of the camera event to request a related image for.
  88          */
  89         public SDMGenerateCameraImageRequest(String eventId) {
  90             super("sdm.devices.commands.CameraEventImage.GenerateImage", entry("eventId", eventId));
  91         }
  92
  93         @Override
  94         public Class<SDMGenerateCameraImageResponse> getResponseClass() {
  95             return SDMGenerateCameraImageResponse.class;
  96         }
  97     }
  98
  99     public static class SDMGenerateCameraImageResults {
 100         /**
 101          * The URL to download the camera image from.
 102          */
 103         public String url;
 104
 105         /**
 106          * Token to use in the HTTP Authorization header when downloading the camera image.
 107          */
 108         public String token;
 109     }
 110
 111     public static class SDMGenerateCameraImageResponse extends SDMCommandResponse {
 112         public SDMGenerateCameraImageResults results;
 113     }
 114
 115     // CameraLiveStream trait commands
 116
 117     /**
 118      * Request a token to access a camera RTSP live stream URL.
 119      */
 120     public static class SDMGenerateCameraRtspStreamRequest
 121             extends SDMCommandRequest<SDMGenerateCameraRtspStreamResponse> {
 122         public SDMGenerateCameraRtspStreamRequest() {
 123             super("sdm.devices.commands.CameraLiveStream.GenerateRtspStream");
 124         }
 125
 126         @Override
 127         public Class<SDMGenerateCameraRtspStreamResponse> getResponseClass() {
 128             return SDMGenerateCameraRtspStreamResponse.class;
 129         }
 130     }
 131
 132     /**
 133      * Camera RTSP live stream URLs.
 134      */
 135     public static class SDMCameraRtspStreamUrls {
 136         public String rtspUrl;
 137     }
 138
 139     public static class SDMGenerateCameraRtspStreamResults {
 140         /**
 141          * Camera RTSP live stream URLs.
 142          */
 143         public SDMCameraRtspStreamUrls streamUrls;
 144
 145         /**
 146          * Token to use to extend the {@link #streamToken} for an RTSP live stream.
 147          */
 148         public String streamExtensionToken;
 149
 150         /**
 151          * Token to use to access an RTSP live stream.
 152          */
 153         public String streamToken;
 154
 155         /**
 156          * Time at which both {@link #streamExtensionToken} and {@link #streamToken} expire.
 157          */
 158         public ZonedDateTime expiresAt;
 159     }
 160
 161     public static class SDMGenerateCameraRtspStreamResponse extends SDMCommandResponse {
 162         public SDMGenerateCameraRtspStreamResults results;
 163     }
 164
 165     /**
 166      * Request a new RTSP live stream URL access token to replace a valid RTSP access token before it expires. This is
 167      * also used to replace a valid RTSP token from a previous ExtendRtspStream command request.
 168      */
 169     public static class SDMExtendCameraRtspStreamRequest extends SDMCommandRequest<SDMExtendCameraRtspStreamResponse> {
 170         /**
 171          * @param streamExtensionToken Token to use to request an extension to the RTSP streaming token.
 172          */
 173         public SDMExtendCameraRtspStreamRequest(String streamExtensionToken) {
 174             super("sdm.devices.commands.CameraLiveStream.ExtendRtspStream",
 175                     entry("streamExtensionToken", streamExtensionToken));
 176         }
 177
 178         @Override
 179         public Class<SDMExtendCameraRtspStreamResponse> getResponseClass() {
 180             return SDMExtendCameraRtspStreamResponse.class;
 181         }
 182     }
 183
 184     public static class SDMExtendCameraRtspStreamResults {
 185         /**
 186          * Token to use to view an existing RTSP live stream and to request an extension to the streaming token.
 187          */
 188         public String streamExtensionToken;
 189
 190         /**
 191          * New token to use to access an existing RTSP live stream.
 192          */
 193         public String streamToken;
 194
 195         /**
 196          * Time at which both {@link #streamExtensionToken} and {@link #streamToken} expire.
 197          */
 198         public ZonedDateTime expiresAt;
 199     }
 200
 201     public static class SDMExtendCameraRtspStreamResponse extends SDMCommandResponse {
 202         public SDMExtendCameraRtspStreamResults results;
 203     }
 204
 205     /**
 206      * Invalidates a valid RTSP access token and stops the RTSP live stream tied to that access token.
 207      */
 208     public static class SDMStopCameraRtspStreamRequest extends SDMCommandRequest<SDMCommandResponse> {
 209         /**
 210          * @param streamExtensionToken Token to use to invalidate an existing RTSP live stream.
 211          */
 212         public SDMStopCameraRtspStreamRequest(String streamExtensionToken) {
 213             super("sdm.devices.commands.CameraLiveStream.StopRtspStream",
 214                     entry("streamExtensionToken", streamExtensionToken));
 215         }
 216     }
 217
 218     // Fan trait commands
 219
 220     /**
 221      * Change the fan timer.
 222      */
 223     public static class SDMSetFanTimerRequest extends SDMCommandRequest<SDMCommandResponse> {
 224         public SDMSetFanTimerRequest(SDMFanTimerMode timerMode) {
 225             super("sdm.devices.commands.Fan.SetTimer", entry("timerMode", timerMode.name()));
 226         }
 227
 228         /**
 229          * @param duration Specifies the length of time in seconds that the timer is set to run.
 230          *            Range: "1s" to "43200s"
 231          *            Default: "900s"
 232          */
 233         public SDMSetFanTimerRequest(SDMFanTimerMode timerMode, Duration duration) {
 234             super("sdm.devices.commands.Fan.SetTimer", entry("timerMode", timerMode.name()),
 235                     entry("duration", duration.toSeconds() + "s"));
 236         }
 237     }
 238
 239     // ThermostatEco trait commands
 240
 241     /**
 242      * Change the thermostat Eco mode.
 243      *
 244      * To change the thermostat mode to HEAT, COOL, or HEATCOOL, use the {@link SDMSetThermostatModeRequest}.
 245      * <br>
 246      * <br>
 247      * This command impacts other traits, based on the current status of, or changes to, the Eco mode:
 248      * <ul>
 249      * <li>If Eco mode is OFF, the thermostat mode will default to the last standard mode (HEAT, COOL, HEATCOOL, or OFF)
 250      * that was active.</li>
 251      * <li>If Eco mode is MANUAL_ECO:
 252      * <ul>
 253      * <li>Commands for the ThermostatTemperatureSetpoint trait are rejected.</li>
 254      * <li>Temperature setpoints are not returned by the ThermostatTemperatureSetpoint trait.</li>
 255      * </ul>
 256      * </li>
 257      * </ul>
 258      *
 259      * Some thermostat models do not support changing the Eco mode when the thermostat mode is OFF, according to the
 260      * ThermostatMode trait. The thermostat mode must be changed to HEAT, COOL, or HEATCOOL prior to changing the Eco
 261      * mode.
 262      */
 263     public static class SDMSetThermostatEcoModeRequest extends SDMCommandRequest<SDMCommandResponse> {
 264         public SDMSetThermostatEcoModeRequest(SDMThermostatEcoMode mode) {
 265             super("sdm.devices.commands.ThermostatEco.SetMode", entry("mode", mode.name()));
 266         }
 267     }
 268
 269     // ThermostatMode trait commands
 270
 271     /**
 272      * Change the thermostat mode.
 273      */
 274     public static class SDMSetThermostatModeRequest extends SDMCommandRequest<SDMCommandResponse> {
 275         public SDMSetThermostatModeRequest(SDMThermostatMode mode) {
 276             super("sdm.devices.commands.ThermostatMode.SetMode", entry("mode", mode.name()));
 277         }
 278     }
 279
 280     // ThermostatTemperatureSetpoint trait commands
 281
 282     /**
 283      * Sets the target temperature when the thermostat is in COOL mode.
 284      */
 285     public static class SDMSetThermostatCoolSetpointRequest extends SDMCommandRequest<SDMCommandResponse> {
 286         /**
 287          * @param temperature the target temperature in degrees Celsius
 288          */
 289         public SDMSetThermostatCoolSetpointRequest(BigDecimal temperature) {
 290             super("sdm.devices.commands.ThermostatTemperatureSetpoint.SetCool", entry("coolCelsius", temperature));
 291         }
 292     }
 293
 294     /**
 295      * Sets the target temperature when the thermostat is in HEAT mode.
 296      */
 297     public static class SDMSetThermostatHeatSetpointRequest extends SDMCommandRequest<SDMCommandResponse> {
 298         /**
 299          * @param temperature the target temperature in degrees Celsius
 300          */
 301         public SDMSetThermostatHeatSetpointRequest(BigDecimal temperature) {
 302             super("sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat", entry("heatCelsius", temperature));
 303         }
 304     }
 305
 306     /**
 307      * Sets the minimum and maximum temperatures when the thermostat is in HEATCOOL mode.
 308      */
 309     public static class SDMSetThermostatRangeSetpointRequest extends SDMCommandRequest<SDMCommandResponse> {
 310         /**
 311          * @param minTemperature the minimum target temperature in degrees Celsius
 312          * @param maxTemperature the maximum target temperature in degrees Celsius
 313          */
 314         public SDMSetThermostatRangeSetpointRequest(BigDecimal minTemperature, BigDecimal maxTemperature) {
 315             super("sdm.devices.commands.ThermostatTemperatureSetpoint.SetRange", entry("heatCelsius", minTemperature),
 316                     entry("coolCelsius", maxTemperature));
 317         }
 318     }
 319 }