Serge NOEL
485 lines
21 KiB
Plaintext
485 lines
21 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<title>YAAT</title><!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
|
|
<style type="text/css">
|
|
dt {padding-top: 10px;}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<div id="mainContent" class="no-sidebar">
|
|
<h1>YetAnotherAutoTrain.py -- Data driven automatic trains</h1>
|
|
|
|
<p>Jython (Java based Python) scripting is a common tool for running trains automatically.
|
|
The Python language is relatively easy to use and provides easy access to JMRI facilities,
|
|
such as turnouts, sensors, blocks, etc. Access to JMRI throttles provides the ability to
|
|
control locomotives.</p>
|
|
|
|
<p>The typical script sets turnouts, acquires a locomotive, runs the locomotive while keeping
|
|
track of its location. Some scripts use occupancy sensors for the location, others rely on
|
|
time durations.</p>
|
|
|
|
<p>Frequently the original script needs modifications as additional details are added. When a
|
|
second train is added which has to share track with the first one, the script becomes ever
|
|
more complicated.</p>
|
|
|
|
<p>YAAT is designed to eliminate the programming by using text files that contain English
|
|
like phrases. For example:</p>
|
|
|
|
<pre>
|
|
sensor = sensors.getSensor('S-Sensor')
|
|
If sensor is not None:
|
|
sensor.setKnownState(ACTIVE)
|
|
</pre>vs.
|
|
|
|
<pre>
|
|
Set sensor S-Sensor active
|
|
</pre>
|
|
<p>Each train has its own text file, but they can coordinate actions by using JMRI sensors,
|
|
etc.</p>
|
|
|
|
<p class="noted">Note: The JMRI <strong><em>preference:</em></strong> keyword refers to the
|
|
user files location. See <strong>Help ⇒ File Locations</strong> to see the current path
|
|
for the user files location.</p>
|
|
|
|
<h2>Using YAAT</h2>
|
|
|
|
<p>YAAT works by referencing JMRI objects, such as turnouts, sensors, etc. This means that
|
|
the layout definition needs to accurately describe the layout that will run the trains that
|
|
YAAT will be controlling.</p>
|
|
|
|
<p>Some of the YAAT actions have specific requirements. The signal head and signal mast
|
|
actions are obvious. The block actions need to have blocks assigned to Layout Editor track
|
|
components, such as track segments and turnouts.</p>
|
|
|
|
<p>Since the <strong>YetAnotherAutoTrain.py</strong> script needs to be modified, the script
|
|
should be copied from the JMRI install location to the user files location. See <strong>Help
|
|
⇒ File Locations</strong>.</p>
|
|
|
|
<div class="noted">
|
|
<h3>YAAT 3.0 — YetAnotherAutoTrain3.py</h3>
|
|
|
|
<p>The process for managing train definitions has been changed so that the script does not
|
|
need to be manually changed. The script can be run from the standard JMRI install location.</p>
|
|
|
|
<p>The script options are stored in the <strong>preference:yaat/config.txt</strong> file. If
|
|
the file does not exist, a file will be created with a default set of options.</p>
|
|
|
|
<p>The train definition text files are also stored in the <strong>preference:/yaat</strong>
|
|
directory.</p>
|
|
|
|
<p>When the script is started, the train text file names listed in the
|
|
<strong>preference:/yaat/LoadTrains.txt</strong> file will be loaded. Each line in the file
|
|
is a single file name, such as <strong>Back and Forth.txt</strong>. Train file names not
|
|
listed in the <strong>LoadTrains.txt</strong> can be loaded on demand using the memory
|
|
variable specified by the <strong>yaatMemory</strong> option.</p>
|
|
|
|
<p>The support for embedded train definitions has been removed.</p>
|
|
|
|
<p>The support for custom extensions has been removed.</p>
|
|
|
|
<p>The detail comments in the script have been removed. The script was approaching the JMRI
|
|
limit on script file size. The content was previously moved to this help page.</p>
|
|
|
|
</div>
|
|
|
|
<h3>Global Settings</h3>
|
|
|
|
<dl>
|
|
<dt>logLevel</dt>
|
|
|
|
<dd>YAAT sends logging information to either the JMRI system console or the script monitor
|
|
located at <strong>Scripting</strong> {<em>Old: <strong>Panels</strong></em>} <strong>⇒
|
|
Script Output</strong>. Zero is no logging, 4 provides the maximum detail.</dd>
|
|
|
|
<dt>statusSensor</dt>
|
|
|
|
<dd>Optional. Provide feedback to JMRI indicating that one or more train threads are
|
|
running.</dd>
|
|
|
|
<dt>masterSensor</dt>
|
|
|
|
<dd>Optional. If this sensor becomes active, YAAT will terminate all of the train threads.
|
|
NOTE: Trains might keep running at their last speed.</dd>
|
|
|
|
<dt>saveYAATcompiles</dt>
|
|
|
|
<dd>
|
|
If set to True, the train compiles will be retained. See <a href="#CompTrains">Compiled
|
|
Trains</a>.
|
|
</dd>
|
|
|
|
<dt>yaatMemory<span class="since">since YAAT 3.0</span></dt>
|
|
|
|
<dd>
|
|
Optional memory variable that contains a filename for starting a train. This makes it
|
|
possible to start a train using Logix, LogixNG, scripting or even a YAAT train using
|
|
the <strong><em>Set <memory name> to <value></em></strong> YAAT action.
|
|
</dd>
|
|
|
|
<dt>enableIncludes<span class="since">since YAAT 3.4</span></dt>
|
|
|
|
<dd>
|
|
Set to True to enable the <em>@include filename</em> statement. See <a href="#includes">Includes</a>.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3>Trains</h3>
|
|
|
|
<p class="noted">The following applies to YAAT 2.3 and below. See above for YAAT 3 changes.</p>
|
|
<p>Each train needs a set of actions. The orignal design had the actions included in the
|
|
script file. That feature will be removed in a future release.</p>
|
|
|
|
<p>Define actions:</p>
|
|
|
|
<dl>
|
|
<dt>External File</dt>
|
|
|
|
<dd>Create a text file with one action per line. Blank lines and lines starting with a
|
|
comment character, #, are ok. Add the train name and file name to the
|
|
<strong>trainList</strong>. The file name can be the complete path or the file name can
|
|
include a keyword for the location, such as "preference:" which is replaced by the path to
|
|
the user files location at run time.</dd>
|
|
|
|
<dt>File of files</dt>
|
|
|
|
<dd>In addition to modifying the script's trainList, it is possible to create a text file
|
|
that has the same format as the <strong>trainList</strong>. If the file exists, its
|
|
contents will be added to the <strong>trainList</strong>. The file is located in the
|
|
<strong>yaat</strong> directory in the user files location. The filename is
|
|
<strong>TrainList.txt</strong>. This file is optional.</dd>
|
|
|
|
<dt>Embedded</dt>
|
|
|
|
<dd>The actions are added to a Python list. Each action is enclosed in single or double
|
|
quotes and end with a comma at the end of the line. The embedded method requires a unique
|
|
block of code at the end of the script for each embedded action list. <em>Note: This method
|
|
will be removed in a future release. It requires too much manual code
|
|
modification.</em></dd>
|
|
</dl>
|
|
|
|
<h2>Action Phrases</h2>
|
|
|
|
<p>The following descriptions used the following formatting:</p>
|
|
|
|
<ul>
|
|
<li><?? | ??> — List of choices</li>
|
|
|
|
<li><????> — Required values, usually names or numbers</li>
|
|
|
|
<li>Brackets, [], are optional phrases</li>
|
|
|
|
<li>Text and names are case sensitive</li>
|
|
</ul>
|
|
|
|
<h3>Standard Actions</h3>
|
|
|
|
<dl>
|
|
<dt>Assign <long | short> address <dccaddr>[ as <train name>[ in
|
|
<block name>]]</dt>
|
|
|
|
<dd>Create a JMRI throttle using the DCC address. If a block name is supplied, the
|
|
optional train name will be used for block tracking.</dd>
|
|
|
|
<dt>Halt<span class="since">since YAAT 3.0</span></dt>
|
|
|
|
<dd>Do an unconditional stop of the train. Prior to doing the <strong>Halt</strong> action,
|
|
the throttle speed should be set to zero and the throttle should be released. This is
|
|
generally used when starting another train using the <strong>Set memory</strong> action.</dd>
|
|
|
|
<dt>Hold signal head <name><span class="since">since YAAT 3.2</span></dt>
|
|
|
|
<dd>Enable the <strong>Held</strong> state for the signal head table entry.</dd>
|
|
|
|
<dt>Hold signal mast <name><span class="since">since YAAT 3.2</span></dt>
|
|
|
|
<dd>Enable the <strong>Held</strong> state for the signal mast table entry.</dd>
|
|
|
|
<dt>Loop</dt>
|
|
|
|
<dd>Marks the end of the one time start up actions, such as the throttle assignment,
|
|
positioning a train before starting repeating actions, etc.</dd>
|
|
|
|
<dt>Print <message text></dt>
|
|
|
|
<dd>Display a message in the script output window or the system console log. Useful for
|
|
debugging.</dd>
|
|
|
|
<dt>Release signal head <name><span class="since">since YAAT 3.2</span></dt>
|
|
|
|
<dd>Disable the <strong>Held</strong> state for the signal head table entry.</dd>
|
|
|
|
<dt>Release signal mast <name><span class="since">since YAAT 3.2</span></dt>
|
|
|
|
<dd>Disable the <strong>Held</strong> state for the signal mast table entry.</dd>
|
|
|
|
<dt>Release throttle<span class="since">since YAAT 3.0</span></dt>
|
|
|
|
<dd>Normally the throttle is released by the Stop action. This action can be used when
|
|
preparing to chain train definitions.</dd>
|
|
|
|
<dt>Repeat if sensor <sensor name> is <active | inactive></dt>
|
|
|
|
<dd>Skip the remaining steps and start over. Use the same sensor as Stop with the opposite
|
|
test. This provides a cleanup section before Stop. Requires that a "Loop" action was
|
|
included in the action list.</dd>
|
|
|
|
<dt>Set block <block name> <occupied | unoccupied | reserved | free></dt>
|
|
|
|
<dd>The occupied and unoccupied states are used to simulate train movement. It works best
|
|
if a simulation sensor is used in conjunction with an If statement. Reserved and free
|
|
control the alternate track color.</dd>
|
|
|
|
<dt>Set direction to <forward | reverse></dt>
|
|
|
|
<dt>Set function key <0 to 68> <on | off>[, wait <n> seconds]</dt>
|
|
|
|
<dd>Set the function key on or off. The number can be from 0 to 68. If seconds is greater
|
|
than zero, the opposite action will be performed after the number of seconds has
|
|
passed.</dd>
|
|
|
|
<dt>Set memory <memory name> to <value><span class="since">since YAAT 3.0</span></dt>
|
|
|
|
<dd>Set the memory value to a constant. By setting the memory variable to a YAAT train
|
|
definition, it is possible to chain YAAT trains.</dd>
|
|
|
|
<dt>Set route <route name></dt>
|
|
|
|
<dt>Set sensor <sensor name> <active | inactive></dt>
|
|
|
|
<dd>Can be used to pass status to other trains.</dd>
|
|
|
|
<dt>Set speed to <0 to 1.0></dt>
|
|
|
|
<dt>Set turnout <turnout name> <closed | thrown>[, wait <n> seconds]</dt>
|
|
|
|
<dd>The process will wait for up to 5 seconds for turnout feedback. If seconds is entered
|
|
and greater than zero, a wait allows the turnout command to complete, capacitors to
|
|
recharge, etc.</dd>
|
|
|
|
<dt>Set turntable <turntable name> on panel <panel name> to ray <#>
|
|
<span class="since">since YAAT 2.3</span></dt>
|
|
|
|
<dd>Set the turntable position to the ray index using the <code>setPosition(int)</code>
|
|
method. The turntable name is the internal name on the layout editor panel, such as
|
|
<code>TUR1</code>. The panel name is the panel's title. The time required to move the
|
|
turntable bridge is variable. The following statement should be a <strong><em>wait for n
|
|
seconds</em></strong> or a <strong><em>wait for sensor active</em></strong> if a turntable
|
|
position sensor is available for each ray.</dd>
|
|
|
|
<dt>Start when sensor <sensor name> is <active | inactive></dt>
|
|
|
|
<dd>An optional action that defers running the train until the condition has been
|
|
satisfied. This can also be used to pause a train between runs.</dd>
|
|
|
|
<dt>Stop if sensor <sensor name> is <active | inactive></dt>
|
|
|
|
<dd>This action needs to be the last one in the list. If the sensor state matches, the
|
|
throttle will be released and the script stopped. If it does not, the script will do the
|
|
sequence of actions again. If the Stop action is missing, the script will run forever,
|
|
until the script thread is killed, or JMRI is stopped.</dd>
|
|
|
|
<dt>Wait for <n> [to <n>] seconds</dt>
|
|
|
|
<dd>Wait until the time has expired. Normally used for station stops.</dd>
|
|
|
|
<dd>The optional second number is used to provide a random wait time between the two
|
|
values.<span class="since">since YAAT 3.1</span></dd>
|
|
|
|
<dt>Wait for block <block name> to become <occupied | unoccupied | reserved |
|
|
free></dt>
|
|
|
|
<dt>Wait for memory <memory name> value to change<span class="since">since 5.11.7</span></dt>
|
|
|
|
<dt>Wait for sensor <sensor name> to become <active | inactive></dt>
|
|
|
|
<dt>Wait for signal head <head name> to [not] show <appearance name> [or
|
|
...]</dt>
|
|
|
|
<dd>The appearance names are language specific. Use the signal head table to get the
|
|
available appearance names.</dd>
|
|
|
|
<dt>Wait for signal mast <mast name> to [not] display <aspect name> [or
|
|
...]</dt>
|
|
|
|
<dd>Use the signal mast table to get the valid aspect names. Remember that the names vary
|
|
based on signal mast type.</dd>
|
|
|
|
<dt>Wait while signal mast <mast name> speed is less than <aspect name>
|
|
speed</dt>
|
|
|
|
<dd>Use the signal mast table to get the valid aspect names. Remember that the names vary
|
|
based on signal mast type.</dd>
|
|
</dl>
|
|
|
|
<h3>If/Else/Endif Actions</h3>
|
|
|
|
<p>The <strong><em>If</em></strong> and <strong><em>Endif</em></strong> actions are required.
|
|
The <strong><em>Else</em></strong> action is optional and is used to separate the true and
|
|
false actions. Nesting is supported.</p>
|
|
|
|
<dl>
|
|
<dt>If block <block name> is <occupied | unoccupied | reserved | free></dt>
|
|
|
|
<dt>If sensor <sensor name> is <active | inactive></dt>
|
|
|
|
<dt>If signal head <head name> does [not] show <appearance> [or ...]</dt>
|
|
|
|
<dt>If signal mast <mast name> does [not] display <aspect> [or ...]</dt>
|
|
|
|
<dt>If speed for signal mast <mast name> is <eq | ne | lt | gt | le | ge>
|
|
<speed name></dt>
|
|
|
|
<dd>For information on speed names, look at the JMRI install location:
|
|
xml/signals/signalSpeeds.xml</dd>
|
|
|
|
<dt>If value for memory <memory name> is <eq | ne | lt | gt | le | ge> <value>
|
|
<span class="since">since 5.11.7</span></dt>
|
|
|
|
<dt>Else</dt>
|
|
|
|
<dt>Endif</dt>
|
|
</dl>
|
|
|
|
<h3>GoSub/Sub/EndSub Actions</h3>
|
|
|
|
<p>The sub routines are placed at the end of an embedded list or text file. The sub routines
|
|
cannot be nested, but a sub routine can call another sub routine. The sub routine name cannot
|
|
have spaces. Control returns to the statement after the CallSub when the sub routine is
|
|
finished.</p>
|
|
|
|
<dl>
|
|
<dt>CallSub <subname></dt>
|
|
|
|
<dt>Sub <subname></dt>
|
|
|
|
<dt>EndSub <subname></dt>
|
|
</dl>
|
|
|
|
<h3>Dispatcher Support (Created by Bill Fitch)</h3>
|
|
|
|
<dl>
|
|
<dt>Dispatch using file <traininfo.xml>[, type <USER, value <dccAddress> |
|
|
ROSTER, value <roster entry name> | OPERATIONS, value <train name>>]</dt>
|
|
|
|
<dd>
|
|
The Dispatcher train info filename is required. The optional USER, ROSTER and OPERATIONS
|
|
keywords can override the train info content. Examples:
|
|
<ul>
|
|
<li>Dispatch using file routefrom1-2.xml (uses the train info xml file set up by "Save
|
|
Train info" in "Create New Train" in dispatcher)</li>
|
|
|
|
<li>Dispatch using file routefrom1-2.xml, type USER, value 3 (uses train with dcc
|
|
address 3 instead of the train in the xml file</li>
|
|
|
|
<li>Dispatch using file routefrom1-2.xml, type ROSTER, value diesel104 (uses diesel104
|
|
from roster instead of the train in the xml file)</li>
|
|
</ul>
|
|
The <traininfo.xml> file will have been generated by dispatcher prior to running
|
|
YAAT and will have been placed in preference:dispatcher/traininfo by dispatcher. Note:
|
|
"preference:" is the keyword for the user files location.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2>YAAT Demo</h2>
|
|
|
|
<p>A demonstration system is available at <a href="YAAT.jmri.zip">YAAT Demo</a>. The zip file
|
|
is a JMRI profile. After expanding the zip file, place the <strong>YAAT.jmri</strong>
|
|
directory next to the other profiles and it should show up in the profile list. The demo
|
|
panel is based on JMRI 4.20.</p>
|
|
|
|
<p>A second demonstration system which includes an example for turntable control and
|
|
linking trains is available at <a href="YAAT3.jmri.zip">YAAT3 Demo</a>. The zip file
|
|
is a JMRI profile. After expanding the zip file, place the <strong>YAAT3.jmri</strong>
|
|
directory next to the other profiles and it should show up in the profile list. The
|
|
demo panel is based on JMRI 5.3.7.</p>
|
|
|
|
<h3>Running the demo</h3>
|
|
|
|
<p>After starting <strong>PanelPro</strong>, click on the <strong>Open Panel File</strong>
|
|
button and select <strong>yaat demo.xml</strong>.</p>
|
|
|
|
<div style="margin-left: 2em">
|
|
<a href="images/yaat_demo.png"><img src="images/yaat_demo.png" alt="YAAT demo" height="576"
|
|
width="1023"></a>
|
|
</div>
|
|
|
|
<p>Click on the <strong>Load YAAT</strong> button to start the process. After several seconds
|
|
the button label will change to <strong>Running</strong>. Click on the
|
|
<strong>Paused</strong> button to start a train. The button label will change to
|
|
<strong>Run</strong>. Clicking again will pause the train when it finishes a loop. Click on
|
|
<strong>Stop</strong> to terminate the train and remove it from the system.</p>
|
|
|
|
<p>The <strong>Stop Threads</strong> button will terminate all trains immediately. Active
|
|
trains might continue running at the last throttle setting.</p>
|
|
|
|
<h2>Advanced Features</h2>
|
|
|
|
<h3 id="CompTrains">Compiled Trains</h3>
|
|
|
|
<p>The standard YAAT process compiles each train from its text file. The result of the compile
|
|
process is a set of tokens that are interpreted while the train is running. The duration of
|
|
the compile step depends on the number of trains and the number of actions.</p>
|
|
|
|
<p>If the <strong>saveYAATcompiles</strong> option is true, a compiled train will be used
|
|
instead of doing the compile step.</p>
|
|
|
|
<p>A compiled train is located in the <strong>preference:yaatp/<trainname></strong>
|
|
directory. When YAAT is started, the date/time for each train source file is checked when it
|
|
is loaded. If it is greater than the compiled train, if any, the compile will occur. Otherwise
|
|
the compiled version will be loaded.</p>
|
|
|
|
<h3 id="includes">Includes<span class="since">since YAAT 3.4</span></h3>
|
|
|
|
<p>The <strong>Includes</strong> feature inserts blocks of YAAT code while a program file is
|
|
being loaded. This is enabled by setting <strong>enableIncludes</strong> to <strong>True</strong>
|
|
in the <strong>config.txt</strong> global settings file. The included files are located in
|
|
the <strong>includes</strong> sub-directory within the <strong>yaat</strong> directory. The
|
|
<strong>@include some file name.txt</strong> line is replaced by the YAAT text located in the
|
|
indicated file name. The included file cannot have includes.</p>
|
|
|
|
<p>Here is an example.</p>
|
|
<pre>
|
|
# Move 2019 from SCS 1A to SCS 1
|
|
|
|
Assign long address 2019 as 2019 in SCS-1A
|
|
Set direction to forward
|
|
|
|
@include SCS1A-SCS1.txt
|
|
|
|
Set sensor 2019-SCS1A-SCS1 inactive
|
|
Release throttle
|
|
Halt
|
|
|
|
@include _sub_SCS-Turnout-Locks.txt
|
|
@include _sub_SCS-Signals.txt
|
|
@include _sub_SCS-XO-Locks.txt
|
|
</pre>
|
|
|
|
<h3>Custom Extensions</h3>
|
|
|
|
<p class="noted">This feature has been removed from YAAT 3.0.</p>
|
|
|
|
<p>An extension is a separate Python file that contains additional actions.</p>
|
|
|
|
<p>Each action requires a <strong>do<name></strong> method (def) and a
|
|
<strong>compile<name></strong> method (def). The format of an action name is
|
|
<strong>verb_noun</strong>, such as <strong>Set_memory...</strong> The typical space for
|
|
built-in actions is replaced with an underscore.</p>
|
|
|
|
<p>The custom actions are added to the <strong>customExtensions</strong> dictionary. The key
|
|
is the file name and the data is a list of actions.</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|