Package jmri

Class Block

All Implemented Interfaces:
Comparable<NamedBean>, PropertyChangeProvider, NamedBean, PhysicalLocationReporter
Direct Known Subclasses:

public class Block
extends AbstractNamedBean
implements PhysicalLocationReporter
Represents a particular piece of track, more informally a "Block".

A Block (at least in this implementation) corresponds exactly to the track covered by at most one sensor. That could be generalized in the future.

As trains move around the layout, a set of Block objects that are attached to sensors can interact to keep track of which train is where, going in which direction. As a result of this, the set of Block objects pass around "token" (value) Objects representing the trains. This could be e.g. a Throttle to control the train, or something else.

A block maintains a "direction" flag that is set from the direction of the incoming train. When an arriving train is detected via the connected sensor and the Block's status information is sufficient to determine that it is arriving via a particular Path, that Path's getFromBlockDirection becomes the direction of the train in this Block.

Optionally, a Block can be associated with a Reporter. In this case, the Reporter will provide the Block with the "token" (value). This could be e.g an RFID reader reading an ID tag attached to a locomotive. Depending on the specific Reporter implementation, either the current reported value or the last reported value will be relevant, this can be configured.

Objects of this class are Named Beans, so can be manipulated through tables, have listeners, etc.

The type letter used in the System Name is '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 tracking 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 a 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.

Possible state values:

  • UNKNOWN - The sensor shows UNKNOWN, so this block doesn't know if it's occupied or not.
  • INCONSISTENT - The sensor shows INCONSISTENT, so this block doesn't know if it's occupied or not.
  • OCCUPIED - This sensor went active. Note that OCCUPIED will be set even if the logic is unable to figure out which value to take.
  • UNOCCUPIED - No content, because the sensor has determined this block is unoccupied.
  • UNDETECTED - No sensor configured.

Possible Curvature attributes (optional) User can set the curvature if desired for use in automatic running of trains, to indicate where slow down is required.

  • NONE - No curvature in Block track, or Not entered.
  • GRADUAL - Gradual curve - no action by engineer is warranted - full speed OK
  • TIGHT - Tight curve in Block track - Train should slow down some
  • SEVERE - Severe curve in Block track - Train should slow down a lot

The length of the block may also optionally be entered if desired. This attribute is for use in automatic running of trains. Length should be the actual length of model railroad track in the block. It is always stored here in millimeter units. A length of 0.0 indicates no entry of length by the user.