jmri
Interface Turnout

Show UML class diagram
All Superinterfaces:
NamedBean
All Known Implementing Classes:
AbstractTurnout, AcelaTurnout, CbusTurnout, EasyDccTurnout, EcosTurnout, EliteXNetTurnout, JMRIClientTurnout, LnTurnout, MarklinTurnout, NceTurnout, OlcbTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SerialTurnout, SprogCSTurnout, SprogTurnout, SRCPTurnout, TamsTurnout, XNetTurnout, XpaTurnout

public interface Turnout
extends NamedBean

Represent a Turnout on the layout.

A Turnout has two states:

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

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 in the jmrix package, 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 (e.g. LocoNet, NCE, etc) 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 Summary
static int CABLOCKOUT
          Constant representing turnout lockout cab commands
static int CLOSED
          Constant representing an "closed" state, either in readback or as a commanded state.
static int DIRECT
          Constant representing "direct feedback method".
static int EXACT
          Constant representing "exact feedback method".
static int INDIRECT
          Constant representing "indirect feedback".
static int LOCKED
          Constant representing a locked turnout
static int MONITORING
          Constant representing "feedback by monitoring sent commands".
static int ONESENSOR
          Constant representing "feedback by monitoring one sensor".
static int PUSHBUTTONLOCKOUT
          Constant representing turnout lockout pushbuttons
static int SIGNAL
          Constant representing "feedback for signals" .
static int THROWN
          Constant representing an "thrown" state, either in readback or as a commanded state.
static int TWOSENSOR
          Constant representing "feedback by monitoring two sensors".
static int UNLOCKED
          Constant representing a unlocked turnout
 
Fields inherited from interface jmri.NamedBean
INCONSISTENT, UNKNOWN
 
Method Summary
 boolean canInvert()
          Determine if turnout can be inverted If true turnouts can be inverted
 boolean canLock(int turnoutLockout)
          Determine if turnout can be locked.
 void enableLockOperation(int turnoutLockout, boolean locked)
          Enable turnout lock operators.
 int getCommandedState()
          Query the commanded state.
 int getControlType()
          Get control type.
 String getDecoderName()
          Get a human readable representation of the decoder type for this turnout.
 float getDivergingLimit()
           
 String getDivergingSpeed()
           
 int getFeedbackMode()
          Get the feedback mode in machine readable form.
 String getFeedbackModeName()
          Get the feedback mode in human readable form.
 NamedBeanHandle<Sensor> getFirstNamedSensor()
          Get the first sensor, if defined.
 Sensor getFirstSensor()
          Get the first sensor, if defined.
 boolean getInhibitOperation()
          Get the indicator for whether automatic operation (retry) has been inhibited for this turnout
 boolean getInverted()
          Get turnout inverted If true commands are reversed to layout
 int getKnownState()
          Query the known state.
 boolean getLocked(int turnoutLockout)
          Get turnout locked If true turnout is locked, must specify which type of lock, will return true if both tested and either type is locked.
 int getNumberOutputBits()
          Get number of output bits.
 boolean getReportLocked()
          Determine if we should send a message to console when we detect that a turnout that is locked has been accessed by a cab on the layout.
 NamedBeanHandle<Sensor> getSecondNamedSensor()
          Get the first sensor, if defined.
 Sensor getSecondSensor()
          Get the Second sensor, if defined.
 float getStraightLimit()
           
 String getStraightSpeed()
           
 TurnoutOperation getTurnoutOperation()
           
 String[] getValidDecoderNames()
          Get a human readable representation of the decoder types.
 String[] getValidFeedbackNames()
          Get a human readable representation of the feedback type.
 int getValidFeedbackTypes()
          Get a representation of the feedback type.
 boolean isConsistentState()
          Show whether state is one you can safely run trains over
 void provideFirstFeedbackSensor(String pName)
          Provide Sensor objects needed for some feedback types.
 void provideSecondFeedbackSensor(String pName)
           
 void setBinaryOutput(boolean state)
          Turn this object into just a binary output.
 void setCommandedState(int s)
          Change the commanded state, which results in the relevant command(s) being sent to the hardware.
 void setControlType(int num)
          Set control type.
 void setDecoderName(String decoderName)
          Set a human readable representation of the decoder type for this turnout.
 void setDivergingSpeed(String s)
           
 void setFeedbackMode(int mode)
          Set the feedback mode from a integer.
 void setFeedbackMode(String mode)
          Set the feedback mode from a human readable name.
 void setInhibitOperation(boolean io)
          Change the value of the inhibit operation indicator
 void setInitialKnownStateFromFeedback()
          Sets the initial known state (CLOSED,THROWN,UNKNOWN) from feedback information, if appropriate.
 void setInverted(boolean inverted)
          Set turnout inverted If true commands are reversed to layout.
 void setLocked(int turnoutLockout, boolean locked)
          Lock a turnout.
 void setNumberOutputBits(int num)
          Set number of output bits.
 void setReportLocked(boolean reportLocked)
          Set turnout report If true report any attempts by a cab to modify turnout state
 void setStraightSpeed(String s)
           
 void setTurnoutOperation(TurnoutOperation toper)
          set current automation class
 
Methods inherited from interface jmri.NamedBean
addPropertyChangeListener, addPropertyChangeListener, dispose, getComment, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListeners, getPropertyKeys, getState, getSystemName, getUserName, removeProperty, removePropertyChangeListener, setComment, setProperty, setState, setUserName, updateListenerRef
 

Field Detail

CLOSED

static final int CLOSED
Constant representing an "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 an "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

CABLOCKOUT

static final int CABLOCKOUT
Constant representing turnout lockout cab commands

See Also:
Constant Field Values

PUSHBUTTONLOCKOUT

static final int PUSHBUTTONLOCKOUT
Constant representing turnout lockout pushbuttons

See Also:
Constant Field Values

UNLOCKED

static final int UNLOCKED
Constant representing a unlocked turnout

See Also:
Constant Field Values

LOCKED

static final int LOCKED
Constant representing a locked turnout

See Also:
Constant Field Values
Method Detail

getKnownState

int getKnownState()
Query the known state. This is a bound parameter, so you can also register a listener to be informed of changes. A result is always returned; if no other feedback method is available, the commanded state will be used.


setCommandedState

void setCommandedState(int s)
Change the commanded state, which results in the relevant command(s) being sent to the hardware. The exception is thrown if there are problems communicating with the layout hardware.


getCommandedState

int getCommandedState()
Query the commanded state. This is a bound parameter, so you can also register a listener to be informed of changes.


isConsistentState

boolean isConsistentState()
Show whether state is one you can safely run trains over

Returns:
true iff state is a valid one and the known state is the same as commanded

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.


getValidFeedbackNames

String[] getValidFeedbackNames()
Get a human readable representation of the feedback type. The values depend on the implemented system.


setFeedbackMode

void setFeedbackMode(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.

Throws:
IllegalArgumentException

setFeedbackMode

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.

Throws:
IllegalArgumentException

getFeedbackModeName

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


getFeedbackMode

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


getInhibitOperation

boolean getInhibitOperation()
Get the indicator for whether automatic operation (retry) has been inhibited for this turnout


setInhibitOperation

void setInhibitOperation(boolean io)
Change the value of the inhibit operation indicator

Parameters:
io -

getTurnoutOperation

TurnoutOperation getTurnoutOperation()
Returns:
current operation automation class

setTurnoutOperation

void setTurnoutOperation(TurnoutOperation toper)
set current automation class

Parameters:
toper - TurnoutOperation subclass instance

provideFirstFeedbackSensor

void provideFirstFeedbackSensor(String pName)
                                throws JmriException
Provide Sensor objects needed for some feedback types. Since we defined two feeedback 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.

Throws:
JmriException

provideSecondFeedbackSensor

void provideSecondFeedbackSensor(String pName)
                                 throws JmriException
Throws:
JmriException

getFirstSensor

Sensor getFirstSensor()
Get the first sensor, if defined.

Returns null if no Sensor recorded.


getFirstNamedSensor

NamedBeanHandle<Sensor> getFirstNamedSensor()
Get the first sensor, if defined.

Returns null if no Sensor recorded.


getSecondSensor

Sensor getSecondSensor()
Get the Second sensor, if defined.

Returns null if no Sensor recorded.


getSecondNamedSensor

NamedBeanHandle<Sensor> getSecondNamedSensor()
Get the first sensor, if defined.

Returns null if no Sensor recorded.


setInitialKnownStateFromFeedback

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.


getNumberOutputBits

int getNumberOutputBits()
Get number of output bits.

Currently must be one or two.


setNumberOutputBits

void setNumberOutputBits(int num)
Set number of output bits.

Currently must be one or two.


getControlType

int getControlType()
Get control type.

Currently must be either 0 for steady state, or n for pulse for n time units.


setControlType

void setControlType(int num)
Set control type.

Currently must be either 0 for steady state, or n for pulse for n time units.


getInverted

boolean getInverted()
Get turnout inverted

If true commands are reversed to layout


setInverted

void setInverted(boolean inverted)
Set turnout inverted

If true commands are reversed to layout.

Changing this changes the known state from CLOSED to THROWN and vice-versa, with notifications; UNKNOWN and INCONSISTENT are left unchanged, as is the commanded state.


canInvert

boolean canInvert()
Determine if turnout can be inverted

If true turnouts can be inverted


getLocked

boolean getLocked(int turnoutLockout)
Get turnout locked

If true turnout is locked, must specify which type of lock, will return true if both tested and either type is locked.


enableLockOperation

void enableLockOperation(int turnoutLockout,
                         boolean locked)
Enable turnout lock operators.

If true the type of lock specified is enabled.


canLock

boolean canLock(int turnoutLockout)
Determine if turnout can be locked. Must specify the type of lock.

If true turnouts can be locked.


setLocked

void setLocked(int turnoutLockout,
               boolean locked)
Lock a turnout. Must specify the type of lock.

If true turnout is to be locked.


getReportLocked

boolean getReportLocked()
Determine if we should send a message to console when we detect that a turnout that is locked has been accessed by a cab on the layout. If true, report cab attempt to change turnout.


setReportLocked

void setReportLocked(boolean reportLocked)
Set turnout report

If true report any attempts by a cab to modify turnout state


getValidDecoderNames

String[] getValidDecoderNames()
Get a human readable representation of the decoder types.


getDecoderName

String getDecoderName()
Get a human readable representation of the decoder type for this turnout.


setDecoderName

void setDecoderName(String decoderName)
Set a human readable representation of the decoder type for this turnout.


setBinaryOutput

void setBinaryOutput(boolean state)
Turn this object into just a binary output.


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


Copyright © 1997-2013 JMRI Community.
JMRI, DecoderPro, PanelPro, SoundPro, DispatcherPro and associated logos are our trademarks.

Additional information on copyright, trademarks and licenses is linked here.
Site hosted by: Get JMRI Model Railroad Interface at SourceForge.net. Fast, secure and Free Open Source software downloads