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
• Glossary of Terms
• Using Transits and Sections in Dispatching Active Trains
• The Dispatcher Window
• The Active Trains Table
• The Allocation Requests Table

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 Blocks that are allocated as a unit by the dispatcher using Dispatcher functions. Blocks are usually defined to facilitate signaling on a layout. 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 (including automatic station stops for passenger trains), support for linking signals to allocation via simple APB signaling support, and automatic setting of turnouts when a section of track is allocated. Many of these functions are included in the current version of Dispatcher; others will follow in future releases of JMRI.

Central to Dispatcher is the Active Train, which carries the information needed to run a train around the layout. Basically, an Active Train is created by the dispatcher by combining a Transit with 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 any special actions that need to take place 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 specified 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, like train priority and a request to run the Active Train automatically may also be entered. More options are expected to be added in the future as more functionality is added to JMRI.

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, and 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. The Dispatcher Window is discussed in detail below.

Note: The current version of JMRI does not have automated dispatching or automatic running of trains. Those optional features will be added 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 Dispatcher use, blocking of mainline track is required. Hardware occupancy detection is optional. Dispatcher works best if hardware block occupancy detection is present, but it can work 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. 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.

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. Action on an Allocation Request can be delayed for a number of reasons, for example, if the requested Section is not FREE, but is allocated to a Active Train.

Allocated Section - A Section that is currently assigned to an Active Train. 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 window listing all Allocated Sections may be displayed by clicking a button in the Dispatcher window. This Allocated Section window is where Sections are released manually by the dispatcher.

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.

An Active Train usually starts from a Block outside of the Transit, but connected to a Block within the Transit. Optionally a train may start from a Block within a Section in the Transit. A train moves through a Transit in only one direction-- defined by the order in which Sections are included in the Transit. Trains move from lower sequence number Sections toward higher sequence number Sections. 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 as needed 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 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 Allocation Request table in the Dispatcher window.

Transits provide for a special action to be performed when a train is in a Section. Currently two special actions are supported: Pause for a user-designated number of fast clock minutes, and Await a manual restart. The Pause action may be used for automatic station stops. The Await action is designed to support an engineer doing work in a specified Section, and requesting a restart when the work is complete. More actions may be added in the future as needed.

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, two Active Trains have been created. The top Active Train, ATSF4581, has been allocated a Section and is RUNNING. The second Active Train, SP234 is WAITING for its first allocation. An Allocation Request has been entered for the first Section needed by SP234. The requested Section is FREE and UNOCCUPIED, so it could be allocated by clicking the Allocate button in the lower table or the Allocate Next button in the upper table.

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

• New Train... - Click this button to bring up an Activate New Train window that allows the dispatcher to create an Active Train. The Train source used by this window is set in the Options window. More information on creating new Active Trains may be found in the help file for the Activate New Train window, along with a simple procedure to follow when creating an Active Train. Options should not be changed with the Activate New Train window open.

• Show Allocations... - Click this button to bring up a window containing a table that displays all Sections currently allocated to Active Trains. The Allocated Sections window displays information about each Allocated Section and provides for release of Allocated Sections. This table is in a separate window, instead of being included in the Dispatcher window to allow more flexibility in placing windows on the computer screen.

• Allocate Extra... - Click this button to bring up a window that allows the dispatcher to allocate Sections to an Active Train that may not be the "next" Section in the Active Train's Transit. Any Section that is FREE and is connected to an Allocated Section of the Active Train may be allocated to the Active Train using this window. More information and a simple procedure for allocating extra Sections may be found in the help file of the Allocate Extra window.

• Terminate Train... - Click this button to terminate an Active Train. A small window appears to allow the selection of which Active Train the dispatcher wants to terminate. When an Active Train is terminated, all Sections allocated to it are automatically released. The Train and Transit are freed up to be used in other Active Trains as needed.

  An Active Train is usually terminated when it reaches its destination Block, however, it may be terminated at any point during its transit of the layout. The dispatcher is responsible for deciding whether it is appropriate to terminate an Active Train before it reaches its destination.

Dispatcher options allow tailoring of the dispatcher function. Options are accessed via the Dispatcher window's Options menu. Descriptions of currently available options, the Options menu, the Options window are contained in the Options help file.

The Active Trains Table

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

• Transit - The name of the Transit of the Active Train is shown. The displayed name is the system name followed by the User Name in parentheses.

• Train - The name of the Train of the Active Train is shown.

• Train Status - Active Train status is displayed here. An Active Train may have any one of the following statuses:

  • RUNNING - Actively running on the layout, according to its mode of operation.
  • PAUSED - Paused waiting for a user-specified number of fast clock minutes. The Active Train is expected to move to either RUNNING or WAITING once the specified number of minutes has elapsed. This is intended for automatic station stops.
  • WAITING - Stopped waiting for a Section allocation. This is the status the Active Train is in when it is created.
  • WORKING - Performing work under control of a human engineer. This is the status an Active Train assumes when an engineer is picking up or setting out cars at industries or in a yard.
  • READY - Indicates the Active Train has completed WORKING, and is awaiting a restart - dispatcher clearance to resume running.
  • DONE - Indicates the Active Train has reached its destination and is ready to be terminated by the dispatcher.

  Not all Active Trains will use all the above statuses.

  Note: In the current version of Dispatcher all statuses are not implemented. More statuses will be implemented as functionality is added in future JMRI versions.

• Mode - Mode of operation of the Active Train is displayed. The following modes are allowed:

  • DISPATCHED - Indicates the Active Train is run by an operator using a throttle. A dispatcher will allocate Sections to the Active Train as needed, control optional signals using a CTC panel or computer logic, and arbitrate any conflicts between Active Trains. If signals are present, the operator is expected to follow signals as set by the computer or the dispatcher.
  • AUTOMATIC - Indicates the Active Train will be run under automatic control of the computer. Under AUTOMATIC running, the computer is expected to follow signals set by the dispatcher. Automatic station stops will occur, as described above. If the Active Train reaches a Section where work must be done (e.g. setting out or picking up cars), the mode of operation changes to MANUAL until the work is complete. Restarting from MANUAL work changes the mode back to AUTOMATIC.
  • MANUAL - Indicates an Active Train running in AUTOMATIC mode has reached a Special Action in its Transit that requires MANUAL operation. When this happens, the status changes to WORKING, and the mode changes to MANUAL. While in MANUAL mode, the Active Train is run by an operator using a throttle. AUTOMATIC running is resumed when the work has been completed.

  Note: In this version of Dispatcher, only DISPATCHED mode is implemented. Automatic running of Active Trains will be added in a future release of JMRI.

• Allocated Section - Displays the name of the Section of the Transit that was last allocated to this Active Train.

• Next Section - Displays the name of the Section of the Transit that will need to be allocated next.

• Allocate Next Button - Click this button to request that the Section shown in the Next Allocation column be allocated to this Active Train. If the Section is FREE and not occupied it will be allocated immediately, and the Sections in the Allocated Section and Next Section columns will be updated.

  If the Section is not FREE, an Allocation Request will be entered into the Allocation Requests table (see below). If the Section is FREE, but is OCCUPIED, the dispatcher will be queried. The dispatcher is responsible for deciding whether an OCCUPIED Section should be allocated. If the Next Section is the first Section to be allocated, and the Active Train is occupying that Section, Dispatcher knows that allocating the OCCUPIED Section is appropriate, so the dispatcher is not queried.

The Allocation Requests Table

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

• Active Train - Shows the Active Train requesting the Section. Active Train names are displayed in either short form (shown above) or long form depending on the option selected in the Dispatcher's Options window.

• Priority - Shows the priority of the Active Train requesting the Section. Larger numbers are higher priority. If two Active Trains are requesting the same Section, the higher priority Active Train would normally take precedence.

• Requested Section - Shows the name of the requested Section.

• Section Status - Shows the allocation status of the requested Section. The Section will be either:

  • FREE - Available for allocation.
  • ALLOCATED - Allocated to a different Active Train.

• Occupancy - Shows the occupancy of the requested Section. Three entries are possible:

  • UNOCCUPIED - Nothing is detected in any Block of the Section. (The occupancy sensors of all Blocks in the Section are INACTIVE.)
  • OCCUPIED - Something is detected in one of the Blocks of the Section. (The occupancy sensor of at least one Block in the Section is ACTIVE.)
  • UNKNOWN - The occupancy status of at least one of the Blocks of the Section is not known. This indicates that the occupancy sensor of at least one Block in the Section is neither ACTIVE nor INACTIVE. - OR- The Dispatcher option "Layout has block detection hardware" is not checked - see Dispatcher Options.

• Allocate Button - Click this button to request immediate allocation of the Section to the requesting Active Train. If the Section is FREE, and if the Section occupancy is either UNOCCUPIED or UNKNOWN, the Section will be allocated to the requesting Active Train. If the Section is FREE, but the Section is OCCUPIED, the dispatcher is prompted to either override the occupancy or wait.

  If the Section is ALLOCATED to another Active Train, the button click will be ignored. A Section may be allocated to only one Active Train at a time. If an ALLOCATED Section needs to be reallocated to a different Active Train, it must first be released. (See the Allocated Sections window help file for instruction on releasing Allocated Sections.)

  If "Use connectivity ..." is checked in the Options window, Dispatcher will check that turnouts are set correctly before actually allocating a Section. If turnouts are not set correctly, Dispatcher will attempt to set the turnouts if Auto Set Turnouts is checked in the Options menu (or checked in the Options window). If turnouts are not set correctly, the dispatcher is warned and given the option of overriding the turnout check and proceeding with allocation of the Section. For more information see Dispatcher Options.

• Cancel Button - Click this button to delete the Allocation Request without allocating the requested Section.

---