001package jmri; 002 003import javax.annotation.CheckReturnValue; 004 005/** 006 * Represent an analog I/O on the layout. 007 * 008 * @author Daniel Bergqvist Copyright (C) 2018 009 */ 010public interface AnalogIO extends NamedBean { 011 012 /** 013 * Is the value an absolute value or a relative value? 014 * In both cases, AnalogIO.getMin() and AnalogIO.getMax() tells the 015 * limits of the value. 016 */ 017 enum AbsoluteOrRelative { 018 019 ABSOLUTE(Bundle.getMessage("AnalogIO_Absolute")), 020 RELATIVE(Bundle.getMessage("AnalogIO_Relative")); 021 022 private final String _str; 023 024 private AbsoluteOrRelative(String str) { 025 _str = str; 026 } 027 028 @CheckReturnValue 029 @Override 030 public String toString() { 031 return _str; 032 } 033 } 034 035 /** 036 * Show whether the analog value is stable. 037 * 038 * @return true if the analog value is stable 039 */ 040 @CheckReturnValue 041 default boolean isConsistentValue() { 042 return true; 043 } 044 045 /** 046 * Change the commanded value, which results in the relevant command(s) 047 * being sent to the hardware. The exception is thrown if there are problems 048 * communicating with the layout hardware. 049 * <p> 050 * The value must be a valid number, not a NaN or infinity number. 051 * 052 * @param value the desired analog value 053 * @throws jmri.JmriException general error when setting the value fails 054 * @throws IllegalArgumentException if the value is Double.NaN, 055 * Double.NEGATIVE_INFINITY or 056 * Double.POSITIVE_INFINITY 057 */ 058 void setCommandedAnalogValue(double value) throws JmriException; 059 060 /** 061 * Query the commanded value. This is a bound parameter, so you can also 062 * register a listener to be informed of changes. 063 * <p> 064 * The result must be a valid number, not a NaN or infinity number. 065 * 066 * @return the analog value 067 */ 068 @CheckReturnValue 069 double getCommandedAnalogValue(); 070 071 /** 072 * Query the known analog value. This is a bound parameter, so you can also 073 * register a listener to be informed of changes. A result is always 074 * returned; if no other feedback method is available, the commanded value 075 * will be used. 076 * <p> 077 * The result must be a valid number, not a NaN or infinity number. 078 * 079 * @return the known analog value 080 */ 081 @CheckReturnValue 082 default double getKnownAnalogValue() { 083 return getCommandedAnalogValue(); 084 } 085 086 /** 087 * Provide generic access to internal state. 088 * <p> 089 * This generally shouldn't be used by Java code; use the class-specific 090 * form instead (setCommandedAnalogValue). This is provided to 091 * make scripts access easier to read. 092 * 093 * @param value the analog value 094 * @throws JmriException general error when setting the state fails 095 */ 096 @InvokeOnLayoutThread 097 void setState(double value) throws JmriException; 098 099 /** 100 * Provide generic access to internal state. 101 * <p> 102 * This generally shouldn't be used by Java code; use the class-specific 103 * form instead (getCommandedAnalogValue). This is provided to 104 * make scripts easier to read. 105 * 106 * @param v only used to select this method which returns an analog value. 107 * It's recommended to use 0.0 as the parameter. 108 * @return the state 109 */ 110 @CheckReturnValue 111 double getState(double v); 112 113 /** 114 * Get the minimum value of this AnalogIO. 115 * @return minimum value. 116 */ 117 @CheckReturnValue 118 double getMin(); 119 120 /** 121 * Get the maximum value of this AnalogIO. 122 * @return maximum value. 123 */ 124 @CheckReturnValue 125 double getMax(); 126 127 /** 128 * Get the resolution of this AnalogIO. 129 * @return analog resolution. 130 */ 131 @CheckReturnValue 132 double getResolution(); 133 134 /** 135 * Is this AnalogIO absolute or relative? 136 * @return if absolute or relative. 137 */ 138 @CheckReturnValue 139 AbsoluteOrRelative getAbsoluteOrRelative(); 140 141 /** 142 * Request an update from the layout soft/hardware. May not even happen, and 143 * if it does it will happen later; listen for the result. 144 */ 145 default void requestUpdateFromLayout() { 146 } 147 148}