JMRI is...

JMRI provides powerful tools for working with your layout.

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

JMRI: LRoute Documentation

What are LRoutes?

LRoutes extend the capabilities of Routes. Lights and Signal Heads are included in the collection of Turnouts and/or Sensors whose states may be set all at once and used for control of the LRoute. As with Routes, when an LRoute is triggered a sound may be played, or a script may be run. LRoutes are capable of performing all of the tasks that Routes can do. For further discussion and examples consult the main Route documentation.

How LRoutes differ from Routes?

Whereas a Route may be controlled by up to three sensors and/or by a control turnout, an LRoute may use any number or combination of Sensors, Turnouts, Lights, and/or Signal Heads to control the "route".

LRoutes are implemented as a group of Conditionals in a Logix. This provides another extension of capabilities in that, this Logix may be edited in the Logix Editor where Conditionals can be edited or created to preform other tasks. When a LRoute is created, or when it is read from a configuration file, the LRoute is 'activated'; it is set up to monitor automatically any changes in state of its control entities. When these entities change in the user-specified way, the LRoute is 'set' ('triggered') and the actions selected by the user are taken - And if specified, a sound is played or a script is run.

The LRoute Table contains an 'Enabled' column. For an LRoute to be triggered by its control entities, it must be "enabled". That is, its check box in the 'Enabled' column must be checked. This check box enables/disables the Logix implementing the LRoute.

How to set up for adding or editing LRoutes

First make sure the Tables for Sensors, Turnouts, Lights and/or SignalHeads contain all the entities involved in the LRoutes to be defined. Next select LRoute Table from the Tools menu.

To add a new LRoute:

Click the Add... button at the bottom of the pane to bring up the Add LRoute pane.

Enter a system name, such as 'RTX100'. Any short name can be used provided it is different from the system name of other LRoutes.

By convention, system names usually start with "RTX" for an LRoute.
Enter a user name. Any string of characters that is different from the user name of other LRoutes will be accepted, but it's wise to use a string that describes the intended use of the LRoute.
Note the four tabs beneath the menu bar. Select the tab labeled Actions (output). This displays a table with all of the Sensors, Turnouts, Lights, and/or SignalHeads that the user has defined in their respective tables.
Select the entities to be included for actions to be taken in the LRoute from the list by clicking on the checkbox in the Include column. For each included item, use the combo box in the Set Action column to select the action that should be taken for the entity. For example, an included turnout is to be 'Set Closed', 'Set Thrown' or 'Toggle'd and an included sensor is to be 'Set Active', 'Set Inactive' or 'Toggle'd when the LRoute is 'Set' - similarly for lights. An included SignalHead can be set to any one of its 'appearances'. Don't worry if everything isn't perfect. It's easy to edit this information later.
Note that the 'Actions (output)' Tab allows you to display 'All' the entities or just the 'Included' ones. This is only for your convenience in checking that all desired entities have been included; it does not affect entered information.
Next select the tab labeled Triggers/Controls (input). This also displays a table with all the Sensors, Turnouts, Lights and/or SignalHeads that the user has defined in their respective tables.
Select the entities to be included to control (i.e. trigger) the LRoute from the list by clicking on the checkbox in the Include column. For each included item, use the combo box in the Trigger State column to select the state that should be taken to trigger the entity. For example, an included turnout may be set to trigger 'On Closed', 'On Thrown' or On Change'. It will prevent triggering when thrown if 'Veto When Thrown' is selected or prevent triggering when closed if 'Veto When Closed' is selected. The selections are similar for an included Sensor or Light. An included SignalHead has the choices for "On" for each of its appearances and choices for "Veto When" for each appearance.
This tab also has 'All' and 'include' radio buttons that operate in a similar manner as the previous tab.
Next select the tab labeled Alignment/Locks/etc..
If you want the LRoute 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 LRoute triggers, enter its file name into the text box labeled 'Run Script'. The Set button can be used as above to assist in entering script file information.
Checking the check box Set Locks will lock the turnouts included from the 'Actions (output)' tab when the entities from the 'Triggers/Controls (input)' trigger. When these entities are no longer determine a trigger state, the above turnouts are unlocked. For more information on turnout locks, see Turnout Lock feature .
The table on the 'Alignment/Locks/etc.' tab lists all the sensors defined in the Sensor Table. A sensor (or sensors) may be chosen to go active when the actions of the entities included from the 'Actions (output)' tab are completed. You may choose to indicate 'alignment' of the Sensors, Turnouts, Lights, and/or SignalHeads in separate groups or for all them together. If the group actions are completed in by means other than the LRoute trigger, the sensor will still indicate 'alignment'.
Finally, select the tab labeled LRoute Basics to return to the first tab.
Click the Create button at the bottom of the pane. If everything is fine, a message stating "New LRoute added ... " will be displayed in the notes box near the bottom of the tab. If there is trouble with anything, an error message will be displayed in the notes box; you should correct the error and click Add LRoute again.

To abort adding the LRoute, press the Cancel button.

To edit an existing LRoute:

Edit of an existing LRoute may be started in either of two ways:
- Click on a LRoute's Edit button in the LRoute Table.
- Enter the system name of the LRoute to be edited in the Add/Edit LRoute window and click the Edit LRoute button at the bottom of the Add/Edit LRoute window. This must be the same as the system name shown in the LRoute Table.
The Add LRoute and Edit LRoute buttons in the Add/Edit LRoute window will change to Delete LRoute, Update LRoute and Cancel.
Make whatever changes or additions you need to the information in the dialog. Note that the system name of the edited LRoute may not be changed, but the user name may be changed. Other items are as described above.
After making changes to the LRoute information, click Update LRoute to change the selected LRoute. If everything is fine, a message stating "LRoute 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 LRoute again.
Click Cancel to exit edit mode without changing the selected LRoute. If the Add/Edit LRoute window is dismissed (closed) while in edit mode, Cancel is automatically selected, and no changes are made to the selected LRoute.

To delete the LRoute, press the Delete LRoute button.

LRoute Table controls

Below the LRoute Table you'll find the Add... button to add new LRoutes.

To save LRoutes to disk:

LRoutes 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 LRoute Table (or other tables from the Tools menu), or select Store Panel... in the Panel menu. Note that the enabled/disabled state of each LRoute is not saved in the configuration file. When LRoutes are loaded from a configuration file, they are all enabled.

Controlling LRoutes from Control/Trigger Entities

The operation of an LRoute can be controlled by many means: sensors connected to occupancy detectors or switches on the layout, or lights in the case of C/MRI. Even SignalHead appearances can control the route. The sensors and turnouts can be real or internal entities.

For example, by default when any one of the included sensors goes to the active state, the LRoute will be set. This could be used to set a LRoute when a block became occupied, or when a button was pushed.

Each control Sensor has a "mode" associated with it, which can be:

"On Active": The default method, the LRoute is triggered when the sensor goes active, e.g. "Throw turnout 12 when sensor 12 goes active"
"On Inactive": The LRoute is triggered when the sensor goes inactive. For example, using the LRoute above, plus a second LRoute "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 LRoute is triggered when the sensor state changes, either from active to inactive or from inactive to active.
"Veto When Active": If this sensor is active, the LRoute will not trigger, no matter what states the other control entities change to. This has several uses, e.g. to prevent throwing a turnout under a train when the block shows occupied.
"Veto When Inactive": Like veto active, but the other polarity logic.

Similar to the control sensors discussed above, a control turnout has a "mode" associated with it, which can be:

"On Closed": The default method, the LRoute is triggered when the turnout changes to the closed state.
"On Thrown": The LRoute is triggered when the turnout changes to the thrown state.
"On Change": The LRoute is triggered when the turnout state changes, either from closed to thrown or from thrown to closed.
"Veto When Closed": If this turnout is closed, the LRoute is prevented from triggering.
"Veto When Thrown": If this turnout is thrown, the LRoute is prevented from triggering.

Likewise, Light controls have "modes" which can be:

"On Lit": The default method, the LRoute is triggered when the light changes to the lit state.
"On Not Lit": The LRoute is triggered when the light changes to the unlit state.
"On Change": The LRoute is triggered when the light state changes, either from lit to unlit or from unlit to lit.
"Veto When Lit": If this light is lit, the LRoute is prevented from triggering.
"Veto When Unlit": If this light is not lit, the LRoute is prevented from triggering.

The SignalHead control "modes" differ somewhat from the above. They are:

"On Red": The LRoute is triggered when the signal changes to the Red appearance.
"On Red Flashing": The LRoute is triggered when the signal changes to the Red Flashing appearance.
"On Yellow ": The LRoute is triggered when the signal changes to the Yellow appearance.
"On Yellow Flashing": The LRoute is triggered when the signal changes to the Yellow Flashing appearance.
"On Green ": The LRoute is triggered when the signal changes to the Green appearance.
"On Green Flashing": The LRoute is triggered when the signal changes to the Green Flashing appearance.
"On Lit ": The LRoute is triggered when the signal changes from dark to lit.
"On Held ": The LRoute is triggered when the signal set to Held.
"Veto When Red": The LRoute is prevented from triggering when the signal changes to the Red appearance.
"Veto When Red Flashing": The LRoute is prevented from triggering when the signal changes to the Red Flashing appearance.
"Veto When Yellow ": The LRoute is triggered when the signal changes to the Yellow appearance.
"Veto When Yellow Flashing": The LRoute is prevented from triggering when the signal changes to the Yellow Flashing appearance.
"Veto When Green ": The LRoute is prevented from triggering when the signal changes to the Green appearance.
"Veto When Green Flashing": The LRoute is prevented from triggering when the signal changes to the Green Flashing appearance.
"Veto When Lit ": The LRoute is prevented from triggering when the signal changes from dark to lit.
"Veto When Held ": The LRoute is prevented from triggering when the signal set to Held.

Note that there is an implied "and/or" here. All of the 'veto' sensors, the 'veto' turnouts, 'veto' lights and 'veto' signals must be in their non-veto state and at least one of the triggering entities must experience the appropriate change for the LRoute to be set. A single 'veto' turnout, 'veto' sensor, 'veto' light or 'veto' signal appearance will prevent the LRoute from being triggered. The logical expression defined by the LRoute is that the "non-veto entities are OR'ed together as a clause and the "veto" entities are AND'ed together as a clause. The two clauses are then joined by an AND operator.

Setting Behavior to Match that of Routes

In Routes, the 'veto' entities are passive. That is, although the 'veto' state prevents the Route from triggering, when the 'veto' state is left, it does not trigger the Route. On the other hand, generally a Logix Conditional has all its state variable trigger actions when they change. The radio buttons on the 'LRoute Basics' tab Route Logix Type give either option. If you want the LRoute to perform in this passive manner as a Route does, press the Old button. If you want the LRoute to trigger its actions when all the 'veto's are removed, press the New button.

Common Tools

System-specific Tools

Layout Automation