Package jmri.implementation

Class AbstractVariableLight

  • All Implemented Interfaces:
    java.lang.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.

    • Method Detail

      • 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:
        java.lang.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

      • 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:
        java.lang.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:
        java.lang.IllegalArgumentException - when intensity is less than 0.0 or more than 1.0
        java.lang.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:
        java.lang.IllegalArgumentException - when intensity is less than 0.0 or more than 1.0
        java.lang.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

      • 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.