JMRI: DecoderPro User Guide - Updating Decoder Definitions

# JMRI: DecoderPro User Guide

## Updating Decoder Definitions

Many people have contributed decoder definition files to DecoderPro. Between new releases, new files may be created that you might want to use. These can usually be found either on the JMRI web site or 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").

## 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.