[ Home ] [ Up ] [ Previous Page ] [ Next Page ]


What is JMRI?

If you use DCC, you might find JMRI interesting, if not, move along, nothing to see here.

JMRI is the Java Model Railroad Interface, an open source software project that provides connectivity between your computer and your railroad. JMRI itself is free on Sourceforge along with documentation and help. JMRI comes in versions for Windows, Mac OS X, and Linux. Since JMRI is written in Java, it is portable and all the versions are actually the same. Java is interpreted so that JMRI can get slow on older computers.

JMRI is written by volunteers who are active model railroaders. If you know Java, maybe you can help too. However, just because this is a volunteer project doesn't indicate low quality. These guys have gone to a lot of trouble to write this stuff and it does work quite well.

JMRI currently consists of two major applications, DecoderPro and PanelPro, two minor applications, JMRIDemo and LocoTools, plus a LOT of supporting data that these applications use. DecoderPro basically is a decoder programming tool. PanelPro allows a layout to be diagrammed and DCC equipped locos to be run, either manually or in an automatic fashion provided that hardware support for automation is provided by the user.

LocoNet to Macintosh Connectivity

Computers typically don't come with ports that will interface directly to a DCC system. Some form of data bridge is required to get bits to move back and forth between the layout and a computer in a usable fashion. I have only experience with connectivity of the Digitrax LocoNet to a Macintosh but there are ways, explained on the JMRI website, to get pretty much any computer, even an old clunker, to talk to any major DCC system.

The key to getting a Mac on the LocoNet is a hardware interface. JMRI itself may be free, but the hardware is not. I purchased a LocoBuffer-USB by RR-CirKits for about $56 at Litchfield Station. All the hardware and drivers that I needed were in the package.

However, what wasn't there was a really clear set of instructions as to how to configure the thing once the hardware was installed. It really wasn't that hard, but it took a little cut and try to get it to work.

You will also need Java and some Java communications libraries installed on a Macintosh running a recent version of the Mac OS, Tiger and Leopard work fine. Older versions may work too. If you haven't done it already, use Software Update on the Macintosh to get the latest version of Java that your computer will support. You will also need a Java Communications library installed to enhance the USB drivers to allow communications with a LocoBuffer-USB. This comes with the LocoBuffer-USB.

The LocoBuffer-USB is a merely a hardware interface between the computer and the LocoNet. It provides optical isolation to prevent ground loop problems. The USB side is powered by the computer's USB port. The LocoNet side is powered by the LocoNet, no power adaptor is required. There are two green lights on the box, if both are on, the unit is getting power from both sides. There is also a red light that flickers with LocoNet traffic. Basically plug into the computer and LocoNet and twist a selected throttle and if both green lights are on and the red light flickers, the hardware is working.

The CD that comes with the LocoBuffer has drivers to allow a Mac or PC to communicate with the LocoBuffer via USB. There are older serial LocoBuffers if your selected computer doesn't have USB.

Once the low level stuff is installed, then the configuration of the LocoBuffer (or interface to another kind of system) must be set from within the JMRI software itself. Fire up either DecoderPro or PanelPro and if that configuration has not been set, it will ask you for the info it needs. In the case of a LocoBuffer-USB, find the item in the Layout Connection pull down that says LocoNet LocoBuffer-USB. For the serial port, pick /dev/tty.usbserial. Then pick your command station. Since the LocoBuffer works only with Digitrax's LocoNet, it will list only Digitrax command stations. If you have some other kind of interface, it should list the possible command stations that it could talk to. Note that each of the four applications requires this same setup.

Unlike any other Macintosh application that I have seen, when you change preferences, you must quit the JMRI application to actually save the preferences to make sure that they get loaded properly the next time you fire up JMRI.

JMRI loads pretty slowly on an old Macintosh (PowerBook G4) so be patient when you open DecoderPro or PanelPro. A regular menu bar populated with command menus will appear eventually.

JMRI saves all your user specific data, such as configuration files, and loco roster information, in your home directory. However, Spotlight apparently doesn't index the location where the stuff is stored so it is not easy to find it unless you guess well. The path to the stored information is:


Where "~" is the path to your home directory. Time Machine will automatically back this stuff up, but if you use another backup method, it would be a good idea to make sure that this path is covered by your backup software. JMRI isn't easily faked out by an alias placed in this location that points to the real data stored elsewhere.


DecoderPro, as it's name implies, is intended to deal with programming DCC decoders. It does present the information graphically and it does make setting up speed tables easier. Since JMRI communicates through your command station, it can only do things that your command station can do. For example, a DB150 that comes with the Empire Builder set is not capable of reading back information from decoders on the programming track. Therefore, JMRI interfaced to a DB150 cannot read back decoder data either, the hardware necessary to do that in the command station is simply not there.

DecoderPro recognizes most decoders and formats windows with only the decoder's capability shown. It can do a mass read of all the CV's in the decoder and save that information along with information about the loco that the decoder is installed in. This is handy for reviewing how the decoder is programmed and as a safe place to keep a working configuration while you mess with the decoder. Depending on the system and decoder used, it can take from a few seconds to nearly an hour to read back all the data in the decoder. To read back data from a decoder, the command station has to play a game of "20 questions" until it hears all the answers. It can only ask "does CVx contain the value y?". If the CVx does contain y, then the decoder will draw a pulse of current that the command station can detect as a "yes." If the command station doesn't see the pulse in some short period of time, it increments y by one and tries again. If it tries all 256 values and the decoder doesn't respond, the readback fails. It then has to try this on every CV that the decoder is known to support. QSI decoders have LOTS of CVs and they can take awhile to read back. Simple ones, like MRC decoders, finish a full readback in less than a minute. Writing data back to a decoder goes much more quickly.

When a new loco is put on the programming track, the first thing to do is to read back a CV with a regular throttle to see if the decoder is actually responding properly. If the readback is garbled by some problem, then JMRI isn't going to make much sense of it either. Problems in programming track readback are usually caused by parasitic loads, such as lights, that are still connected. These draw current all the time and confuse the command station as it won't see the current pulse in the way that it expects. Sometimes a sound system installed along with the decoder must be disconnected to leave the decoder alone connected to the programming track.

If the address readback is good, then use DecoderPro to try to figure out what decoder is installed. CV7 and CV8 contain manufacturer and versions numbers. These are sufficient to narrow down the choices to a class of decoders which DecoderPro will highlight. Pick the decoder model from the list and then Open the programmer (button will become available once a decoder is selected). Sometimes the highlighted decoders will not contain the one that is actually used. In that case, pick the one that is actually in there. If the actual decoder is NOT in the list, look on other similar lists or for other similar decoders. If a suitable decoder is nowhere to be found, then there is a way to add it but you have to hand edit some .XML files. I had to do this once for an ancient NCE D408.

Once the programmer opens, you can manually fill in information about the loco. The decoder type will be already filled in with the one that you picked from the list. The decoder's address will get filled in once you read back data from the decoder. Press Read All Sheets to read back all the information that the decoder contains. When DecoderPro finishes, Save and Close the window and move on to the next loco. If you need to change CV values, then you can go to the sheet that contains the CV that you want, enter the data and write it.

Setting up the 28 step speed tables manually can be a real pain. DecoderPro can make it a lot easier as it will interpolate the values surrounding the one that you change manually to make a smooth table with a variety of possible shapes.

DecoderPro supports both Service Mode (programming track) programming, or OPS mode (main line) programming. DecoderPro also has menus for various tools that can come in handy. One of them is a DCC throttle tool. This is handy for testing so that you make changes in OPS mode, you can test the change immediately.


At this point, I have little experience with PanelPro. This will come later. PanelPro also has is a throttle in a window so that you can command a train right from you desktop.

PanelPro allows a layout to be diagrammed with stationary features indicated so that these features can be controlled as well provided that they are wired to be controlled by the command station.

As yet, I have very hazy view of the automation possibilities of PanelPro. This will come with time. Unfortunately, there doesn't seem to be a manual yet written for PanelPro, at least I haven't found it.


There is a third application in JMRI called LocoTools. These tools are Digitrax LocoNet specific so that they won't be of any use on non-Digitrax command stations. The various parts of LocoTools are also available in PanelPro and DecoderPro if a Digitrax command station is selected in the preferences.

These tools include:

If these tools don't make sense to you, then you can safely ignore them.

I found that the DS64 programmer is quite useful. It is easy enough to program a DS64 from a throttle, but it is easier to handle the OPsw part via the DS64 programmer. However, you still have to set up the address from the throttle so that LocoTools knows which one to configure.


The JMRIDemo tool is a sort of preview of the whole system, including parts that you wouldn't normally see because those parts pertain to hardware that you don't have. It is a sandbox that you can play in without doing any damage to anything. The JMRI website indicates that some new features that aren't in the latest stable release often show up in JMRIDemo before they make it into the real tools so that they can be sanity checked before release in a production tool.

Connecting Multiple Computers to the LocoNet

If you have a Digitrax LocoNet, multiple computers can connect to the LocoNet at the same time. There are three ways to do this as described at JMRI Hardware Guide: Methods to Connect Multiple Computers to a LocoNet Layout. The throttles will allow a loco to be "stolen" without notification but the JMRI throttle will update when changed by the original throttle.

I've tried the Client/Server method and it works. This is the one that I will continue to use as I have a pre-existing server computer one wall away from my LocoNet. Then I won't have to drag my laptop outside or to the garage to connect to the layout and I won't have to deal with the LocoNet dongle and the possible trip hazard for both myself and my laptop due to the extra wires. I can also then use JMRI from my desktop which is inside the house and not located near any LocoNet connection.

The WiThrottle, a wireless JMRI throttle

I stumbled across an iPhone/iPod touch application that makes the device into a wireless JMRI throttle. This application was released into the iTunes App Store only on Dec 12, 2009 so it is fairly new. However, it works.

The WiThrottle costs $9.99 and requires a working JMRI (version 2.7.9 or later) installation that will allow control of the layout with the virtual JMRI throttle and a wireless network that can access a computer currently running JMRI. If you have that setup already, the application installation and setup is quite painless. I had all this stuff running already. All I had to do was update JMRI on my server (it was running v2.4) and start the WiThrottle sever. WiThrottle does require iPhone OS 3.0.

The only thing that you have to do to JMRI to get it to connect to the WiThrottle is to start the WiThrottle server from the Debug menu. The server can be started automatically from the Advanced preferences menu.

The first release of WiThrottle allows the selection and operation of a single locomotive or consist. It does remember previously selected locos in a scrolling list. It is fairly easy to switch between locos, but you have to switch between app screens to do it and when you pick up the second loco, the first one stops. If you receive a phone call while a loco is running, the loco is idled during the call. Currently there is no control of switches and no ability to do decoder programming BUT the throttle is full duplex and allows locos to be selected and deselected wirelessly. WiThrottle supports function 0 through 28.

I like this toy, it may also save me the cost of upgrading to full duplex Digitrax throttles.

[ Home ] [ Up ] [ Previous Page ] [ Next Page ]

This page has been accessed hit counter times since 20 Mar 09.

© 2009-2010 George Schreyer
Created 20 Mar 09
Last Updated January 1, 2010