JMRI: RPS Icon

RPS is a system for measuring the positions of rolling stock on your layout. More information on RPS is available on the main RPS help page. RPS Reporter icons move around on the panel to show where the corresponding equipment is on the layout.

This page is still under construction, but the RPS icon support itself is already present in JMRI. Go ahead and try it out!

RPS icons are a way of putting icons on a panel that will move around as the RPS system finds the location of an associated transmitter.

Adding an RPS Icon to a Panel

Usually, each RPS icon represents one RPS transmitter, hence one locomotive. Currently, you need to add one for each RPS-equipped piece of equipment you want to track. Although this is a pain, it gives you very fine control over which transmitter's positions are displayed and how they are presented. Section still needs lots of work

Click "Add RPS reporter" on the panel editor. An RPS icon will appear on the panel at the default location, but it won't work yet until it's calibrated.

Right-click or option-click on the icon to see the popup menu, where you can calibrate the icon.

Calibrating an RPS Icon

When you calibrate an RPS icon, you're specifying how RPS measured locations correspond to positions on the panel.

The steps are:

Stop the RPS system polling, so things won't move around on you.
Add the icon to the panel.
Drag the icon until it sits over the position that corresponds to the 0,0 origin of your RPS installation.
Right-click or option-click on the icon to get the pop-up menu, and select "Set Origin".
Move the actual locomotive to some other point on the layout, and start the RPS system polling again. Get a good measurement of the position. Stop the RPS system.
Drag the icon to where you want it to be on the screen when the transmitter is in that location.
From the icon's popup menu, select "Set Current Location".
Get the popup menu again. It should no longer say "Not Calibrated", and instead should show you the current position.

Don't forget to save your panel!

Popup Menu

The popup menu for an RPS icon contains:

RPS Position Readout: This is just a title; selecting it doesn't do anything
Rotate: Rotates how the icon is displayed, in 90-degree increments. Note that this is not a rotation of the RPS coordinate system, but merely of the icon presentation.
Show ID: When checked, the ID string will be displayed in addition to the icon.
Set Origin: Sets the current display position of the icon as the 0,0 position of the RPS system. This must be done as the first step in calibration.
Set Current Location: Changes the calibration so that it's position on the screen and the RPS measurement agree. To use this, first make sure that the RPS system has made a good measurement of the transmitters position, then drag the icon to where it should appear on the screen, and finally choose "Set Current Location" from the popup menu. In the future, when the RPS system measures the same location, the icon will appear in that position.
Not Calibrated: A status message, not a control, this appears when the icon has not been calibrated. Calibration ensure the icon's position on the screen properly reflects the location that RPS has measured.
At (x), (y): Once the icon has been calibrated, the popup menu displays the most recent RPS location measurement.
Show ID: If checked, the icon will have it's ID information displayed next to it.
Set Filter: Opens a window that lets you enter a filter value for this icon.
Disable: Controls whether or not the icon can be dragged around manually.
Remove: Removes the RPS icon from the panel. This is a permanent deletion.
Help: Shows this page

Filtering and Multiple Locomotives

We're still trying to figure out how best to configure multiple icons on a panel. A single icon, with no special settings, will hop around as readings come in. It will go to the position of one reading, and then move directly to the position of the next reading, which might come from another locomotive transmitter.

If you want to have multiple icons, each showing the position of a single locomotive, you can configure filters on each icon.

Add an RPS icon to the panel
Open the icon's pop-up menu, and select "Set Filter".
This will open a small window in which you can enter the ID value for the locomotive you want this icon to track. Once you've done this, the icon will only move to the position measured for this locomotive.

This method is a little tedious, particularly if you have a large roster, since you'll have to do it manually for each locomotive. And you'll have to calibrate them all. (One good way to do this is to copy the lines defining one icon in the panel file, in effect making a bunch of duplicate calibrated icons, and then set the filters; see below). But it has the advantage that you can control exactly which locomotives to display and which not to. This method also allows you to attach custom images (e.g. a picture of a specific locomotive) to the specific icon that represents each ID.

Customization

Starting Position

When you first open the panel, the icons are put back to the same position on the screen that they occupied when the screen was saved to the file.

You can use this to e.g. put the icons out of the way initially. They'll stay in that position until a valid reading moves them, so you can use this to "park" locomotives that are not on the track off the active part of the panel.

Displaying a Custom Icon

Although there is not yet a graphical interface for this yet (it's coming!), you can modify the icon for a transmitter that's being tracked by the RPS system so that it displays e.g. a small picture of the locomotive. To do this, you'll edit the panel definition file directly. (There's more information on the XML format we use here) The steps are:

Create the icon on the panel editor, and save the panel into a file.
Make a backup copy of the file, in case something goes wrong.
Using a text editor, open the file to change it.

Find the line that defines the icon. It will contain the string "RpsPositionIconXml", so one approach is to search for that. It will look something like (it'll probably be all on one line):


    <sensoricon x="95" y="150" level="10" 
            active="resources/icons/smallschematics/tracksegments/circuit-occupied.gif" 
            error="resources/icons/smallschematics/tracksegments/circuit-error.gif" 
            rotate="0" forcecontroloff="false" momentary="false" 
            sxscale="11.849106591612951" syscale="-11.889381744148094" 
            sxorigin="41" syorigin="768" 
            class="jmri.jmrit.display.configurexml.RpsPositionIconXml" />

To make the icon track a specific transmitter, enter the transmitter's ID as a "filter" attribute. For example, to have it track transmitter 5510, change the line to:


    <sensoricon filter="5510" x="95" y="150" level="10" 
            active="resources/icons/smallschematics/tracksegments/circuit-occupied.gif" 
            error="resources/icons/smallschematics/tracksegments/circuit-error.gif" 
            rotate="0" forcecontroloff="false" momentary="false" s
            xscale="11.849106591612951" syscale="-11.889381744148094" 
            sxorigin="41" syorigin="768" 
            class="jmri.jmrit.display.configurexml.RpsPositionIconXml" />

The "active" and "error" attributes are the icons to be displayed when the system is getting good readings and not getting good readings, respectively. You can change these to the location of any icon file you'd like. For example, you can change them to a (small) photo of a locomotive, or to an image with the train number.

A nice graphical interface for this is coming, but it's not here yet.