JMRI: Using Trackers
Author: Pete Cressman
Keywords: JMRI help Using Tracker

# Train Trackers

A Tracker is a means to to see the movement of trains on your layout panel. A Tracker has a marker identifying a train moving on your panel layout diagram following wherever an operator drives his train on your layout. The position of each tracked train and the time is spends occupying a block is displayed in a window. A status log is kept of the progress of the trackers.

## What's Needed to Have a Tracker

Trackers function on the same foundation as Warrants. That is, track occupation detection is by OBlocks and the directions trains move by Portals and Paths. For detailed information about what these objects are and how to make them see Circuit Builder or Occupancy Block Tables.

Next, your panel layout diagram must done with Indicator Track icons. These icons display the status of the block they represent with colors and can show names. If your diagram has already been created using regular track icons, they can easily be converted to Indicator Track icons with Circuit Builder. The Item Palette help provides more information about Indicator Track icons.

All the track of your layout should be represented with OBlocks, even the sections with no sensors. Although Tracker cannot detect when such a "dark block" is entered, it is smart enough to know when a train has passed through one. So it is beneficial to configure them when there is a path through them connecting one occupancy block with another.

The last requirement is each block should have at least one Indicator Track icon configured to display names. The popup window displayed when the Edit Icon menu item is selected has a checkbox labeled "Display Train Name when occupied". (You must edit with Control Panel Editor to get this window.) Check this box to show the current location of a tracked train.

## How to Make a Tracker

The Warrants menu has a Train Trackers item that opens the Tracker Table window. The table has a New Tracker... button that displays a Create Tracker dialog. Enter the name of the train and the block that it occupies to make a tracker for the train. The name will appear on the track icon selected for display in every block the train occupies. As train moves track icons change colors and show the name of the tracker

### An Easier Way to Make a Tracker

A much easier way to make a Tracker is simply to drag and drop a Marker icon onto the block the train occupies. This opens the Tracker Table window automatically and creates a Tracker with the text and color of the marker. When a tracker is made this way, the marker will return to its docking position. A marker's docking position can be set from its popup menu. Markers have a popup menu to configure them when not in an editing mode, but setting the docking position must be done in an editing mode.

## The Tracker Table

The Tracker Table window consists of a list of the active trackers with their current status. Each line shows the block the train is currently occupying the longest and the elapsed time it has been there. A Stop button on each row will terminate the tracker.

Below the list is the Last Event status window. The events shown are: when a trains enters a block, leaves a block and any error or warning message. When leaving a block the elapsed time the block was occupied is recorded. A mouse click on the window drops down a record of the last 20 events.

Below the status window are two buttons; the New Tracker... button which was mentioned above, and the Refresh Tracker Info button. This button updates the elapsed time each tracker has spent in its current block.

### The Tracking Options Menu

The Tracking Options menu has three items:

- Multiple Trackers Ranking applies only when several trackers are running. It is an advanced feature discussed below.
- OBlock Pick List opens a OBlock table window. The items can be dragged to the New Tracker dialog.
- Open Session Log opens a dialog to create a session log. All Tracker events and Warrant events are logged to this file. The default directory of this file is the File Location directory you specified in Preferences.

## When Multiple Trackers Are Active

A tracker posts an identifying label on all the blocks that its train currently occupies. Any block adjacent to the head or tail of its train becoming occupied is assumed to be the move of the train. However, when two or more trackers have adjacent blocks in common and a common block becomes occupied, which tracker has actually made the move is indeterminate. When this happens a dialog is displayed for the panel user to determine which tracked train occupies contested the block.

### Filtering Multiple Trackers

When multiple trackers "compete" for occupation of a block there is no way to guarantee the selection of the train actually entering the block. However, the Tracker Table can make an educated guess. The Multiple Trackers Ranking menu item Only Show Most Likely Trackers activates this feature. Note that unlike warrants which always set turnouts to be paths in a block, manual operators can throw switches that don't configure a path. This "Most Likely" option is based on the following logic:

A tracker that has both a path set to exit its current block and a path set to enter the newly occupied block is chosen over a tracker having only one path exiting or entering the block. The latter such tracker has precedence over a tracker with neither an exit nor an entrance path set.

This could be useful in situations where the panel operator does not have full view of the layout. Should ties occur in the ranking, the dialog to pick the tracker is displayed.