DecoderPro User Guide - Updating Decoder Definitions

Many people have contributed decoder definition files to DecoderPro. Between new releases, new files will be created that you might want to use. New ones can usually be found either on the JMRI web site or in the files area of the jmriusers Yahoo group.

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.

JMRI Version 2.3.6 And After

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.

Select the "Import Decoder URL" item from the "Debug" menu.
You'll be prompted for the URL. Enter it, and click OK.

Unless there are errors, the file will be copied onto your local computer and installed in your JMRI preferences directory.

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.
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, just delete yours from your preferences directory and select "Rebuild Decoder Index" in the debug menu.

JMRI Version 2.3.5 And Before

This section describes adding a new decoder definition when you are using JMRI version 2.3.5 or before.

On Windows Systems

Go to the files menu 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 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 Decoder Pro and choose the Debug menu item. It's one of the menu items on the top horizontal menu on the opening screen.
From the drop down debug menu choose the item that says "rebuild (or recreate) decoder index". After you have rebuilt the decoder index the decoder should show up.
The key to make this work is that the downloaded XML file needs to be in the JMRI/XML/decoders directory, otherwise Decoder Pro doesn't know that it is there, and won't see it when you rebuild the decoder index.