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

    • CLOSED

      static final int CLOSED
      Constant representing a "closed" state, either in readback or as a commanded state. Note that it's possible to be both CLOSED and THROWN at the same time on some systems, which should be called INCONSISTENT
      See Also:

    • THROWN

      static final int THROWN
      Constant representing a "thrown" state, either in readback or as a commanded state. Note that it's possible to be both CLOSED and THROWN at the same time on some systems, which should be called INCONSISTENT
      See Also:

    • DIRECT

      static final int DIRECT
      Constant representing "direct feedback method". In this case, the commanded state is provided when the known state is requested. The two states never differ. This mode is always possible!
      See Also:

    • EXACT

      static final int EXACT
      Constant representing "exact feedback method". In this case, the layout hardware can sense both positions of the turnout, which is used to set the known state.
      See Also:

    • INDIRECT

      static final int INDIRECT
      Constant representing "indirect feedback". In this case, the layout hardware can only sense one setting of the turnout. The known state is inferred from that info.
      See Also:

    • MONITORING

      static final int MONITORING
      Constant representing "feedback by monitoring sent commands". In this case, the known state tracks commands seen on the rails or bus.
      See Also:

    • ONESENSOR

      static final int ONESENSOR
      Constant representing "feedback by monitoring one sensor". The sensor sets the state CLOSED when INACTIVE and THROWN when ACTIVE
      See Also:

    • TWOSENSOR

      static final int TWOSENSOR
      Constant representing "feedback by monitoring two sensors". The first sensor sets the state THROWN when ACTIVE; the second sensor sets the state CLOSED when ACTIVE.
      See Also:

    • SIGNAL

      static final int SIGNAL
      Constant representing "feedback for signals" . This is DIRECT feedback, with minimal delay (for use with systems that wait for responses returned by from the command station).
      See Also:

    • DELAYED

      static final int DELAYED
      Constant representing "automatic delayed feedback" . This is DIRECT feedback with a fixed delay before the feedback (known state) takes effect.
      See Also:

    • LNALTERNATE

      static final int LNALTERNATE
      Constant representing "loconet alternate feedback method". In this case, the layout hardware can sense both positions of the turnout, which is used to set the known state. Hardware use OPS_SW_REP alternate message.
      See Also:

    • CS_VPIN

      static final int CS_VPIN
      Constant representing "CS VPIN output mode". The command station drives a VPIN directly via the <z> command with no pre-definition required in the CS output table. Differs from DIRECT (which sends a DCC accessory packet); this sends a VPIN pin-control command resolved by the CS HAL layer at runtime. The known state is updated optimistically on send.
      See Also:

    • CABLOCKOUT

      static final int CABLOCKOUT
      Constant representing turnout lockout cab commands
      See Also:

    • PUSHBUTTONLOCKOUT

      static final int PUSHBUTTONLOCKOUT
      Constant representing turnout lockout pushbuttons
      See Also:

    • UNLOCKED

      static final int UNLOCKED
      Constant representing a unlocked turnout
      See Also:

    • LOCKED

      static final int LOCKED
      Constant representing a locked turnout
      See Also:

    • PROPERTY_COMMANDED_STATE

      static final String PROPERTY_COMMANDED_STATE
      String constant for Property Change to set Commanded State.
      See Also:

    • PROPERTY_FEEDBACK_MODE

      static final String PROPERTY_FEEDBACK_MODE
      String constant for Property Change to set Feedback Mode.
      See Also:

    • PROPERTY_INVERTED

      static final String PROPERTY_INVERTED
      String constant for Property Change to set the Inverted Mode.
      See Also:

    • PROPERTY_LOCKED

      static final String PROPERTY_LOCKED
      String constant for Property Change to set the Locked state.
      See Also:

    • PROPERTY_REPORT_LOCKED

      static final String PROPERTY_REPORT_LOCKED
      String constant for Property Change to set the Report Locked state.
      See Also:

    • PROPERTY_DECODER_NAME

      static final String PROPERTY_DECODER_NAME
      String constant for Property Change to set Decoder Name.
      See Also:

    • PROPERTY_TURNOUT_OPERATION_STATE

      static final String PROPERTY_TURNOUT_OPERATION_STATE
      String constant for Property Change to set Turnout Operator.
      See Also:

    • PROPERTY_TURNOUT_FEEDBACK_FIRST_SENSOR

      static final String PROPERTY_TURNOUT_FEEDBACK_FIRST_SENSOR
      String constant for when changing the First Feedback Sensor in use.
      See Also:

    • PROPERTY_TURNOUT_FEEDBACK_SECOND_SENSOR

      static final String PROPERTY_TURNOUT_FEEDBACK_SECOND_SENSOR
      String constant for when changing the Second Feedback Sensor in use.
      See Also:

    • PROPERTY_TURNOUT_DIVERGING_SPEED

      static final String PROPERTY_TURNOUT_DIVERGING_SPEED
      String constant for when the Diverging Speed has changed.
      See Also:

    • PROPERTY_TURNOUT_STRAIGHT_SPEED

      static final String PROPERTY_TURNOUT_STRAIGHT_SPEED
      String constant for when the Straight Speed has changed.
      See Also:

    • PROPERTY_LEADING_TURNOUT

      static final String PROPERTY_LEADING_TURNOUT
      String constant for when the Leading Turnout is set.
      See Also:

  • 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