Package jmri.jmrix

Class AbstractThrottle

java.lang.Object
jmri.beans.PropertyChangeSupport
jmri.jmrix.AbstractThrottle
All Implemented Interfaces:
PropertyChangeFirer, PropertyChangeProvider, DccThrottle, Throttle
Direct Known Subclasses:
BiDiBThrottle, CbusThrottle, DCCppThrottle, DebugThrottle, EasyDccThrottle, EcosDccThrottle, LocoNetThrottle, MarklinThrottle, MqttThrottle, MrcThrottle, Mx1Throttle, NceThrottle, OlcbThrottle, Pr2Throttle, SerialThrottle, SprogCSThrottle, SprogThrottle, SRCPThrottle, TamsThrottle, Throttle, XNetThrottle, XpaThrottle
public abstract class AbstractThrottle extends PropertyChangeSupport implements DccThrottle
An abstract implementation of DccThrottle. Based on Glen Oberhauser's original LnThrottleManager implementation.

Note that this implements DccThrottle, not Throttle directly, so it has some DCC-specific content.

  • Field Details

  • Constructor Details

    • AbstractThrottle

      public AbstractThrottle(@Nonnull 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(@Nonnull 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 Details

    • getMemo

      @Nonnull protected SystemConnectionMemo getMemo()
      Get the System Connection this throttle is on.
      Returns:
      non-null system connection.

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

    • getFunctionNoWarn

      protected boolean getFunctionNoWarn(int fN)
      Get Function Number without warning if Throttle does not support. When sending a whole Function Group, a function number may not be present.
      Parameters:
      fN - Function Number
      Returns:
      Function value, or false if not present.

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

    • getFunctionMomentaryNoWarn

      protected boolean getFunctionMomentaryNoWarn(int fN)
      Get Momentary Function Number without warning if Throttle does not support. When sending a whole Function Group, a function number may not be present.
      Parameters:
      fN - Function Number
      Returns:
      Function value, or false if not present.

    • 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

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener l)
      Temporary behaviour only allowing unique PCLs. To support Throttle PCL's ( eg. WiThrottle Server ) that rely on the previous behaviour of only allowing 1 unique PCL instance. To be removed when WiThrottle Server has been updated. Add a PropertyChangeListener to the listener list.
      Specified by:
      addPropertyChangeListener in interface PropertyChangeProvider
      Overrides:
      addPropertyChangeListener in class PropertyChangeSupport
      Parameters:
      l - The PropertyChangeListener to be added

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener l)
      Remove the specified listener from this object.
      Specified by:
      removePropertyChangeListener in interface PropertyChangeProvider
      Overrides:
      removePropertyChangeListener in class PropertyChangeSupport
      Parameters:
      l - The PropertyChangeListener to remove.

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

    • sendFunctionGroup6

      protected void sendFunctionGroup6()
      Send the message to set the state of functions F29 - F36.

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

    • sendFunctionGroup7

      protected void sendFunctionGroup7()
      Send the message to set the state of functions F37 - F44.

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

    • sendFunctionGroup8

      protected void sendFunctionGroup8()
      Send the message to set the state of functions F45 - F52.

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

    • sendFunctionGroup9

      protected void sendFunctionGroup9()
      Send the message to set the state of functions F53 - F60.

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

    • sendFunctionGroup10

      protected void sendFunctionGroup10()
      Send the message to set the state of functions F61 - F68.

      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.

    • sendMomentaryFunctionGroup6

      protected void sendMomentaryFunctionGroup6()
      Send the message to set the Momentary state of functions F29 - F36

      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.

    • sendMomentaryFunctionGroup7

      protected void sendMomentaryFunctionGroup7()
      Send the message to set the Momentary state of functions F37 - F44

      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.

    • sendMomentaryFunctionGroup8

      protected void sendMomentaryFunctionGroup8()
      Send the message to set the Momentary state of functions F45 - 52

      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.

    • sendMomentaryFunctionGroup9

      protected void sendMomentaryFunctionGroup9()
      Send the message to set the Momentary state of functions F53 - F60

      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.

    • sendMomentaryFunctionGroup10

      protected void sendMomentaryFunctionGroup10()
      Send the message to set the Momentary state of functions F61 - F68

      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

    • getSpeedStepMode

      public SpeedStepMode getSpeedStepMode()
      Description copied from interface: DccThrottle
      Get the current speed step value.
      Specified by:
      getSpeedStepMode in interface DccThrottle
      Returns:
      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

    • startClock

      protected void startClock()

    • stopClock

      void stopClock()

    • finishRecord

      protected void finishRecord()

    • setRosterEntry

      public void setRosterEntry(BasicRosterEntry re)
      Specified by:
      setRosterEntry in interface Throttle

    • getRosterEntry

      public BasicRosterEntry getRosterEntry()
      Specified by:
      getRosterEntry in interface Throttle

    • 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