JMRI: Sections Documentation
This document describes the characteristics of Sections. Sections and Transits provide the foundation for the Dispatcher tool.
What is a Section?
A Section is a group of one or more connected Blocks that may be allocated to a train traveling in a given direction. Sections were created to solve the direction problem that can occur when using Blocks directly. A Section has only two directions, "forward" or "reverse". Sections can be traversed by a Train in either direction. Section direction is independent of the direction set for the locomotive by a throttle. In addition to solving the direction problem, Sections offer the user other useful features.
Sections can be considered an extension of Blocks. Many Sections contain only one Block. All Blocks contained in a multi-Block Section must be different. Blocks are kept in order--the first block is connected to the second, the second is connected to the third, etc. That means a Block in a Section must be connected to the Block before it (if there is one) and to the Block after it (if there is one), but may not be connected to any other Block in the Section. A Section may not contain any reverse loops.
Sections and their associated Transits are designed to provide support for dispatching, either manual dispatching (by a dispatcher sitting at a panel), or automatic dispatching by the computer. Dispatching is the temporary allocation of Sections for the exclusive use of a train, either run by an engineer with a throttle, and/or run automatically by the computer. Support for dispatching is provided by Dispatcher, which also provides for set up and running of trains automatically.
A Section's direction is defined by the sequence in which Blocks are added to a multi-Block Section. For a single Block Section the direction is chosen arbitrarily when the Section is created. A train may run through a Section in either the forward direction (from first block to last block) or reverse direction (from last block to first block). If a Section has only one Block, the direction of that Section is chosen when setting up its Entry Points (see below).
Therefore, when setting up multi-block sections, you should choose blocks in the same order across the layout for sequentially connected sections. That way, the forward and reverse directions will have consistent meaning for sections on a relative basis. For example, a loop style layout might declare clockwise to be forward. A point-to-point layout might define left to right as forward.
A Section has one or more Entry Points. An Entry Point defines a connection from a Block inside the Section to a Block outside of the Section. Entry Points are set up using Paths of Blocks in the Section--Paths that represent connections to Blocks not contained in the Section. Entry Points are classified in one of two ways:
- Whether entering the Section at that Entry Point will result in a train traveling in the "forward" direction.
- Whether entering at that Entry Point will result in a train traveling in the "reverse" direction.
Sections are designed to be allocated to one train at a time. If a portion of connected track is long enough to support multiple trains simultaneously traveling in the same direction, one following the other, that connected track should be divided into two or more Sections, if the user wants to run following trains in that area.
Direction and Stopping Sensors
Optionally, each Section may have two direction sensors, one for the Forward direction and one for the Reverse direction. These are normally internal Sensors, bearing system names that begin with IS. They automatically follow the state of their Section. A Section has three states: FREE (not allocated to a train), FORWARD (allocated for travel in the forward direction), and REVERSE (allocated for travel in the reverse direction. When the state of the Section is FREE, both direction sensors are set ACTIVE. When the state of the Section is FORWARD, the forward direction sensor is INACTIVE and the reverse direction sensor is ACTIVE. Similarly, when the state of the Section is REVERSE, the forward direction sensor is ACTIVE and the reverse direction sensor is INACTIVE. These sensors may be used in signal logic to force signals for travel in the direction opposite to the allocated direction to RED (Stop). Tools are provided in the Section Table menu to automatically add direction sensors to signal logic or to automatically remove all direction sensors from signal logic. Alternatively, if Dispatcher is being used, it can add direction sensors to signal logic as needed.
The direction sensors can also be used with Signal Mast Logic. The direction sensors are manually added or removed using the Signal Mast Logic Sensor tab. Select the direction sensor that corresponds to the direction to the destination mast and set the desired state to INACTIVE. As indicated above, the direction sensors are normally ACTIVE. This forces signal mast logic to set the mast aspect to Stop. When a transit is activated, the Forward or Reverse direction sensors for the sections in the transit are set to INACTIVE. This triggers signal mast logic to update the signal mast aspect.
Also optionally each Section may have two stopping sensors that indicate when a train in the Section has reached the end of the Section by traveling in the forward direction or in the reverse direction. Stopping sensors should be physical sensors on the layout, for example infrared point detectors. For manual dispatching, these sensors may be displayed on a panel to indicate to the dispatcher when a train has reached the end of its allocation. For automatic running, these sensors may be used to stop a train before it reaches the end of its allocated Section, and before it overruns a red signal, if signals are present.
If your signaling is based on Signal Mast Logic and the associated logic has been generated using the Layout Editor, then it is possible to also have Sections automatically generated based upon that same logic.
The tool to accomplish this can be found in the Signal Mast Logic Table | Tools | Generate Sections. Running this will immediately create Sections that each contain all of the Blocks between any already-defined Signal Mast Pairs. It will also set up each "Automatically Generated" Section so that they include those Blocks in the correct order, with the direction being set as FORWARD travel, going from the Source to the Destination Signal Mast. Please note that the Block details are not saved when the Panel is stored, but are re-created when the file is loaded.
The tool will also automatically create forward and reverse direction Sensors and place them in the Section. However the Signal Mast Logic does not use the direction sensors and their creation is only there to allow validation of the Section (or inclusion by the user in unrelated Logix if desired). If desired, they can be added to the signal mast logic as described above.
Sections generated with the tool will only have a pair of Entry Points and simply follow the Path between the two Signals.
The details of the Optional Direction and Stopping Sensors are saved when the Panel file is stored.
To use the Sections that have been built this way, you will next need to set up Transits. Following that, you will also need to set the Dispatcher to use SignalMast Logic via the Dispatcher's Options menu.
Sections build on JMRI's Blocks and Path structures. So before attempting to create any Sections, you should have Blocks and Paths fully initialized for your layout. 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.
Layout blocking should be carefully planned, to provide "reasonable" Sections--Sections that make sense for a Dispatcher to allocate to a certain Train. For right-handed or left-handed Turnouts switching mainline track, for example, this usually means including the Turnout in the same Block as the track entering at the Turnout throat, and providing separate Blocks for continuing and diverging tracks. Some users prefer to have a Turnout in a separate Block, and that works fine also. From a Dispatching perspective, tracks of mainline Turnouts that branch to industries do not need to be separately blocked, but blocking here is acceptable. A layout blocking scheme that works well for Signals, should work fine for Sections also.
Signals are not required for using Sections, but Sections will work fine with Signals installed. If Signals are installed, the direction Sensors included in Sections provide an easy way to set up simple APB signaling (see above).
How to setup Sections
Creating and Displaying Sections
All the Sections that JMRI knows about can be viewed using the Section Table. Select Sections in the Tables submenu of the Tools menu of the main JMRI program window. Sections can either be created manually from the Section Table pane, or they can be created automatically if you also plan to use Signal Mast Logic.
Section Table Controls
Below the Section Table there's an Add... button.
The Tools menu gives access to:
- Validate All Sections...
- Set Direction Sensors in Logic...
- Remove Direction Sensors from Logic...
Creating a new Section
To Create a new Section, click the "Add..." button.
Saving Sections to disk
Use the Store item in the File menu of the Section Table (or the Store Panels... item in the Panels menu of the main JMRI window) to save Section information to disk, allowing to reload it next time you run JMRI. This information (and any modified signal logic 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.