Package jmri

Interface Turnout

All Superinterfaces:
Comparable<NamedBean>, DigitalIO, NamedBean, PropertyChangeProvider
All Known Implementing Classes:
AbstractTurnout, AcelaTurnout, 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
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