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     public @Nullable LoginInfo login() throws LoginException, UnauthorizedException;
  60
  61     /**
  62      * Get a list of beds connected to the account.
  63      *
  64      * @return the list of beds
  65      * @throws LoginException
  66      *             if the login request fails for any reason other than bad
  67      *             credentials (including missing credentials)
  68      * @throws SleepIQException
  69      */
  70     public List<Bed> getBeds() throws LoginException, SleepIQException, BedNotFoundException;
  71
  72     /**
  73      * Get a list of sleepers registered to this account for beds or bed positions
  74      * (left or right side).
  75      *
  76      * @return the list of sleepers
  77      * @throws LoginException
  78      * @throws SleepIQException
  79      */
  80     public List<Sleeper> getSleepers() throws LoginException, SleepIQException;
  81
  82     /**
  83      * Get the status of all beds and all air chambers registered to this
  84      * account.
  85      *
  86      * @return the complete status of beds on the account
  87      * @throws LoginException
  88      * @throws SleepIQException
  89      */
  90     public FamilyStatusResponse getFamilyStatus() throws LoginException, SleepIQException;
  91
  92     /**
  93      * Get the Sleep Data for a sleeper registered to this account.
  94      *
  95      * @param sleeperId the sleeper Id to query
  96      * @param interval The time period for which data is to be queried
  97      * @return the Sleep Data
  98      * @throws BedNotFoundException
  99      *             if the bed identifier was not found on the account
 100      * @throws LoginException
 101      * @throws SleepIQException
 102      */
 103     public SleepDataResponse getSleepData(String sleeperId, SleepDataInterval interval)
 104             throws BedNotFoundException, LoginException, SleepIQException;
 105
 106     /**
 107      * Get the status of "pause mode" (disabling SleepIQ data upload) for a
 108      * specific bed. A bed in pause mode will send no information to the SleepIQ
 109      * cloud services. For example, if a sleeper is in bed and disables SleepIQ
 110      * (enables pause mode), the service will continue to report that the bed is
 111      * occupied even after the sleeper exits the bed until pause mode is
 112      * disabled.
 113      *
 114      * @return the status of pause mode for the specified bed
 115      * @throws BedNotFoundException
 116      *             if the bed identifier was not found on the account
 117      * @throws LoginException
 118      * @throws SleepIQException
 119      */
 120     public PauseModeResponse getPauseMode(String bedId) throws BedNotFoundException, LoginException, SleepIQException;
 121
 122     /**
 123      * Set the sleep number for a chamber of a bed
 124      *
 125      * @param bedId the unique identifier of the bed
 126      * @param side thethe chamber of the bed
 127      * @param sleepNumber the new sleep number
 128      *
 129      * @throws LoginException
 130      * @throws SleepIQException
 131      */
 132     public void setSleepNumber(String bedId, Side side, int sleepNumber) throws LoginException, SleepIQException;
 133
 134     /**
 135      * Set the pause (privacy) mode for a bed
 136      *
 137      * @param bedId the unique identifier of the bed
 138      *
 139      * @throws LoginException
 140      * @throws SleepIQException
 141      */
 142     public void setPauseMode(String bedId, boolean command) throws LoginException, SleepIQException;
 143
 144     /**
 145      * Get the foundation features for a bed
 146      *
 147      * @param bedId the unique identifier of the bed
 148      *
 149      * @throws LoginException
 150      * @throws SleepIQException
 151      */
 152     public FoundationFeaturesResponse getFoundationFeatures(String bedId) throws LoginException, SleepIQException;
 153
 154     /**
 155      * Get the foundation status for a bed
 156      *
 157      * @param bedId the unique identifier of the bed
 158      *
 159      * @throws LoginException
 160      * @throws SleepIQException
 161      */
 162     public FoundationStatusResponse getFoundationStatus(String bedId) throws LoginException, SleepIQException;
 163
 164     /**
 165      * Set a foundation preset for the side of a bed
 166      *
 167      * @param bedId the unique identifier of the bed
 168      * @param side the chamber of the bed
 169      * @param preset the foundation preset
 170      * @param speed the speed with which the adjustment is made
 171      *
 172      * @throws LoginException
 173      * @throws SleepIQException
 174      */
 175     public void setFoundationPreset(String bedId, Side side, FoundationPreset preset, FoundationActuatorSpeed speed)
 176             throws LoginException, SleepIQException;
 177
 178     /**
 179      * Set a foundation position for the side of a bed
 180      *
 181      * @param bedId the unique identifier of the bed
 182      * @param side the chamber of the bed
 183      * @param actuator the head or foot of the bed
 184      * @param position the new position of the actuator
 185      * @param speed the speed with which the adjustment is made
 186      *
 187      * @throws LoginException
 188      * @throws SleepIQException
 189      */
 190     public void setFoundationPosition(String bedId, Side side, FoundationActuator actuator, int position,
 191             FoundationActuatorSpeed speed) throws LoginException, SleepIQException;
 192
 193     /**
 194      * Turn a foundation outlet on or off
 195      *
 196      * @param bedId the unique identifier of the bed
 197      * @param outlet the foundation outlet to control
 198      * @param operation set the outlet on or off
 199      *
 200      * @throws LoginException
 201      * @throws SleepIQException
 202      */
 203     public void setFoundationOutlet(String bedId, FoundationOutlet outlet, FoundationOutletOperation operation)
 204             throws LoginException, SleepIQException;
 205
 206     /**
 207      * Create a default implementation instance of this interface. Each call to
 208      * this method will create a new object.
 209      *
 210      * @param config the configuration to use for the new instance
 211      * @param httpClient handle to the Jetty http client
 212      * @return a concrete implementation of this interface
 213      */
 214     public static SleepIQ create(Configuration config, HttpClient httpClient) {
 215         return new SleepIQImpl(config, httpClient);
 216     }
 217
 218     /**
 219      * Close down the cloud service
 220      */
 221     public void shutdown();
 222 }