JMRI® is...
JMRI tools for working with your layout:
Layout Automation
Use JMRI to automate parts of your layout and operations:
Supported Hardware
JMRI supports a wide range of DCC systems, command stations and protocols.
By the community of

JMRI Help:

Contents Index
Glossary FAQ

Donate to

JMRI: Block Tracking

Background Information

Model railroad control systems generally can't tell you which train occupies a particular piece of track at any given time.

This is unfortunate, because there are lots of reasons you might want to know. For example, you might want to command any train that reaches a particular red signal to stop. But you can't do that unless you know which train it is that is reaching the signal.

JMRI provides experimental tools for tracking trains as them move around on the layout.

Basic Concepts

Imagine a simple loop of track that's been wired with occupancy sensors on individual segments of track, which we'll call "Blocks". Imagine the train is in Block A, and will shortly move to Block B, then C.

At first the sensor for Block A is showing active. As the train moves into Block B, the Sensor for B will go active. When the train has completely left A, it's sensor will go inactive etc.

Although a particular Block only knows whether it's active or not (occupied or not), by also looking at the occupancy of the adjacent Blocks it can tell more. In the example above, if the code knew that train 321 was in Block A, when Block B goes active, the program can infer that 321 is now also in Block B.

This doesn't always work, unfortunately. Imagine the case above, where there is both a train in Block A and also a train in Block C. When Block B goes from inactive to active (unoccupied to occupied), which train moved in? The one from A, or the one from C?

Some of this ambiguity can be removed by careful arrangement of the detection Blocks, by accepting limitations on how trains can run (or how short Blocks have to be), and by using more intelligent logic that thinks about the direction and priority of trains. But it's clear that even straight track poses some problems.

Turnouts add an additional layer of complexity. Imagine a train is sitting in the Block next to the normal (closed) route, and another is sitting in the reversed (thrown) route. When the occupancy Sensor for the Turnout goes active, which Train has entered the Turnout track? That depends on which way the Turnout is set, so the program needs to be able to consider that information too.

JMRI Block Tools

JMRI provides a "Block" class to handle the tracking.

Note that this is test code, and not all features are completely present. For example, you cannot store Block objects in a Configuration file; they must be manually created in your scripts. This limitations will be removed with time.

Block Table

The Block Table lets you see the status of your Blocks.


There is no functional requirement for a type letter in the System Name, but by convention we use 'B' for 'Block'. The default implementation is not system-specific, so a system letter of 'I' is appropriate. This leads to system names like "IB201".

The direction of a Block is set from the direction of the incoming train. When a train is found to be coming in on a particular Path, that Path's getFromBlockDirection becomes the direction of the train in this Block.


Do not assume that only one Block object uniquely represents a piece of track. To allow independent development, it must be possible for multiple Block objects to take care of a particular section of track.

Technical Information

For technical information, see the Javadoc pages for