Author: Bob Jacobsen
Keywords: java model railroad JMRI Block tracking

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

### Issues

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.

Issues:

- Doesn't handle a train pulling in behind another well:
  - When the 2nd train arrives, the Sensor is already active, so the value is unchanged (but the value can only be a single object anyway)
  - When the 1st train leaves, the Sensor stays active, so the value remains that of the 1st train
- The assumption is that a train will only go through a set turnout. For example, a train could come into the turnout Block from the main even if the turnout is set to the siding. (Ignoring those layouts where this would cause a short; it doesn't do so on all layouts)
- Does not handle closely-following trains where there is only one electrical Block per Signal. To do this, it probably needs some type of "assume a train doesn't back up" logic. A better solution is to have multiple sensors and Block objects between each signal head.
- If a train reverses in a Block and goes back the way it came (e.g. b1 to b2 to b1), the Block that's re-entered will get an updated direction, but the direction of this Block (b2 in the example) is not updated. In other words, we're not noticing that the train must have reversed to go back out.

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

- Block - represents each Block and its connections
- Path - represents the connections to and from another Block, including any Turnout settings, etc, that are needed.