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