Skip to main content

JMRI is...

Common Tools

JMRI provides powerful tools for working with your layout.

System-specific Tools

Layout Automation

JMRI can be used to automate parts of your layout, from simply controlling a crossing gate to running trains in the background.

JMRI: Routes Documentation

What are Routes?

Routes are collections of Turnouts and/or Sensors whose states may be set all at once. Also when a Route is triggered, a sound may be played, or a script may be run. For example, a Route may be set up to clear all turnouts on a mainline with one computer or fascia panel button. Routes may also be set up to control the setting of ladders of turnouts in staging areas or yards. Another use is to set layout turnouts to default positions when beginning an operating session. JMRI Routes are similar to the routes implemented in the Digitrax Chief system, except the JMRI Routes can mix turnouts controlled by different hardware systems, and also can set sensors, play a sound, or run a script.

Optionally a Route may be controlled by up to three sensors and/or by a control turnout. When a Route is created, or when it is read from a configuration file, the Route is 'activated'; it is set up to monitor automatically any changes in state of its control sensors and/or control turnout. When the controlling sensors or turnout change in the user-specified way, the Route is 'set' ('triggered'); included turnouts and included sensors are set as specified, and if specified, a sound is played or a script is run.

The Route Table contains an 'Enabled' column. For a Route to be triggered by its control sensors or its control turnout, it must be "enabled", that is its check box in the 'Enabled' column must be checked. You can uncheck this box to temporarily disable a Route from being triggered, i.e. prevent it from setting its turnouts, sensors, etc. when a control sensor or control turnout changes.

The Route Table

Routes can be viewed and configured using the Route Table. It contains the following columns:

Route Table Controls

Below the table is the Add... button.

How to setup Routes

First make sure the Turnout Table contains all Turnouts involved in the Routes to be defined, and that the Sensor Table contains all Sensors needed.
Then select Tools -> Tables -> Routes, and click the Add... button at the bottom of the pane to bring up the Add/Edit Route pane.

Adding a new Route

  1. Enter a System Name, such as 'IR100' - any short name can be used provided it is different from the System Name of other Routes.

    By convention, System Names usually start with "IR" for Internal Route.

  2. Enter a User Name. Any string of characters that is different from the User Name of other Routes will be accepted, but it's wise to use a string that describes the intended use of the Route.

    Note that before JMRI version 1.5.6, there was a bug that prevented you from having more than one blank (empty) User Name. In more recent versions, you can have as many Routes with blank User Names as you'd like; these have to be referenced via their System Names, of course.

  3. Select Turnouts to be included in the new Route in the list of all defined Turnouts, by clicking on the checkbox in the Include column. For each included Turnout, use the combo box in the Set State column to select whether that included Turnout is to be 'Set Closed', 'Set Thrown' or 'Toggle'd when the Route is 'Set'. Don't worry if everything isn't perfect. It's easy to edit this information later.

    Note that the Add/Edit Route pane allows you to display 'All' Turnouts and Sensors or only the already 'Included' Turnouts and Sensors. This is only for your convenience in checking that all desired Turnouts and/or Sensors have been included; it does not affect entered information.

  4. Similarly, select Sensors to be included in the new Route in the list of all defined Sensors, by clicking on the checkbox in the Include column. For each included Sensor, use the combo box in the Set State column to select whether that Sensor is to be 'Set Active', 'Set Inactive' or 'Toggle'd when the Route is 'Set'.

  5. If you want the Route to play a sound when it triggers, enter the file name of a sound file in the text box following 'Play sound file'. Clicking Set will bring up a file selection dialog to help locate the file. Once the file is located, clicking on its name in the dialog will copy it, complete with path, into the text box.

  6. Similarly if you want a script to be run when the Route triggers, enter its file name into the text box on the right. The Set button can be used as above to assist in entering script file information.

  7. If you want the setting of the Route to be controlled by one or more input Sensors, enter their names (System Name or User Name) and select what kind of logic they'll obey. Logic choices are described in detail below.

    When you save and restore your Routes using a configuration file, the Sensor name you enter here is used to recreate the Route. A System Name will always be associated with the same input Sensor. A User Name can be moved to another input by changing the entries in the Sensor Table. For example, "East OS Occupancy" could be changed from LocoNet Sensor input LS12 to LS24 by just associating that User Name with a different System Name; this makes layout rewiring easy. User Names entered here must exist however; if you change the Sensor's User Name from "East OS Occupancy" to "East Occupancy", the Route won't load properly until you edit it to use the new name.

  8. Also optional, if you want to enable setting of the Route when a particular Turnout changes state, enter a Turnout name (System Name or User Name) and select the logic that it will obey. Logic choices are explained in detail below.

    When you save and restore your Routes using a configuration file, the Turnout name you enter here is used to recreate the Route. A System Name will always be associated with the same Turnout. A User Name can be moved to another Turnout by changing the entries in the Turnout Table. For example, "Set Track 5" could be changed from LocoNet Control Turnout 105 to Turnout 5 by just associating that User Name with a different System Name; this makes layout rewiring easy. User Names entered here must exist however; if you change the Turnout's User Name from "Set Track 5" to "Set Trk 5", the Route won't load properly until you edit it to use the new name.

  9. The "Added delay" entry is normally left at "0". When a Route sets its Turnouts, it waits 250 milliseconds between Turnout control commands. If this is not enough time between commands for your type of Turnout control, you can increase the time between commands by entering an added delay (in milliseconds).

  10. Click the Add Route button at the bottom of the pane. If everything is fine, a message stating "New Route added ... " will be displayed in the notes box near the bottom of the pane. If there is trouble with anything, an error message will be displayed in the notes box; you should then correct the error and click Add Route again.

Editing an existing Route

  1. Edit of an existing Route may be started in either of two ways:
    • Click on a Route's Edit button in the Route Table.
    • Enter the System Name of the Route to be edited in the Add/Edit Route pane and click the Edit Route button at the bottom of the pane. This must be the same as one of the System Names shown in the Route Table.
    The Add Route and Edit Route buttons in the Add/Edit Route pane will change to Update Route and Cancel.
  2. Make whatever changes or additions you need to the information in the dialog. Note that the System Name of the edited Route may not be changed, but the User Name may be changed. Other items are as described above.
  3. After making changes to the Route information, click Update Route to change the selected Route. If everything is fine, a message stating "Route updated... " will be displayed in the notes box near the bottom of the window. If there is any trouble, an error message will be displayed in the notes box, and the update is stopped for you to correct the error and click Update Route again.
  4. Click Cancel to exit edit mode without changing the selected Route. If the Add/Edit Route window is dismissed (closed) while in edit mode, Cancel is automatically selected, and no changes are made to the selected Route.

Setting (trigger) a Route

Routes may be 'set' by clicking the Set button in the State column of the Route Table. A Route may also be set by fascia panel buttons if Sensors for these buttons are defined as control Sensors in the Route information. If a control Turnout is defined in the Route information, throwing or closing that Turnout from your physical throttle will also trigger the Route. Note that control Turnouts may be real turnouts, phantom turnouts, or internal turnouts as described below. A Route may also be triggered from a Logix, as the action of one of its conditionals. If you need more powerful logic to control your Route than provided by the Route itself, consider using a Logix.

Note that enabled/disabled and 'veto' logic discussed below for control Sensors and for the control Turnout apply only to a Route's automated control mechanism. Neither 'disabled' nor 'veto' logic will prevent a Route from being set (triggered) using the Set button or from a Logix.

It's also useful to note that when a Route has been triggered and is actively sending commands to Turnouts, the Route is marked as busy until this operation is complete. A Route cannot be triggered again while it is busy, i.e. until its current operation is complete.

Saving Routes to disk

Routes are saved in your layout configuration file, along with Turnouts, Sensors, Signal Heads, Lights, etc. To store this information on disk, use Store Configuration... in the File menu at the top of the Routes Table (or other tables from the Tools menu), or select Store Panel... in the Panel menu. Note that the enabled/disabled state of each Route is not saved in the configuration file. When Routes are loaded from a configuration file, they are all enabled.

Controlling Routes from Sensors

The operation of a Route can be controlled by up to three Sensors. These can be connected to occupancy detectors or switches on the layout, or even just used to operate the Route from a control Panel on the computer. These Sensors can be real sensors or internal sensors.

By default, when any one of the defined Sensors goes to the Active state, the Route will be set. This could be used to e.g. set a Route when a Block became occupied, or when a button was pushed.

More powerful logic can also do things like "define Routes to have the position of a Turnout follow the position of a panel switch". For this, each of the three Sensors has a "mode" associated with it, which can be:

"On Active"
The default method, the Route is triggered when the Sensor goes Active, e.g. "Throw Turnout 12 when Sensor 12 goes Active"
"On Inactive"
The Route is triggered when the Sensor goes Inactive. For example, using the Route above, plus a second Route "Close Turnout 12 when Sensor 12 goes Inactive" will have Turnout 12 follow a panel switch connected to Sensor 12 as it is flipped back and forth.
"On Change"
The Route is triggered when the Sensor state changes, either from Active to Inactive or from Inactive to Active.
"Veto Active"
If this Sensor is Active, other Sensors set to "On Active", "On Inactive" "On Change" will be ignored, and a control Turnout set to "On Closed", "On Thrown", or "On Change" will also be ignored. This has several uses, e.g. to prevent throwing a Turnout under a train when the Block shows occupied.
"Veto Inactive"
Like Veto Active, but the other polarity logic.

Note that there is an implied "and/or" here. All of the 'veto' Sensors and the 'veto' Turnout, if there is one, must be in their non-veto state _and_ at least one of the triggering Sensors or a triggering Turnout must see the appropriate change for the Route to be set.

Controlling Routes from a Turnout

The setting (triggering) of a Route can be controlled from a Turnout. This Turnout can be a real physical turnout, a 'phantom' turnout (a DCC Turnout number with no corresponding physical turnout), or an 'internal' turnout.

Similar to the Control Sensors discussed above, the Control Turnout has a "mode" associated with it, which can be:

"On Closed"
The default method, the Route is triggered when the Turnout changes to the Closed state.
"On Thrown"
The Route is triggered when the Turnout changes to the Thrown state.
"On Change"
The Route is triggered when the Turnout state changes, either from Closed to Thrown or from Thrown to Closed.
"Veto Closed"
If this Turnout is Closed, Sensors set to "On Active", "On Inactive" "On Change" will be ignored.
"Veto Thrown"
If this Turnout is Thrown, Sensors set to "On Active", "On Inactive" "On Change" will be ignored.

A single 'veto' Turnout or 'veto' Sensor can prevent the Route from being triggered. All of the 'veto' Sensors and the 'veto' Turnout, if there is one, must be in their non-veto state _and_ at least one of the triggering Sensors or a triggering Turnout must see the appropriate change for the Route to be set.