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.sleepiq.internal.api;
  14
  15 import java.util.List;
  16
  17 import org.eclipse.jdt.annotation.NonNullByDefault;
  18 import org.eclipse.jdt.annotation.Nullable;
  19 import org.eclipse.jetty.client.HttpClient;
  20 import org.openhab.binding.sleepiq.internal.api.dto.Bed;
  21 import org.openhab.binding.sleepiq.internal.api.dto.FamilyStatusResponse;
  22 import org.openhab.binding.sleepiq.internal.api.dto.FoundationFeaturesResponse;
  23 import org.openhab.binding.sleepiq.internal.api.dto.FoundationStatusResponse;
  24 import org.openhab.binding.sleepiq.internal.api.dto.LoginInfo;
  25 import org.openhab.binding.sleepiq.internal.api.dto.PauseModeResponse;
  26 import org.openhab.binding.sleepiq.internal.api.dto.SleepDataResponse;
  27 import org.openhab.binding.sleepiq.internal.api.dto.Sleeper;
  28 import org.openhab.binding.sleepiq.internal.api.enums.FoundationActuator;
  29 import org.openhab.binding.sleepiq.internal.api.enums.FoundationActuatorSpeed;
  30 import org.openhab.binding.sleepiq.internal.api.enums.FoundationOutlet;
  31 import org.openhab.binding.sleepiq.internal.api.enums.FoundationOutletOperation;
  32 import org.openhab.binding.sleepiq.internal.api.enums.FoundationPreset;
  33 import org.openhab.binding.sleepiq.internal.api.enums.Side;
  34 import org.openhab.binding.sleepiq.internal.api.enums.SleepDataInterval;
  35 import org.openhab.binding.sleepiq.internal.api.impl.SleepIQImpl;
  36
  37 /**
  38  * This interface is the main API to access the SleepIQ system.
  39  *
  40  * @author Gregory Moyer - Initial contribution
  41  * @author Mark Hilbush - Added foundation functionality
  42  */
  43 @NonNullByDefault
  44 public interface SleepIQ {
  45     /**
  46      * Login to the {@link Configuration configured} account. This method is not
  47      * required to be called before other methods because all methods must
  48      * ensure login before acting. However, when the only desired action is to
  49      * login and not retrieve other data, this method is the most efficient
  50      * option.
  51      *
  52      * @return basic information about the logged in user
  53      * @throws UnauthorizedException
  54      *             if the credentials provided are not valid
  55      * @throws LoginException
  56      *             if the login request fails for any reason other than bad
  57      *             credentials (including missing credentials)
  58      */
  59     @Nullable
  60     LoginInfo login() throws LoginException, UnauthorizedException;
  61
  62     /**
  63      * Get a list of beds connected to the account.
  64      *
  65      * @return the list of beds
  66      * @throws LoginException
  67      *             if the login request fails for any reason other than bad
  68      *             credentials (including missing credentials)
  69      * @throws SleepIQException
  70      */
  71     List<Bed> getBeds() throws LoginException, SleepIQException, BedNotFoundException;
  72
  73     /**
  74      * Get a list of sleepers registered to this account for beds or bed positions
  75      * (left or right side).
  76      *
  77      * @return the list of sleepers
  78      * @throws LoginException
  79      * @throws SleepIQException
  80      */
  81     List<Sleeper> getSleepers() throws LoginException, SleepIQException;
  82
  83     /**
  84      * Get the status of all beds and all air chambers registered to this
  85      * account.
  86      *
  87      * @return the complete status of beds on the account
  88      * @throws LoginException
  89      * @throws SleepIQException
  90      */
  91     FamilyStatusResponse getFamilyStatus() throws LoginException, SleepIQException;
  92
  93     /**
  94      * Get the Sleep Data for a sleeper registered to this account.
  95      *
  96      * @param sleeperId the sleeper Id to query
  97      * @param interval The time period for which data is to be queried
  98      * @return the Sleep Data
  99      * @throws BedNotFoundException
 100      *             if the bed identifier was not found on the account
 101      * @throws LoginException
 102      * @throws SleepIQException
 103      */
 104     SleepDataResponse getSleepData(String sleeperId, SleepDataInterval interval)
 105             throws BedNotFoundException, LoginException, SleepIQException;
 106
 107     /**
 108      * Get the status of "pause mode" (disabling SleepIQ data upload) for a
 109      * specific bed. A bed in pause mode will send no information to the SleepIQ
 110      * cloud services. For example, if a sleeper is in bed and disables SleepIQ
 111      * (enables pause mode), the service will continue to report that the bed is
 112      * occupied even after the sleeper exits the bed until pause mode is
 113      * disabled.
 114      *
 115      * @return the status of pause mode for the specified bed
 116      * @throws BedNotFoundException
 117      *             if the bed identifier was not found on the account
 118      * @throws LoginException
 119      * @throws SleepIQException
 120      */
 121     PauseModeResponse getPauseMode(String bedId) throws BedNotFoundException, LoginException, SleepIQException;
 122
 123     /**
 124      * Set the sleep number for a chamber of a bed
 125      *
 126      * @param bedId the unique identifier of the bed
 127      * @param side thethe chamber of the bed
 128      * @param sleepNumber the new sleep number
 129      *
 130      * @throws LoginException
 131      * @throws SleepIQException
 132      */
 133     void setSleepNumber(String bedId, Side side, int sleepNumber) throws LoginException, SleepIQException;
 134
 135     /**
 136      * Set the pause (privacy) mode for a bed
 137      *
 138      * @param bedId the unique identifier of the bed
 139      *
 140      * @throws LoginException
 141      * @throws SleepIQException
 142      */
 143     void setPauseMode(String bedId, boolean command) throws LoginException, SleepIQException;
 144
 145     /**
 146      * Get the foundation features for a bed
 147      *
 148      * @param bedId the unique identifier of the bed
 149      *
 150      * @throws LoginException
 151      * @throws SleepIQException
 152      */
 153     FoundationFeaturesResponse getFoundationFeatures(String bedId) throws LoginException, SleepIQException;
 154
 155     /**
 156      * Get the foundation status for a bed
 157      *
 158      * @param bedId the unique identifier of the bed
 159      *
 160      * @throws LoginException
 161      * @throws SleepIQException
 162      */
 163     FoundationStatusResponse getFoundationStatus(String bedId) throws LoginException, SleepIQException;
 164
 165     /**
 166      * Set a foundation preset for the side of a bed
 167      *
 168      * @param bedId the unique identifier of the bed
 169      * @param side the chamber of the bed
 170      * @param preset the foundation preset
 171      * @param speed the speed with which the adjustment is made
 172      *
 173      * @throws LoginException
 174      * @throws SleepIQException
 175      */
 176     void setFoundationPreset(String bedId, Side side, FoundationPreset preset, FoundationActuatorSpeed speed)
 177             throws LoginException, SleepIQException;
 178
 179     /**
 180      * Set a foundation position for the side of a bed
 181      *
 182      * @param bedId the unique identifier of the bed
 183      * @param side the chamber of the bed
 184      * @param actuator the head or foot of the bed
 185      * @param position the new position of the actuator
 186      * @param speed the speed with which the adjustment is made
 187      *
 188      * @throws LoginException
 189      * @throws SleepIQException
 190      */
 191     void setFoundationPosition(String bedId, Side side, FoundationActuator actuator, int position,
 192             FoundationActuatorSpeed speed) throws LoginException, SleepIQException;
 193
 194     /**
 195      * Turn a foundation outlet on or off
 196      *
 197      * @param bedId the unique identifier of the bed
 198      * @param outlet the foundation outlet to control
 199      * @param operation set the outlet on or off
 200      *
 201      * @throws LoginException
 202      * @throws SleepIQException
 203      */
 204     void setFoundationOutlet(String bedId, FoundationOutlet outlet, FoundationOutletOperation operation)
 205             throws LoginException, SleepIQException;
 206
 207     /**
 208      * Create a default implementation instance of this interface. Each call to
 209      * this method will create a new object.
 210      *
 211      * @param config the configuration to use for the new instance
 212      * @param httpClient handle to the Jetty http client
 213      * @return a concrete implementation of this interface
 214      */
 215     static SleepIQ create(Configuration config, HttpClient httpClient) {
 216         return new SleepIQImpl(config, httpClient);
 217     }
 218
 219     /**
 220      * Close down the cloud service
 221      */
 222     void shutdown();
 223 }