Serge NOEL
417 lines
19 KiB
Plaintext
417 lines
19 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<title>JMRI: LRoute Documentation</title>
|
|
<meta name="author" content="Pete Cressman">
|
|
<meta name="keywords" content="layout java model railroad JMRI panelpro tools LRoute">
|
|
<!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>JMRI: LRoute Documentation</h1>
|
|
|
|
<h2>What are LRoutes?</h2>
|
|
|
|
<p>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 <a href="Routes.shtml">Route
|
|
documentation</a>.</p>
|
|
|
|
<h2>How LRoutes differ from Routes?</h2>
|
|
|
|
<p>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".</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2>How to set up for adding or editing LRoutes</h2>
|
|
|
|
<p>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 <strong><a href=
|
|
"../../package/jmri/jmrit/beantable/LRouteTable.shtml">LRoute Table</a></strong> from the
|
|
<strong>Tools</strong> menu. If you add or change any entities with the LRoutes table window
|
|
open, you will have to close and reopen it for the list of entities seen by LRoutes to be
|
|
refreshed.</p>
|
|
|
|
<h3 id="addroute">To add a new LRoute:</h3>
|
|
|
|
<p>Click the <strong><a href=
|
|
"../../package/jmri/jmrit/beantable/LRouteAddEdit.shtml">Add...</a></strong> button at the
|
|
bottom of the pane to bring up the Add LRoute pane.</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Enter a system name, such as 'RTX100'. Any short name can be used provided it is
|
|
different from the system name of other LRoutes.</p>
|
|
|
|
<p>By convention, system names usually start with "RTX" for an LRoute.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li>Note the four tabs beneath the menu bar. Select the tab labeled <strong>Actions
|
|
(output)</strong>. This displays a table with all of the Sensors, Turnouts, Lights, and/or
|
|
SignalHeads that the user has defined in their respective tables.</li>
|
|
|
|
<li>
|
|
<p>Select the entities to be included for actions to be taken in the LRoute from the list
|
|
by clicking on the checkbox in the <strong>Include</strong> column. For each included
|
|
item, use the combo box in the <strong>Set Action</strong> 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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Next select the tab labeled <strong>Triggers/Controls (input)</strong>. This also
|
|
displays a table with all the Sensors, Turnouts, Lights and/or SignalHeads that the user
|
|
has defined in their respective tables.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Select the entities to be included to control (i.e. trigger) the LRoute from the list
|
|
by clicking on the checkbox in the <strong>Include</strong> column. For each included
|
|
item, use the combo box in the <strong>Trigger State</strong> 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.</p>
|
|
</li>
|
|
|
|
<li>This tab also has 'All' and 'include' radio buttons that operate in a similar manner as
|
|
the previous tab.</li>
|
|
|
|
<li>
|
|
<p>Next select the tab labeled <strong>Alignment/Locks/etc.</strong>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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 <strong>Set</strong>
|
|
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.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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 <strong>Set</strong> button can be used as
|
|
above to assist in entering script file information.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Checking the check box <strong>Set Locks</strong> 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 <a href=
|
|
"../../package/jmri/jmrit/beantable/RouteAddEdit.shtml#Turnout%20lock%20feature">Turnout
|
|
Lock feature</a> .</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>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'.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Finally, select the tab labeled <strong>LRoute Basics</strong> to return to the first
|
|
tab.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click the <strong>Create</strong> 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 <strong>Add
|
|
LRoute</strong> again.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>To abort adding the LRoute, press the <strong>Cancel</strong> button.</p>
|
|
|
|
<h3>To edit an existing LRoute:</h3>
|
|
|
|
<p><strong>NOTE:</strong> If you have edited the Logix created for a particular existing
|
|
LRoute, or have edited any of the entities used by an LRoute without closing and reopening
|
|
the LRoute table window, you will get an error message when you go to edit that LRoute. This
|
|
can be avoided by closing and reopening the LRoute table window before attempting any
|
|
edits.</p>
|
|
|
|
<ol>
|
|
<li>Edit of an existing LRoute may be started in either of two ways:
|
|
<ul>
|
|
<li>Click on a LRoute's <strong>Edit</strong> button in the LRoute Table.</li>
|
|
|
|
<li>Enter the system name of the LRoute to be edited in the Add/Edit LRoute window and
|
|
click the <strong>Edit LRoute</strong> button at the bottom of the Add/Edit LRoute
|
|
window. This must be the same as the system name shown in the LRoute Table.</li>
|
|
</ul>
|
|
The <strong>Add LRoute</strong> and <strong>Edit LRoute</strong> buttons in the Add/Edit
|
|
LRoute window will change to <strong>Delete LRoute</strong>, <strong>Update
|
|
LRoute</strong> and <strong>Cancel</strong>.
|
|
</li>
|
|
|
|
<li>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 <a href="#addroute">above</a>.
|
|
</li>
|
|
|
|
<li>After making changes to the LRoute information, click <strong>Update LRoute</strong> 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 <strong>Update LRoute</strong> again.</li>
|
|
|
|
<li>Click <strong>Cancel</strong> to exit edit mode without changing the selected LRoute.
|
|
If the Add/Edit LRoute window is dismissed (closed) while in edit mode,
|
|
<strong>Cancel</strong> is automatically selected, and no changes are made to the selected
|
|
LRoute.</li>
|
|
</ol>
|
|
|
|
<p>To delete the LRoute, press the <strong>Delete LRoute</strong> button.</p>
|
|
|
|
<h3>LRoute Table controls</h3>
|
|
|
|
<ul>
|
|
<li>Below the LRoute Table you'll find the <a href=
|
|
"../../package/jmri/jmrit/beantable/LRouteAddEdit.shtml">Add...</a> button to add new
|
|
LRoutes.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>To save LRoutes to disk:</h3>
|
|
|
|
<p>LRoutes are kept in your <em>layout configuration</em>, along with turnouts, sensors,
|
|
signal heads, lights, control panel setup etc. To store this information on disk, see
|
|
<a href="../apps/LoadStoreWork.shtml">Loading and Storing Your Work</a>. 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.</p>
|
|
|
|
<h3 id="sensorlogic">Controlling LRoutes from Control/Trigger Entities</h3>
|
|
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.
|
|
<p>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.</p>
|
|
|
|
<p>Each control Sensor has a "mode" associated with it, which can be:</p>
|
|
|
|
<dl>
|
|
<dt>"On Active"</dt>
|
|
|
|
<dd>The default method, the LRoute is triggered when the sensor goes active, e.g. "Throw
|
|
turnout 12 when sensor 12 goes active"</dd>
|
|
|
|
<dt>"On Inactive"</dt>
|
|
|
|
<dd>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.</dd>
|
|
|
|
<dt>"On Change"</dt>
|
|
|
|
<dd>The LRoute is triggered when the sensor state changes, either from active to inactive
|
|
or from inactive to active.</dd>
|
|
|
|
<dt>"Veto When Active"</dt>
|
|
|
|
<dd>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.</dd>
|
|
|
|
<dt>"Veto When Inactive"</dt>
|
|
|
|
<dd>Like veto active, but the other polarity logic.</dd>
|
|
</dl>
|
|
|
|
<p>Similar to the control sensors discussed above, a control turnout has a "mode" associated
|
|
with it, which can be:</p>
|
|
|
|
<dl>
|
|
<dt>"On Closed"</dt>
|
|
|
|
<dd>The default method, the LRoute is triggered when the turnout changes to the closed
|
|
state.</dd>
|
|
|
|
<dt>"On Thrown"</dt>
|
|
|
|
<dd>The LRoute is triggered when the turnout changes to the thrown state.</dd>
|
|
|
|
<dt>"On Change"</dt>
|
|
|
|
<dd>The LRoute is triggered when the turnout state changes, either from closed to thrown or
|
|
from thrown to closed.</dd>
|
|
|
|
<dt>"Veto When Closed"</dt>
|
|
|
|
<dd>If this turnout is closed, the LRoute is prevented from triggering.</dd>
|
|
|
|
<dt>"Veto When Thrown"</dt>
|
|
|
|
<dd>If this turnout is thrown, the LRoute is prevented from triggering.</dd>
|
|
</dl>
|
|
|
|
<p>Likewise, Light controls have "modes" which can be:</p>
|
|
|
|
<dl>
|
|
<dt>"On Lit"</dt>
|
|
|
|
<dd>The default method, the LRoute is triggered when the light changes to the lit
|
|
state.</dd>
|
|
|
|
<dt>"On Not Lit"</dt>
|
|
|
|
<dd>The LRoute is triggered when the light changes to the unlit state.</dd>
|
|
|
|
<dt>"On Change"</dt>
|
|
|
|
<dd>The LRoute is triggered when the light state changes, either from lit to unlit or from
|
|
unlit to lit.</dd>
|
|
|
|
<dt>"Veto When Lit"</dt>
|
|
|
|
<dd>If this light is lit, the LRoute is prevented from triggering.</dd>
|
|
|
|
<dt>"Veto When Unlit"</dt>
|
|
|
|
<dd>If this light is not lit, the LRoute is prevented from triggering.</dd>
|
|
</dl>
|
|
|
|
<p>The SignalHead control "modes" differ somewhat from the above. They are:</p>
|
|
|
|
<dl>
|
|
<dt>"On Red"</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal changes to the Red appearance.</dd>
|
|
|
|
<dt>"On Red Flashing"</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal changes to the Red Flashing appearance.</dd>
|
|
|
|
<dt>"On Yellow "</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal changes to the Yellow appearance.</dd>
|
|
|
|
<dt>"On Yellow Flashing"</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal changes to the Yellow Flashing appearance.</dd>
|
|
|
|
<dt>"On Green "</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal changes to the Green appearance.</dd>
|
|
|
|
<dt>"On Green Flashing"</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal changes to the Green Flashing appearance.</dd>
|
|
|
|
<dt>"On Lit "</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal changes from dark to lit.</dd>
|
|
|
|
<dt>"On Held "</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal set to Held.</dd>
|
|
|
|
<dt>"Veto When Red"</dt>
|
|
|
|
<dd>The LRoute is prevented from triggering when the signal changes to the Red
|
|
appearance.</dd>
|
|
|
|
<dt>"Veto When Red Flashing"</dt>
|
|
|
|
<dd>The LRoute is prevented from triggering when the signal changes to the Red Flashing
|
|
appearance.</dd>
|
|
|
|
<dt>"Veto When Yellow "</dt>
|
|
|
|
<dd>The LRoute is triggered when the signal changes to the Yellow appearance.</dd>
|
|
|
|
<dt>"Veto When Yellow Flashing"</dt>
|
|
|
|
<dd>The LRoute is prevented from triggering when the signal changes to the Yellow Flashing
|
|
appearance.</dd>
|
|
|
|
<dt>"Veto When Green "</dt>
|
|
|
|
<dd>The LRoute is prevented from triggering when the signal changes to the Green
|
|
appearance.</dd>
|
|
|
|
<dt>"Veto When Green Flashing"</dt>
|
|
|
|
<dd>The LRoute is prevented from triggering when the signal changes to the Green Flashing
|
|
appearance.</dd>
|
|
|
|
<dt>"Veto When Lit "</dt>
|
|
|
|
<dd>The LRoute is prevented from triggering when the signal changes from dark to lit.</dd>
|
|
|
|
<dt>"Veto When Held "</dt>
|
|
|
|
<dd>The LRoute is prevented from triggering when the signal set to Held.</dd>
|
|
</dl>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2 id="setroutebehavior">Setting Behavior to Match that of Routes</h2>
|
|
|
|
<p>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 <strong>Route Logix Type</strong>
|
|
give either option. If you want the LRoute to perform in this passive manner as a Route does,
|
|
press the <strong>Old</strong> button. If you want the LRoute to trigger its actions when all
|
|
the 'veto's are removed, press the <strong>New</strong> button.</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|