Dispatcher

Contents

This document describes Dispatcher, and how to use Dispatcher to help with dispatching and running trains on layouts with PanelPro panels. The document is divided into sections; click below to jump to the named section. Underlined items are links to sections of this document or to other help files.

Introduction to Dispatcher

Dispatcher provides functions and organizes information relating to dispatching trains on a model railroad layout. It's main function is 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. There was no attempt to make Dispatcher look or feel prototypical. It was simply designed to be functional for dispatching a model railroad layout.

Dispatcher requires that a layout be divided into Blocks, and that Blocks along the mainline be organized into Sections. It also requires that Sections be used to define routes, called Transits, that describe paths that trains will follow when active on the layout. 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 facilitate 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.

Functionality provided by Dispatcher includes: support for train start up and termination, information to allow easy set up of meets at passing sidings, automation of some dispatcher functions, set up of automatic running of trains, support for starting trains according to a fast clock, support for linking signals to allocation via simple APB signaling support, optional automatic setting of turnouts when a section of track is allocated, and finally automatic running of trains along with manually run trains. Initial versions of these functions are included in the current version of Dispatcher; enhancements will follow in future releases of JMRI.

Central to Dispatcher is an Active Train, which carries the information needed to run a train around 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 route to be followed by the Train, including which Sections need to be allocated 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 specified by 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 train at a specified fast clock time, and a request to run the Active Train automatically.

All Active Trains are displayed in a table in the Dispatcher Window, along with status information about the Active Train. The Dispatcher Window also contains a table of pending Allocation Requests, 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 the first version of an automated allocation option. To request Dispatcher to attempt to automatically allocate Sections to Active Trains, select the Auto Allocate option. 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.

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

Glossary of Terms

Block - 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 into blocks will allow Dispatcher to be used for manually running trains. Hardware occupancy detection is also optional for manual running trains. 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.

Section - 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 Table help file, along with instructions on how to create a Section.

Transit - 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 Table help file.

Train - 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 engines in the JMRI engine roster, may be selected from trains created in JMRI Operations, or 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. The Active Trains Table section below 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.

Allocation Request - 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 - A 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.

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. Note: The current version of Dispatcher has limited support for automated allocation of Sections.

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, and a table of pending Allocation Requests. It provides buttons that allow the dispatcher to easily allocate Sections, create new Active Trains, terminate Active trains, and display a table of all Allocated Sections. Allocated Sections are released using buttons in the Allocated Sections table. Dispatcher window buttons are discussed below. The Active Trains table and the Allocation Request table are discussed in the following sections.

A typical Active Trains window early in a train running session is shown below.

In the example window above, three Active Trains have been created. The top Active Train, GTW 6418, has been allocated a Section and is RUNNING in AUTOMATIC mode. The second Active Train, Amtrak 515 is WAITING for its first allocation, following its initial allocation when it was created. Amtrak 515 is in DISPATCHED mode (manual throttle). The third Active Train, Amtrak 139, is scheduled to start at 8:35 on the fast clock, and will run in AUTOMATIC mode. Allocation Requests have been entered for the next Sections needed by two of the 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 Amtrak 139 would require the dispatcher override its scheduled start time. The Sections currently allocated to the three 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. Options are accessed via the Dispatcher window's Options menu. Descriptions of items available in the Options window, and of the Options menu, are contained in the Options help file.

The Active Trains Table

The Active Train Table from the above example Dispatcher window is shown below.

Each row of Active Trains table corresponds to one Active Train. The columns are explained below.

The Requested Allocations Table

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

This table, headed Requested Allocations waiting for Dispatch, displays pending Allocation Requests. Each row corresponds to one Allocation Request. Columns are explained below.

The Allocated Sections Table

The Allocated Sections table displays all Sections currently allocated to Active Trains. This table serves two purposes. It shows which Allocated Sections are allocated to which Active Trains, and it allows the dispatcher to release an Allocated Section for use by a different Active Train.

The table columns are as follows:

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 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 Allocation Request 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 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

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:

Support 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:

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 slow speed of 35% of the allowable speed range. If the train is preparing to stop, it will slow to a restricted speed of 25% of the allowable speed range.

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 exampled, when passing through a town.

Since all locomotives do not run the same, when an Auto Active Train is created, a Speed Factor in the range of 0.5 to 1.5 is specified. This Speed 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 1.0 is appropriate. For locomotives that run slower than "normal", use a factor greater than 1.0, and for trains that run faster than "normal", a factor less than 1.0 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 the 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 each Section. Use of Stop Sensors for automatic station stops and passing tracks is strongly recommended. For the second stopping method to work, 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. The lengths assigned to Blocks do not need to be highly accurate. Lengths should not include the lengths of turnouts at the ends of the Section, or the lengths of 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 a fully configured Layout Editor panel be present to provide layout connectivity information. Some of the automatic running requirements are strongly recommended for manual running also. Requirements are explained below:

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.