Introduction to DecoderPro

THIS HELP FILE IS WORK IN PROGRESS. Please help JMRI by contributing to improve this help file !

DecoderPro presents a list of your locomotives (the Roster) and provides access to tools for programming decoder configuration variables (CV's). Some stationary decoders can also be added to this database.

Description of DecoderPro Window

The DecoderPro Window is divided into five main sections from top to bottom.

Roster Window
  1. The Menu Bar.
  2. The Tool Bar (or Button Bar). Containing buttons and controls.
  3. The Roster Table. Containing a list of decoders in your Roster. An entry in the Roster can be highlighted with the mouse.
  4. The Decoder Information Area. This shows information about the highlighted entry in the Roster table.
  5. A status bar. This reports information in a single line. Error information is also posted here.

Main Tasks with DecoderPro

DecoderPro is designed for the management of DCC decoders fitted to locomotives. The locomotives known to DecoderPro are displayed in the Roster Table. The anticipated main tasks are: creating a new locomotive and changing the settings in an existing locomotive (programming).

New Locomotive

To add a new locomotive (or first locomotive, or stationary decoder), click on the "New Entry" button on the Tool Bar.
This will open a "Create New Loco" window, where the decoder can be either identified or selected from the list. To create the locomotive, having selected (or identified) a decoder, select the Programmer format (Basic or Comprehensive) and click "Open Programmer". A Programming window for the new locomotive will open, with the "Roster Entry" tab foremost. It is recommended to give the locomotive a name in the "ID:" field, and then click "Save to Roster". You can also proceed to program the decoder, giving it a DCC address (in the "Basic" tab), and set other values. On closing the Programming window, if prompted, save the results into the Roster.

Identifying An Existing Locomotive Entry

If a locomotive is placed on the Programming Track, the "Find in Roster" button will read details from the decoder and try to match it to an entry in the Roster Table. Some decoders only work with a limited range of programming modes, and it may be necessary to change the programming mode with the "Programming Mode" drop down list.
If a locomotive is correctly identified, it will be highlighted in the Roster Table, and its details will appear in the lower Decoder Information Area.

Using the Roster Table

The Roster Table shows one row for each locomotive in your roster. There are several things you can do with the table entries:

Change some fields of the entry

You can directly edit the contents of some of the fields, such as the Owner, Road Number, Manufacturer, Model and Comment. Click in a field to show an edit cursor, then type your changes. Hit the Return or Enter key to save your changes.

The comment field and the user-added fields can accept multi-line text. To create a new line, type ctrl-Return or alt-Return. As usual, you hit Return or Enter with no modifiers when you're done editing.

Note: As of February 2026, the cell height doesn't expand to show the new lines you've typed with ctrl-Return or alt-Return until you've saved your changes by hitting Enter or Return. Unfortunately, you have to type your changes in blind and then hit Enter/Return to see them, and correct them as needed. We're working on a fix for this.

Sort by Values and Rearrange Columns

To sort by the contents of a column, click the heading at the top of the column. Click again to sort in the opposite order.

You can change the size of a column by pressing-and-dragging the line between the column headings. You can move columns around by pressing-and-dragging in the center center of the heading.

To hide or show columns, right-press or ctrl-press on a column heading. This will show you a contextual menu where you can check the boxes by the columns you want to see, and uncheck the columns you don't want to see.

Add New Columns for User Data

You can add additional columns if there's some other information you'd like to keep track of. For example, you might want to keep track of the driver layout (0-4-0, 2-6-2, etc) for a steam locomotive. To create a new column: Once you've created the new column, you can edit the contents directly in the Roster Table, or by going back to the "Roster Media" tab.

Programming an existing Locomotive

Once a locomotive has been selected, either by manually finding it within the Roster Table, or through the "Identify" button, a summary of its details will appear in the lower Decoder Information Area. Buttons to open the programmer are to the right of the Decoder Information Area.

Select the type of programming required with the radio buttons, choose between the Programming Track, Programming on the Main Line or Edit the file only (no programming of a locomotive). Having selected the type of programming, you can open either the Basic Programmer (which allows change of locomotive address) or the Comprehensive Programmer (which allows changing of all locomotive decoder features known to DecoderPro).

Changing Throttle Labels and Roster Media

Throttle Labels are used by the JMRI on-screen Throttles and by the smart-phone throttles through the WiThrottle interface. They allow Function keys to have meaningful names such as "Horn", "Whistle", rather than "F2" and "F4". Their use is optional.

Roster Media is where pictures of locomotives can be loaded into JMRI. These are displayed in the Roster, and can be used within Throttles. Their use is optional.

Roster Groups

Roster Groups are a means of filtering your entries in the Roster. For example, you might have "diesel locos", "steam locos", but also "Burlington Locos" and "Canadian Pacific Locos". Thus a single locomotive in the Roster could be a member of several groups. Roster Groups are used to filter the Roster View in DecoderPro, and select the locomotives offered in an on-screen Throttle.

To create your first Roster Group, use the "Create Roster Group" command on the "Settings" menu. When you have created a Roster Group, a new drop-list is added to the Tool Bar in DecoderPro. Having created a group, it is initially empty. The next step is to add locomotives to the group. You can drag and drop a selected (highlighted line) locomotive from the table and drop it on the group you want to include it in.

If you want to add a number of locomotives to a group. the "Roster Group Table Association" command on the "Settings" menu is a convenient tool. With the "Roster Group Table" window, select the Roster Group in the drop-menu, and then place a tick alongside all locomotives requires in that group. Repeat for any other groups, and when finished close the window with the close-box in the upper right-hand corner.

You can also add locomotives to groups one at a time using the "Add Roster Entry to Group..." entry in the "Settings" menu. Or you can right-press or ctrl-press on a selected line in the table to get a pop-up menu that contains an "Add to Group..." item.

File menu

Edit menu

Settings menu

Actions menu

Command Station Specific menu

A menu will appear for the command station connected to JMRI. The command station is set in the Preferences. The content of this menu will be specific to your command station type.

Window menu

Lists the windows that are currently active.

Help menu

Window Help opens this page.

The tool bar is initially at the top of the DecoderPro window. By grabbing the left end with your mouse, you can move it to other places on the screen as desired.

Tool Bar

Help button

Opens this page.

New Entry button

Opens Service Mode Programmer Decoder selection Screen.

Find in Roster button

Attempts to identify the loco on the Programming track.

Print Table button

Prints the current contents of the roster table.

Programming mode drop down

Opens the selection of programming modes.

Roster Group Pane

The Roster Group Pane only appears if a Roster Group has been defined. It appears to the left of the Roster Table (if not hidden using the Settings menu). Further groups can be added using the "+" button, and groups can be removed with the "-" button. Locos can be dragged from the Roster Table to the Roster Group Pane. The Roster Group Pane can be hidden with a menu option (under Settings), or with the triangular shrink/expand keys in the frame border. Removing a loco from a Roster Group can be done using the "Roster Group Table Associations" pane, accessible from the "Settings" menu.