JMRI: Warrants Introduction

Getting Started: This page is a brief introduction to warrants with links to other help pages. Read the more complete Warrants Help, including the section "Get Started with Warrants." See also the clinic presentation by Dick Bronson: JMRI 2014: Automatic Train Control Using Warrants (in two parts and a little out-of-date, but still useful for getting started).

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. Trains can also be tracked on the panel as they run on the layout.

A JMRI Warrant is suggestive of what a warrant is used for 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 which is available in Control Panel Editor. The Warrants List is only available when the building blocks for warrants (OBlocks, OPaths, and Portals) have been previously defined. These elements are created by:

• entering data directly into the Occupancy Block Table (under Tools ⇒ Tables),
• creating them based on Layout Editor Blocks (select "Import Blocks as Occupancy Blocks" under Option in the Occupancy Block Table window),
• or using the graphical interface of the Circuit Builder (also part of Control Panel Editor).

Note that OBlocks, OPaths, and Portals are stored independently of Blocks used by the Layout Editor. Sensors used for determining occupancy can be used simultaneously by both Blocks and OBlocks.

Trains are tracked on the CPE panel as they run on the layout if the layout includes Indicator Track Icons.

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.
• An NX Warrant (eNtry/eXit), where throttle commands are generated automatically to move a train between Blocks chosen by you "on the fly".
• 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. This type of warrant is better suited to smaller layouts.

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 (OBlocks, OPaths) linked together so a train may travel over it. A Warrant Route is created by first choosing an Origin block (an OBlock), a starting path (OPath) and a portal (Portal) to exit the Originating block. Then, a Destination block (another OBlock) is chosen and a path (an OPath) on which to end the route. Optionally, you may also choose a Via Block, that is, an OBlock the route must include and an Avoid Block, that is, any OBlock the route must not include.

Recording the Commands

The second part of a Warrant comprises 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 command script contain the elapsed time between commands so that playback will attempt to duplicate this timing. If, however, a Warrant is run with a different engine or a different consist, or even the same engine depending on whether its motor is hot or cold, this timing may not be exact. The command script will synchronize upon entering each detection OBlock by either issuing additional commands immediately if the train is fast or waiting to issue commands if the train is slow.

More Warranted Reading

• The Warrant List: table from which you can control warrant routes and dispatch trains
• Preferences related to Warrants
• Definitions of OBlocks, Portals and OPaths
• Creating OBlocks, Portals and OPaths using tables
• Using the Circuit Builder Tool for creating OBlocks, Portals and Paths
• Creating and Editing Warrants.
• Using Train Trackers to display the identity of trains as they are moved by operators from one occupancy block to another.
• About NX Warrants and creating temporary eNtry/eXit (NX) Warrant.
• How Warrants handle speed changes
• Clinic presentation by Dick Bronson: NMRA 2014 Automatic Train Control Using Warrants (in two parts)