Warrants: The Occupancy Block Tables
The Occupancy Block (OBlock) Tables were developed to define the elements needed to create
" 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
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
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.
Warrants and the Occupancy Tables use the following elements:
Blocks are implemented in JMRI as OBlocks, which are extensions of JMRI
Blocks. They have the following characteristics:
- An OBlock has from 1 to N Portals.
- Although an OBlock can be defined without a Sensor, i.e. a "Dark Block", it should
have a Sensor. If it has more than one Sensor, these Sensors should be "OR"ed together
and trigger a single internal Sensor for the Block.
- An OBlock has from 1 to M OPaths.
- An OBlock has 0 to K PathTurnouts.
Portals separate Blocks. They have the following characteristics:
- A Portal has exactly two Blocks (no more, no less)
- A Portal serves both directions of travel.
- A Portal may have 0 to 2 Signals. If a Portal has a Signal, it faces one of its
Blocks. A second Signal, if it exists, faces the other Block. Each Signal controls the
movement of a Train exiting the Block it faces and thus the entrance of the Train to
the other Block.
Paths traverse a Block. They are implemented as JMRI OPaths, which are
extensions of JMRI Paths. They have the following characteristics:
- An OPath has 0 to N Path Turnouts, each with a defined state allowing a Train to
follow the Path.
- An OPath has at least one, and no more than two, Portals.
- An OPath serves both directions of travel, so no duplicates are needed to travel N
How OBlocks, Portals and OPaths are used is described in the Warrants
Help. You may want to browse that before reading
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):
- As a "tabbed" set in the regular JMRI Tables style, with dedicated editing panels and
combo-boxes to select items already defined in JMRI:
- As a virtual "desktop" of windows grouped table windows, supporting Drag-n-Drop and
in-table editing and validation
Tabbed OBlock GUI
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
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:
- System Name: The System Name of the OBlock. The system letter 'O', and
type letter 'B' is used for 'OBlock' although the implementation is not
If these letters are not entered they are automatically prepended.
- User Name: The User Name of the OBlock.
- Comment: You may enter any text in this field you wish.
- Sensor: The Sensor that detects occupancy of the Block.
- State: Shows a bit map of the Occupancy Sensor's state. Click on the
cell to see the word values.
- Length: The length of the Block (see next line for units). This is an
important parameter if you use NX Warrants.
- Units: The unit used to determine the length (inches or
- Speed Notch: An optional speed limit for the Block. A drop-down box
lists the Signal Aspects controlling speed. A blank entry indicates any speed restriction
will continue to be enforced. This should be the typical setting. "Normal" indicates speed
will return to the previous normal speed.
- Paths: A button that opens the Block-Path Table where
the Paths of this Block are entered. This table is described below.
- Delete: A button to delete the Block. To make the deletion permanent,
save your configuration file to disk
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
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.
- Block Name: The user or system name of the OBlock on one side of the
- Portal Name: The portal name. The names of portals must be
- Block Name: The user or system name of the OBlock on the other side of
- Delete: A button to delete the Portal. To make the deletion permanent,
save your configuration file to disk
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.
- Signal Name: Enter the name of the Signal, either the System Name or
User Name (In the case where the same name is used for both a Signal Mast and Signal Head,
the Signal Mast will be chosen by the program).
- From (Approach) Block: Enter the name, either System Name or User
Name, of the Block that the Signal faces. The Signal controls the movement of a Train
exiting from the approach Block and entering into the protected Block.
- (Through) Portal: Enter the name of the Portal where the Signal is
- To (Protected) Block: Enter the name, either System Name or User Name,
of the Block whose entrance is protected by the Signal.
- Offset: (Optional) The distance added (or subtracted for negative
values) to the point where a speed change required by the Signal's Aspect should begin.
Often this equals the distance from where the mast of the signal is placed to where the gap
of the Block it protects is.
- Units: The unit used to determine the offset length (in inches or
centimeters, click to convert).
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'.
- From Portal: The Portal name of one entrance/exit point of the
- Path Name: The name of the Path. Path names only have to be unique
within the Block. E.g, "Westbound Main" could be used as the Path Name in all the Blocks of
the "Westbound Main" on your layout.
- To Portal Name: The Portal name of the other entrance/exit point of
Turnouts: A button that opens the Block-Path-Turnout
table, where the turnouts that define the Path are entered. This table is described
- Delete: A button to delete the Path. To make the deletion permanent,
save your configuration file to disk
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.
- System/User Name: The System Name or User Name of the Turnout in the
- Turnout Setting: the position of the Turnout to make the path
- Delete: A button to delete the Turnout settings. To make the deletion
permanent, save your configuration file to disk
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
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:
- Show Occupancy Block Table: Opens the Occupancy Block window, if it is
minimized. This table cannot be closed.
- Show Portal Table: Opens the Portal window, if it is minimized. This
table cannot be closed.
Show Block-Portal Cross Reference: Opens a
table window that cross references Portals to their Blocks. It organized per Block,
showing all the portals attached to the block. It is a counterpoint to the Portal Table
which is organized per portal.
- Open Block-Path Tables: This is a cascading menu that opens a Path
pane for a Path from a Block. Most likely there will be so many of these panes that the
menu will be larger than the screen.
It is probably easier to open these panes from the Paths button in a row
of the Occupancy Block table.
- Open Block-Path-Turnout Tables: This is a cascading menu that opens a
Turnout pane for a Path from a Block. Most likely there will be so many of these panes that
the menu will be larger than your screen.
It is probably easier to open these panes by clicking on the Turnout
button in a row in a Block-Path Table window.
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.
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.