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     public abstract boolean isManualModeEnabled();
  46
  47     /**
  48      * Enters the "manual" mode of the device so that API requests are accepted.
  49      *
  50      * @throws Exception
  51      */
  52     public abstract void enterManualMode() throws CommunicationApiException, UnauthorizedApiException;
  53
  54     /**
  55      * Disables the manual mode, if it is enabled.
  56      *
  57      * @throws Exception
  58      */
  59     public abstract void leaveManualMode() throws CommunicationApiException, UnauthorizedApiException;
  60
  61     /**
  62      * Starts a station on the OpenSprinkler device for the specified duration.
  63      *
  64      * @param station Index of the station to open starting at 0.
  65      * @param duration The duration in seconds for how long the station should be turned on.
  66      * @throws Exception
  67      */
  68     public abstract void openStation(int station, BigDecimal duration)
  69             throws CommunicationApiException, GeneralApiException;
  70
  71     /**
  72      * Closes a station on the OpenSprinkler device.
  73      *
  74      * @param station Index of the station to open starting at 0.
  75      * @throws Exception
  76      */
  77     public abstract void closeStation(int station) throws CommunicationApiException, GeneralApiException;
  78
  79     /**
  80      * Returns the state of a station on the OpenSprinkler device.
  81      *
  82      * @param station Index of the station to open starting at 0.
  83      * @return True if the station is open, false if it is closed or cannot determine.
  84      * @throws Exception
  85      */
  86     public abstract boolean isStationOpen(int station) throws CommunicationApiException, GeneralApiException;
  87
  88     /**
  89      * Returns the current program data of the requested station.
  90      *
  91      * @param station Index of the station to request data from
  92      * @return StationProgram
  93      * @throws Exception
  94      */
  95     public abstract StationProgram retrieveProgram(int station) throws CommunicationApiException;
  96
  97     /**
  98      * Returns the state of rain detection on the OpenSprinkler device.
  99      *
 100      * @return True if rain is detected, false if not or cannot determine.
 101      * @throws Exception
 102      */
 103     public abstract boolean isRainDetected();
 104
 105     /**
 106      * Returns the current draw of all connected zones of the OpenSprinkler device in milliamperes.
 107      *
 108      * @return current draw in milliamperes or -1 if sensor not supported
 109      */
 110     public abstract int currentDraw();
 111
 112     /**
 113      * Returns the state of the second sensor.
 114      *
 115      * @return 1: sensor is active; 0: sensor is inactive; -1: no sensor.
 116      */
 117     public abstract int getSensor2State();
 118
 119     /**
 120      *
 121      * @return The Wifi signal strength in -dB or 0 if not supported by firmware
 122      */
 123     public abstract int signalStrength();
 124
 125     /**
 126      *
 127      * @return The pulses that the flow sensor has given in the last time period, -1 if not supported.
 128      */
 129     public abstract int flowSensorCount();
 130
 131     /**
 132      * CLOSES all stations turning them all off.
 133      *
 134      */
 135     public abstract void resetStations() throws UnauthorizedApiException, CommunicationApiException;
 136
 137     /**
 138      * Returns true if the internal programs are allowed to auto start.
 139      *
 140      * @return true if enabled
 141      */
 142     public abstract boolean getIsEnabled();
 143
 144     public abstract void enablePrograms(Command command) throws UnauthorizedApiException, CommunicationApiException;
 145
 146     /**
 147      * Returns the water level in %.
 148      *
 149      * @return waterLevel in %
 150      */
 151     public abstract int waterLevel();
 152
 153     /**
 154      * Returns the number of total stations that are controllable from the OpenSprinkler
 155      * device.
 156      *
 157      * @return Number of stations as an int.
 158      */
 159     public abstract int getNumberOfStations();
 160
 161     /**
 162      * Returns the firmware version number.
 163      *
 164      * @return The firmware version of the OpenSprinkler device as an int.
 165      * @throws Exception
 166      */
 167     public abstract int getFirmwareVersion() throws CommunicationApiException, UnauthorizedApiException;
 168
 169     /**
 170      * Sends all the GET requests and stores/cache the responses for use by the API to prevent the need for multiple
 171      * requests.
 172      *
 173      * @throws CommunicationApiException
 174      * @throws UnauthorizedApiException
 175      */
 176     public abstract void refresh() throws CommunicationApiException, UnauthorizedApiException;
 177
 178     /**
 179      * Ask the OpenSprinkler for the program names and store these for future use in a List.
 180      *
 181      * @throws CommunicationApiException
 182      * @throws UnauthorizedApiException
 183      */
 184     public abstract void getProgramData() throws CommunicationApiException, UnauthorizedApiException;
 185
 186     /**
 187      * Returns a list of all internal programs as a list of StateOptions.
 188      *
 189      * @return List<StateOption>
 190      */
 191     public abstract List<StateOption> getPrograms();
 192
 193     /**
 194      * Return a list of all the stations the device has as List of StateOptions
 195      *
 196      * @return List<StateOption>
 197      */
 198     public abstract List<StateOption> getStations();
 199
 200     /**
 201      * Runs a Program that is setup and stored inside the OpenSprinkler
 202      *
 203      * @param Program index number that you wish to run.
 204      *
 205      * @throws CommunicationApiException
 206      * @throws UnauthorizedApiException
 207      */
 208     public abstract void runProgram(Command command) throws CommunicationApiException, UnauthorizedApiException;
 209
 210     /**
 211      * Fetch the station names and place them in a list of List<StateOption>.
 212      * Use getStations() to retrieve this list.
 213      *
 214      * @throws CommunicationApiException
 215      * @throws UnauthorizedApiException
 216      */
 217     public abstract JnResponse getStationNames() throws CommunicationApiException, UnauthorizedApiException;
 218
 219     /**
 220      * Tells a single station to ignore the rain delay.
 221      *
 222      * @param station
 223      * @param command
 224      * @throws CommunicationApiException
 225      * @throws UnauthorizedApiException
 226      */
 227     public void ignoreRain(int station, boolean command) throws CommunicationApiException, UnauthorizedApiException;
 228
 229     /**
 230      * Asks if a single station is set to ignore rain delays.
 231      *
 232      * @param station
 233      * @return
 234      */
 235     public abstract boolean isIgnoringRain(int station);
 236
 237     /**
 238      * Sets how long the OpenSprinkler device will stop running programs for.
 239      *
 240      * @param hours
 241      * @throws UnauthorizedApiException
 242      * @throws CommunicationApiException
 243      */
 244     public abstract void setRainDelay(int hours) throws UnauthorizedApiException, CommunicationApiException;
 245
 246     /**
 247      * Gets the rain delay in hours from the OpenSprinkler device.
 248      *
 249      * @return QuantityType<Time>
 250      */
 251     public abstract QuantityType<Time> getRainDelay();
 252 }