JMRI: Warrants

A Warrant in JMRI is a collection of information sufficient to run an automated train. It will set the turnouts for a specified route and drive the train over the route. When running, using block occupancy detection and signal configuration, it will make a best effort to control speed according to signal aspects or by occupancy of other trains or other track conditions ahead.
A JMRI Warrant is suggestive of what a warrant does on a prototype railroad, but there is no intention to replicate any particular railroad's mode of operation. It is simply the idea of giving an automated train the trackage rights to move from point A to point B (and then move it along). Warrants are issued using the Control Panel Editor and the The Warrants List.

Warrants depend on having an accurate description of the layout in terms of OBlocks, Portals and OPaths.
since 2.7.8 These elements are created by entering data into the Occupancy Block Tables or by using the graphical interface of the Circuit Builder, part of Control Panel Editor. Initially however, these tools are not visible in the Panel Editor as they require some preparations, described next.

Get Started with Warrants

Definitions of OBlocks, Portals and OPaths may be found here.

• First, it is important that the scale of your layout is known so that the Warrant can compute the distances required when encountering signals. Open the Warrants pane of JMRI Preferences to set the layout scale. There are other parameters related to Warrants there that you may wish to change later, but the defaults are generally sufficient without further change. See Warrant Preferences for information about configuration of Warrant parameters.
• Next, open the Occupancy Block Tables by choosing the Tools ⇒ Tables ⇒ Occupancy Blocks menu item from the main PanelPro menu bar, or the Add Items ⇒ Occupancy Blocks menu item from within Control Panel Editor.
• Create your OBlocks, Portals and OPaths using these tables, as described in Creating and Editing OBlocks, Portals and OPaths.
• OBlocks, Portals and Paths can also be created using the Circuit Builder tool found in the Control Panel Editor. Using that tool, OBlocks, Portals and OPaths are defined by selecting track icons of your layout diagram. The Circuit Builder can be opened using the Open Circuit Builder menu item under the Warrants menu. Follow the Circuit Builder instructions.

The Circuit Builder Tool

since 2.12

Circuit Builder is an interactive tool that creates OBlocks, Portals and Paths graphically. In order to use the tool, you need to have a track diagram of your layout expressed with track icons (track segments and turnout icons) in a Control Panel Editor panel. OBlocks and OPaths are created by clicking on the track icons. The Circuit Builder can convert the track segments and turnout icons of your Panel into Indicator Track and Indicator Turnout icons. These icons display the status of the OBlock they represent by color, i.e. whether the track circuit of the OBlock is Occupied or Unoccupied, whether a Warrant has allocated it or whether a Train under Warrant currently is proceeding over the circuit. Details are found in the Circuit Builder Help.

Compatibility with Layout Editor

Layout Editor panel Blocks are created and stored independently from OBlocks, although they can share use of the same Sensors for determining block occupancy. OBlocks, Portals and OPaths can be created manually (without using Circuit Builder in a CPE panel) and imported from Layout Editor Blocks (see the command under Options in the Occupancy Block Table. It is possible to use OBlocks, Portals, and OPaths without a CPE panel but that would be unusual.

Creating a Warrant

In order to create a Warrant you must first have created two or more OBlocks. These Blocks don't have to be fully defined, but their existence indicates that you are interested in using Warrants, that is, you have a block to start a train and a block to stop it. When two or more OBlocks exist in PanelPro, Control Panel Editor will change the Warrants menu to include the following menu items:

• Warrant List - Opens a table of Warrants from which you can control warrant routes and dispatch trains. See The Warrant List.
• Edit Warrant... - Shows the list of existing Warrants. Selecting one will open a Warrant Editing Window. The operations of this frame are discussed in Creating and Editing Warrants.
• Create New Warrant - Opens the window used for creating and editing warrants. This window has several display modes. In this case, it is opened in the mode to create a route for a new warrant. The Creating and Editing Warrants help page has information about creating a warrant.
• Train Trackers - Opens the Tracker Table window. The Train Trackers help page discusses how the movements of a train can be displayed as they move from one occupancy block to another.
• Create NX Warrant - Opens a window to create a temporary eNtry/eXit (NX) Warrant. This is discussed in About NX Warrants.
• Open Session Log - since 3.7.3 Opens a window to name a file that records the Warrant and train tracking status messages.
• Open Circuit builder - Opens a window for the circuit Builder to present its options for interactively editing and creating OBlocks, Portals, Paths. Also configures Signals and Indicator Track icons. Circuit Builder has details.

Warrants without Occupancy Detection

It is possible to create and run Warrants without block detection. OBlocks can be defined when they do not necessarily have to have detection sensors. Such blocks are called "Dark Blocks". Dark blocks, the portals and paths within the block can be defined for a layout diagram without detection sensors. A Warrant can be recorded and can be played back, including having its route set. However, be advised for such trains without detection sensors there is no protection for having it collide with other trains or throwing switches under other trains. Trains will run merely according to the elapsed times and throttle settings that were recorded.

Warrants without Turnout Control

It is possible to create and run Warrants without having turnouts thrown by JMRI. JMRI internal turnout devices will show the route on the layout panel, but you will need to manually set and verify that the route is properly set on the layout itself. Again, the train will proceed according to the elapsed times and throttle settings that were recorded.

The Importance of Block Path Lengths

A Warrant detects a position of its train when it enters a block having occupancy detection. All other positional information must be calculated. For this, the track speed of the train and the length of the path it is on must be known.

To properly respond to a slower speed change required by a signal aspect, the train should prototypically slow down and complete the speed change before entering the block the signal protects. This requires the Warrant to calculate the time and position for the slowdown to occur.

See When Warrant Speeds Are Modified for what track conditions require speed changes, they are detected and how Warrants make gradual changes of speed.

Warrant Types

There are three types of Warrants available:

• A Recorded Script Warrant, where throttle commands are recorded from a throttle you use to drive a train over preselected route. The Warrant then replicates all the commands when played back. To create a Recorded Script Warrant, select the Warrants ⇒ Tables ⇒ Create New Warrant menu item and select 'Prototypical' or 'Add Speeds' as Warrant type.
• An NX Warrant (eNtry/eXit), where throttle commands are generated automatically to move a train between Blocks chosen by you "on the fly". A dialog allows you to choose start and destination distances and to set the maximum Throttle settings. To create an NX Warrant, select the Warrants ⇒ Tables ⇒ Create NX Warrant menu item. More on NX Warrants
• A Fast Reacting Warrant. This type does not follow the usual Warrant rules, but reacts to signals when entering their approach block with an immediate speed change. The throttle settings are a fixed proportion of the Aspect Speed Names in Warrant Preferences. This type of warrant is better suited to smaller layouts. To create this type of Warrant, select the Warrants ⇒ Tables ⇒ Create New Warrant menu item and select 'Fast Reacting' as Warrant type. More on Fast Reacting Warrants

Creating a Warrant

A Warrant consists of two parts:

• The Route over which a Train will run
• the Commands it will receive when running over the route.

To define the commands for a Warrant, you drive the train over the route you selected and the commands you used are recorded for playback later. For an NX Warrant, commands are generated automatically for the route you have selected.

Creating the Route

A Warrant Route is a series of Block Paths linked together so a Train may travel over it. A Warrant Route is created by first choosing an Origin block, a starting Path and a Portal to exit the originating block. Then, a Destination block is chosen and a Path on which to end the route. Optionally, you may also choose a Via Block, that is, a Block the route must include and an Avoid Block, that is, a Block the route must not include. Blocks are inserted by typing in the block name or dragging it from a displayed OBlock Table. Blocks can also be selected in Control Panel Editor by clicking on track icons that represent these OBlocks. To use this feature, your Control Panel must have your layout depicted by Indicator Track Icons placed there either by Circuit Builder or manually defined by you.
Successive clicks cycle through the four block fields and fill in the name of the Block you clicked on.

A computer algorithm determines all the intermediate blocks, portals and paths to make the route. If more than one route meets the criterion, you are presented with a list to review and select the route you want. Note that the Portal and Paths need to be chosen for the route also. If no route is found, a dialog is offered where you can examine the routes that were attempted with the current Block, Portal and Path selections. Creating and Editing Warrants has more information about creating routes.

Scripting the Train Action

The second part of a Warrant are the throttle commands to control the train as it traverses the route. These commands are recorded automatically by running a train over the route in "Learn Mode" or are generated automatically as an "NX Warrant". The script commands contain the elapsed time between commands. Playback will duplicate this timing. However, when a Warrant is run with a different engine or a different consist, or even the same train depending whether the motor is hot or cold, this timing may not be replicated exactly. Because of this the command script is synchronized upon entering each detection OBlock. So, if the train is slow in reaching the next block, the commands for the next block will be delayed until the train enters the block. Conversely, if the train reaches the next block ahead of time, any remaining commands in the block just left are issued immediately so that the Train can catch up to the script.

Warrant scripts are recorded or generated with a "Clear" Aspect throughout the route, even through blocks with restricted speeds. These speeds in the script are the "Normal" speeds. However, after creation when running, track conditions may not be "Clear", due to a signal's speed restriction, a block's speed restriction, occupancy by a rogue train or even intervention by you to halt the train.
Warrants are able to deal with these restrictions and will modify their "Normal" speeds as needed to comply with the restrictions. When Warrant Speeds Are Modified explains this relationship.

Recording Scripts

A Warrant script is written by putting a JMRI screen Throttle into Learn Mode to record all the throttle commands you make when driving the train over the route. The script can then be replayed to drive the train automatically. All possible throttle functions can be recorded and played back. Creating and Editing Warrants details how to do this.

With LocoNet you may steal the address and manual LocoNet throttle. For other command systems, a WiFi throttle may take the same address as the screen throttle and be used to record a walk around script.

Generated Scripts

For NX Warrants, the script is generated by the Warrant itself. It ramps the train up to a specified speed and ramps it down at the destination. It obeys all the traffic occupancy and signals as do the Recorded Warrants. See About NX Warrants for how to run these.

"Normal" Track Speeds

When recording a Warrant throttle command script, the train should be run with all track conditions set to "Clear". NX Warrant script are generated using "Clear" track conditions also. This is reported in status messages as the "Normal" speed. However, when running the Warrant, the train may be confronted with occupation ahead by another train or a signal required a reduction of speed. Warrants respond to these and other track conditions by automatically modifying the scripted throttle settings. When Warrant Speeds Are Modified has details about how Warrants modify recorded speeds.

Customizing the Script

A Warrant script can be edited to modify the recorded commands. Additional non-throttle events can be added to the script such as triggering or responding to external sensors. Creating and Editing Warrants has more information about creating and customizing scripts.

Using the Warrant List

The Warrant List menu item opens the Warrant Table. Each row represents a Warrant that was created and saved or a running NX Warrant. The Warrant Table reports the current status of each Warrant in the list and can issue commands to Halt, Resume or Abort. Warrant routes can be allocated, i.e. reserved for that Warrant, the Turnouts for route can be set and when the Warrant is run, its status is shown and controlled using the columns in the table. See The Warrant List for more information.

Tracking Trains

Any train running on the layout can be tracked. The layout must be represented with Indicator Track Icons to track trains. Train Trackers, the fourth item in the Warrants menu, opens the Tracker Table. Pressing the New Tracker... button in this window opens a dialog to enter a train name and the OBlock it occupies. Pressing the [Create] button creates a row in the Tracking Table. The row shows the train name and the block it currently occupies and the length of time it has occupied the block. As the train moves from block to block, this status is updated. The Indicator Track Icons can display the train name.

The window also has a Refresh Tracker Info button to poll the trackers listed in the Tracker table and an OBlock Pick List button to display a picklist.

The location of the train can be set by typing, by dragging block name from the picklist, or by clicking on an Indicator Track Icon in the panel.

Tracking can also be done for a train by dragging and dropping a Loco Icon onto the OBlock the train occupies. This is the most simple way of tracking in that both the name and location are done with a single drag and drop.

Using Warrants in Logix and LogixNG

Several of the operations that can be done from the Warrant List and Warrant Editing frame can be done with Logix/LogixNG conditionals. You may design and implement a dispatcher's panel using the Warrant state variables/expressions and actions found in Logix/LogixNG.

Detailed LogixNG descriptions are at LogixNG Actions and LogixNG Expressions.

Warrant State Variables (Logix)

When a Warrant has been allocated or is in effect, the following state variables can be tested in a Logix conditional.

• Route Free: - True when all Blocks in the Warrant route are not allocated to anyone and are not occupied. False otherwise.
• Route Set: - True when all blocks in the Warrant route are allocated and the turnouts set for this Warrant. False otherwise.
• Route Allocated: - True when all blocks in the Warrant route are allocated to this Warrant. False otherwise.
• Route Occupied: - True when none of the blocks in the Warrant route, other than the origin block, are occupied. (Assumes the train of this Warrant is occupying the origin block). False otherwise.
• Train Running: - True when the train specified in the Warrant is running either in Learn Mode or Auto Run Mode. False otherwise.

Warrant Actions (Logix)

• Allocate Warrant Route: - Allocates the route to this Warrant.
• Deallocate Warrant: - Deallocates the route of this Warrant (only). This will not deallocate the route of a different Warrant.
• Set Route Turnouts: - Sets the signals and turnouts for the route as far along the route that it can until it reaches an occupied block or a block allocated to another Warrant.
• Auto Run Train: - Issue the throttle commands to the train in the Warrant. This should only be done when the train occupies the Origin block.
• Set Train Id: - Set the engine consist to be used in the Warrant from a trainId in the Engine Roster. Alternatively, the DCC address can be used to identify the engine.
• Set Train Name: - Set the name of the train to display in the loco marker indicating the current position of the train when running.
• Control Train: - Send a control command (Halt, Resume or Abort) to a running train under warrant.

More Warranted Reading

• Introduction to Warrants
• How to prepare for Warrants using OBlocks and Portals.
• Setting global Warrant Preferences
• JMRI Automation, in general
• Step-by-step instruction on Warrants and Circuit Builder (slightly outdated) clinic presentation by Dick Bronson JMRI 2014 Control Panel Editor plus Warrants

---