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.opensprinkler.internal.api;
  14
  15 import java.math.BigDecimal;
  16 import java.util.List;
  17
  18 import javax.measure.quantity.Time;
  19
  20 import org.eclipse.jdt.annotation.NonNullByDefault;
  21 import org.openhab.binding.opensprinkler.internal.OpenSprinklerState.JnResponse;
  22 import org.openhab.binding.opensprinkler.internal.api.exception.CommunicationApiException;
  23 import org.openhab.binding.opensprinkler.internal.api.exception.GeneralApiException;
  24 import org.openhab.binding.opensprinkler.internal.api.exception.UnauthorizedApiException;
  25 import org.openhab.binding.opensprinkler.internal.model.StationProgram;
  26 import org.openhab.core.library.types.QuantityType;
  27 import org.openhab.core.types.Command;
  28 import org.openhab.core.types.StateOption;
  29
  30 /**
  31  * The {@link OpenSprinklerApi} interface defines the functions which are
  32  * controllable on the OpenSprinkler API interface.
  33  *
  34  * @author Chris Graham - Initial contribution
  35  * @author Florian Schmidt - Refactoring
  36  */
  37 @NonNullByDefault
  38 public interface OpenSprinklerApi {
  39
  40     /**
  41      * Whether the device entered manual mode and accepts API requests to control the stations.
  42      *
  43      * @return True if this API interface is connected to the Open Sprinkler API. False otherwise.
  44      */
  45     boolean isManualModeEnabled();
  46
  47     /**
  48      * Enters the "manual" mode of the device so that API requests are accepted.
  49      *
  50      * @throws CommunicationApiException
  51      * @throws UnauthorizedApiException
  52      */
  53     void enterManualMode() throws CommunicationApiException, UnauthorizedApiException;
  54
  55     /**
  56      * Disables the manual mode, if it is enabled.
  57      *
  58      * @throws CommunicationApiException
  59      * @throws UnauthorizedApiException
  60      */
  61     void leaveManualMode() throws CommunicationApiException, UnauthorizedApiException;
  62
  63     /**
  64      * Starts a station on the OpenSprinkler device for the specified duration.
  65      *
  66      * @param station Index of the station to open starting at 0.
  67      * @param duration The duration in seconds for how long the station should be turned on.
  68      * @throws CommunicationApiException
  69      * @throws GeneralApiException
  70      */
  71     void openStation(int station, BigDecimal duration) throws CommunicationApiException, GeneralApiException;
  72
  73     /**
  74      * Closes a station on the OpenSprinkler device.
  75      *
  76      * @param station Index of the station to open starting at 0.
  77      * @throws CommunicationApiException
  78      * @throws GeneralApiException
  79      */
  80     void closeStation(int station) throws CommunicationApiException, GeneralApiException;
  81
  82     /**
  83      * Returns the state of a station on the OpenSprinkler device.
  84      *
  85      * @param station Index of the station to open starting at 0.
  86      * @return True if the station is open, false if it is closed or cannot determine.
  87      * @throws CommunicationApiException
  88      * @throws GeneralApiException
  89      */
  90     boolean isStationOpen(int station) throws CommunicationApiException, GeneralApiException;
  91
  92     /**
  93      * Returns the current program data of the requested station.
  94      *
  95      * @param station Index of the station to request data from
  96      * @return StationProgram
  97      * @throws CommunicationApiException
  98      */
  99     StationProgram retrieveProgram(int station) throws CommunicationApiException;
 100
 101     /**
 102      * Returns the state of rain detection on the OpenSprinkler device.
 103      *
 104      * @return True if rain is detected, false if not or cannot determine.
 105      */
 106     boolean isRainDetected();
 107
 108     /**
 109      * Returns the current draw of all connected zones of the OpenSprinkler device in milliamperes.
 110      *
 111      * @return current draw in milliamperes or -1 if sensor not supported
 112      */
 113     int currentDraw();
 114
 115     /**
 116      * Returns the state of the second sensor.
 117      *
 118      * @return 1: sensor is active; 0: sensor is inactive; -1: no sensor.
 119      */
 120     int getSensor2State();
 121
 122     /**
 123      *
 124      * @return The Wifi signal strength in -dB or 0 if not supported by firmware
 125      */
 126     int signalStrength();
 127
 128     /**
 129      *
 130      * @return The pulses that the flow sensor has given in the last time period, -1 if not supported.
 131      */
 132     int flowSensorCount();
 133
 134     /**
 135      * CLOSES all stations turning them all off.
 136      *
 137      */
 138     void resetStations() throws UnauthorizedApiException, CommunicationApiException;
 139
 140     /**
 141      * Returns true if the internal programs are allowed to auto start.
 142      *
 143      * @return true if enabled
 144      */
 145     boolean getIsEnabled();
 146
 147     void enablePrograms(Command command) throws UnauthorizedApiException, CommunicationApiException;
 148
 149     /**
 150      * Returns the water level in %.
 151      *
 152      * @return waterLevel in %
 153      */
 154     int waterLevel();
 155
 156     /**
 157      * Returns the number of total stations that are controllable from the OpenSprinkler
 158      * device.
 159      *
 160      * @return Number of stations as an int.
 161      */
 162     int getNumberOfStations();
 163
 164     /**
 165      * Returns the firmware version number.
 166      *
 167      * @return The firmware version of the OpenSprinkler device as an int.
 168      * @throws CommunicationApiException
 169      * @throws UnauthorizedApiException
 170      */
 171     int getFirmwareVersion() throws CommunicationApiException, UnauthorizedApiException;
 172
 173     /**
 174      * Sends all the GET requests and stores/cache the responses for use by the API to prevent the need for multiple
 175      * requests.
 176      *
 177      * @throws CommunicationApiException
 178      * @throws UnauthorizedApiException
 179      */
 180     void refresh() throws CommunicationApiException, UnauthorizedApiException;
 181
 182     /**
 183      * Ask the OpenSprinkler for the program names and store these for future use in a List.
 184      *
 185      * @throws CommunicationApiException
 186      * @throws UnauthorizedApiException
 187      */
 188     void getProgramData() throws CommunicationApiException, UnauthorizedApiException;
 189
 190     /**
 191      * Returns a list of all internal programs as a list of StateOptions.
 192      *
 193      * @return {@code List<StateOption>}
 194      */
 195     List<StateOption> getPrograms();
 196
 197     /**
 198      * Return a list of all the stations the device has as List of StateOptions
 199      *
 200      * @return {@code List<StateOption>}
 201      */
 202     List<StateOption> getStations();
 203
 204     /**
 205      * Runs a Program that is setup and stored inside the OpenSprinkler
 206      *
 207      * @param command Program index number that you wish to run.
 208      *
 209      * @throws CommunicationApiException
 210      * @throws UnauthorizedApiException
 211      */
 212     void runProgram(Command command) throws CommunicationApiException, UnauthorizedApiException;
 213
 214     /**
 215      * Fetch the station names and place them in a list of {@code List<StateOption>}.
 216      * Use getStations() to retrieve this list.
 217      *
 218      * @throws CommunicationApiException
 219      * @throws UnauthorizedApiException
 220      */
 221     JnResponse getStationNames() throws CommunicationApiException, UnauthorizedApiException;
 222
 223     /**
 224      * Tells a single station to ignore the rain delay.
 225      *
 226      * @param station
 227      * @param command
 228      * @throws CommunicationApiException
 229      * @throws UnauthorizedApiException
 230      */
 231     void ignoreRain(int station, boolean command) throws CommunicationApiException, UnauthorizedApiException;
 232
 233     /**
 234      * Asks if a single station is set to ignore rain delays.
 235      *
 236      * @param station
 237      * @return
 238      */
 239     boolean isIgnoringRain(int station);
 240
 241     /**
 242      * Sets how long the OpenSprinkler device will stop running programs for.
 243      *
 244      * @param hours
 245      * @throws UnauthorizedApiException
 246      * @throws CommunicationApiException
 247      */
 248     void setRainDelay(int hours) throws UnauthorizedApiException, CommunicationApiException;
 249
 250     /**
 251      * Gets the rain delay in hours from the OpenSprinkler device.
 252      *
 253      * @return {@code QuantityType<Time>}
 254      */
 255     QuantityType<Time> getRainDelay();
 256
 257     /**
 258      * Returns the Number of zones in the queue as an int.
 259      *
 260      * @return Number of zones in the queue as an int.
 261      */
 262     int getQueuedZones();
 263
 264     /**
 265      * Returns the connection status of the OpenSprinkler Cloud.
 266      *
 267      * @return Connection state 0: not enabled, 1: connecting, 2: disconnected, 3: connected
 268      */
 269     int getCloudConnected();
 270
 271     /**
 272      * Returns the paused status of the OpenSprinkler.
 273      *
 274      * @return int 0 to 600 seconds
 275      */
 276     int getPausedState();
 277
 278     /**
 279      * Sets the amount of time that the OpenSprinkler will stop/pause zones.
 280      *
 281      * @param seconds for the pause duration in seconds (0 to 600)
 282      * @throws UnauthorizedApiException
 283      * @throws CommunicationApiException
 284      */
 285     void setPausePrograms(int seconds) throws UnauthorizedApiException, CommunicationApiException;
 286 }