Warrants: The Occupancy Block Tables


The Occupancy Block (OBlock) Tables were developed to define the elements needed to create "Warrants" that allow trains to run automatically over predetermined routes. It was also a design goal to generate these routes automatically by merely specifying the origin and destination of Trains. Furthermore, it was designed for use by Logix so that users can define and control automated Trains running from Panel Editor panels of their own design.

What are Portals and why use them?

Occupancy Blocks, or more properly named "track circuits", are portions of track having one or more Sensors to detect occupancy by Trains. These rail blocks, called OBlocks, are usually separated by gaps cut in the track which isolate the detecting sensors. However this is not always the case, since optical sensors might also be used to detect occupancy in a section of track. But whatever method is used to determine a block and the means of detecting its occupancy, there is some point that separates one block from another block. This dividing line between two blocks, whether a physical gap or an imaginary line, marks a transition from one block to another. These transition points are called Portals.

Undoubtably you created Blocks on your layout because it was important for you to know when one section of track was exited and another was entered. One or more track circuits might be grouped together to make a prototypical Block, i.e. a section of track whose use is governed by signals. This can provide Interlocking. The Signals governing a Block are logically placed at the Portal points. If you have signals on your layout, consider where they are located. Most likely they are placed near dividing points between Blocks. So regardless of the name, Portals are a significant concept.

OPaths through Portals

There may be many ways to traverse an OBlock. For example, in the diagram below both OPaths 31a and 31b traverse Block 31.
A Path within a Block will enter at one Portal and exit through another Portal. See for example Path 31b in the diagram, which enters Block 31 through Portal 2-31b and exits via Portal 31-5.
Or a Path may terminate within the Block, that is, the Path is a spur. Again, Portals are a useful concept to indicate these entrance and exit points.

Note that a Path must have at least one Portal for an entry/exit point and cannot have more than two Portals. A Path is unambiguously defined by specifying the Turnouts and their settings for a Train to proceed safely through the Block.

OBlock Portals Paths Concept Track Diagram


Warrants and the Occupancy Tables use the following elements: How OBlocks, Portals and OPaths are used is described in the Warrants Help. You may want to browse that before reading further.

OBlocks, Portals and OPaths can be created and edited using the methods described below, or they can also be created and edited from a WYSIWYG graphical interface described in the Circuit Builder Help.

Circuit Builder can be used you if you have a Control Panel Editor track diagram using track icons showing your layout. Otherwise you will need to use the tables below. See Creating and Editing OBlocks, Portals and OPaths for more details on using the tables.

Tables to edit Occupancy Block, Portals and Path

In JMRi Preferences > Display you can choose your preferred interface to edit these items in tables (restart required):

Tabbed OBlock GUI

since 4.21.3

The information in the tables is basically the same as you find in the desktop style, but instead of an empty bottom row. New items are added by clicking one of the [Add...] buttons below the tables. This opens up a pane to configure all items for a new OBlock etc. Feedback in the status bar and tooltips assists to fill in the correct information.
When you are done, click [Create] to complete the definition in JMRI, after which it shows up as an extra row in the table.
To edit an item in one of the tables, click the [Edit] button at the end of its table row.
To prevent duplication, please refer to the detailed description of all items below.
Specific help is accessible via the Window Help menu.

Desktop OBlock GUI

The tables to edit OBlocks etc are contained within a single frame that can be minimized or closed. The individual table frames can be minimized within this parent frame using the familiar OS window buttons.

Each of the tables in the Occupancy Block, Portal, Path Frame has a bottom row with blank entries. Entering data into these entries and pressing the 'Enter' key will create a new item in the table. 'Drag and Drop' and 'Copy and Paste' are implemented to provide easy ways to move text from table to table.

Columns in the Occupancy Block Table

Each Occupancy Block on your layout should be entered as a row in this table, listing:

This table is initially sorted by the System Name of the OBlocks. This means that when a new row is added the entry will jump to its position in the sort. After entering a new OBlock, you may find it at the top of the window should you need to do further editing.
since 2.12You can sort the table by clicking on a column header.

Several columns are hidden in the OBlock table. To hide/unhide a column, right click in the Header portion of the table.

Columns in the Portal Table

The Portal table has columns for the blocks each portal separates. You do not need to be concerned about the direction of travel through the portal. It does not matter which side of the portal the blocks names are entered, since the algorithms that compute train routes will decipher the correct entrance and exit points.

This table is sorted by Portal Name. This means that when a new row is added the entry will jump to its position in the sort. After entering a new Portal, you may find it at the top of the window for further editing.

Columns in the Signal Table

For each signal on your layout, make an entry in the Signal Table. This Signal will control the actions of any warranted train - changing its speed according to the Signal's indication when the train reaches the Portal where the signal is placed. That is, the Signal 'protects' the Blocks beyond the Portal. The Signal may be either a Signal Mast or a Signal Head.

How Signal Aspects change Speed

A Warrant detects the signal Aspect when it's train enters the approach Block and - if needed - prepares to change the speed before it reaches the protected Block. Any speed change is ramped down to the speed required by the Signal. The Warrant calculates when the speed ramp-down should begin using the parameters involved with the Speed Profile or throttle factor of the engine (see Warrants). The point where the speed change should complete can be adjusted (+/-) by the above Length amount, should that be desirable.

Likewise, when the Signal indicates a Clear or increased speed from a stopped or reduced speed condition, the speed will be ramped up to the allowed or recorded speed.

Columns in Block-Path Tables

Each Block in the Occupancy Block Table will have one or more Paths in it. Pressing the Paths button in a row of the Occupancy Block Table will open this table. Direction of the path is immaterial. 'from' and 'to' do not have to correspond to any particular side of the Block; they are just Portal names for the Path that traverses from 'this portal' to 'that portal'.

Columns in Block-Path-Turnout Tables

If the Path crosses a Turnout, then it is necessary to have the Turnout in the correct position in order to traverse the Path. This table is used to define these settings (if the path does not cross any turnouts, this table is left empty). Note there will be lots of these tables, one for each path in each Block of the Occupancy Block Table.

Columns in the Block-Portal Cross Reference Table

This is a read only table to assist in identifying all the Portals to a Block. It lists all the Portals that have been defined for each Block, grouped under each Block heading. It is opened from the Show Block-Portal Cross Reference menu item.

Menus of the Occupancy Block, Portal, Path frame

The File menu

This menu has the standard menu items for saving configuration files and panels.

The Edit menu

This menu has the standard menu items for Cut, Copy and Paste.

The Tables menu

This menu has items to open the tables in the Occupancy Block, Portal, Path frame:

The Windows menu

This menu has the standard menu items for opening JMRI window frames.

The Help menu

This menu has the standard menu items for JMRI help.

Further Reference

To read about how OBlocks, Portals and OPaths can be used to generate train Routes and make automated train Scripts, see Warrants.

See Creating and Editing OBlocks, Portals and OPaths for more details on using these Tables.

See Circuit Builder for creating and editing OBlocks, Portals and OPaths from a graphical representation of your track plan.