JMRI® is...
By the community of
JMRI tools for working with your layout:
Layout Automation
Use JMRI to automate parts of your layout and operations:
Supported hardware
JMRI supports a wide range of devices, DCC systems, command stations, networks, and protocols.
JMRI Setup and Installation
JMRI environments...

JMRI Help:

Contents Index
Glossary FAQ

Donate to

JMRI: DecoderPro User Guide

DecoderPro Details

This page provides information on how DecoderPro (Symbolic Programmer) works.
For details on the JMRI internals, please see the Technical Documentation pages.

Configuration Files

There are three types of Configuration Files:

  • Decoder configuration files - These carry the description of a specific type of decoder, and control how the programmer displays the variable information.
  • Locomotive configuration files - These carry the specific information on a single locomotive.
  • Programmer definitions - These define the formats for the various programming sheets.

The programmer can read either type of file. If you select a decoder file after clicking Read File, the programmer will be set up with the variables, options, etc for that type. The values will be blank, as the programmer doesn't know anything about what's been programmed into a specific decoder unit.

If you select a locomotive file after clicking Read File, information on both the decoder configuration and the specific settings in this locomotive will be displayed. This shows you how the locomotive is already configured, allowing you to make small changes with less chance of confusion.

You can also write locomotive files with the Write File button. This will store the known contents of the decoder, allowing you to come back to it later.

The configuration files are stored in XML format. This is a standard form for structured data. XML is being widely used to standardize the exchange of data between different manufacturers in many fields; perhaps someday DCC decoder manufacturers will provide an XML description of each decoder they make. In the meantime, the configuration files are being created by volunteers. If one doesn't exist for a specific decoder you've got, you can create your own. You can also modify a file if you'd prefer different names, a different grouping of options, or you just never want to see that certain options that you don't use. A simple text editor can create these files easily, as the format doesn't have fixed length fields, special characters, etc. There are also powerful public-domain XML tools that make it really easy to manage a large number of decoder files.


A "variable" defines the value that will be loaded into all or part of a CV. For example, a variable can be defined that sets the value of the three most-significant bits of CV 47. If there are several options configured in a single CV, these would normally be handled by separate variables. Currently, there are several types of variables:

  • Decimal - numbers entered in the usual decimal notation. These are useful for short address, starting voltages, etc.
  • Enum (enumerated) - choose from a set of options. These can be used for simple on/off, yes/no choices, or more complicated sets like the FX lighting example above. The configuration contains a name for each possibility.
  • Long address - like a decimal value, except the constraints on a valid long address are taken into account.
  • Hex - This is not so much needed, since the multiple options in a single CV can be handled by multiple variables. But if its needed for some reason, the capability is present.
  • Speed table - not yet really working well, this type of variable is intended to provide a graphic speed table chart that you can drag around to configure as you wish.
Programmer communication: States

Communication with the Command Station/programmer, hence reading and writing of the decoder, are only done when the "Read" or "Write" buttons are pressed. DecoderPro keeps track of whether a value has been sent to the decoder using four States for variables or CVs:

  • Read - The value shown was read from the decoder.
  • Stored - The value shown has been written to the decoder.
  • Edited - The value shown has been changed in the computer, but not yet written to the decoder. Push the Write button when you're happy with the value.
  • Unknown - A default value, or a read has failed, or for some other reason the program has no confidence that the value is what you really want. Edit the value or press the Write button.