JMRI: DecoderPro User Guide
Updating Decoder Definitions
New and updated decoder definitions are occasionally created.
The best way to get them is to update your copy of JMRI to the
most recent
test release.
If you don't want to wait for a monthly test release, you can also
pick up a
development release.
Development releases are available within a day of the new decoder definition being
merged into JMRI.
Sometimes, a user will put a new/updated definition in the files area of JMRI users (log in to access).
To use these xml files you need to download and install them.
The installation process was simplified in JMRI 2.3.6, where "Import Decoder File" and
"Import Decoder URL" menu items were added to the Debug menu (in PanelPro or "legacy"
DecoderPro) and to the File menu (in DecoderPro "Roster view").
Note that this download and install process only works for the main
decoder definition file.
Some decoder definitions include small subsidiary files from subdirectories. Updates
to these are best obtained via a test or development release to ensure consistency.
JMRI v 2.3.6 and later
This section describes adding a new decoder definition when you are using JMRI version 2.3.6
or later.
Loading a definition from the web
If you have a URL for a decoder definition, perhaps copied from a web page or email, and your
computer has an active Internet connection, you can directly install the definition.
- Copy the URL address from your mail etc.
- Select the "Import Decoder URL" item from the "Debug" menu (in PanelPro or "legacy"
DecoderPro) or from the File menu (in DecoderPro "Roster view").
- You'll be prompted for the URL. Enter it, or paste it in and click OK.
Unless there are errors, the file will be copied onto your local computer and installed in
your JMRI Preferences directory.
Learn about
JMRI Configuration Files
Loading a definition from a file
If you have local file containing a decoder definition, perhaps downloaded from a web page or
received via email, you can install that definition in JMRI.
- Select the "Import Decoder File" item from the "Debug" menu (in PanelPro or "legacy"
DecoderPro) or from the File menu (in DecoderPro "Roster view").
- You'll be shown a file selection dialog.
- If the file doesn't have a ".xml" extension, you may have to select the "show all
files" filter at the bottom of the dialog.
- Navigate to your file, and click OK.
Unless there are errors, the file will be copied into your JMRI Preferences directory and
installed.
How This Works
Both of these tools take the decoder definition information from the source you indicate and
copy it to your local JMRI Preferences directory so that it will be available from now on.
For this to work, you can't already have a decoder definition file there by the same name. If
such a file does exist, the program will indicate an error and not replace the file.
The definition is stored in your Preferences directory, instead of the JMRI distribution
directory, so that installing a new version of JMRI doesn't delete it. Note, however, that if
a newer version of JMRI comes along with a copy of this decoder definition installed, the
program will give priority to the specific version that you imported. JMRI thinks you knew
what you were doing when you specifically imported that specific version. If you'd prefer to
use the one in the new JMRI version, you should delete yours from your Preferences directory
and select "Rebuild Decoder Index" in the debug menu.
JMRI v 2.3.5 and earlier
This section describes adding a new decoder definition when you are using JMRI version 2.3.5
or before.
On Windows Systems
- In Windows Explorer, go to the location where the decoder.xml file is located and right
click on the file.
(Don't double click or you will open the file rather than saving it.)
- Choose the menu selection "Save as..." or "Save target as...". After you choose this
menu item a window will pop up and ask you for a location that you want to save the file.
You can either type in a directory name or click the browse button. To save a step I
suggest that you choose "Browse..." and then select the "Program
files\JMRI\xml\decoders\" directory.
If you save the file to any other directory, or to the desktop, you will have to copy
the file over to the correct directory using the copy and paste in Windows Explorer. It's
easier to just save it in the correct directory in the first place.
- Once the file is in the decoders directory you need to open DecoderPro and choose the
Debug menu item. It's one of the menu items on the main menu on the
opening screen.
- From the drop down Debug menu, choose the item that says "Rebuild decoder index". After
you have rebuilt the decoder index the new decoder should show up in the drop down list of
the Programmer.
The key to make this work is that the downloaded .xml file needs to be in the
JMRI/xml/decoders directory, otherwise DecoderPro doesn't know that it is there, and
won't see it when you rebuild the decoder index.
Note that a new JMRI install may overwrite your customized decoder definition.
On Mac OS X Systems
- Create a new folder inside your JMRI Preferences folder /Users/me/Library/JMRI/ and
name it "decoders"
- Copy or drag the new decoder.xml file into this new "decoders" folder.
- From the drop down Debug menu, choose the item that says "Rebuild decoder index". After
you have rebuilt the decoder index, the new decoder should show up in the drop down list of
the Programmer.
