JMRI® is...
JMRI tools for working with your layout:
Layout Automation
Use JMRI to automate parts of your layout and operations:
Supported Hardware
JMRI supports a wide range of DCC systems, command stations and protocols.
By the community of

JMRI Help:

Contents Index
Glossary FAQ

Donate to JMRI Donate to

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:

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:

Creating a Warrant

A Warrant consists of two parts:

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