The Section Table

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. A Block may be in multiple Sections. All Blocks contained in a given 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 be used for dispatching, either manual dispatching (by a dispatcher sitting at a panel), or automatic dispatching by the computer. Dispatching may be used for trains run by engineers with a throttle, and/or for trains run automatically by the computer.

A Section has a direction defined by the sequence in which Blocks are added to the Section. 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 defined when setting up its Entry Points (see below).

A Section has two or more Entry Points. An Entry Point defines a connection to a Block outside of the Section. Entry Points are derived from Paths of Blocks in the Section--Paths that represent connections to Blocks not contained in the Section. Entry Points are grouped according to whether entering the Section at that Entry Point will result in a train traveling in the "forward" direction, or whether entering at that Entry Point will result in a train traveling in the "reverse" direction.

Sections are designed so that a Section of sufficient length may be allocated to more than one train provided the trains are traveling in the same direction. There must be at least one block between trains traveling in the same direction in a Section. Note: Allocating a Section to two trains at the same time is not currently supported by Dispatcher.

Requirements for using Sections

Sections may be used with a Panel Editor panel, with a Layout Editor panel, with a CTC machine, or directly without any panel provided. Sections build on JMRI's Blocks and Paths structure. So Before attempting to create any Sections, you should have Blocks and Paths fully initialized for your layout. (An easy way to automatically initialize your Blocks and Paths is to sketch out a Layout Editor panel of your layout, with blocks assigned.)

Layout blocking should be carefully planned, to provide "reasonable" Sections--Sections that make sense for a dispatcher to allocate to a 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 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 below).

Support for Optional 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, i.e. when the state of the Section is FORWARD, the Forward Sensor is INACTIVE and the Reverse Sensor is ACTIVE. These sensors may be used to force signals for travel in their respective directions to RED when they are ACTIVE. When a Section is FREE, both of its direction Sensors are ACTIVE. Tools are provided to automatically add direction sensors to signal logic ( see below).

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. 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.

Using the Section Table to Display and Create 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. There are eight columns in the Section Table:

System Name - The system name is assigned to the Section when it's created, and can't be changed.
User Name - If you're interested in having your Sections carry "human readable" names, you can click in the "User Name" column and change that information to whatever you want.
State - The state of a Section tells whether a section is "allocated" or "in use" by one or more trains. The state of a newly added section is always FREE. When a Section is allocated for travel in the direction from the "First Block" toward the "Last Block", the state is FORWARD. When allocated for travel in the opposite direction, the state is REVERSE.
Comment - This column is for your use to record any comment you may want to use to keep track of your Sections. It is for information only.
Click the Delete button in a specific row to delete the Section in that row. Remember to remove any Transits associated using this Section. Any Transit that uses a deleted Section will be broken! Use this button with caution!
First Block - This column displays the first block in the Section. Since a section is a group of one or more connected blocks, there is always an entry.
Last Block - This column shows the final block in the Section. Since a section may contain only one block, this entry may be the same as the Begin Block entry.
Click the Edit button in a row to view or change entered information for a Section. System name cannot be changed. User name may be changed, blocks may be redefined, entry points may be reconfigured, etc. Only one Section may be edited at a time. A Section may not be edited if another is being created.

To Create a new Section, click the "Add.." button. A window will be brought up that will allow you to define the blocks included in the new Section, and if necessary, designate which entry points to the section result in travel in the FORWARD and REVERSE directions.

Currently the user must manually select FORWARD or REVERSE for each Entry Point after all Blocks are added to a Section. The program will set some directions automatically, but others are left as UNKNOWN. An Entry Point should be set to FORWARD if a train entering the Section at that Entry Point would be traveling in the FORWARD direction. Otherwise it should be set to REVERSE. A possible future addition is to set directions of Entry Points automatically from the connectivity found in a Layout Editor panel.

For Sections with more than one Block, travel from a lower-numbered block to a higher-numbered block is FORWARD travel. Stated a different way, moving from a block higher in the block list to a block lower in the list is FORWARD travel. Similarly moving from a higher-numbered block to a lower-numbered block is REVERSE travel. For Sections with only one block, it doesn't make any difference which direction through the Section is designated FORWARD, as long as

All Entry Points must be consistent. That is:

REVERSE and FORWARD directions of travel must be opposite.
Entering at any FORWARD Entry Point must result in travel in the same direction as entering at all other FORWARD Entry Points.
Entering at any REVERSE Entry Point must result in travel in the same direction as entering at all other REVERSE Entry Points.

WARNING: if Entry Points are not consistent strange behavior may result when using the Section.

Section Table Tools

The Section Table has a Tools menu to facilitate use of Sections. Normally these tools would be used after all Sections are defined. The menu items and their use are described below:

Validate All Sections... - When this item is selected, each Section is tested for self consistency. Current tests include checking the connectivity between multiple blocks, checking that there are no missing Entry Points or extra Entry Points, and, if a Layout Editor panel is available, checking that Paths are correctly set up for the Blocks in the Sections. This tool does not check if the FORWARD and REVERSE directions are correctly set for each Entry Point, but that feature is a planned future addition. After testing is complete a message is displayed giving the results of the testing. Detailed error messages, if any, are placed in the JMRI error log.

Set Direction Sensors in Logic... - When this item is selected, direction sensors defined for each Section are placed in the signal logic of appropriate signal heads--those signal heads internal to the Section or protecting entry to the Section. Direction sensors follow the allocation status of their Sections. When a Section is FREE (not allocated), both of its direction sensors are set ACTIVE. By placing these sensors in appropriate signal head logic, all signals internal to or protecting entry points to the Section are forced RED when the Section is FREE. When a Section is allocated for travel in the FORWARD direction, its forward direction sensor is set INACTIVE, allowing signal head logic to function normally for travel through the Section in the FORWARD direction, but keeping signals governing travel in the REVERSE direction set RED. Similarly, when the Section is allocated for travel in the REVERSE direction, the reverse direction sensor is set INACTIVE, and the forward direction sensor is set ACTIVE, allowing signals to clear travel in the REVERSE direction, but to block travel in the FORWARD direction. Setting of direction sensors is done automatically by software in Dispatcher that allocates Sections.

This tool should only be used after all Sections have been defined and all signal head logic has been set up. A Layout Editor panel is required, because the software needs the panel's connectivity to figure out which signal heads need which direction sensor. If a direction sensor is already in the Simple Signal Logic (SSL) for a signal head, it is not duplicated. However, if an incorrect direction sensor is in the SSL, it is not removed. (Use the tool described below to remove direction sensors.) After placing direction sensors is complete a message is displayed giving results. Detailed error messages, if any, are placed in the JMRI error log. When an error occurs, the most common reasons are 1) missing information (signal heads missing or signal logic not set up) or 2) errors in setting up Section Entry Point directions.
Remove Direction Sensors from Logic... - This tool assembles a list of all direction sensors defined in Sections currently in the Section Table, then removes all sensors that are contained in this list from the Simple Signal Logic (SSL) of all signal heads. This tool cancels the effect of the Set Direction Sensors in Logic... tool, and in addition removes any defined direction sensors that might be in an incorrect SSL. If errors were noted while setting direction sensors using the above tool, then corrected, running this tool before attempting to set direction sensors again is sometimes useful.

A Layout Editor panel is required to run this tool. After removal of direction sensors from signal logic is complete a message is displayed giving the results of running the tool. Detailed error messages, if any, are placed in the JMRI error log.

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. 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.