JMRI Hardware Guide: Digitrax DCC

LocoNet® Connections
PR2 and PR3 Programmers
Setup
Using JMRI with LocoNet®
LocoNet® Conenction Limitations
Networked Computers and LocoNet®
Debugging
- Erratic or Non-Functioning CV Readback
- Command Station Turnout Command Rejection and JMRI Turnout Command Handling
See Also

LocoNet® Connections

JMRI software, including DecoderPro and PanelPro, works with your Digitrax command station to program decoders. To do this, it communicates with the command station over the LocoNet® using one of several types of ® adapter.

Supported Command Stations

JMRI software supports the following LocoNet-based command stations:

Zephyr Starter Set
Zephyr Xtra Starter Set
Super Empire Builder Set
Chief Starter Set
Super Chief Set
Super Chief Xtra Set
DCS50 Command Station/Booster/Throttle
DCS51 Command Station/Booster/Throttle
DB150 Command Station/Booster
DCS100 Command Station/Booster
DCS200 Command Station/Booster
Intellibox: The Uhlenbrock Central Unit
Intellibox II or IB-Com
DCC-Mux: DCC data combiner with built-in LocoNet command station

For systems which do not provide a LocoNet command station, two additional options are supported. When a layout uses LocoNet peripheral devices but not a LocoNet-based command station, a "Standalone" LocoNet is used. See Standalone LocoNet. In addition, JMRI software may be configured to use a simulated LocoNet connection instead of a real LocoNet connection. This is the "LocoNet Simulator".

Supported Computer Interfaces

To connect your computer to the LocoNet, and hence to the command station, you need one of the following adapters:

Generally, any of these can be used with any type of computer to communicate with any type of command station. Currently, the LocoBuffer-USB and PR3 are the recommended computer interface solutions. The LocoBuffer II and original LocoBuffer are no longer commercially available; their primary advantage now is that they use a traditional serial port, which may be the only suitable connection type available on some older computers.

The MS100 is not recommended; it sometimes fails to provide reliable communications, and it cannot be used with JMRI if you are using Mac OS X or on most Windows Vista machines. If you have problems with the MS100, you might not be able to fix them, and nobody may be able to help you.

The Uhlenbrock Intellibox can also be controlled directly through it's serial port; there's a separate page on how to do this.

PR2 and PR3 Programmers

JMRI can also use a Digitrax PR2 or PR3 to program and test decoders. The PR2 is a stand-alone decoder programming unit which does not connect to the rest of the layout, the command station, nor to a LocoNet. For more information on using a PR2 with DecoderPro, please see the PR2 setup page. The PR3 can be configured in JMRI to operate as either a stand alone programmer, or as an interface to to a LocoNet. There is more information on the PR3 setup page.

Setup

To connect your computer to a Digitrax DCC system, you need a LocoBuffer-USB, PR3, LocoBuffer-II, LocoBuffer, or MS100 to act as an adapter. See below for more information on these. The LocoBuffer-USB is highly recommended.

Note that except for the PR3, these are only LocoNet interfaces, not stand alone programmers like the Digitrax PR2 and PR3. Readback of decoder CVs is possible when using a programming track controlled by a PR3 (in stand-alone programming mode) or a programming track controlled by a Chief or Zephyr command station. The Empire Builder command station does not allow Readback of decoder CVs; users of the Empire Builder can add CV readback capability by using a programming track connected to a PR3 operating in stand-alone programming mode.

The steps below show how to add a connection to JMRI (DecoderPro, PanelPro, etc.) for a LocoNet-based system.

Connect your adapter to the LocoNet, and connect your computer to it with the appropriate serial or USB cable.
Mac and Windows users should install the proper USB drivers if they are using USB devices.
Linux and Mac users should be sure that the correct Java communications packages have been installed.
Open a JMRI program and go to the "Preferences" panel. This normally opens automatically the first time each program is run, or you can select it from the "Edit" menu.
Select the "Connections" item in the window at the left.
Select "Digitrax" in the "System Manufacturer" box.
Select the appropriate adapter type in the "System Connection" box.
You can then configure the proper settings in the "Settings" box. The "Serial Port" must be properly selected and the connection settings properly configured in order for JMRI to talk to the adapter hardware. On some systems with some system connection adapter types, the "Serial Port" setting will be automatically selected. In other cases the first possible "Serial Port" connection will be selected by default. It may be necessary to use tools provided with the computer operating system to determine which "Serial Port" is appropriate for your particular situation.
Select the appropriate "Command Station Type".
When the "Connection Type" is set for the PR3, the "Command Station Type" can be set to "PR3 in stand-alone programming mode" or set to one of the command station types. When set for stand-alone programming, the PR3 will not communicate with LocoNet. When set for a specific command station type, the PR3 programming track is not used; instead, decoder programming is done through the mechanisms provided by the selected command station.
When "DB150 (Empire Builder)" is selected, JMRI decoder programming is done via the DB150 programming mechanisms. The DB150 is not capable of reading decoder CV values, so JMRI will not be able to read decoder CV values via the DB150 programming mechanisms. Empire Builder users can use a PR3 in stand-alone programmer mode, instead of the Empire Builder programming track, to allow decoder CV readback. Some users configure DecoderPro for programming decoders using the PR3 in stand-alone programming mode, and then configure PanelPro to use the PR3 in LocoNet interface mode (also called "MS100 mode") to allow PanelPro to communicate with the Empire Builder command station and LocoNet-connected peripherals. More PR3 setup information can be found on the PR3 setup page.
The "Connection Prefix" is used to help JMRI communicate separately with multiple "connections" to layout hardware. Each "connection" must have a unique identifier, which is specified as the "Connection Prefix". By default, the first LocoNet connection is given a prefix of "L", and additional LocoNet are given prefixes like "L1", "L2", ... Most users should be able to use the default "Connection Prefix" value provided by the JMRI tools.
It is recommended that all connections for LocoNet hardware use a prefix that begins with "L", as other characters are normally associated with other hardware connection types.
When a JMRI tool is configured for more than one connection, each connection gets a menu item on the main JMRI tool window. To help users differentiate between their different connections, each connection has a "Connection Name", which is used as the name of the associated menu item on the main JMRI tool window. Users may change the "Connection Name" for any connection to suit their needs.
Some adapters may have addition configuration options, which may be shown by checking the "Additional Connection Settings". This may show additional settings which may be made for some adapter types. These include, but are not limited to, the options listed here.
- The "Baud Rate" setting. When multiple settings are available, this must be set to match the needs of the particular hardware adapter specified in the "System Connection" setting. This setting will be pre-set and unchangeable you have selected a LocoBuffer-USB, PR3, or MS100 "System Connection". There are two speed choices for the LocoBuffer and LocoBuffer-II; select the one that corresponds to the jumper settings on your LocoBuffer unit. We recommend that you start with the 19,200 choice for the LocoBuffer or LocoBuffer-II; see the LocoBuffer-II and LocoBuffer pages for more information.
- The "Command Station Turnout Command Rejection and JMRI Turnout Command Handling" setting is described below.
- The "Connection Uses" selection determines how "flow control" is implemented in software. This selection should be configured for "hardware flow control" unless you later consistently get a JMRI console message about the LocoBuffer control leads being improperly set up, in which case you might want to try to bypass that by selecting "no flow control". This box will be blank if you've selected LocoBuffer-USB, PR3 or MS100.
=======
Click "Save". You'll be asked if it's OK for the program to quit, click "Yes".
Restart the program. You should be up and running.

If you are going to control turnouts, signals or other devices on your layout from JMRI or another program, we recommend that you set the command station's "Meter route/switch output when not in trinary" option off. (T) When on, this option greatly reduces the number of commands the LocoNet can handle each second, which can cause significant delays when you're controlling signals, etc. To turn it off, you can use the "Configure Command Station" tool in the LocoNet menu to set Option Switch 31 to "T" (thrown), or set it directly in the command station using a Digitrax throttle.

If you will have multiple connections, the "Defaults" settings in the "Preferences" window may be used to direct certain types of operations to different connections. A good example of this is a system with two PR3 connections, one in stand-alone programmer mode for programming decoder CVs, and the other for communication with a layout LocoNet and command station. In this case, use the "Defaults" settings to select one LocoNet connection only for "Programmer" and the other LocoNet connection for "Throttles", "Power Control", and "Command Station".

Using JMRI with LocoNet®

JMRI provides a number of features which allow it to interact with LocoNet.

Many LocoNet devices can be directly addressed by JMRI, such as the individual turnout outputs on a DS54, or the individual block detection inputs on a BDL16x. For more information on how to find those addresses, see this page.
JMRI provides a variety of LocoNet-related tools. These primarily allow configuration of LocoNet device functionality, but also include some tools for status monitoring. Information on these tools can be found at the LocoNet® tools page.

Networked Computers and LocoNet®

There are several mechanisms available to allow multiple computers to communicate with LocoNet. These communicate via standard TCP/IP protocols, and can even work remotely. At least one of the networked computers must have a functioning LocoNet interface. See this page for more information.

LocoNet® Conenction Limitations

Uhlenbrock Intellibox - The Intellibox has two LocoNet connections, called LocoNet-T and LocoNet-B. The LocoNet-T connection can drive more devices, but does not provide the Rail-Synch signals that some LocoNet devices (particularly boosters and the BDL16, BDL162 and DL1B68) require. A LocoBuffer should be connected to the LocoNet-T connection.

Uhlenbrock Intellibox II and IB-Com - These systems currently do not support programming, either via a programming track or on the main.
The Intellibox II and IB-Com has two LocoNet connections, called LocoNet-T and LocoNet-B. The LocoNet-T connection can drive more devices, but does not provide the Rail-Synch signals that some LocoNet devices (particularly boosters and the BDL16, BDL162 and DL1B68) require. A LocoBuffer should be connected to the LocoNet-T connection.

PR-1 not supported - Note that DecoderPro cannot directly program decoders via a PR1 programmer. JMRI supports decoder programming either via the PR3 as a stand-alone programmer or via a command station.

Mac OS X and the MS100 - Because Mac OS X can't communicate at the special baud rate used by the MS100, the MS100 won't work with Mac OS X. You should get a LocoBuffer-USB instead.

Microsoft Vista and the MS100 - It has been reported that Vista does not support the special baud rate used by the MS100. If you find that your MS100 does not work on your Vista machine you should get a LocoBuffer-USB or PR3 instead.

Debugging

When using the LocoBuffer or LocoBuffer-II, be sure that the JMRI preferences for the connection are set to use the same Baud rate as the LocoBuffer or LocoBuffer-II.
On Windows O/S machines, be sure that the JMRI connection is set to use the correct COM port. Use Windows "Device Manager" to help determine which COM port your interface hardware is using, then verify that JMRI is configured to use that COM port.
On Windows platforms, the COM port assignment can change if the interface hardware is moved from one USB port on the computer to another USB port. Avoid changing how your LocoNet-to-computer interface is connected to the computer.
On Windows platforms, the COM port assignment can change if the interface hardware is connected via a USB hub. At Windows start-up, the computer can assign different COM port numbers to devices downstream of USB hubs, even if all of the USB hardware connected in the system has not been changed. Avoid connecting your LocoNet-to-computer hardware downstream of a hub. Note that a computer monitor which has USB connectors, and which is connected to a PC using a USB cable is considered to have a built-in USB hub.
Some PR3 devices were shipped with poor quality USB cables. These cables have been known to cause a computer to fail to communicate with the PR3 or to have intermittent communication. Users should consider replacing the original USB cable from the PR3 with a known-good USB cable.
Erratic or Non-Functioning CV Readback
- Some mobile decoders will only allow proper readback of CV values when there is a sufficient electrical load connected to the F0F (front headlamp) output connections or the motor connections. This means that an incandescent lamp or LED is properly connected to the front headlamp connection and functional. Other mobile decoders will only provide proper CV readback when a motor is connected to the mobile decoder motor connections. Consult the documentation for your mobile decoder to determine what connections are required to allow proper CV readback.
- Some Digitrax hardware is capable of successful CV read and write operations on some mobile decoders but is unable to reliably read and/or write CVs for other mobile decoders. This problem is most obvious with sound decoders from some manufacturers. Some suggestions are listed here.
  - When using a Zephyr (DCS50) or Zephyr Xtra (DCS51), enable its "Blast Mode" programming feature. This will often allow correct writing of mobile decoder CV values.
  - "Programming on the main" can allow a Chief (DCS100 or DCS200) to properly write to difficult mobile decoder's CV values.
  - A programming booster, such as the SoundTraxx PTB-100 or the DCC Specialties Power Pax can often be used between the command station programming track connections and the programming track to allow successful read and write access of CVs on mobile decoders which do not allow readback on a programming track connected directly to the programming hardware.
  - Some PR3 users report that the PR3 programming track can successfully read and program sound decoders when the PR3 is powered using an 18VDC power supply instead of a lower-voltage power supply such as the PS12 or PS14.
Command Station Turnout Command Rejection and JMRI Turnout Command Handling
Digitrax command stations pass LocoNet switch command messages to the DCC track signal so that track-connected accessory decoders can receive the switch commands. Digitrax command stations seem to buffer the switch requests and forward them to the DCC track signal in a way that does not have a noticeable impact on mobile decoder response to throttle control operations. This buffer is limited, and under conditions of heavy LocoNet switch command traffic, can overflow. When this happens, the command station will respond with a message (a \ opcode) saying that it rejected (did not accept) the switch command. When the command station gives this response, the switch command is not placed into the buffer and is forgotten.

This can be problematic, depending on how the device which sent the switch command responds to the rejection message on LocoNet. Many LocoNet devices do not notice the rejection message, so do not attempt to re-send the switch command. Other LocoNet devices can pay attention to the rejection message and can wait a while before re-sending the message. Some LocoNet devices can be programmed either to resend the switch command if the rejection message is seen, or to not resend if the rejection message is seen.

This wide variety of behaviors can cause inconsistent or unreliable behavior of any device which relies on stationary decoder messages on the DCC track signal. Note that this can include devices which connect to LocoNet and which monitor the DCC track signal which is available on the LocoNet cable "RailSync" wires.

JMRI has various mechanisms to help handle these temporary LocoNet switch command buffer overloads. These mechanisms are controlled by the "Turnout Command Handling" option for each LocoNet-based connection. The four JMRI Turnout Command Handling options are described below.
- Normal - the default setting, is recommended for the vast majority of layouts. In this mode of operation, JMRI will quickly retry the last LocoNet switch command seen before the command station's switch command rejection message, and will continue to repeat the switch command until a switch command is accepted by the command station. This quick retry can cause extremely high levels of activity on LocoNet.
- Spread - This mode is the same as "Normal", described above, except that JMRI implements additional delay between any switch commands which it sends to LocoNet. This should reduce the liklihood that JMRI commands would cause an overflow of the the Digitrax command station switch command buffer, but does not have any effect on other LocoNet devices which generate LocoNet switch commands. The retry mechanism described above for the "Normal" mode is enabled.
- Once Only - This disables the JMRI retry mechanism for rejected switch commands. JMRI will not retry any LocoNet switch command messages. The amount of delay between any two JMRI-generated switch commands sent to LocoNet is the same as "Normal" mode.
- Both - This option both disables the JMRI rejected switch command retry mechanism and increases the delay between any two switch commands sent by JMRI to LocoNet.
These options do not take effect until the preferences are saved and JMRI is restarted.

None of these options can guarantee that all LocoNet switch messages will be passed to the DCC track signal.

Some users may be able to reduce the liklihood of this problem occurring by allowing signal hardware to generate blinking signal aspects instead of programming JMRI to sequentially send "on" and "off" messages to the signal hardware.

Other users who do not have any hardware which are controlled by DCC stationary decoder messages on the DCC track signal (or on the LocoNet cable's RailSync wires) may decide to prevent the command station from forwarding any LocoNet switch control messages to the DCC track signal (and RailSync wires) by enabling the command station's "Bushby bit". See the JMRI LocoNet Configure Command Station tool.

One good way to avoid this problem is to prevent the Digitrax command station from receiving the LocoNet switch control messages. This can be done by using only devices which send and/or receive switch control messages via the LocoNet data bus, and to implement a standalone LocoNet for use by those devices. This standalone LocoNet can be separately connected to JMRI so that JMRI can access the command station, throttles, fast clock, and other resources via one LocoNet connection, and access signals and turnouts via another LocoNet connection. This requires a separate LocoNet adapter for each connection. See Standalone LocoNet® for background, ideas, and suggestions for implementing a standalone LocoNet.

Support

Support for Digitrax hardware products is available through Digitrax, Inc. Digitrax product manuals may be found here. Note that Digitrax does not provide support for JMRI software.

Many knowledgeable Digitrax users contribute to the Digitrax User's "Yahoo Group". If you have a problem with Digitrax equipment, this is a good place to pose your Digitrax-specific problems. This user's group is run by and for Digitrax users. It is not directly supported by Digitrax.

For JMRI-specific questions, including questions about how JMRI and Digitrax hardware interact, the JMRI Users "Yahoo group" is very helpful.