Creating and Editing Warrants

A Warrant contains the information needed to run a train. This includes the DCC address of the locomotive(s), the route train will take, the settings of the turnouts to traverse the route and the throttle commands to use at various points along the route - e.g. speed, when to show lights, sound horns, bells or other sound effects. For an overview discussion of Warrants, see Warrants.

There are three steps in creating a Warrant:

1. Define the route
2. Select a train, and
3. Record the throttle commands.

On the Create/Edit pane are two tabs: Define Route and Record/Playback Script.

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.

A Warrant route is created by selecting the block and path where the train will begin its trip and the portal by which it should leave. Then you select the block, path and entry portal where the train should end its trip. Press the Calculate Route button and the computer will determine all the intermediate paths needed to make the trip.

• 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 consist of 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.

  1. 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
  2. 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.
  3. 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, the Record/Playback Script tab will be selected for you:
At the very top are two radio buttons which allow you to select either the Route Table or the Throttle Command Table. The Route Table shows the track circuits (OBlock, Portals and Paths) the warrant defines. The Throttle Command Table shows the throttle commands that will be used when driving the train over the warrant's route. Additional items on this tab allow you pick the engine to power your train and to test and modify the recorded script. Presently the Throttle Commands table is empty. The bottom half displays six outlined areas; Choose Engine Consist, Setect Type, Settings, Learn mode, Run Parameters, and Test Run Train,. The first thing to do is to choose an engine consist.

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 Train Name, and Address text fields and assigns them to the warrant.

A DCC address typed into theAddress text field will be used whether or not it is found in the JMRI Engine Roster.

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.

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 should be chosen.

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.

Pressing the Stop button will end the recording.

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. When the train is run by playing back the script, any changes to signal aspects will be taken into account and the train's speed and scheduled times will be altered accordingly. The recorded speeds and elapsed times should be for unrestricted "Normal" speeds.

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.

Run Parameters

This area has check boxes to modify how the train will operate when running the Warrant.

• 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.
• 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.

Run Mode

After a script is recorded, pressing the AutoRun button in the Test Run Train box will send the throttle commands to the train specified in the warrant.

The Status field will display each block entered by the train as it traverses the route.

The Test Run Train box has four radio buttons to control the train and override the Throttle commands.

• HaltStop the train.
• ResumeRamp the speed up to its previous speed.
• E-StopIssue an Emergency Stop to the train.
• AbortStop the train and null the warrant.

Saving the Warrant

When you are satisfied with the performance of the warrant, press the Save button to add the warrant to the Warrant Table.

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).
• Value: - The value of the command.
• Block or Sensor Name: - The block the train occupied when the throttle command was recorded.
• Speed (mm/sec) - The track speed of the recording train at the corresponding throttle setting.

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.

Synchronizing Commands to Block boundaries.

In spite of attempting to maintain the recorded track speed, changing the consist of a train or perhaps 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 the "Learn Mode" train recorded them.

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.

If a more precise way is needed to have a script event occur at a particular location, see the section Internal Synchronization From External Events below.

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. The values in the Throttle Command Table are changed by typing new entries into cells of the table.

Rows may be inserted or deleted from the table using the 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)

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 Add Speeds button. Warrants recorded before Release 4.9.2 can be upgraded this way.

Triggering External Events From Scripts

External animation or other events may be triggered by entering a "Set Sensor" command. To do this, insert a row with the words Set Sensor in the Command column and a valid sensor name in the Block column. The Value column should have the action you want the sensor to take at its execution time. That is enter the words active or inactive. Also enter 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.

Internal Synchronization From 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, insert a row with the words Wait Sensor in the Command column and a valid sensor name in the Block column. The Value column should have the action words active or inactive. 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. In this case the "Wait Sensor" might be an optical sensor positioned to detect specific point. Bracket the "Wait Sensor" command with speed commands, the one before with a very slow speed and the one after with speed 0 (or -1). The script will then have the train creep at the slow speed until the sensor makes the detection. Then the script continues and the speed 0 command stops the train.

The script and train will stay stopped until a second "Wait Sensor" command triggers the script to continue.

Note: Care must be taken when using this command. To be clear, the following is a sample script segment.

#	ET(msec)	Command	Value	Block or Sensor Name
10	1000	speed	0.1111	OB_WEST_YARD
11	1000	speed	0.05	OB_WEST_YARD
12	0	Wait Sensor	Active	IS_STOP_TRAIN
13	0	speed	0.0	OB_WEST_YARD
14	10	Wait Sensor	Inactive	IS_STOP_TRAIN
15	0	speed	0.1111	OB_WEST_YARD

The train continues the speed of Command #11 until the sensor at command #12 changes to active. If already active, the train continues to move. Command #13 stops the train and it remains stopped until the sensor at command #14 changes to inactive.

Automatic Sequencing of Scripts

since 3.11.1

It is possible to start another script from a script. To do this, insert a row with the words Run Warrant in the Command column and name of a warrant in the Block column. This command launches the second warrant. Note that a train with the address specified in the second warrant must be placed in the starting block of the second warrant.

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.

Script Commands

Command	Value	Block or Sensor Name
Forward	true/false	block name	direction
Fn	true/false	block name	any function key
F0	true/false	block name	e.g. head light
Speed	decimal	block name	throttle setting
Set Sensor	active/inactive	Sensor name	sets a sensor
Wait Sensor	active/inactive	Sensor name	halts commands for a sensor
Run Warrant	integer	Warrant name	chains to another warrant

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 three buttons 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.

---