Package jmri.implementation

Class AbstractVariableLight

java.lang.Object
jmri.implementation.AbstractNamedBean
jmri.implementation.AbstractLight
jmri.implementation.AbstractVariableLight
All Implemented Interfaces:
Comparable<NamedBean>, AnalogIO, PropertyChangeProvider, DigitalIO, Light, NamedBean, VariableLight
Direct Known Subclasses:
AnymaDMX_UsbLight, BiDiBLight, MqttLight, SerialLight
public abstract class AbstractVariableLight extends AbstractLight implements VariableLight
Abstract class providing partial implementation of the logic of the Light interface when the Intensity is variable.

Now it includes the transition code, but it only does the steps on the fast minute clock. Later it may do its own timing but this was simple to piggy back on the fast minute listener.

The structure is in part dictated by the limitations of the X10 protocol and implementations. However, it is not limited to X10 devices only. Other interfaces that have a way to provide a dimmable light should use it.

X10 has on/off commands, and separate commands for setting a variable intensity via "dim" commands. Some X10 implementations use relative dimming, some use absolute dimming. Some people set the dim level of their Lights and then just use on/off to turn control the lamps; in that case we don't want to send dim commands. Further, X10 communications is very slow, and sending a complete set of dim operations can take a long time. So the algorithm is:

  • Until the intensity has been explicitly set different from 1.0 or 0.0, no intensity commands are to be sent over the power line.

Unlike the parent class, this stores CurrentIntensity and TargetIntensity in separate variables.

  • Field Details

  • Constructor Details

  • Method Details

    • describeState

      @Nonnull public String describeState(int state)
      System independent operational instance variables (not saved between runs).
      Specified by:
      describeState in interface NamedBean
      Overrides:
      describeState in class AbstractLight
      Parameters:
      state - the state to describe
      Returns:
      the state in localized form

    • setState

      public void setState(int newState)
      Handle a request for a state change. ON and OFF go to the MaxIntensity and MinIntensity, specifically, and all others are not permitted

      ON and OFF avoid use of variable intensity if MaxIntensity = 1.0 or MinIntensity = 0.0, and no transition is being used.

      Specified by:
      setState in interface Light
      Specified by:
      setState in interface NamedBean
      Overrides:
      setState in class AbstractLight
      Parameters:
      newState - new state

    • setTargetIntensity

      public void setTargetIntensity(double intensity)
      Set the intended new intensity value for the Light. If transitions are in use, they will be applied.

      Bound property between 0 and 1.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Values at or below the minIntensity property will result in the Light going to the OFF state immediately. Values at or above the maxIntensity property will result in the Light going to the ON state immediately.

      Specified by:
      setTargetIntensity in interface VariableLight
      Parameters:
      intensity - the desired brightness
      Throws:
      IllegalArgumentException - when intensity is less than 0.0 or more than 1.0

    • startTransition

      protected void startTransition(double intensity)
      Set up to start a transition
      Parameters:
      intensity - target intensity

    • sendIntensity

      protected abstract void sendIntensity(double intensity)
      Send a Dim/Bright commands to the hardware to reach a specific intensity.
      Parameters:
      intensity - new intensity

    • sendOnOffCommand

      protected abstract void sendOnOffCommand(int newState)
      Send a On/Off Command to the hardware
      Parameters:
      newState - new state

    • newInternalMinute

      protected void newInternalMinute()
      Layout time has changed to a new minute. Process effect that might be having on intensity. Currently, this implementation assumes there's a fixed number of steps between min and max brightness.

    • getNumberOfSteps

      protected abstract int getNumberOfSteps()
      Provide the number of steps available between min and max intensity
      Returns:
      number of steps

    • notifyTargetIntensityChange

      protected void notifyTargetIntensityChange(double intensity)
      Change the stored target intensity value and do notification, but don't change anything in the hardware
      Overrides:
      notifyTargetIntensityChange in class AbstractLight
      Parameters:
      intensity - intensity value

    • isTransitionAvailable

      public boolean isTransitionAvailable()
      Description copied from interface: VariableLight
      Can the Light change its intensity setting slowly?

      If true, this Light supports a non-zero value of the transitionTime property, which controls how long the Light will take to change from one intensity level to another.

      Unbound property

      Specified by:
      isTransitionAvailable in interface VariableLight
      Returns:
      true if brightness can fade between two states; false otherwise

    • setTransitionTime

      public void setTransitionTime(double minutes)
      Set the fast-clock duration for a transition from full ON to full OFF or vice-versa.

      Bound property

      Specified by:
      setTransitionTime in interface VariableLight
      Parameters:
      minutes - time to fade
      Throws:
      IllegalArgumentException - if minutes is not valid

    • getTransitionTime

      public double getTransitionTime()
      Get the number of fastclock minutes taken by a transition from full ON to full OFF or vice versa.
      Specified by:
      getTransitionTime in interface VariableLight
      Returns:
      0.0 if the output intensity transition is instantaneous

    • isTransitioning

      public boolean isTransitioning()
      Convenience method for checking if the intensity of the light is currently changing due to a transition.

      Bound property so that listeners can conveniently learn when the transition is over.

      Specified by:
      isTransitioning in interface VariableLight
      Returns:
      is transitioning

    • getCurrentIntensity

      public double getCurrentIntensity()
      Get the current intensity value. If the Light is currently transitioning, this may be either an intermediate or final value.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Specified by:
      getCurrentIntensity in interface VariableLight
      Returns:
      current intensity

    • getTargetIntensity

      public double getTargetIntensity()
      Get the target intensity value for the current transition, if any. If the Light is not currently transitioning, this is the current intensity value.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Bound property

      Specified by:
      getTargetIntensity in interface VariableLight
      Returns:
      target intensity

    • setObservedAnalogValue

      protected void setObservedAnalogValue(double value)
      Used when current state comes from layout
      Parameters:
      value - Observed current state

    • setCommandedAnalogValue

      public void setCommandedAnalogValue(double value) throws JmriException
      Description copied from interface: AnalogIO
      Change the commanded value, which results in the relevant command(s) being sent to the hardware. The exception is thrown if there are problems communicating with the layout hardware.

      The value must be a valid number, not a NaN or infinity number.

      Specified by:
      setCommandedAnalogValue in interface AnalogIO
      Parameters:
      value - the desired analog value
      Throws:
      JmriException - general error when setting the value fails

    • getMinIntensity

      public double getMinIntensity()
      Get the current value of the minIntensity property.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Specified by:
      getMinIntensity in interface VariableLight
      Returns:
      min intensity value

    • setMinIntensity

      public void setMinIntensity(double intensity)
      Set the value of the minIntensity property.

      Bound property between 0 and 1.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Specified by:
      setMinIntensity in interface VariableLight
      Parameters:
      intensity - intensity value
      Throws:
      IllegalArgumentException - when intensity is less than 0.0 or more than 1.0
      IllegalArgumentException - when intensity is not less than the current value of the maxIntensity property

    • getMaxIntensity

      public double getMaxIntensity()
      Get the current value of the maxIntensity property.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Specified by:
      getMaxIntensity in interface VariableLight
      Returns:
      max intensity

    • setMaxIntensity

      public void setMaxIntensity(double intensity)
      Set the value of the maxIntensity property.

      Bound property between 0 and 1.

      A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.

      Specified by:
      setMaxIntensity in interface VariableLight
      Parameters:
      intensity - max intensity
      Throws:
      IllegalArgumentException - when intensity is less than 0.0 or more than 1.0
      IllegalArgumentException - when intensity is not greater than the current value of the minIntensity property

    • getState

      public double getState(double v)
      Provide generic access to internal state.

      This generally shouldn't be used by Java code; use the class-specific form instead (getCommandedAnalogValue). This is provided to make scripts easier to read.

      Specified by:
      getState in interface AnalogIO
      Parameters:
      v - only used to select this method which returns an analog value. It's recommended to use 0.0 as the parameter.
      Returns:
      the state

    • setState

      public void setState(double newState) throws JmriException
      Provide generic access to internal state.

      This generally shouldn't be used by Java code; use the class-specific form instead (setCommandedAnalogValue). This is provided to make scripts access easier to read.

      Specified by:
      setState in interface AnalogIO
      Parameters:
      newState - the analog value
      Throws:
      JmriException - general error when setting the state fails

    • getResolution

      public double getResolution()
      Description copied from interface: AnalogIO
      Get the resolution of this AnalogIO.
      Specified by:
      getResolution in interface AnalogIO
      Returns:
      analog resolution.

    • getCommandedAnalogValue

      public double getCommandedAnalogValue()
      Description copied from interface: AnalogIO
      Query the commanded value. This is a bound parameter, so you can also register a listener to be informed of changes.

      The result must be a valid number, not a NaN or infinity number.

      Specified by:
      getCommandedAnalogValue in interface AnalogIO
      Returns:
      the analog value

    • getMin

      public double getMin()
      Description copied from interface: AnalogIO
      Get the minimum value of this AnalogIO.
      Specified by:
      getMin in interface AnalogIO
      Returns:
      minimum value.

    • getMax

      public double getMax()
      Description copied from interface: AnalogIO
      Get the maximum value of this AnalogIO.
      Specified by:
      getMax in interface AnalogIO
      Returns:
      maximum value.

    • getAbsoluteOrRelative

      public AnalogIO.AbsoluteOrRelative getAbsoluteOrRelative()
      Description copied from interface: AnalogIO
      Is this AnalogIO absolute or relative?
      Specified by:
      getAbsoluteOrRelative in interface AnalogIO
      Returns:
      if absolute or relative.