Author: Paul Bender
Keywords: hardware layout java model railroad JMRI CMRI decoderpro panelpro tools loconet lenz nce easydcc dcc nmra

# JMRI: Consisting Tool

## What is a Consist?

There are three types of consists used on DCC systems:

1. A basic or primary address consist.

   In this type of consist, each Locomotive is assigned the same address on the programming track, or on the main with OpsMode Programming (if supported by the command station and decoder). You can use either a long (CV17 and CV18) or short (CV1) address for a primary address consist.

2. A Command Station Assisted Consist (CSAC).

   A command station assisted consist is built using a function of your command station.
   Command Station Assisted Consists go by the trade names listed in the table below. The table also lists the known limitations imposed by each manufacturer.

   Manufacturer | Trade Name | Usage Notes
   --- | --- | ---
   Digitrax | Universal Consist | Limited to number of slots supported by the system. | Allows any address to be used.
   Lenz | Double Header | Limited to 2 Locomotives | Allows any address but 00 to be used.
   NCE | Old Style Consist | Limited to 8 Locomotives | Allows any address but 00 to be used.
   EasyDCC | Standard Consist | Limited to 8 Locomotives | Allows any address but 00 to be used.

   The common trait shared by all versions of CSAC is that a separate speed and direction command is sent to the track for each Locomotive that is in the consist.

3. A Decoder Assisted Consist (DAC), also referred to frequently as an Advanced Consist.
   The NMRA has set aside CV19 as a dedicated location for consist addresses.
   If CV19 contains a value other than 0, the Locomotive will respond to speed and direction instructions on the address in CV19. Otherwise, it will respond to speed and direction commands sent only on the usual short or long decoder address.
   Since the consist address is a single CV, it is limited to the range of 1 to 127. If you add 128 to the consist address, the Locomotive will run backwards (relative to it's normal direction of travel) in the consist.
   For most decoders, this type of consist can be by programming operations in the same ways that a basic Consist can be. We say most here because some decoders block writing to any address CV using operations mode programming.
   The NMRA has also set aside a special command to set up a Decoder Assisted Consist on the mainline. This command should be supported by all decoders that support Decoder Assisted Consisting.
   The advantage to DAC, when compared to CSAC is that only one speed and direction command is sent to the entire consist.
   By default, Locomotives in a DAC ignore function commands sent to the consist address. You can configure some decoders so they will respond to function commands issued to the consist address as well (through CVs 21 and 22). If supported by the decoder, The appropriate values can also be configured through DecoderPro using the Consisting Tab in the comprehensive programmer.
   One final note: Advanced Consists operate in 28 speed steps (always). You may need to make sure your throttle is sending 28 speed steps to the address to avoid flickering headlights.

### Consisting Support in JMRI

JMRI provides support for consists using the Consist Tool, which is accessible through the Tools or Actions menu of any JMRI application. (There is also a NCE-specific Consisting Tool that works somewhat differently from the tool described here)

The Consisting tool provides a visual tool for manipulating the Decoder Assisted Consists and, on some command stations, Command Station Assisted Consists.
Backing up the Consist Tool is a consist manager. The consist manager is responsible for maintaining information about existing consists and for communicating the necessary information between the consist tool and the Command Station.

#### Available JMRI Consist Managers

- The Generic Consist Managers are used on any system which does not have it's own consist manager, but supports either operations mode programming or a sending raw DCC packets.
  There are two generic consist managers, one uses operations mode programming to change CV19, and the other sends a special DCC packet to change CV19. Which version is used is dependent on the support the associated system provides, and is not user selectable.
  The Generic Consist Managers only able to manipulate Decoder Assisted Consists.
  The Generic Consist Manager bypasses any routines the command station has to set the consist address. The importance of this is that IF your command station provides a method for you to run a consist by selecting a Locomotive by it's address, this won't function. You'll need to use the short address identifier you selected for the consist ID to control the consist speed and direction.
- The XPressNet Consist Manager uses support provided by XPressNet Based systems to manipulate consists. This consist manager is able to construct a Lenz "Double Header" in addition to Advanced Consists.
  Since this consist manager uses the consist creation instructions provided by the XPressNet protocol, the Lenz Smart Consisting feature works with consists created by the tool. On Lenz systems, Smart Consisting refers to the ability to be able to run a consist from any of the consisted Locomotive addresses or from the consist address.
  The XPressNet Consist Manager is capable of reading consist information from the command station, both for Advanced Consists and Lenz Double Headers.
- The EasyDCC Consist Manager uses support provided by CVP's EasyDCC system to manipulate consists. This consist manager is able to construct EasyDCC "Standard Consists" in addition to Advanced Consists.
  CVP does not provide a method to construct Advanced Consists. As a result, advanced consists are created by bypassing the command station. Unlike the Generic Consist Manager, the EasyDCC Consist Manager creates these by issuing a Consist Control packet to the track. This allows inclusion of Locomotives that do not permit writing CV19 using operations mode programming. As with the Generic Consist Manager, you must use the short address selected as the consist address to control the consist.
  For EasyDCC Standard Consists, there are a couple of restrictions imposed by the EasyDCC Protocol. First, as with consists created on the command station directly, consists are limited to 8 addresses. Second, unlike consists created on the command station directly, CVP limits the standard consist address to addresses between 1 and 255.
  The EasyDCC Consist Manager will read Standard Consist information for consists in the allowed range (1-255) from the command station's memory. Since the command station is bypassed to create Advanced Consists, these cannot be read from the command station.
- The Internal Consist Manager is a special consist manager associated with the Internal JMRI system. It functions like the Generic Consist Managers, but it is a available as a user selectable option so that users can choose to bypass a system specific consist manager.

#### Selecting a Consist Manager

To select the consist manager in use, we first need to open the defaults tab in the preferences.

Once the preferences are loaded, the choices for the consist manager will be selectable in the "Consists" column (inside the box labeled 1 in the figure above). Here we see two choices, one for a LocoNet connection, labeled A and one for the Internal connection labeled B.
If you have more system connections available, other options may be available as well.

If you choose option A, then you choose to use the consist manager associated with the system. This will either be a system specific consist manager or one of the generic consist managers, depending on the support of the system.

If you choose option B, then the Internal Consist Manager manager is used. In this case, if there is a selection made in the Command Station column (in the box labeled 2 in the figure) then the consist will be created on the system with the selected command station. This selection will cause consists to be created using a special DCC packet for creating consists.

If you choose option B and there is no selection for the command station, consists will be created on the system with an Ops Mode Programmer selected in Column 3. This selection will cause consists to be created using Operations Mode Programming. Note that if the Internal system is selected in this case, no consists will be created.

#### Consists and the JMRI Roster

JMRI users sometimes create Advanced Consists using the programmer to set the value of CV19. Begining with JMRI Version 4.17.3, the JMRI consisting tools provide some tools to synchronize the advanced consists created by programming with those of the advanced

##### Import From Roster

Users can import consists created with the programmer into the Consist Manager by selecting the Scan Roster for Consists option in the Consist Control's File menu.

Once the scan completes, any consists discovered will be added to the list of consists available to the Consist Control. Please note that this tool does not write the consists to the DCC system.

##### Keeping the Roster Synchronized

Users may choose to have JMRI update consist information in their roster when creating and removing locomotives from Advanced Consists. This optin is activated by checking the Update CV19 in roster when modifying advanced consists box in the Consist Control section of the JMRI preferences.

Selecting this option may cause a performance impact when modifying rosters, due to reading and writing the roster file. This option is disabled by default.

## Using the Consist Tool

You find this tool

- in DecoderPro: in the Actions menu
- in PanelPro: in the Tools menu

When you first open the Consist Tool, you will see a screen similar to the following:

The radio buttons in the top row are used to select between an Advanced (or Decoder Assisted) Consist and a Command Station Assisted Consist. If the Command Station Assisted Consists are not supported by the tool for your system, these selections will be grayed out.

The box next to the label Consist: lets you enter the Consist ID. For Decoder Assisted Consists, this should be the short address used to identify the consist. For Command Station Assisted Consists, this value may automatically be filled in with the lead Locomotive address when you try to add it to the consist.
To specify how you wish to use an address from 1 to 127 (excluding 3) that can be either short or long, use the drop down list next to the Consist text field to select your choice:

Setting a typical ID for a Decoder Assisted Consist should now look like the following:

The second line of the consisting tool is used to add Locomotives to your Consist. A Locomotive may be added either by entering it's number in the box next to New Locomotive:

or by selecting it's number from the roster drop down box:

Clicking the Add button will add the Locomotive to the Consist, and it will appear in the list below the second line:

Clicking the Reset button will clear the information on the New Loco entry line.

The Direction Normal checkbox allows the user to specify if the new Locomotive is traveling in Forward or Reverse when the Consist is traveling Forward.
You may notice from the previous screen shots that this box is grayed out until a lead Locomotive is selected. When adding subsequent Locomotives, you can (un)check this box to indicate the direction of each new Locomotive relative to the lead Locomotive.
After adding a second Locomotive to the consist, with the direction reversed, you should see something like the following:

If you made a mistake, and add a second Locomotive to the Consist with the wrong direction set, you can change it's direction simply by clicking on the checkbox in the Direction Normal column.
The direction of the first (lead) Locomotive cannot be changed once added.

To delete an individual Locomotive from the consist, you can select the Delete button in the right most column of the appropriate row of the table of addresses.

To delete an entire Consist you can use the Delete button at the bottom of the screen.

The Throttle button at the bottom of the screen can be used to bring up a JMRI throttle for this Consist address.

To add a new Consist, select the first, blank entry in the drop-down box next to the current consist's ID:

To recall an existing Consist for inspection, select the appropriate entry from the drop-down box next to the current Consist's ID:

## Keeping Track of Consists

If you'd like, you can track your consists in a new column in the DecoderPro listing. To do this, you create the column, then manually enter the consist information (There is no automatic population of this column DecoderPro can't keep track of all the various methods of consisting; we want to avoid user confusion when automatic updates show invalid info)

To do this:

1. Select a locomotive
2. Under the Action menu, select Labels and Media
3. On that window, select Roster Media
4. In the lower half of the window, enter "Consist Info" over the three dots (…) in the Name column, and your value over the three dots in the Value column.
5. Hit Return, and then click “Save to Roster”
6. Close the window.
7. The first time you do this, quit and restart JMRI (it would be nice if this wasn’t necessary, but right now it often is)
8. On the main roster, right-click or ctrl-click on the heading in any column. Select your new Consist Info entry to put a checkmark next to it. A new column should appear titled Consist Info and showing the value you entered on that locomotive. Ctrl-drag on the heading to move the column to where you want it.
9. Now that it’s set up, you can click on a cell in that column to enter the your value for any locomotive. DecoderPro will keep the info from one run to another in the roster.