JMRI: Turnout Table Help
Author: Bob Jacobsen
Keywords: JMRI help Turnout Table

# The Turnout Table

This table contains a list of all Turnouts that exist for this Panel. From this table you can change the state of a Turnout, change the feedback mode, enter Sensors for feedback, invert, lock, and delete it.

## Turnout Table Columns

Contents of the Turnout Table are displayed by selecting it under Tools ⇒ Tables. As with all JMRI tool tables, you can add or remove columns from the display by right-clicking anywhere in the column header and selecting or deselecting the desired columns from the menu that appears (see picture at right). You can change the order of the columns by dragging their titles, change the width of columns by dragging the vertical line between columns, and sort the rows by clicking the column title (a triangle will appear indicating the direction of the sort).

System Name
  The System Name cannot be changed once entered into the table. The "Add..." button located in the lower left corner of the pane allows you to add a new Turnout to the table. The System Name is automatically generated when using the "Add..." button.
  See Names for more info about the format.
User Name
  You can directly enter or change the "User Name" for an existing Turnout (double click in the cell). This can be pretty much anything you wish to describe the Turnout.
State
  Pushing one of the buttons/icons in the "State" column will change the state of that particular Turnout.
  Choose between textual and graphic display of the Turnout state in the Display preferences.
Delete
  Pushing the "Delete" button will remove that Turnout from the table.

  Note that this doesn't remove the Turnout from any files you've saved that contain it. If you load one of those files, perhaps when you restart the program, the Turnout will reappear. You should use one of the "Store to file" options in the "File" menu to save new versions of any files that contain this Turnout.

Inverted
  When checked, the Turnout command and status to and from the layout is inverted. For example, an inverted Turnout means that when JMRI sends a "CLOSE" turnout command, it becomes a "THROW" to the layout. Turnouts that can not be inverted have grayed out boxes and can not be checked.
Locked
  When checked, the Turnout is locked. There are two types of locks supported by JMRI: Cab lockout and Pushbutton lockout. When a Turnout is locked, only Turnout commands from JMRI will move the Turnout. Cabs and/or pushbuttons on the layout are disabled. You can decide for each Turnout if you want "Both" cabs and pushbuttons locked, "Cabs only", or "Pushbuttons only". Click the "Show Lock information" box on the lower edge of the pane to see the lock options. Not all stationary decoders support pushbutton lockout, and not all systems support cab lockout. Turnouts that can not be locked have grayed out boxes and can not be checked. See Turnout Lock feature below.
Edit
  Click this button to inspect and set Basic settings, Feedback, Lock, Speed, Usage and (custom) Properties of a particular Turnout in a tabbed pane.
Feedback
  This shows the known state of a turnout on the layout, which may differ from the last Cmd sent.
Mode
  The pull down boxes allow you to select the method of operation for a Turnout. See Turnout Feedback below.
Sensor 1
  Shows the System Name of the optional Sensor that provides the feedback for a Turnout. You can also directly enter or change the System Name of Sensor 1 for a Turnout.
Sensor 2
  Shows the System Name of the optional Sensor that provides the feedback for a Turnout. You can also directly enter or change the System Name of Sensor 2 for a Turnout.
Retry Automation
  Shows what specific retry method has been configured for this Turnout. See the section on Turnout Automation below.
Edit Auto
  Click this button to set custom retry values for a specific turnout. This button is inactive when Automate is set to Off or Use Global.
Lock Mode
  Shows which lockouts, if any, are active for this Turnout. "Both" means that cabs and pushbuttons will be locked out if the Lock is active. "Cabs only" means that cabs will be locked out, but pushbuttons will continue to work when the Lock is active. And "Pushbuttons only" means that pushbuttons will be locked out, but cabs will continue to work when the Lock is active. Note, when JMRI locks a Turnout's pushbutton, it does so by sending a Lock command to the Turnout decoder's lock control CV register. You must unlock the Turnout before shutting down the JMRI program if you want to restore the operation of the pushbuttons. Cab lockout automatically terminates when the JMRI program is shut down. For more information on this, see Turnout Lock below.
Decoder
  When you're using the lock feature, the program needs to know what type of DCC decoder is in use so it can handle it properly. If you're not using the lock feature, don't bother with this field; JMRI is capable of commanding any type of accessory decoder to move back and forth.

  Currently the program only supports lock mode for NCE revision C and CVP accessory decoders. CVP decoders support one or two pushbutton operation. Select the number of pushbuttons used to operate that specific turnout. `CVP_AD4_1B` means one button, and `CVP_AD4_2B` means two buttons. We recommend that you enter all four CVP Turnouts per decoder into the Turnout Table, even if you're only locking one. You do not need to specify the number of pushbuttons for NCE. Unfortunately, NCE revisions A and B accessory decoders do not support pushbutton lockout.

Closed and Thrown Speed
  The closed and thrown speed is used with certain automation tools and logic, to help determine the speed at which a Train can be set through the Turnout when it is set to different states. It is also used by the Signal Mast Logic for determining which aspect should be displayed on a Signal Mast.

  In the drop down list, you are presented a set of named fixed speeds that have been predefined in the `signalSpeed.xml` file, in addition to a global and use block speed options.
  In addition it is also possible to enter a numerical value to represent a speed.

  The global value is set via the Speeds menu option.

  When "Use Block Speed" is selected this in effect tells any automation tool to ignore the speed setting through this Turnout; the tool should then only consider speeds that are set on Blocks.

Forget

  The Forget button will set the Commanded Turnout state to Unknown. For Turnouts using Feedback Sensors, the feedback state is unaffected, whereas for Direct and Delayed Mode the Turnout feedback state will also be Unknown.

Query

  For some system types, the Query button can poll the Sensor to obtain the current status. There is also a LogixNG Action to Query All Sensors for a particular connection.

## Turnout Table Controls

Along the bottom of the Turnout Table pane are buttons and checkboxes that control its operation.

Add...
  Pressing this button opens a pane where you can add a new Turnout.
Automatic retry
  When checked, enables the Automate - Global Default setting for all Turnouts. Currently the Global Default does not cause retries for Turnouts. See the section on Turnout Automation below for more information i.e. to set Automate properties for an individual Turnout.
Show feedback information
  When checked, the optional Feedback columns are shown.
Show Lock information
  When checked, the optional Lock columns are shown.
Show Turnout Speed information
  When checked, lets you set the Thrown and Closed speeds for each Turnout. Choose either Use Block Speed or one of the speed values from the list.
Show State Query actions
  When checked, the optional Sensor State Query and State Forget columns are shown.
Retry Automation menu
  To read or set global (system wide) turnout retry settings, choose the Automation -> Edit... menu. Change the number of retries and the interval between them.
Speeds menu
  To read or set global (system wide) turnout speeds, choose the Speeds -> Defaults... menu.

## Turnout Feedback

Model railroaders want different things when it comes to knowing the status of the turnouts on their layout. Some are quite happy to say "I told it to move, that's good enough for me". These people don't worry about whether a turnout on their layout actually moved when they told it to. Those people can just ignore this page, and leave the JMRI settings at their default.

But some modelers want to have better information about the status of the turnouts on their layout, and so use some form of "feedback" to indicate turnout position. This could be as complicated as two microswitches, adjusted to only close when the turnout is properly seated in either position. Or it could be something simpler.

In the JMRI program, Turnout objects actually know about two different states: "Commanded" state and "Known" state. The commanded state is "This is what was asked for last". The known state is "This is what's happening on the layout as far as I know".

Built into NCE, LocoNet and XPressNet systems are limited abilities to monitor what is happening on their networks. This allows JMRI to capture messages or poll the system concerning Turnout state changes. All the other protocols normally use a "you told it to change, so it did" logic. In other words, when something in the code (the Turnout Control Tool or a script) commands a state change from closed to thrown, the default is for both both the commanded state and the known state to change to "Thrown".

But it is also possible to control this in more detail if you have wired your layout to allow it.

The whole question of Turnout feedback is then "How do we configure the program to understand the known state properly, given my layout hardware?"

In the Turnouts pane (Tools -> Tables -> Turnouts) click on the box near the bottom that is labeled "Show feedback information". To the right of the Turnouts pane you'll find four extra columns associated with feedback:

"Feedback"
  This is the "known state". You can't change it, but this column will show you what the program thinks it is.
"Mode"
  This is the feedback method used by this Turnout. (You can change it for each Turnout individually, but note the change doesn't take effect until you click somewhere else, and you might need to add some Sensor names in the next column(s))
"Sensor 1", "Sensor 2"
  These define the Sensors needed by certain types of feedback. You can type a Sensor number, System Name or User Name here; the program will change it to the System Name that it needs.

Available Feedback modes are:

DIRECT
  The default in many cases. When something tells the Turnout to change, it's just immediately assumed that it actually did it.
ONESENSOR
  The Turnout monitors the Sensor defined by the "Sensor 1" column, which could be the input from a microswitch on the turnout or similar.
  When the Sensor is "Active", the turnout is known to be in the "Thrown" position. When it's "Inactive", the turnout is known to be in the "Closed" position.

  Sensor 1 | Feedback (known) State
  --- | ---
  Active | Thrown
  Inactive | Closed
  Unknown | Inconsistent since 4.21.5
  Inconsistent | Inconsistent since 4.21.5

TWOSENSOR
  The Turnout monitors two Sensors defined by the "Sensor 1" and "Sensor 2" columns, which could be inputs from microswitches at either end of the turnout's throw bar or from servo travel events.
  The Turnout feedback state is determined by both Sensors: <-- Table in same order as 2 Sensor Feedback Unit Tests within AbstractTurnoutTestBase -->

  Sensor 1 | Sensor 2 | Feedback (known) State |
  --- | --- | --- | ---
  Active | Inactive | Thrown |
  Inactive | Active | Closed |
  Inactive | Inactive | Inconsistent | Typical condition for a Turnout mid-throw
  Unknown | Unknown | Unknown | Typical startup condition
  Active | Active | Inconsistent |
  Active | Inconsistent | Inconsistent | Changed from Unknown > Inconsistent 4.21.5
  Inactive | Inconsistent | Inconsistent |
  Inconsistent | Active | Inconsistent |
  Inconsistent | Inactive | Inconsistent |
  Unknown | Active | Inconsistent |
  Unknown | Inactive | Inconsistent |
  Unknown | Inconsistent | Inconsistent |
  Inconsistent | Unknown | Inconsistent | Changed from Unknown > Inconsistent 4.21.5
  Active | Unknown | Inconsistent |
  Inactive | Unknown | Inconsistent |
  Inconsistent | Inconsistent | Inconsistent | Changed from Unknown > Inconsistent 4.21.5

DELAYED
  When something tells the Turnout to change, it immediately starts the operation and goes to the INCONSISTENT state to reflect that the points are moving. After a few seconds delay, the operation completes and the final state is reported. The default delay duration is 4 seconds. The delay duration for the current JMRI session can be changed using the `SetDefaultDelayedTurnoutDelay.py` script.
MONITORING
  Default for LocoNet Turnouts (and probably XpressNet soon), and available for NCE. When selected, the network is monitored for messages about the status of the Turnout. This mode is only available for certain systems, i.e. some systems can't do the monitoring properly, and don't have this choice.
INDIRECT
  Currently only available for LocoNet Turnouts, this informs the program that the turnout is being driven by a Digitrax DS54 with a microswitch attached to the switch lead. For more information, see the DS54 examples page.
EXACT
  Currently only available for LocoNet Turnouts, this informs the program that the turnout is being driven by a Digitrax DS54 with two microswitches attached to the switch and aux leads. For more information, see the DS54 examples page on the JMRI website.

## Turnout Retry Automation

JMRI can watch a Turnout and automate certain operations on it. This was originally added to handle the case of "I usually have to click that turnout a couple times to get it to throw over", but it can be used for other things too.

The three forms are:

No Feedback
  This just repeats the messages a fixed number of times, with a delay in between.
Sensor
  This repeats the messages, with a delay in between, until either the Sensor feedback indicates the turnout has moved or a limit on the number of attempts is reached.
Raw
  This sends raw DCC packets to command the turnout to move over, instead of working through the usual mechanisms for the specific system. This mode is intended as a way of getting around certain kinds of incompatibility between DCC components.
  (Note: Raw is not available with MONITORING feedback, because that relies on system-specific messages that aren't used in this mode. It's also not available for systems that don't have a DCC command station present to send the raw messages)

Normally, turnouts are only thrown once, which is the "Off" setting under "Automation". You can set a Turnout to use "No Feedback" automation by selecting it in the Automation column for the individual Turnout. If there are feedback Sensors defined, you can also select the "Sensor" method there.

You can customize the automation by clicking "Edit Auto" for an individual Turnout.

It's also possible to set global Retry Automation defaults, and some Turnouts use those. Use the Retry Automation -> Edit... menu to access those defaults.

## Turnout Lock feature

The Turnout Lock feature allows you to selectively disable accessory (Turnout) commands from cabs and/or locally-wired pushbuttons. The Lock can be set (Locked) or unset (Unlocked) from a checkbox in the Turnout Table, from a Route or Logix, or from scripts.

#### Cab Lockout

To do the Cab Lockout, JMRI works with the DCC system to prevent people from changing the position of a locked Turnout. JMRI can only do this with some DCC systems. To do it, the JMRI program monitors the Turnout's accessory address and if it detects a change command from a Cab, will cancel the command by immediately sending out the opposite command to the Turnout.

To use this feature with an NCE command station, you must select MONITORING as the feedback mode for the Turnout and the NCE command station must have the 2007 or newer EPROM.

#### Pushbutton Lockout

JMRI can also work with certain types of DCC accessory decoders to lock out their locally-wired pushbuttons. To do this, JMRI sends DCC commands to the decoder. These commands are decoder-type specific, so the program needs to know what type of accessory decoder operates each lockable Turnout. (There is no industry standard for the "Lock" messages, unlike for the messages to move the turnout back and forth, so we have to create the right custom ones for each type.) The various types are selected in the "Decoder" column of the Turnout Table.

#### Locking Routes

To help you select a set of Turnouts to lock, a Route can also be locked. All Turnouts that are being monitored by the JMRI program and are included in the Route will be locked. See the Routes help page for more information.