JMRI: DecoderPro
Author: Nigel Cliffe
Keywords: JMRI help DecoderPro

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

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:

- Select the first locomotive you'd like to add a value to.
- Click "Labels & Media", then open the "Roster Media" tab
- In the bottom part of that tab, there's a two column table. The last of the entries in the right column will be "...".
- Click on that cell and type the name of your new column. Hit the Return or Enter key.
- Click on the cell to the right of that and enter a value for this locomotive in this new column you're adding. Hit the Return or Enter key.
- Click "Save" at the bottom.
- Quit and restart DecoderPro
- Your new column should show in the Roster Table. You may have to drag the content to the right to see it, or ctrl-click/right-click on one of the column headers to set it to visible.

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.

## Menu Bar

### File menu

- New Roster Window
- Import Decoder File...
- Import Decoder URL...
- ------------------
- Export Roster Entry...
- Import Roster Entry...
- ------------------
- Export Complete Roster...
- Import Complete Roster...
- ------------------
- Rebuild Roster
- Validate XML File
- ------------------
- Open PanelPro Window
- ------------------
- Close Window
- ------------------
- Print Displayed Roster Table
- Print Roster ->
  - Selected entry
  - Summary
- Print Preview Roster ->
  - Selected entry
  - Summary
- -------------------
- Quit (on Windows and Linux; on macOS it's in the DecoderPro menu)

### Edit menu

- Cut
- Copy
- Paste
- -----------
- New Entry...
- Duplicate Entry
- Delete Entry
- -----------
- Preferences

### Settings menu

- Hide/Show Summary Pane
- Reset Window sizes
- Reset Column Widths
- Hide/Show Roster Image
- Hide/Show Roster Groups
- --------------
- Programming ->
  - Programming Track
  - Programming On Main
  - Edit Only
- --------------
- Create Roster Group
- Rename Roster Group
- Duplicate Roster Group
- Delete Roster Group
- --------------
- Roster Group Table Association

### Actions menu

- Program
- Labels and Media
- Edit Throttle Lables
- New Throttle
- Load default throtttle layout
- --------------
- Consisting Tool
- Turnout Control
- Power Control
- SpeedoMeter
- Single CV Programmer
- Multi-Decoder Control
- --------------
- Start WiThrottle Server
- Start Web Server
- --------------
- Recreate Roster Index
- Recreate Decoder Index
- Update Decoder Definitions
- --------------
- Run Script...

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