Creating and Editing Warrants
A Warrant contains the information needed to run a train. This includes the DCC address of
the locomotive or consist, the turnout settings of the paths through the blocks of the route
and the throttle commands to use at various points along the route. Among these are speed
changes, when to show lights, sound horns, bells or other sound effects. For an overview
discussion of Warrants, see
Warrants.
NOTE: Warrants can only be created if the PanelPro configuration has at
least two OBlocks defined.
There are three steps in creating a Warrant:
- Define the route
- Select a train, and
- Record the throttle commands.
When a Create Warrant menu is selected, a window to define the warrant is
displayed. At the top, you may enter a System Name and a User Name. After the warrant is
saved by pressing the Save button at the bottom of the window, the System
name cannot be changed. The User Name may be changed anytime the warrant is edited.
Defining a Warrant Route
Routes are created using the
Define Route tab in the Edit Warrant pane.
Origin, Destination, Via and Avoid Blocks
The
Origin Block is where a train given this route will start and the
starting path within the origin block is the track it is on - e.g. a path named "Departure
Track #3" in block named "Main Terminal". Choosing the portal of the path, e.g. portal "West
Approach to #3" where the train should exit the origin block determines the direction of the
train on the route. A computer algorithm will find portals, paths and blocks needed to take
the train to the Destination Block and path - e.g. "Arrival Track #1" in the destination
block.
After selecting the block and path where the train will begin its trip and the portal by
which it should leave and similarly the block, path and entry portal where the train should
end its trip, pressing the Calculate Route button will determine all the
intermediate paths needed to make the trip.
Note: The right hand portion of the Create Warrant window is a table
listing all the OBlocks you have defined. Either the System Name or the User Name of a
Block can be dragged and dropped into the Location Block fields on the left hand side of
the pane. Alternatively, you can mouse click on an Indicator Track icon of the block in the
layout diagram and it will be selected for the location.
-
Originating Location: - Consists of a text field for the originating
Block Name, a drop down menu to choose the starting Path
Name and a drop down menu to select the Exit Portal Name.
The block may have several paths and the default path showing may not be the one where
you intend the train to start. Also, Since paths usually have two portals, the exit
portal showing may not be the one the train should pass through when leaving the origin
block.
Setting the Exit Portal determines the direction the train will take. There is no further
need to specify direction, since the algorithm will only provide routes that leave in
that direction.
-
Destination Location: - Consists of a text field for the destination
Block Name and a drop down menu for the terminating Path
Name and a drop down menu to select the Entry Portal Name.
As above the block may have several paths and the path where you intend the train to
finish its run needs to be specified. It is important to specify the Entry portal for
the destination. This is needed when the layout has reversing loops allowing the path
to be entered from either end.
A common mistake where no route will be found is to specify an Entry
Portal or Path that cannot be reached by the direction taken
when leaving the origin OBlock.
Note: when a Path is chosen, only the Portals of that Path are shown
in the Exit or Entry Portal drop down menus. Thus, even though the block may have many
Portals, you will only see at most two portals.
- Via Location: - Consists of a text field for a Block
Name and a drop down menu for the Path Name where you want the
route to pass through.
Typically, it is not necessary to enter any block name in this field, since it is likely
the algorithm will detect the route you want. This entry is used when there are many routes
possible from origin to destination and you want only to consider routes passing through a
particular path on this block.
- Avoid Location: - Consists of a text field for a Block
Name and a drop down menu for the Path Name that you do not want
the route to use.
This entry is used when there are many routes possible from origin to destination and you
want only to consider routes that do not pass through a particular path on this block.
- More information about OBlocks,
Portals and OPaths can be found at The Occupancy Block Tables.
Calculate and Debug
After the origin and destination blocks and paths have been chosen, press the
Calculate Route button. The "Searching for Route" text box will show
some statistics on the number of routes and their length in blocks that have been found
while searching for routes. The text field "Max Number of Blocks in Route" limits how far
the computer will look routes. The Stop button will terminate the search
for routes.
After the Stop button is pressed or the computer exhausts all the possible routes less
than or equal the "max length", it presents a list of the routes that it found and their
lengths. Choose a route by pressing its radio button. Pressing the
Review button will display the route for you to examine in a Train Route
Table. Each block, its path and portals used to traverse the route is displayed. Also you
can view the route on the PanelPro layout diagram if the track icons are Indicator
Track, icons.

You may inspect all the routes in this manner. Choosing a route and pressing the
Select button will dismiss the dialog. and bring up the
Record/Playback Script tab. If exactly one route is found, the list
dialog is skipped.
Frequently, more than one route will be found and the list may be quite long -
especially when the route is a repeating loop. If the list is too lengthy, there are
several ways you can restrict the number of routes found.
- Specify a maximum number of blocks to use in a route by entering a smaller number
in the Max Number of Blocks in Route box. The computer will only list
routes with this number or fewer blocks
- Specify an intermediate Via Location block and path that must be
included in the route. The computer will calculate the route with this "must include"
restriction and present you only with routes through the specified "Via" block and
path.
- Specify an Avoid Location block and path that must not be in the
route. The computer will not list any routes containing this "must avoid" block and
path
Sometimes the dialog message "No Route found from "Origin Block', path ..." etc. is
displayed. Responding Yes to the question, "Show the search tree?" will
open a window with a graphic description of all paths beginning at the Origin block, path
and exit portal. Trace what you believe to be a likely route by clicking on the nodes.
Each node is a block path and will display its path and block name and the entry and exit
portals it uses. At the end of each branch, the leaf node will be the point where the
route could not continue. Normally these leaves are spurs. However, these are also the
places where you may find an error or omission that you made when defining the OBlocks,
OPaths and Portals. As you trace the attempted routes you may find that you have
forgotten to enter a path or mis-labeled the correct portal to a path. A common
mistake is to incorrectly specify the path or portal that must be used to leave the
starting block or to enter the destination block.
Another possible reason is the search depth was reached before the route can be
completed. In this case, increase the maximum number of blocks to use in a route by
entering a larger number in the Max Number of Blocks in Route box.
Creating the Throttle Command Script
When you are satisfied with the route and have selected it, the
Record/Playback
Script tab will be displayed for you:

The route is shown in a table. For each OBlock. the entry portal, path and exit portal are
displayed.
The bottom half displays six outlined areas; Choose Engine Consist,
Select Type, Settings, Learn mode,
Run Parameters, and Test Run Train. More about the use of
these areas will be discussed below.
The first thing to do is to choose an engine to power your train.
Choosing a Train
The
Train Name field is used to provide a name that can be displayed by an
indicator track icon as the train travels along the warrant route. If you have defined an
JMRI engine roster, the train names are displayed in the
Engine Roster drop
down ComboBox. Selecting a name from this list will fill in the
Address text
field and assigns the engine to power the warrant.
Alternatively a DCC address can be typed into the Address text field and
it will be used whether or not it is found in the JMRI Engine Roster. Chose or enter the
address of the train positioned on the "Origin" block of the route.
Learn Mode
Throttle commands are created by recording the commands you send to a train while operating
it manually from a throttle in
Learn Mode. The
Prototypical
button must be chosen from the
Warrant Types box.
Learn Mode Throttle
If a train has been assigned, that is, has a valid DCC address in the warrant, then a
throttle can be acquired by pressing the
Start button. A screen throttle
will be displayed. This throttle will operate the acquired train and all the throttle
commands will be recorded until the
Stop button is pressed. It can be
inconvenient to use the computer screen Learn Mode throttle. Under LocoNet a handheld
throttle may "steal" the screen throttle address and its commands will be recorded. For all
other systems a walkaround WiFi throttle can be used to "steal" and record commands. Whatever
throttle is used, start and stop the recording with the buttons in the
Learn
Mode box.
Be sure that the train is located on the path of the Origin block of the route and note
the direction of you intend the train to take. If needed, the first command you make on the
learn throttle should be the engine direction toward the exit portal of the Origin block.
The learn script should be done with a completely clear route - All turnouts should be set
for the route, all blocks unoccupied (except the origin), all signals should be set for clear
running and no changes made during the recording period. The recorded speeds and elapsed
times should be for unrestricted "Normal" speeds. Once the Start button is
pressed and recording has begun, the Route Pane is replaced by the Throttle Commands
Pane.

In normal operation, when the script is played back, the train will follow the commands as
recorded. However if a track condition ahead of it is detected that requires a speed change,
the warrant will modify the recorded speed accordingly. When the warrant makes such a speed
change it "ramps" the change in small steps to give a more prototypical smooth look to the
change. When decreasing speed it calculates and issues these step-wise speed changes so that
the required speed is achieved just at the point where the speed limit must be enforced. When
increasing speed it begins a similar "ramp up" when entering the block permitting the speed
increase. Warrant Speed Changes has details about how
warrants modify recorded speeds.
Note: The train should not be moving when the
recording is stopped. When play back of the warrant ends, the train might continue to run
without a warrant to control it! After recording a script, check the ending throttle
commands to see that the speed is set to 0.0
When the route has been traversed and all throttle commands are done, recording is
completed by pressing the Stop button. After this, the throttle commands can
be edited and additional run parameters set.
What the Warrant Does on Playback.
The script records the elapsed times traversing each occupancy block and knows when to expect
the train to enter each block.
The throttle commands of the next block will be delayed until the train enters the block.
That is, the elapsed time of the NoOp command must be reached before any more commands are
issued to the running train. This will be the case if the train is late in arriving at the
block. On the other hand if the train arrives earlier than expected the remaining commands of
the preceding block are executed in fractions of a second to catch up.
The warrant sends commands to the addressed engine in the order they were recorded with
the same number of elapsed milliseconds between them. In spite of an exact repeat of the
recorded throttle settings, the track speed and position of the train may not be at the same
place as they were when it was recorded. Changing the consist of the train or even a
temperature change between recording and playback, may result in the train not performing a
throttle command at exactly the same place on the on the route where it was recorded.
If a more precise way is needed to have a script event occur at a particular location, see
the section Triggering External Events From Scripts below.
Editing and Running the Warrant Script
Warrant scripts can be tested and modified prior to saving them.
Test Running
After a script is recorded, reset the train to the Origin block and press the
AutoRun button in the Test Run Train box. This sends the
throttle commands to the train specified in the warrant.
The Test Run Train box has four radio buttons to control the train and
override the Throttle commands.
- Halt Stop the train.
- Resume Ramp the speed up to its previous speed.
- Emergency Stop Issue an Emergency Stop to the train.
- Abort Stop the train and null the warrant.
Name and save the warrant when you are satisfied by its performance by pressing the
Save button. This adds the warrant to the Warrant Table and closes the Create/Edit Warrant window.
Run Parameters
This area has check boxes to modify how the train will operate when running the Warrant for a
particular instance.
- Clearance to Share Route - Normally a track warrant assigns exclusive
rights to only one train. This option allows several trains to share rights to a route,
such as train sections following one another. Multiple "shared warrants" are still subject
to ramping speed changes due to signals or rogue occupancy.
- Add Tracker after run completes - Upon completion of the warrant
script, the movement of the train by a manual operator can be tracked.
- Don't Ramp Speed Changes - Suppress the ramping calculations. Instead,
the Warrant makes immediate speed change upon entering the approach block to the block
requiring a speed change. since 4.5.7
- Use Elapsed Time Only - Do not use block detection. Using this
option allows Warrants to be run on layouts without block detection.
Using the "Don't Ramp" or "Elapsed Time" options are the only cases where block path lengths
and engine speed factors are
not necessary.
Changing Engine Consist
The warrant can be edited to use a different engine. A different engine may have different
speed characteristics. If the engine has a Speed Profile, it can be viewed.
The View Speed Profile button displays a table of the track speeds
corresponding to the throttle settings for the addressed locomotive or consist. The speed
units can be changed to scale speed.
Note: A value of "0.000" does not mean zero speed. It
means there is no track speed for that throttle setting.
Editing the Throttle Command Table
The Throttle Command Table has the following columns:
- ET (msec): - The elapsed time in milliseconds to wait before issuing
the throttle command.
- Command: - The throttle command that was recorded (direction, speed,
or button press or release). The command can be edited by choosing an item from the drop
down combo box.
- Value: - The value of the command. Chose a value from the drop down
combo box. the choices are dependent on the command being edited.
- Block or Sensor Name: - The block the train occupied when the throttle
command was recorded. If the command being edited is Set Sensor or
Wait Sensor then the name of the sensor should be entered. If the command
is Run Warrant then the name of the warrant should be entered
- Track or Scale Speed - The track speed of the warranted train
calculated from the throttle setting and the Speed Profile of engine consist.
The recorded throttle commands execute according to the elapsed time between commands. The
entry into each block is recorded with a "NoOp" marker. These markers are used to synchronize
the elapsed time of the automatic running of the train when it enters a block. This reset is
done so events recorded in the block occur according to the elapsed time in the block.
Editing Recorded Throttle Commands
Most of the columns in the Throttle Command Table can be edited. Perhaps you want to touch up
the timing for the horn blasts or modify the speeds. Just enter the data you want. Other
values in the Throttle Command Table are changed by selecting an item from the cell's drop
down combo box.
Rows may be inserted or deleted from the table using the Insert and
Delete buttons to the right of the table. Note that an inserted row has 0
elapsed time from the previous command so you may want to adjust this by taking time away
from either the previous row or the following row and entering it into the inserted row.
Also, when a row is deleted, its elapsed time is added to the time of the following row.
These default elapsed times for inserting and deleting rows are entered to keep the total
elapsed time in the block constant.
Some caution should be taken to only make modest changes since new commands when executed
in playback could cause dramatic events. It may be wiser to re-record the commands in a new
Learn Mode session if major changes are made.
Track Speeds
Recording the track speeds in the
Speed column was added in
Release
4.9.2. On playback, if possible, the warrant uses track speed to make the throttle
setting. For this to be done, a speed profile is needed for the locomotive/consist running
the warrant. The feature helps compensate for changes in the size of the train or different
address of the power, by attempting to produce the same track speed. Lacking a speed profile,
the recorded throttle setting is used. In
Release 4.9.4 the scripted throttle
setting is not modified by the track speed. (i.e. the above is a 4.9.2 feature only)
On the right of the Throttle Command table is a button labeled Track
Speed or Scale speed. Pressing the button will display the last
column of the Throttle Command table (estimated layout speed of throttle setting) in terms of
one of four kinds of units - millimeters per second, inches per second track speed or miles
per hour, kilometers per Hour scale speed.
The DCC address used in the recording is the "standard power" of the warrant. To base the
track speeds on a different address or roster entry, select that entry and press the
track/scale speed button. Warrants recorded before Release 4.9.2 can be
upgraded this way.
NOTE:Recording track speeds in warrants makes panels saved with Release
4.9.2 fail to load with earlier versions of JMRI. However, Recorded track speeds can be set
to "0.000" by selecting no address or roster entry then pressing Add
Speeds. Saving the panel now will allow it to be loaded by earlier versions.
Triggering External Events From Scripts
External animation or other events may be triggered by the "
Set Sensor"
command. To do this insert a row, then select
Set Sensor from the list of
items under the
Command column. Next select the action
(
active or
inactive) you want from the
Value column. Lastly, enter a sensor name in the
Block or
Sensor column. Also enter or adjust the elapsed time when to trigger the setting of
the sensor. On playback when this command is executed the state of the sensor will be set.
Script Synchronization With External Events
Additional synchronization can be done within a block. For example stopping a train at a
water tower or over an uncoupling device or for any reason where using the elapsed time of a
command is not precise enough. To do this, there is a
Wait Sensor command.
Insert a row and follow the same procedure as was done with set Sensor. On playback when this
command is executed the script is suspended and the current movement of the train is
sustained until the sensor changes to the specified state. When that happens the script
continues to execute according to the recorded times.
For example the "Wait Sensor" might be an optical sensor named "sStopTrain" positioned to
detect specific point. The "Wait Sensor" command is bracketed with speed commands, the one
before with a very slow speed and the one after with speed 0. Sensor "sStopTrain" is set
inactive and then the script is set to wait until it goes active. The script will then have
the train creep at the current slow speed of 11.4 mm/sec until the sensor detects the trains
desired position. Then the script continues to set speed to 0, which stops the train.
Following that, the scrip must wait for another sensor named "sStartTrain" to go active
before it can continue.

The script and train will stay stopped until the second "Wait Sensor" command triggered from
an external event allows the script to continue.
Automatic Sequencing of Warrants
since 3.11.1
It is possible to start another script from a script. To do this, insert a row and select
the Run Warrant in the Command column. Enter the
name of a warrant in the Block or Sensor column. This command
launches the second warrant. Note that a train with the address specified in the second
warrant must be present in the starting block of the second warrant.
Otherwise, the second train will start running in uncontrolled places.
This feature can be used to loop a train repeatedly by using the same warrant name. If a
script terminates with the destination block equal to the origin block, it will repeat for
the number of times entered into the Value column. If a negative
number is entered the script will repeat indefinitely until an abort command is manually
issued. Another possibility would be to use warrant "from A to B" and warrant "from B to A",
where warrant "from A to B" runs warrant "from B to A" and warrant "from B to A" runs warrant
"from A to B" and each Warrant specifies the same train ID and the same number of
repeats.
Running Trains on Dark Blocks
The Learn mode and Run Mode functions can be used on blocks that do not have detection
sensors. However, without detection, other than the initial setting of turnouts, the warrant
cannot reset the turnouts or modify its speed while the train is
en route. This
means there is no protection from rogue trains fouling the route or from turnouts being
changed while the train is
en route. Therefore, run trains with caution over Dark
Blocks.
Note that entry into a Dark Block is detected differently than an Occupancy Block.
Obviously, entry into an occupancy Block is recorded when the occupancy block detects
occupancy. However entry into a Dark Block can only be recorded when the previous occupancy
Block shows no occupancy. That is, the elapsed time for entry into a Dark Block is recorded
by the tail of the train entered the dark, not the head.
Save etc.
At the bottom of the Create Warrant pane the
Status field displays messages
when doing test runs from the
AutoRun button. Below that are three buttons
that let you:
- Save: - Saves the warrant so it can be shown in the list of warrants
on the Warrant Table. A permanent copy of the warrant is saved when the panel is saved to
the Configuration file.
- Copy: - Makes a copy of the warrant.
- Cancel: - Cancels any editing that may have been done.
Back to Warrants Help.