Package jmri

Interface Turnout

All Superinterfaces:
Comparable<NamedBean>, DigitalIO, NamedBean, PropertyChangeProvider, VariableControlSpanBean
All Known Implementing Classes:
AbstractTurnout, AcelaTurnout, BiDiBTurnout, CbusTurnout, DCCppTurnout, EasyDccTurnout, EcosTurnout, EliteXNetTurnout, IpocsTurnout, JMRIClientTurnout, LnTurnout, MarklinTurnout, MqttTurnout, MrcTurnout, Mx1Turnout, NceTurnout, OlcbTurnout, RaspberryPiTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SprogCSTurnout, SprogTurnout, SRCPTurnout, TamsTurnout, XBeeTurnout, XNetTurnout, XpaTurnout, Z21XNetTurnout, ZTC611XNetTurnout
public interface Turnout extends DigitalIO, VariableControlSpanBean
Represent a Turnout on the layout.

A Turnout has two states:

  • The "commandedState" records the state that's been commanded in the program. It might take some time, perhaps a long time, for that to actually take effect.
  • The "knownState" is the program's best idea of the actual state on the the layout.

There are a number of reasons that commandedState and knownState differ:

  • A change has been commanded, but it hasn't had time to happen yet
  • Something has gone wrong, and a commanded change isn't actually going to happen
  • Although the program hasn't commanded a change, something on the layout has made the turnout change. This could be a local electrical button, a mechanical movement of the points, or something else.
  • For a bus-like system, e.g. LocoNet or XpressNet, some other device might have sent a command to change the turnout.

Turnout feedback is involved in the connection between these two states; for more information see the feedback page.

The AbstractTurnout class contains a basic implementation of the state and messaging code, and forms a useful start for a system-specific implementation. Specific implementations, e.g. for LocoNet and NCE, will convert to and from the layout commands.

The states and names are Java Bean parameters, so that listeners can be registered to be notified of any changes.

A sample use of the Turnout interface can be seen in the jmri.jmrit.simpleturnoutctrl.SimpleTurnoutCtrlFrame class, which provides a simple GUI for controlling a single turnout.

Each Turnout object has a two names. The "user" name is entirely free form, and can be used for any purpose. The "system" name is provided by the system-specific implementations, and provides a unique mapping to the layout control system (for example LocoNet or NCE) and address within that system.

Turnouts exhibit some complex behaviors. At the same time, they are sometimes used as generic binary outputs where those get in the way. Eventually, we need to have a separate e.g. Output class, but for now you can defeat much of the advanced behaviors with the setBinaryOutput(true) method. This is a configuration property; changing it on the fly may give unexpected results. It's value is not persisted.

This file is part of JMRI.

JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See Also:

  • Field Details

  • Method Details

    • getValidFeedbackModes

      Set<Integer> getValidFeedbackModes()
      Get a list of valid feedback types. The valid types depend on the implemented system.
      Returns:
      array of feedback types

    • getValidFeedbackTypes

      int getValidFeedbackTypes()
      Get a representation of the feedback type. This is the OR of possible values: DIRECT, EXACT, etc. The valid combinations depend on the implemented system.
      Returns:
      the ORed combination of feedback types

    • getValidFeedbackNames

      @Nonnull String[] getValidFeedbackNames()
      Get a human readable representation of the feedback type. The values depend on the implemented system.
      Returns:
      the names of the feedback types or an empty list if no feedback is available

    • setFeedbackMode

      @InvokeOnLayoutThread void setFeedbackMode(@Nonnull String mode) throws IllegalArgumentException
      Set the feedback mode from a human readable name. This must be one of the names defined in a previous getValidFeedbackNames() call.
      Parameters:
      mode - the feedback type name
      Throws:
      IllegalArgumentException - if mode is not valid

    • setFeedbackMode

      @InvokeOnLayoutThread void setFeedbackMode(int mode) throws IllegalArgumentException
      Set the feedback mode from a integer. This must be one of the bit values defined in a previous getValidFeedbackTypes() call. Having more than one bit set is an error.
      Parameters:
      mode - the feedback type to set
      Throws:
      IllegalArgumentException - if mode is not valid

    • getFeedbackModeName

      @Nonnull String getFeedbackModeName()
      Get the feedback mode in human readable form. This will be one of the names defined in a getValidFeedbackNames() call.
      Returns:
      the feedback type

    • getFeedbackMode

      int getFeedbackMode()
      Get the feedback mode in machine readable form. This will be one of the bits defined in a getValidFeedbackTypes() call.
      Returns:
      the feedback type

    • getInhibitOperation

      boolean getInhibitOperation()
      Get if automatically retrying an operation is blocked for this turnout.
      Returns:
      true if retrying is disabled; false otherwise

    • setInhibitOperation

      void setInhibitOperation(boolean io)
      Set if automatically retrying an operation is blocked for this turnout.
      Parameters:
      io - true if retrying is to be disabled; false otherwise

    • getTurnoutOperation

      @CheckForNull TurnoutOperation getTurnoutOperation()
      Returns:
      current operation automation class

    • setTurnoutOperation

      @InvokeOnLayoutThread void setTurnoutOperation(@CheckForNull TurnoutOperation toper)
      set current automation class
      Parameters:
      toper - TurnoutOperation subclass instance

    • invertTurnoutState

      static int invertTurnoutState(int inState)
      Return the inverted state of the specified state Does NOT invert INCONSISTENT
      Parameters:
      inState - the specified state
      Returns:
      the inverted state

    • provideFeedbackSensor

      default void provideFeedbackSensor(@CheckForNull String name, int number) throws JmriException
      Provide Sensor objects needed for some feedback types. Since we defined two feedback methods that require monitoring, we provide these methods to define those sensors to the Turnout.

      The second sensor can be null if needed.

      Sensor-based feedback will not function until these sensors have been provided.

      Parameters:
      name - the user or system name of the sensor
      number - the feedback number of the sensor, indexed from 0
      Throws:
      JmriException - if unable to assign the feedback sensor

    • provideFirstFeedbackSensor

      void provideFirstFeedbackSensor(@CheckForNull String pName) throws JmriException
      Throws:
      JmriException

    • provideSecondFeedbackSensor

      void provideSecondFeedbackSensor(@CheckForNull String pName) throws JmriException
      Throws:
      JmriException

    • getFirstSensor

      @CheckForNull Sensor getFirstSensor()
      Get the first feedback sensor.
      Returns:
      the sensor or null if no Sensor set

    • getFirstNamedSensor

      @CheckForNull NamedBeanHandle<Sensor> getFirstNamedSensor()
      Get the handle for the first feedback sensor.
      Returns:
      the sensor handle or null if no Sensor set

    • getSecondSensor

      @CheckForNull Sensor getSecondSensor()
      Get the second feedback sensor.
      Returns:
      the sensor or null if no Sensor set

    • getSecondNamedSensor

      @CheckForNull NamedBeanHandle<Sensor> getSecondNamedSensor()
      Get the second feedback sensor handle.
      Returns:
      the sensor handle or null if no Sensor set

    • setInitialKnownStateFromFeedback

      @InvokeOnLayoutThread void setInitialKnownStateFromFeedback()
      Sets the initial known state (CLOSED,THROWN,UNKNOWN) from feedback information, if appropriate.

      This method is designed to be called only when Turnouts are loaded and when a new Turnout is defined in the Turnout table.

      No change to known state is made if feedback information is not available. If feedback information is inconsistent, or if sensor definition is missing in ONESENSOR and TWOSENSOR feedback, turnout state is set to UNKNOWN.

    • getControlType

      int getControlType()
      Get control type.
      Returns:
      0 for steady state or the number of time units the control pulses

    • setControlType

      @InvokeOnLayoutThread void setControlType(int num)
      Set control type.
      Parameters:
      num - 0 for steady state or the number of time units the control pulses

    • getInverted

      boolean getInverted()
      Get turnout inverted. When a turnout is inverted the CLOSED and THROWN states are reversed on the layout.
      Returns:
      true if inverted; false otherwise

    • setInverted

      void setInverted(boolean inverted)
      Get turnout inverted. When a turnout is inverted the CLOSED and THROWN states are reversed on the layout.
      Parameters:
      inverted - true if inverted; false otherwise

    • canInvert

      boolean canInvert()
      Determine if turnout can be inverted. When a turnout is inverted the CLOSED and THROWN states are inverted on the layout.
      Returns:
      true if can be inverted; false otherwise

    • getLocked

      boolean getLocked(int turnoutLockout)
      Get the locked state of the turnout. A turnout can be locked to prevent it being thrown from a cab or push button on the layout if supported by the protocol.
      Parameters:
      turnoutLockout - the type of lock
      Returns:
      true if turnout is locked using specified lock method

    • enableLockOperation

      @InvokeOnLayoutThread void enableLockOperation(int turnoutLockout, boolean locked)
      Enable turnout lock operators. A turnout can be locked to prevent it being thrown from a cab or push button on the layout if supported by the protocol.
      Parameters:
      turnoutLockout - the type of lock
      locked - true if locking is enabled for the given type; false otherwise

    • canLock

      boolean canLock(int turnoutLockout)
      Determine if turnout can be locked as currently configured. A turnout can be locked to prevent it being thrown from a cab or push button on the layout if supported by the protocol.
      Parameters:
      turnoutLockout - the type of lock, one of CABLOCKOUT, PUSHBUTTONLOCKOUT or BOTH = CABLOCKOUT | PUSHBUTTONLOCKOUT
      Returns:
      true if turnout is locked using specified lock method; false otherwise

    • getPossibleLockModes

      int getPossibleLockModes()
      Provide the possible locking modes for a turnout. These may require additional configuration, e.g. setting of a decoder definition for PUSHBUTTONLOCKOUT, before canLock(int) will return true.
      Returns:
      One of 0 for none, CABLOCKOUT, PUSHBUTTONLOCKOUT or CABLOCKOUT | PUSHBUTTONLOCKOUT for both

    • setLocked

      @InvokeOnLayoutThread void setLocked(int turnoutLockout, boolean locked)
      Lock a turnout. A turnout can be locked to prevent it being thrown from a cab or push button on the layout if supported by the protocol.
      Parameters:
      turnoutLockout - the type of lock
      locked - true if turnout is locked using specified lock method; false otherwise

    • getReportLocked

      boolean getReportLocked()
      Get reporting of use of locked turnout by a cab or throttle.
      Returns:
      true to report; false otherwise

    • setReportLocked

      @InvokeOnLayoutThread void setReportLocked(boolean reportLocked)
      Set reporting of use of locked turnout by a cab or throttle.
      Parameters:
      reportLocked - true to report; false otherwise

    • getValidDecoderNames

      @Nonnull String[] getValidDecoderNames()
      Get a human readable representation of the decoder types.
      Returns:
      a list of known stationary decoders that can be specified for locking

    • getDecoderName

      @CheckForNull String getDecoderName()
      Get a human readable representation of the locking decoder type for this turnout. In AbstractTurnout this String defaults to PushbuttonPacket.unknown , ie "None"
      Returns:
      the name of the decoder type; null indicates none defined

    • setDecoderName

      void setDecoderName(@CheckForNull String decoderName)
      Set a human readable representation of the locking decoder type for this turnout.
      Parameters:
      decoderName - the name of the decoder type

    • setBinaryOutput

      @InvokeOnLayoutThread void setBinaryOutput(boolean state)
      Use a binary output for sending commands. This appears to expose a LocoNet-specific feature.
      Parameters:
      state - true if the outputs are binary; false otherwise

    • getDivergingLimit

      float getDivergingLimit()

    • getDivergingSpeed

      String getDivergingSpeed()

    • setDivergingSpeed

      void setDivergingSpeed(String s) throws JmriException
      Throws:
      JmriException

    • getStraightLimit

      float getStraightLimit()

    • getStraightSpeed

      String getStraightSpeed()

    • setStraightSpeed

      void setStraightSpeed(String s) throws JmriException
      Throws:
      JmriException

    • isCanFollow

      boolean isCanFollow()
      Check if this Turnout can follow the state of another Turnout.
      Returns:
      true if this Turnout is capable of following; false otherwise

    • getLeadingTurnout

      @CheckForNull Turnout getLeadingTurnout()
      Get the Turnout this Turnout is following.
      Returns:
      the leading Turnout or null if none; null if isCanFollow() is false

    • setLeadingTurnout

      void setLeadingTurnout(@CheckForNull Turnout turnout)
      Set the Turnout this Turnout will follow.

      It is valid for two or more turnouts to follow each other in a circular pattern.

      It is recommended that a following turnout's feedback mode be DIRECT.

      It is recommended to explicitly call setFollowingCommandedState(boolean) after calling this method or to use setLeadingTurnout(jmri.Turnout, boolean) to ensure this Turnout follows the leading Turnout in the expected manner.

      Parameters:
      turnout - the leading Turnout or null if this Turnout should not follow another Turnout; silently ignored if isCanFollow() is false

    • setLeadingTurnout

      void setLeadingTurnout(@CheckForNull Turnout turnout, boolean followingCommandedState)
      Set both the leading Turnout and if the commanded state of the leading Turnout is followed. This is a convenience method for calling both setLeadingTurnout(jmri.Turnout) and setFollowingCommandedState(boolean).
      Parameters:
      turnout - the leading Turnout or null if this Turnout should not follow another Turnout; silently ignored if isCanFollow() is false
      followingCommandedState - true to have all states match leading turnout; false to only have non-commanded states match

    • isFollowingCommandedState

      boolean isFollowingCommandedState()
      Check if this Turnout is following all states or only the non-commanded states of the leading Turnout.
      Returns:
      true if following all states; false otherwise

    • setFollowingCommandedState

      void setFollowingCommandedState(boolean following)
      Set if this Turnout follows all states or only the non-commanded states of the leading Turnout.

      A Turnout can be commanded to be THROWN or CLOSED, but can also have additional states NamedBean.INCONSISTENT and NamedBean.UNKNOWN. There are some use cases where a following Turnout should match all states of the leading Turnout, in which case this should be true, but there are also use cases where the following Turnout should only match the INCONSISTENT and UNKNOWN states of the leading Turnout, but should otherwise be independently commanded, in which case this should be false.

      Parameters:
      following - true to have all states match leading turnout; false to only have non-commanded states match

    • setCommandedStateAtInterval

      void setCommandedStateAtInterval(int s)
      Before setting commanded state, if required by manager, apply wait interval until outputIntervalEnds() to put less pressure on the connection.

      Used to insert a delay before calling DigitalIO.setCommandedState(int) to spread out a series of output commands, as in MatrixSignalMast.updateOutputs(char[]) and DefaultRoute class SetRouteThread#run(). Interval value is kept in the Memo per hardware connection.

      Parameters:
      s - turnout state to forward