Package jmri

Interface Turnout

  • All Superinterfaces:
    java.lang.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:
    TurnoutManager, InstanceManager, SimpleTurnoutCtrlFrame

    • Field Detail

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

    • Method Detail

      • getValidFeedbackModes

        java.util.Set<java.lang.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
java.lang.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
                     java.lang.String mode)
              throws java.lang.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:
        java.lang.IllegalArgumentException - if mode is not valid

      • setFeedbackMode

        @InvokeOnLayoutThread
void setFeedbackMode​(int mode)
              throws java.lang.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:
        java.lang.IllegalArgumentException - if mode is not valid

      • 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

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

      • 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

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

      • 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

      • 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