JMRI: DispatcherPro

This document describes the JMRI Dispatcher tools, and how they can help with dispatching and running trains on layouts with PanelPro panels.
The text is divided into sections. Underlined items in the table of contents link to sections of this document or to other help files.

since 5.1.3

The requirement to select a Layout Editor panel in Dispatcher Options has been removed. All Layout Editor panels are now used for layout connectivity when running auto trains.

Introduction to Dispatcher

since 2.3.5

JMRI Dispatcher provides functions and organizes information relating to dispatching trains on a model railroad layout. Its main function is the allocation of sections of track to various trains running around the layout. Dispatcher is not designed to completely replace a human dispatcher during a session of running trains, but it should make the dispatching job easier and more fun. Dispatcher is envisioned to work alongside a Panel, constructed in either Layout Editor or Panel Editor, which provides visual feedback of layout status. An example of a Dispatcher Panel in action is shown next. No attempt was made to make Dispatcher look or feel prototypical. It was simply designed to be functional for dispatching a model railroad layout.

Dispatcher Panel Example

Note that in this document "Dispatcher" refers to the JMRI Dispatcher software, and "the dispatcher" refers to the person running the Dispatcher software.
Many of the terms in this introduction to Dispatcher may be new to users. Some terms and settings were created specifically for use with Dispatcher. Please review the Glossary of Terms, and come back to it as needed when reading the remainder of this documentation.

Functionality provided by Dispatcher includes:

Central to Dispatcher is the concept of an Active Train, which carries the information needed to run a train around part of the layout.
Basically, an Active Train is created by the dispatcher by linking a Transit and a Train. The Transit provides a description of the itinerary to be followed by the Train, including which Sections need to be allocated in sequence along the route, and, when running automatically, any Actions that need to be initiated in specific Sections.
The Train specifies what is to be run along the route defined in the Transit. Trains can be complete descriptions of all engines and cars as provided by JMRI Operations, or engines selected from the JMRI Roster menu, or simply a train name and dcc address entered by the dispatcher.

When creating an Active Train, the dispatcher also specifies where the Active Train is currently located, and the location of the Active Train when it is terminated after it completes its transit of the layout. Other options are entered, like train Priority and Type, a request to start the Active Train at a specified Fast Clock time, and a request to run it Automatically.

All Active Trains are displayed in a table in the The Dispatcher Window, along with status information about the Active Train. The Dispatcher Window also contains a table of pending Requested Allocations, a table of currently Allocated Sections, and buttons that allow the dispatcher to easily allocate Sections, create new Active Trains, and terminate Active Trains. Allocated Sections are released using buttons in the Allocated Sections table, or automatically if the Auto Release option is selected. The Dispatcher Window is discussed in detail below.

Note: The current version of Dispatcher contains an automated allocation option still under development. To request Dispatcher to attempt to automatically allocate Sections to Active Trains, select the Auto Allocate box. Auto Allocate (discussed in detail below) works fine for single Active Trains, and for some cases of multiple Active Trains. Enhancements are planned in future releases.

Dispatcher Requirements

Dispatcher requires that a layout be divided into Blocks, and that Blocks along the mainline be organized into Sections.
It also requires that these Sections be used to define itineraries, called Transits, that describe paths that trains will follow when active on the layout.

Dispatcher Sections Transits Concept Track Diagram

Blocks are portions of track whose occupancy can be monitored individually. Sections are groups of one or more Blocks that are allocated as a unit by the dispatcher using Dispatcher functions. Blocks are usually defined to support signaling on a layout. Simplest use of Dispatcher does not require that block detection hardware or signals be installed on the physical layout, or even that the physical layout be divided into blocks. Dispatcher will work if layout blocking is defined in a panel only. However, Dispatcher works best if hardware blocks with block detection are present. It works even better if hardware signals are present on the layout, and signal logic uses Section direction sensors.

Glossary of Terms

A portion of track whose occupancy may be individually monitored. Blocks are defined by subdividing the track in a layout. Blocks normally correspond to physical blocks on a layout, each wired for occupancy detection. However, if the layout track is not subdivided into blocks, dividing a Layout Editor Panel track diagram into Blocks will allow Dispatcher to be used for manually running trains.
Hardware occupancy detection is also optional for manual running trains. More on Blocks.
Automatic running of trains requires hardware blocks and hardware occupancy detection. For all Dispatcher use, blocking of mainline track on a Layout Editor panel is required. Dispatcher works best if hardware block occupancy detection is present, but it can be used to run trains manually without it.
A group of one or more connected Blocks that may be allocated to a train for travel in a given direction. Blocks are normally defined to facilitate signals. This often results in short Blocks, sometimes containing only one track switch. Sections allow Blocks to be grouped into track sections that are reasonable for a dispatcher to allocate. More information is contained in the Section Documentation, along with instructions on how to create a Section.
A group of two or more connected Sections that describes a route around the layout for a train traveling in a given direction. Transits are required for Dispatcher, and at least one must be defined before Dispatcher can be opened. Transits also contain information about user-specified actions when running Active Trains automatically. A detailed description of Transits, how they are created, and how they are used is contained in the Transit Documentation
An engine (or consist) usually attached to a group of cars, that travels around the layout as an entity. For use with Dispatcher, Trains may be selected from the list of engines in the JMRI engine Roster, selected from the Trains created in JMRI Operations, or basic train information may be entered manually by the dispatcher.
Active Train
A combination of a Train and a Transit, along with other information and options. The Train describes what is traveling, and the Transit describes where it is going. Details are filled in by other information and options selected when the Active Train is created. Active Trains are central to Dispatcher. How Active Trains are used is described in detail below. Active Trains Table provides more details. Active Trains are created and terminated from the Dispatcher Window.
Auto Active Train
An Active Train that is run automatically by a virtual engineer instead of manually by a human engineer. An Auto Active Train is a special type of Active Train that is operated automatically by the computer using a computer throttle. Automatic operation is requested by the dispatcher when the Active Train is created. Auto Active Trains are described in detail below.
Requested Allocations
A request to allocate (assign) a Section for the exclusive use of an Active Train. Allocation Requests that are not immediately acted upon are gathered in a queue that is displayed in the Dispatcher window. Fulfilling an Allocation Request may be delayed for a number of reasons, for example, if the requested Section is not FREE, but is allocated to a different Active Train, or if the dispatcher is setting up a meet. Allocation Requests are acted upon manually by the dispatcher, or automatically if using the Auto Allocate option.
Allocated Section
Section that is currently assigned to an Active Train for its exclusive use. When a Section is allocated, if there are alternate Sections following the Allocated Section, the dispatcher must choose the next Section from the alternate Sections contained in the Transit. A table listing all Allocated Sections is displayed in the Dispatcher window. The Allocated Sections table is where Sections are released, either manually by the dispatcher, or automatically if using the Auto Release option.
Alternate Section
An alternate Section connecting two Sections in a Transit. In user-specified areas of a Transit, alternate Sections may be designated. For example, to move between the "2nd" and "4th" Sections in a Transit, there may be multiple "3rd" Sections, any of which might be used to travel between the 2nd and 4th Sections. Alternate Sections provide for passing tracks and staging yards.
Safe Section
Sections in a Transit where Trains in opposing directions can pass without blocking the other Train, are marked as Safe. This is not a property of a Section itself, but is to be determined during creation of a Transit. Active Trains can then be allocated To Safe Sections.

Using Transits and Sections in Dispatching Active Trains

When a Transit is paired with a Train to form an Active Train, the starting Block (Active Train location at start) and ending Block (Active Train location when the travel is complete) are specified. The Active Train is referred to by its Train name and its Transit name, each of which must be unique among Active Trains. A Train and a Transit may be in only one Active Train at a time. When an Active Train is terminated, its Transit and its Train are deactivated, and both may be reused in different Active Trains.

Either an Active Train starts from a Block outside of the Transit, but connected to a Block within the Transit, or an Active Train starts from any Block within a Section in the Transit. When an Active Train starts, it moves through a Transit in one direction (FORWARD)--defined by the order in which Sections are included in the Transit. Trains move from lower sequence number Sections toward higher sequence number Sections. To facilitate back and forth running, an option is available for an active train to reverse itself upon reaching the end of its Transit, and back up through the Transit to the first Section of the Transit. To facilitate continuous running of an Active Train, and option is available to automatically restart the Active Train after the Transit is completed.

When an Active Train is created, an Allocation Request is placed for a starting Section. If the Section is free, the Section will be allocated to the Active Train. Allocation means that the Section is assigned to the Active Train, and the Active Train is authorized by the dispatcher to proceed to the end of that Section.

An Active Train may be run by an engineer using a throttle, or automatically by the computer. Dispatching for the Active Train consists of allocating Sections, one by one, to the Active Train, and holding the Active Train in a Section when its needs conflict with the needs of other Active Trains. The actual allocation may be done by the dispatcher by manually clicking buttons in the Dispatcher Window, or the dispatcher may request Auto Allocate by checking Auto Allocate above the Allocated Sections table or by selecting it in the Options menu of the Dispatcher window, and allow the computer do some of the routine work. If a requested Section is currently in use, an Allocation Request is placed in the Requested Allocations table in the Dispatcher window.

For Auto Active Trains (Active Trains run automatically), Transits provide for Actions to be initiated when a train is in a Section of the Transit. Actions are set up when Transits are created or edited in the Transit Table.

The Dispatcher Window

The Dispatcher window is opened when Dispatcher... is selected in the JMRI Tools menu.

It displays a table of Active Trains and their status, a table of pending Requested Allocations, and a table of Allocated Sections. It provides buttons that allow the dispatcher to easily allocate Sections, create new Active Trains, terminate Active trains, etc. The Dispatcher window buttons are discussed below. The Active Trains table and the Requested Allocations table are discussed in the following paragraphs.

The sequence of columns in each table can be changed by dragging the column header. The visibility of individual columns can be changed by using the right click context menu and clicking on the column name. The ID columns have been hidden in the images to reduce clutter.

A typical Active Trains window early in a train running session might look like this:

Dispatcher Window

In the example above, two Active Trains have been created:

  1. The top Active Train, Amtrak 139, has been allocated a Section and is RUNNING in MANUAL mode (manual throttle).
  2. The second Active Train, GTW 6418, is scheduled to start at 8:15 on the fast clock, and will run in DISPATCHED mode.

Allocation Requests have been entered for the next Sections needed by the two Active Trains. The requested Sections are FREE and UNOCCUPIED, so the dispatcher could allocate either of them by clicking the Allocate button in the Requested Allocations table or the Allocate Next button in the Active Trains table. Allocating a Section to GTW 6418 would require the dispatcher override its scheduled start time. The Sections currently allocated to the two Trains are shown in the Allocated Sections table.

The four buttons below the Active Trains table are described below:

Dispatcher options allow tailoring of the dispatcher function. The pane to set these options is accessed via the Dispatcher window's Options menu. Descriptions of items available in the Dispatcher Options pane, and of the Options menu, are contained in the Dispatcher Options help.

The Active Trains Table

The Active Trains table from the above Dispatcher example is repeated below.

Active trains table

Each row of the Active Trains table corresponds to one Active Train. The columns are as follows:

The Requested Allocations Table

The Requested Allocations Table from the above example Dispatcher window is shown below.

Requested allocations table

This table, headed Requested Allocations waiting for Dispatch, displays pending Allocation Requests. Each row corresponds to one Allocation Request. The columns are:

The Allocated Sections Table

The Allocated Sections table displays all Sections currently allocated to Active Trains. This table serves two purposes:

  1. It shows which Allocated Sections are allocated to which Active Trains, and
  2. it allows the dispatcher to release an Allocated Section for use by a different Active Train.
Allocated sections table

The table columns are as follows:

Auto Allocate

The Auto Allocate check box, immediately above the Allocated Sections table, is used to switch on (checked) or off (unchecked) the automated allocation option. If Auto Allocate is off, the dispatcher is responsible for allocating all Sections using the Allocate button of the Allocation Request in the Requested Allocations table or the Allocate Next button of the Active Train in the Active Trains table (see above).

The Auto Allocate option works cautiously. It will never allocate an OCCUPIED Section. It will never override a fast clock start time. It will attempt to avoid gridlock by looking ahead to see if a requested Section will be needed by another Active Train that has started. When possible, it attempts to allocate three Sections ahead of the current position of the head of each Active Train.

The current version of Auto Allocate works fine for single Active Trains and for multiple Active Trains whose Transits don't overlap. It has limited support for simultaneous Active Trains that require the same Sections. Future versions will contain enhanced support for multiple Active Trains.

The Auto Release check box, immediately above the Allocated Sections table, is used to switch on (checked) or off (unchecked) the automated release option. If Auto Release is off, the dispatcher is responsible for releasing Allocated Sections using the Allocated Section's Release button (see above). If Auto Release is on, the program will automatically release Allocated Sections which are UNOCCUPIED, show a Use Status of Exited, and are next-in-line to be released. Auto Release will only release Allocated Sections in the order in which they were allocated. Auto Release will not release Sections allocated using the Allocate Extra... button. Extra Allocated Sections must be released manually by the dispatcher.

Often a Section should not be released if it is still OCCUPIED. When an Active Train is terminated, all of its Allocated Sections are automatically released, regardless of occupancy. Auto Release will not release an OCCUPIED Section automatically. Caution: The dispatcher is responsible for determining whether it is appropriate to release an OCCUPIED Section.

The dispatcher may turn Auto Release and Auto Allocate on and off at any time. Also the dispatcher may override the automatic allocation process by allocating a Section that the Auto Allocate option is refusing to allocate. Turning off Auto Allocate cancels any plans the option might be working on involving multiple Active Trains. Note: Auto Allocate and Auto Release require reliable block occupancy hardware to operate dependably.

Running Trains Automatically with Dispatcher

Dispatcher supports running trains around the layout automatically, provided the layout meets minimum requirements. Once an automatic Active Train (called an Auto Active Train) is created, it is run automatically by a virtual engineer using a computer throttle. The Auto Active Train follows signals around the layout, and performs user-specified Actions, separate from Dispatcher. When an Active Train is created by the dispatcher, automatic running may be requested in the Activate New Train window, and options specific to the Auto Active Train are set at that time.

The dispatcher allocates Sections to an Auto Active Train in the same manner as allocating Sections to an Active Train run manually by a human engineer. From the dispatcher point-of-view, Auto Active Trains are treated the same as manually run Active Trains. There are two exceptions to this:

since 4.3.7Support is provided for RAMPING the speed of an Auto Active Train when changing from its current speed to a new speed. This option is controlled by selecting a Ramp Rate for each Auto Active Train when it is created. The best Ramp Rate for an Auto Active Train depends upon that train's locomotive engine, the type of decoder, and settings of the decoder CV's. Available Ramp Rates are:

Note: Overall ramping rates can be adjusted in Dispatcher Options.

When traversing the layout, an Auto Active Train changes speed in response to the signals it passes. If the next signal it faces is dark, red or flashing red, the train will stop in the current Section (see below). If the facing signal is green or flashing green, the train will run at its maximum allowed speed. If the facing signal is yellow or flashing yellow, the train will run at a reduced speed of 35% of the allowable speed range.

If using SignalMasts, the speed between two SignalMasts is set to the lesser of the SignalMast indicated speed vs. the Block and Turnout speed for that path. This allows you to specify maximum speeds for specific trackage.

When an Auto Active Train is created, a default maximum allowed speed is specified as a fraction of the allowable speed range. Each new speed value is compared to the maximum allowed speed, and reduced if necessary. This allows different Auto Active Trains to run at maximum speeds appropriate to the type of train, regardless of the speed capability of its locomotive. The maximum allowed speed may be changed while running by using the Set Maximum Speed Action. This provides for slowing down or speeding up at specified locations in the Transit, for example, when passing through a town.

Since all locomotives do not run the same, when an Auto Active Train is created, a Loco Speed Compensation in the range of 50 to 150% is specified. This Compensation factor multiplies all speed values immediately before the speed is sent to the throttle (after the speed has been tested against the maximum allowed speed). For "normally" running locomotives, a speed factor of 100% is appropriate. For locomotives that run slower than "normal", use a factor greater than 100% and for trains that run faster than "normal", a factor less than 100% is best.

Three different methods are provided currently for stopping an Auto Active Train when it needs to stop. If the Section has hardware stop Sensors, the train is halted when it reaches the Stop Sensor for its direction of travel. If no Stop Sensors are available for the Section, the train length is compared to the length of the Section to determine if the Auto Active Train will fit in the Section. If the Auto Active Train will fit in the Section, and if all cars of the train are detectable, the Auto Active Train is stopped when it exits the Section previous to the current Section. If neither of the two methods apply, the train is stopped when it enters the Section.
Stopping using a Stop Sensor is the most precise way to stop an Auto Active Train at a specific location. Stop Sensors need not be in place for all Sections, but their use for automatic station stops and passing tracks is strongly recommended.
For the second stopping method to work, train length must be entered, lengths of all Blocks in the Transit must be present in the Block Table, and the train must be fully detectable (this usually means all cars must have resistance wheels on one or more trucks). Block lengths should not include the turnouts at the ends of the Section, or portions of a Section not normally traversed by the Auto Active Train.

Requirements for Automatic Running

Automatic running of Active Trains requires the layout and the train have required hardware and that one or more fully configured Layout Editor panels be present to provide layout connectivity information. Some of the automatic running requirements are strongly recommended for manual running also. Requirements include:

Even if the above requirements are met, automatic running will not be successful unless the layout and the rolling stock are in very good condition. The track must be clean, and the wheels of automatically running trains must be very clean, allowing good block detection. Locomotives must run smoothly, especially at slower speeds. Derailing problems must have been solved. A train should run flawlessly in manual mode, before automatic running is attempted.

Because Auto Active Trains use JMRI signaling for stops, starts and speeds, the signaling should also be flawless, including all blocks, turnouts and direction indicators needed.

Further Reference