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
. 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
Right-click or option-click on the icon to see the popup menu, where you can calibrate the
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
- 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
- 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!
The popup menu for an RPS icon contains:
- RPS Position Readout
- This is just a title; selecting it doesn't do anything
- 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
- 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.
- Controls whether or not the icon can be dragged around manually.
- Removes the RPS icon from the panel. This is a permanent deletion.
- 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.
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"
rotate="0" forcecontroloff="false" momentary="false"
- 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"
rotate="0" forcecontroloff="false" momentary="false" s
- 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.