As of JMRI 4.19.2, the type letter for routes was changed from R to O. The system name for routes now starts with IO.
[After reading this page, see also the LRoutes documentation. LRoutes offer extended routing capabilities, transparently implementing them as a series of Logix conditionals. LRoutes are set up similarly to and are capable of performing all of the tasks of Routes - and more. They can even trigger a Route for complete compatibility.]
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.
Below the table is the Add... button.
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.
Enter a System Name, such as 'IO100' - any short name can be used provided it is different from the System Name of other Routes.
By convention, System Names usually start with "IO" 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 ... 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 ... 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 Create 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 Create again.
since 4.99.4The Copy from... button is used to to copy the configuration of an existing route to a new route. This makes it easy to make a set of routes that have minor differences, such as yard ladders.
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.
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 you to reload it next time you run JMRI, see Loading and Storing Your Work. 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.
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:
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.
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:
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.
You can also specify whether the Route should respond to changes in the Known state (the default) or whether it should respond to changes in the Commanded state. If you are not using turnout feedback these are the same. If you do have feedback enabled, the Commanded state is what JMRI has requested will be set on the turnout, and the Known state is what is returned from the feedback. Usually the default is the right choice here.