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 TableRoutes can be viewed and configured using the Route Table. It contains the following columns:
- System Name
- User Name (optional)
- Comment (optional, double click to edit)
- Enabled (checkbox)
- Locked (checkbox)
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
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.
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.
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.
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'.
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.
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.
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.
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.
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).
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
- Edit of an existing Route may be started in either of
- 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.
- 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.
- 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.
- 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 kept in your layout configuration, along with Turnouts, Sensors, Signal Heads, Lights, control panel setup etc. To store this information on disk, allowing to reload it next time you run JMRI, use Store Configuration... in the File menu at the top of the Route 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.
- If a real turnout is used, the real turnout will receive the original activation command, and then the Route will set whatever Turnout positions and/or Sensor states were specified. This can be used to set multiple Turnouts to match the original real turnout, or to set the turnout back to its original position (if you don't want anybody changing it), etc. The Route will fire when the Turnout is set from JMRI, and/or with some DCC systems (Digitrax LocoNet and Lenz XPressNet systems), it will fire when a layout operator commands the Turnout to change state on a handheld throttle.
- A 'Phantom Turnout' is a DCC Turnout that doesn't actually exist. To use one, just create a Turnout entry for an address number that doesn't exist on your layout. The layout operators can select that phantom Turnout number on their throttles and send commands to it to cause the Route to be set. With the addition of Sensors as vetos in the Route, you can do things like only allowing Operators to change Turnouts (via the Route) when the Dispatcher has set a button to allow local access.
- An 'Internal Turnout' is one that only exists within the JMRI software; it doesn't correspond to any particular address on the layout, and it particularly doesn't correspond to any hardware on the layout. The system name for Internal Turnouts start with "IT", e.g. "IT201". JMRI knows that these are separate from the layout, so it doesn't send any commands to the attached hardware when one changes. Internal Turnouts can be used with Routes to build complicated logic underlying control Panels. For example, an icon on a Panel can set an Internal Turnout, which in turn can set the Turnouts of an entire yard ladder.
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.