JMRI: DecoderPro - Multi-Decoder Tool

# JMRI: DecoderPro User Guide

## Multi-Decoder Tool

Digitrax invented a mechanism for having more than one decoder in locomotive, and still be able to read and write them separately. It uses CV15 and CV16 in a particular way to do this.

CV16 is the ID of a particular decoder; if you have more than one decoder in a locomotive, they should have different values in CV16.

CV15 is used to unlock one decoder (and lock the others), so it can be written.

Only decoders that have the value in CV15 equal to the value in CV16 will respond to reads and writes. Since you're supposed to originally set up the two decoders with different CV16 values, this means you can use CV15 to select which decoder you want to talk to.

## DecoderPro's Handling of CV15 and CV16

Really, the DecoderPro "paned programmer" shouldn't handle CV15 and CV16 at all. They're not really "configuration data", in the sense that you can freely adjust them and see what they do. Rather, CV16 is a "set once before assembling the locomotive", and CV15 is an operational command "which decoder can talk now".

If a DecoderPro user did a write-all-sheets and changed either of those, future programming operations would be problematic.

Hence, people writing decoder definitions are strongly encouraged not to include CV15 and CV16 (when they are used for decoder lock) in their definitions, or to include them only as "constant" CVs so the program will not write them. The user can then program those CVs using the "Single CV Programmer".

## The Multi-Decoder Tool

When this feature was first coming into use, a "Multi-Decoder Tool" was written for JMRI (see image to right).

It has several parts.

At the top are 8 buttons that you can click to unlock a particular decoder in the locomotive. E.g. if you click "3", the decoder configured with "3" in CV16 will be unlocked. If possible, the program tries to verify that the decoder is present and communicating; the status is shown in the middle of the window ("OK" in the illustration).

If you click the "legacy" button, all decoders with the lock feature will be locked out. This is so you can write to an additional decoder without the lock feature. E.g. if you have one decoder with (say "2"), and one without the lock feature, you can still configure them by:

1. Click "2" - both decoders are now active.
2. Write the information for "2", which will go to both.
3. Click "Legacy", locking out "2".
4. Write the information for the non-locking decoder, overwriting what you put in it above

Yes, that's ugly, but it can be made to work.

In the center are some buttons for automated operations you might find useful:

- "Search" - walks through a long series of writes and reads to determine which decoders are present. Buttons for decoders that aren't present will be disabled (grayed out).
- "Reset" - sometimes a decoder, even if installed by itself in the locomotive, can get accidentally locked when CV15 and/or CV16 is set to some spurious value. This button does a bunch of reads and writes to figure out what's happened and unlock the decoder.
- "Init DH163 + SoundTraxx" - If you have a DH163 or similar decoder with the lock feature, plus another decoder without the feature, this button works through a series of operations to configure the Digitrax lock feature so you can use it. (Normally you'd take the locomotive apart so as to be able to load the Digitrax CV16 value).

Finally, the bottom part of the page allows you to control the programming mode in use.

Although it's possible to use this tool in "Ops mode" (programming on the main), in that case it's not able to confirm operations, so one can't be 100% sure that the right decoder is selected.

## Digitrax's Original Proposal

DCC users sometimes want to install more than one decoder in a single locomotive. One common case is using separate decoders for motor control and sound. Because these decoders often need to have their CVs configured separately, a mechanism is needed to communicate with only one at a time.

This mechanism must be able to:

1. Do service-mode read and write from a specific decoder, with no need to disconnect other decoders electrically.
2. Discover the type of decoder(s) present inside a locomotive, without disassembly, and despite multiple decoders being present.
3. Work with existing DCC systems without modification

### Proposal:

CV16 will carry a number from 0 to 7 inclusive. This is called the "ID number". This number identifies a single decoder, so a unique value must be assigned to each decoder in a particular locomotive. Because most users will use this mechanism with decoders that provide different functions, the recommended coding is:

      0: Reset value, as shipped

      1: Motor decoder

      2: Sound decoder

      3: Function-only decoder (e.g. for additional lights)

CV15 is used to select the decoder that will respond. When the values in CV15 and CV16 are equal, all CVs in the decoder can be read or written. When the values in CV15 and CV16 are not equal, only CV15 can be written.

Some manufacturers may want to provide a bit in a CV to enable/disable this feature. If so, that should be in a CV reserved for the manufacturers use, as no NMRA CV has been reserved for this purpose.

Note that a command to reset the decoder to default CV values must not be acted upon unless the CV15 and CV16 values are equal. This prevents the user from accidentally resetting multiple decoders at the same time, and losing the ability to separately address them.

To configure decoders at installation:

Before installing each decoder in the locomotive:

1. Connect it to the programming track all by itself
2. Write 8 to CV8 to ensure CV15 and CV16 are both zero
3. If desired, read CV15 to confirm that the decoder can be addressed (This is a read of 0, hence fast)
4. Write CV16 to the desired ID number, e.g. 2
5. Write CV15 to the ID number
6. Configure the rest of the decoder
7. Disconnect it and install it in the locomotive

Repeat in turn for each decoder to be installed

Note that if the user is installing only one decoder, there is no need to modify the default values of zero in CV15 and CV16.

To access a decoder after installation:

1. Write the ID of the desired decoder into CV15
2. Read or write other CVs as needed

To identify the decoder(s) present in a locomotive:

1. Write a 0 to CV15
2. Attempt to read a 0 from CV16.
3. If no acknowledge is received, there is no decoder with ID 0. If an acknowledge is received, a decoder with ID 0 exists.

Repeat this process for ID 1 through 7 to check for those.

Because the ID values are low, a successful read is quite fast. An unsuccessful read, i.e. when the decoder is not present, will take some time on many existing command stations, but eventually give an answer. This can be made faster in the future by having command stations attempt to read just the expected value, instead of 0 to 255, in the absense of an acknowledge.