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
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface jmri.NamedBean
NamedBean.BadNameException, NamedBean.BadSystemNameException, NamedBean.BadUserNameException, NamedBean.DisplayOptions, NamedBean.DuplicateSystemNameException
-
-
Field Summary
Fields Modifier and Type Field Description static int
CABLOCKOUT
Constant representing turnout lockout cab commandsstatic int
CLOSED
Constant representing a "closed" state, either in readback or as a commanded state.static int
DELAYED
Constant representing "automatic delayed feedback" .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
LNALTERNATE
Constant representing "loconet alternate feedback method".static int
LOCKED
Constant representing a locked turnoutstatic 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 pushbuttonsstatic int
SIGNAL
Constant representing "feedback for signals" .static int
THROWN
Constant representing a "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
DISPLAY_NAME_FORMAT, INCONSISTENT, PROPERTY_STATE, QUOTED_NAME_FORMAT, UNKNOWN
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description boolean
canInvert()
Determine if turnout can be inverted.boolean
canLock(int turnoutLockout)
Determine if turnout can be locked as currently configured.void
enableLockOperation(int turnoutLockout, boolean locked)
Enable turnout lock operators.int
getControlType()
Get control type.java.lang.String
getDecoderName()
Get a human readable representation of the locking decoder type for this turnout.float
getDivergingLimit()
java.lang.String
getDivergingSpeed()
int
getFeedbackMode()
Get the feedback mode in machine readable form.java.lang.String
getFeedbackModeName()
Get the feedback mode in human readable form.NamedBeanHandle<Sensor>
getFirstNamedSensor()
Get the handle for the first feedback sensor.Sensor
getFirstSensor()
Get the first feedback sensor.boolean
getInhibitOperation()
Get if automatically retrying an operation is blocked for this turnout.boolean
getInverted()
Get turnout inverted.Turnout
getLeadingTurnout()
Get the Turnout this Turnout is following.boolean
getLocked(int turnoutLockout)
Get the locked state of the turnout.int
getPossibleLockModes()
Provide the possible locking modes for a turnout.boolean
getReportLocked()
Get reporting of use of locked turnout by a cab or throttle.NamedBeanHandle<Sensor>
getSecondNamedSensor()
Get the second feedback sensor handle.Sensor
getSecondSensor()
Get the second feedback sensor.float
getStraightLimit()
java.lang.String
getStraightSpeed()
TurnoutOperation
getTurnoutOperation()
java.lang.String[]
getValidDecoderNames()
Get a human readable representation of the decoder types.java.util.Set<java.lang.Integer>
getValidFeedbackModes()
Get a list of valid feedback types.java.lang.String[]
getValidFeedbackNames()
Get a human readable representation of the feedback type.int
getValidFeedbackTypes()
Get a representation of the feedback type.static int
invertTurnoutState(int inState)
Return the inverted state of the specified state Does NOT invert INCONSISTENTboolean
isCanFollow()
Check if this Turnout can follow the state of another Turnout.boolean
isFollowingCommandedState()
Check if this Turnout is following all states or only the non-commanded states of the leading Turnout.default void
provideFeedbackSensor(java.lang.String name, int number)
Provide Sensor objects needed for some feedback types.void
provideFirstFeedbackSensor(java.lang.String pName)
void
provideSecondFeedbackSensor(java.lang.String pName)
void
setBinaryOutput(boolean state)
Use a binary output for sending commands.void
setCommandedStateAtInterval(int s)
Before setting commanded state, if required by manager, apply wait interval until outputIntervalEnds() to put less pressure on the connection.void
setControlType(int num)
Set control type.void
setDecoderName(java.lang.String decoderName)
Set a human readable representation of the locking decoder type for this turnout.void
setDivergingSpeed(java.lang.String s)
void
setFeedbackMode(int mode)
Set the feedback mode from a integer.void
setFeedbackMode(java.lang.String mode)
Set the feedback mode from a human readable name.void
setFollowingCommandedState(boolean following)
Set if this Turnout follows all states or only the non-commanded states of the leading Turnout.void
setInhibitOperation(boolean io)
Set if automatically retrying an operation is blocked for this turnout.void
setInitialKnownStateFromFeedback()
Sets the initial known state (CLOSED,THROWN,UNKNOWN) from feedback information, if appropriate.void
setInverted(boolean inverted)
Get turnout inverted.void
setLeadingTurnout(Turnout turnout)
Set the Turnout this Turnout will follow.void
setLeadingTurnout(Turnout turnout, boolean followingCommandedState)
Set both the leading Turnout and if the commanded state of the leading Turnout is followed.void
setLocked(int turnoutLockout, boolean locked)
Lock a turnout.void
setReportLocked(boolean reportLocked)
Set reporting of use of locked turnout by a cab or throttle.void
setStraightSpeed(java.lang.String s)
void
setTurnoutOperation(TurnoutOperation toper)
set current automation class-
Methods inherited from interface jmri.DigitalIO
getCommandedState, getKnownState, isConsistentState, requestUpdateFromLayout, setCommandedState
-
Methods inherited from interface jmri.NamedBean
addPropertyChangeListener, addPropertyChangeListener, compareSystemNameSuffix, compareTo, describeState, dispose, getBeanType, getComment, getDisplayName, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListenersByReference, getPropertyKeys, getState, getSystemName, getUsageReport, getUserName, removeProperty, setComment, setProperty, setState, setUserName, toString, updateListenerRef, vetoableChange
-
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
-
Methods inherited from interface jmri.VariableControlSpanBean
getNumberControlBits, setNumberControlBits
-
-
-
-
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
-
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
-
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 previousgetValidFeedbackNames()
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 previousgetValidFeedbackTypes()
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
-
getFeedbackModeName
@Nonnull java.lang.String getFeedbackModeName()
Get the feedback mode in human readable form. This will be one of the names defined in agetValidFeedbackNames()
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 agetValidFeedbackTypes()
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 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 sensornumber
- the feedback number of the sensor, indexed from 0- Throws:
JmriException
- if unable to assign the feedback sensor
-
provideFirstFeedbackSensor
void provideFirstFeedbackSensor(@CheckForNull java.lang.String pName) throws JmriException
- Throws:
JmriException
-
provideSecondFeedbackSensor
void provideSecondFeedbackSensor(@CheckForNull java.lang.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 theCLOSED
andTHROWN
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 theCLOSED
andTHROWN
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 theCLOSED
andTHROWN
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 locklocked
- 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, beforecanLock(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 locklocked
- 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
-
getDivergingLimit
float getDivergingLimit()
-
getDivergingSpeed
java.lang.String getDivergingSpeed()
-
setDivergingSpeed
void setDivergingSpeed(java.lang.String s) throws JmriException
- Throws:
JmriException
-
getStraightLimit
float getStraightLimit()
-
getStraightSpeed
java.lang.String getStraightSpeed()
-
setStraightSpeed
void setStraightSpeed(java.lang.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 usesetLeadingTurnout(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 ifisCanFollow()
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 bothsetLeadingTurnout(jmri.Turnout)
andsetFollowingCommandedState(boolean)
.- Parameters:
turnout
- the leading Turnout or null if this Turnout should not follow another Turnout; silently ignored ifisCanFollow()
is falsefollowingCommandedState
- 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
orCLOSED
, but can also have additional statesNamedBean.INCONSISTENT
andNamedBean.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 inMatrixSignalMast.updateOutputs(char[])
andDefaultRoute
class SetRouteThread#run(). Interval value is kept in the Memo per hardware connection, default = 0- Parameters:
s
- turnout state to forward
-
-