Package jmri.jmrix

Class AbstractThrottle

    • Constructor Detail

      • AbstractThrottle

        public AbstractThrottle​(SystemConnectionMemo memo)
        Create a new AbstractThrottle with Functions 0-28..

        All function and momentary functions set to Off.

        Parameters:
        memo - System Connection.
      • AbstractThrottle

        public AbstractThrottle​(SystemConnectionMemo memo,
                                int totalFunctions)
        Create a new AbstractThrottle with custom number of functions.

        All function and momentary functions set to Off.

        Parameters:
        memo - System Connection this throttle is on
        totalFunctions - total number of functions available, including 0
    • Method Detail

      • getSpeedSetting

        public float getSpeedSetting()
        speed - expressed as a value 0.0 -> 1.0. Negative means emergency stop. This is a bound parameter.
        Specified by:
        getSpeedSetting in interface Throttle
        Returns:
        speed
      • setSpeedSetting

        public void setSpeedSetting​(float speed)
        setSpeedSetting - Implementing functions should override this function, but should either make a call to super.setSpeedSetting() to notify the listeners at the end of their work, or should notify the listeners themselves.
        Specified by:
        setSpeedSetting in interface Throttle
        Parameters:
        speed - the speed as a 0.0 -> 1.0. fraction of maximum possible speed or -1 for emergency stop.
      • setSpeedSetting

        public void setSpeedSetting​(float speed,
                                    boolean allowDuplicates,
                                    boolean allowDuplicatesOnStop)
        setSpeedSetting - Implementations should override this method only if they normally suppress messages to the system if, as far as JMRI can tell, the new message would make no difference to the system state (eg. the speed is the same, or effectivly the same, as the existing speed). Then, the boolean options can affect this behaviour.
        Specified by:
        setSpeedSetting in interface Throttle
        Parameters:
        speed - the new speed
        allowDuplicates - don't suppress messages
        allowDuplicatesOnStop - don't suppress messages if the new speed is 'stop'
      • setSpeedSettingAgain

        public void setSpeedSettingAgain​(float speed)
        setSpeedSettingAgain - set the speed and don't ever suppress the sending of messages to the system
        Specified by:
        setSpeedSettingAgain in interface Throttle
        Parameters:
        speed - the new speed
      • getIsForward

        public boolean getIsForward()
        direction This is an bound parameter.
        Specified by:
        getIsForward in interface Throttle
        Returns:
        true if locomotive is running forward
      • setIsForward

        public void setIsForward​(boolean forward)
        Implementing functions should override this function, but should either make a call to super.setIsForward() to notify the listeners, or should notify the listeners themselves.
        Specified by:
        setIsForward in interface Throttle
        Parameters:
        forward - true if forward; false otherwise
      • getFunctions

        @Nonnull
        public boolean[] getFunctions()
        Get copy of function array. Typically returns array length of 29, i.e. 0-28.
        Specified by:
        getFunctions in interface Throttle
        Returns:
        function array, length dependant by hardware type.
      • getFunctionsMomentary

        @Nonnull
        public boolean[] getFunctionsMomentary()
        Get copy of function momentary status array. Typically returns array length of 29, i.e. 0-28.
        Specified by:
        getFunctionsMomentary in interface Throttle
        Returns:
        momentary function array, length dependant by hardware type.
      • getFunction

        public boolean getFunction​(int fN)
        Get Loco Function status.
        Specified by:
        getFunction in interface Throttle
        Parameters:
        fN - Function Number, 0-28
        Returns:
        Function State. True on, false off.
      • getFunctionMomentary

        public boolean getFunctionMomentary​(int fN)
        Get the Momentary Function Value.
        Specified by:
        getFunctionMomentary in interface Throttle
        Parameters:
        fN - Momentary function number
        Returns:
        true if momentary function is on, else false.
      • notifyThrottleDisconnect

        protected void notifyThrottleDisconnect()
        Notify listeners that a Throttle has disconnected and is no longer available for use.

        For when throttles have been stolen or encounter hardware error, and a normal release / dispose is not possible.

      • notifyThrottleDispatchEnabled

        public void notifyThrottleDispatchEnabled​(boolean newVal)
        Notify listeners that a Throttle has Dispatch enabled or disabled.

        For systems where dispatch availability is variable.

        Does not notify if existing value is unchanged.

        Specified by:
        notifyThrottleDispatchEnabled in interface Throttle
        Parameters:
        newVal - true if Dispatch enabled, else false
      • notifyThrottleReleaseEnabled

        public void notifyThrottleReleaseEnabled​(boolean newVal)
        Notify listeners that a Throttle has Release enabled or disabled.

        For systems where release availability is variable.

        Does not notify if existing value is unchanged.

        Specified by:
        notifyThrottleReleaseEnabled in interface Throttle
        Parameters:
        newVal - true if Release enabled, else false
      • dispose

        public void dispose​(ThrottleListener l)
        Call from a ThrottleListener to dispose of the throttle instance
        Specified by:
        dispose in interface Throttle
        Parameters:
        l - the listener requesting the dispose
      • dispatch

        public void dispatch​(ThrottleListener l)
        Finished with this Throttle, tell the layout that the locomotive is available for reuse/reallocation by somebody else. If possible, tell the layout that this locomotive has been dispatched to another user. Not all layouts will implement this, in which case it is synonymous with Throttle.release(jmri.ThrottleListener).

        After this, further usage of this Throttle object will result in a JmriException.

        Normally, dispatch ends with a call to dispose.

        Specified by:
        dispatch in interface Throttle
        Parameters:
        l - ThrottleListener to dispatch
      • release

        public void release​(ThrottleListener l)
        Finished with this Throttle, tell the layout that the locomotive is available for reuse/reallocation by somebody else.

        After this, further usage of this Throttle object will result in a JmriException. Do not call dispose after release.

        Normally, release ends with a call to dispose.

        Specified by:
        release in interface Throttle
        Parameters:
        l - ThrottleListener to release. May be null if no ThrottleListener is currently held.
      • throttleDispose

        protected abstract void throttleDispose()
        Dispose when finished with this Throttle. May be used in tests for cleanup. Throttles normally call finishRecord() here.
      • getSpeedIncrement

        public float getSpeedIncrement()
        Handle quantized speed. Note this can change! Value returned is always positive.
        Specified by:
        getSpeedIncrement in interface DccThrottle
        Returns:
        1 divided by the number of speed steps this DCC throttle supports
      • sendFunctionGroup

        protected void sendFunctionGroup​(int functionNum,
                                         boolean momentary)
        Send whole (DCC) Function Group for a particular function number.
        Parameters:
        functionNum - Function Number
        momentary - False to send normal function status, true to send momentary.
      • setFunction

        public void setFunction​(int functionNum,
                                boolean newState)
        Set Loco Function and send to Layout.
        Specified by:
        setFunction in interface Throttle
        Parameters:
        functionNum - Function Number, 0-28
        newState - New Function State. True on, false off.
      • updateFunction

        public void updateFunction​(int fn,
                                   boolean state)
        Update the state of a single function. Updates function value and ChangeListener. Does not send outward message TO hardware.
        Parameters:
        fn - Function Number 0-28
        state - On - True, Off - False
      • updateFunctionMomentary

        public void updateFunctionMomentary​(int fn,
                                            boolean state)
        Update the Momentary state of a single function. Updates function value and ChangeListener. Does not send outward message TO hardware.
        Parameters:
        fn - Momentary Function Number 0-28
        state - On - True, Off - False
      • sendFunctionGroup1

        protected void sendFunctionGroup1()
        Send the message to set the state of functions F0, F1, F2, F3, F4.

        This is used in the setFn implementations provided in this class, but a real implementation needs to be provided.

      • sendFunctionGroup2

        protected void sendFunctionGroup2()
        Send the message to set the state of functions F5, F6, F7, F8.

        This is used in the setFn implementations provided in this class, but a real implementation needs to be provided.

      • sendFunctionGroup3

        protected void sendFunctionGroup3()
        Send the message to set the state of functions F9, F10, F11, F12.

        This is used in the setFn implementations provided in this class, but a real implementation needs to be provided.

      • sendFunctionGroup4

        protected void sendFunctionGroup4()
        Send the message to set the state of functions F13, F14, F15, F16, F17, F18, F19, F20.

        This is used in the setFn implementations provided in this class, but a real implementation needs to be provided.

      • sendFunctionGroup5

        protected void sendFunctionGroup5()
        Send the message to set the state of functions F21, F22, F23, F24, F25, F26, F27, F28.

        This is used in the setFn implementations provided in this class, but a real implementation needs to be provided.

      • setFunctionMomentary

        public void setFunctionMomentary​(int momFuncNum,
                                         boolean state)
        Sets Momentary Function and sends to layout. Set Momentary Loco Function and send to Layout.
        Specified by:
        setFunctionMomentary in interface Throttle
        Parameters:
        momFuncNum - Momentary Function Number, 0-28
        state - New Function State. True on, false off.
      • sendMomentaryFunctionGroup1

        protected void sendMomentaryFunctionGroup1()
        Send the message to set the momentary state of functions F0, F1, F2, F3, F4.

        This is used in the setFnMomentary implementations provided in this class, a real implementation needs to be provided if the hardware supports setting functions momentary.

      • sendMomentaryFunctionGroup2

        protected void sendMomentaryFunctionGroup2()
        Send the message to set the momentary state of functions F5, F6, F7, F8.

        This is used in the setFnMomentary implementations provided in this class, but a real implementation needs to be provided if the hardware supports setting functions momentary.

      • sendMomentaryFunctionGroup3

        protected void sendMomentaryFunctionGroup3()
        Send the message to set the Momentary state of functions F9, F10, F11, F12

        This is used in the setFnMomentary implementations provided in this class, but a real implementation needs to be provided if the hardware supports setting functions momentary.

      • sendMomentaryFunctionGroup4

        protected void sendMomentaryFunctionGroup4()
        Send the message to set the Momentary state of functions F13, F14, F15, F16, F17, F18, F19, F20

        This is used in the setFnMomentary implementations provided in this class, but a real implementation needs to be provided if the hardware supports setting functions momentary.

      • sendMomentaryFunctionGroup5

        protected void sendMomentaryFunctionGroup5()
        Send the message to set the Momentary state of functions F21, F22, F23, F24, F25, F26, F27, F28

        This is used in the setFnMomentary implementations provided in this class, but a real implementation needs to be provided if the hardware supports setting functions momentary.

      • setSpeedStepMode

        public void setSpeedStepMode​(SpeedStepMode mode)
        Set the speed step value. Default should be 128 speed step mode in most cases.

        Specific implementations should override this function.

        Specified by:
        setSpeedStepMode in interface DccThrottle
        Parameters:
        mode - the current speed step mode
      • record

        protected void record​(float speed)
        Processes updated speed from subclasses. Tracks total operating time for the roster entry by starting the clock if speed is non-zero or stopping the clock otherwise.
        Parameters:
        speed - the current speed
      • intSpeed

        protected int intSpeed​(float speed)
        Get an integer speed for the given raw speed value. This is a convenience method that calls intSpeed(float, int) with a maxStep of 127.
        Parameters:
        speed - the speed as a percentage of maximum possible speed; negative values indicate a need for an emergency stop
        Returns:
        an integer in the range 0-127
      • intSpeed

        protected static int intSpeed​(float speed,
                                      int steps)
        Get an integer speed for the given raw speed value.
        Parameters:
        speed - the speed as a percentage of maximum possible speed; negative values indicate a need for an emergency stop
        steps - number of possible speeds; values less than 2 will cause errors
        Returns:
        an integer in the range 0-steps