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:

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