JMRI: Transits Documentation
This document describes the characteristics of Transits. Sections and Transits provide the foundation for the Dispatcher tool.
- Using the Transit Table
- Add/Edit Transit
- Transit Actions
- Sections Documentation
- Dispatcher Documentation
What is a Transit?
A Transit is a group of two or more connected Sections that describes a route around the layout of a Train traveling in a given direction using JMRI Dispatcher. A Section may be in multiple Transits, and may be in a given Transit multiple times. Sections are kept in order—the first Section is connected to the second, the second is connected to the third, etc. That means a Section in a Transit must be connected to the Section before it (if there is one) and to the Section after it (if there is one). The order of the Sections determines the direction of travel in the Transit. Trains travel from Sections with lower sequence numbers toward Sections with higher sequence numbers. Normally Transits would only be defined for mainline track, and sometimes staging yard track.
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. Transits also provide for reverse loops. To provide for back-and-forth running, e.g. for trolley cars, an option is provided in Dispatcher to automatically reverse the direction of running through a Transit when the Train reaches the end of its Transit, and have the Train run in reverse to the beginning of its Transit.
Transits support both Manual and Automatic operation of Trains. When a Train is running in automatic mode, Transits provide for Actions to be activated when the Train reaches a designated Section in the Transit. An Action may be initiated by a number of events, for example, when the Train enters a Section, or when the Train stops. A variety of actions are possible, such as pausing the Train for a user-designated number of fast clock minutes (a station stop), reverting to manual mode for local manual operation, or sounding the horn on a sound decoder.
How are Transits Activated and Used?
Transits are static objects. They specify itineraries for Trains to follow around the layout. Transits do not run trains, or keep track of running trains. A Transit becomes part of the train running process when it is activated by being assigned to an Active Train. Transits are saved as part of a Panel/Configuration file, only need to be set up once, and can be reused. Active Trains, on the other hand, are dynamic and transient. Active Trains are not saved to disk, and must be set up each time they are used.
Transits are activated in the Dispatcher window, where a Transit is linked to a Train to create an Active Train. When an Active Train is created, a Transit is selected, a Train is selected, and a starting Block (Train location at start) and ending Block (Train location when travel is complete) are specified, along with options. This process results in an Active Train, which can then be dispatched. A Transit may be used by only one Active Train at a time. When an Active Train is done, its Transit is deactivated, and may be reused for a subsequent Active Train.
A Train may start from a Block outside of the Transit, but connected to a Block within the Transit, or 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. The only exception to this is the back-and-forth option that allows a train to run in reverse through its Transit back to the beginning of the Transit.
When an Active Train is initiated, an allocation request is placed for a starting Section. If the Section is free, the Section will be allocated to the train. Allocation means that the Section is assigned the Active Train, and the train is authorized by the dispatcher to proceed to the end of that Section.
When an Active Train is created, it may be activated for running by an engineer using a throttle, or automatically by a virtual engineer. Dispatching consists of allocating Sections, one by one, to the Active Train. The actual dispatching may be done by a dispatcher sitting at the computer running JMRI, or semi-automatically by the computer. If a requested Section is currently in use, a request for assignment is placed in the dispatcher's queue. When a Section is freed, the queue is scanned for the highest priority train requesting it.
Transits contain 2 or more Sections which contain one or more blocks with connectivity supplied by paths. The paths are derived from a Layout Editor panel. Therefore a Layout Editor panel of your layout with Blocks assigned is required to create the necessary path information. See Layout Editor for details on creating a Layout Editor panel.
How to setup Transits
Displaying and creating Transits
All the Transits that JMRI knows about can be viewed using the Transit Table. Select Transits in the Tables submenu of the Tools menu of the main JMRI program window.
Transit Table Controls
Below the Transit Table there's an Add... button.
Creating a new Transit
To Create a new Transit, click the "Add..." button at the bottom of the Transit Table pane.
Saving Transits to disk
Use the Store item in the File menu of the Transit Table (or the Store Panels... item in the Panels menu of the main JMRI window) to save Transit information to disk. This information is saved with the configuration and panels in an XML file, along with control panel setup and similar stuff. To store your panels in the same file (recommended), select File>Store>Store Configuration and Panels To File... or select Panels>Store Panels... in the main JMRI window.