Skip to main content

JMRI Install Guide: Mac OS X (for old releases of JMRI)

These directions are for installing older releases of JMRI.

If you're trying to install JMRI 2.10 or later, please see the production installation instructions.

If you're really sure you want to install an old release (I'm sure you have a really good reason), on to the show:

Installing old JMRI releases on to your Mac OS X computer

  1. Determine if your system software is up to date

    2. Mac OS X version 10.4 "Tiger" or later is required for JMRI version 2.4 or later because those JMRI versions require Java 1.5. There's an Apple web page that lists the computers that are able to run Mac OS X 10.4 If you're still running Mac OS X 10.3 "Panther", you can download and use JMRI version 2.2.

    You should have enough memory for your computer to run well, but you don't need any more than that.

    The install will take up about 100MB of disk space, mostly for the help pages.

  2. Determine if you have the needed hardware.

    No Macintosh that runs Mac OS X has built-in serial ports, so if your hardware needs a serial connection, you'll have to use a USB to serial adapter.

    You will need Mac OS X drivers for the serial hardware you're using. If you're using MacOS X 10.4 or later, most hardware won't need a separate driver; they're already present in MacOS X. In some cases you will need a driver, though, so check the manufacturer's web site to make sure.

    We test using a Keyspan PDA Adapter; those drivers are available at http://www.keyspan.com/downloads/. Some device drivers will list each port under several names, e.g. starting with "/dev/tty" or "/dev/cu", for example "/dev/tty.KeyUSA19181.1". In that case, you must select the one that starts with "cu", e.g. "/dev/cu.KeyUSA19181.1".

    There's a Mac OS X driver for USB-serial adapters based on the Prolific PL2303 chipset available here. If you can't access your USB dongle and it seems to use that chipset (you can check in the USB tab of System Profiler), this driver will make it available as /dev/cu.PL2303-xxx.

    Note that because of baud rate limitations in Mac OS X itself, it's not possible to use a Digitrax MS100 currently. Use a RR-CirKits LocoBuffer-USB or Digitrax PR3 instead.

    See our page on USB adapters for more information

  3. Install the serial communications libraries

    4. Versions of JMRI before 2.9.2 required that you install communications libraries on your computer.

    Although Mac OS X comes with an up-to-date Java, it doesn't include the Java communications libraries. These are needed to talk to a command station, so we provide an installer.

    If you're using Mac OS X 10.6 (Snow Leopard), you first have to configure Java on Mac OS X for "32 bit" operation. Mac OS X 10.6 can run in either 32-bit or 64-bit mode, but the communications libraries we currently use are only available in 32-bit mode. To do this, open the "Java Preferences" application from the Utilities folder inside the computer's Applications folder, then set the default "Java Application" in the lower window to "Java SE 6 32-bit". Next, download the installer for the default communications library from http://downloads.sourceforge.net/jmri/RXTX-Leopard.pkg.zip (This installer also works for Intel-based Macintoshes running Mac OS X 10.6, even though it's labelled for Leopard). The file name will be RXTX-Leopard.pkg, but the splash screen will say "Tiger" and "10.4" due to an oversight; just ignore that) If the installer doesn't start automatically, double click on the downloaded and expanded file to install it. You will need the Mac OS X administrator password to run the installer.

    If you're using Mac OS X 10.5 (Leopard), download the installer for the default communications library from http://downloads.sourceforge.net/jmri/RXTX-Leopard.pkg.zip (This installer works for both PowerPC and Intel-based Macintoshes running Mac OS X 10.5. The file name will be RXTX-Leopard.pkg, but the splash screen will say "Tiger" and "10.4" due to an oversight; just ignore that) If the installer doesn't start automatically, double click on the downloaded and expanded file to install it. You will need the Mac OS X administrator password to run the installer.

    f you're using Mac OS X 10.4 (Tiger), download the installer for the default communications library from http://downloads.sourceforge.net/jmri/RXTX-for-Intel-Mac.pkg.zip (This installer works for both PowerPC and Intel-based Macintoshes) Double click on the downloaded and expanded file to install it. You will need the Mac OS X administrator password to run the installer.

    If you want to use Mac OS X 10.2 (Jaguar) or 10.3 (Panther) with a much older version of JMRI, download the necessary installer for the default communications library from http://downloads.sourceforge.net/jmri/JavaCommInstaller2.hqx If the installer doesn't start automatically, double click on the downloaded and expanded file to install it. You will need the Mac OS X administrator password to run the installer.

    Note that you will have to reinstall the driver and javax.com package if you have to reinstall the system software, or if you do a "clean install" of an OS update.

  4. Get JMRI

    5. Download a version of JMRI. If you're on this install page, then that version should be 2.8 or earlier. As the version numbers change with every release, this link takes you to the general JMRI download page, where you can select whichever version you like.

  5. Install JMRI

    6. Normally, the download will open a new window showing a JMRI folder. If not, double-click the file you downloaded above. This will open a window with the "JMRI" folder.

    To install, you just have to move the JMRI folder to where you want it on your computer. Many people put it in "Applications", which is the standard location for this. To do that, just drag the JMRI folder onto the "Applications" icon. If you want to keep it somewhere else, just drag the folder to the desired location.

  6. Installation is complete.

    7. You can run the program by double-clicking on the "DecoderPro" or "PanelPro" or application icons in the JMRI folder.

    Configuring your JMRI setup

  7. Connect your computer system to your command station hardware.

    8. Your next step will be to set the preferences for your particular layout connection.

    MacOS X uses names like "/dev/cu.SomeName" and "/dev/tty.SomeName" for devices, including USB-attached devices like USB-serial converters, LocoBuffer-USBs and similar. Generally, you'll want to use the one that starts with "/dev/cu" if it's present, but see the specific installation page for your particular type of device. Sometimes you can recognize your interface from the right-hand part of the name. If not, the easiest way to find the name for your interface is to disconnect it, start JMRI, write down the list of available devices, close JMRI, reconnect the interface, start JMRI again, and look to see which extra name has appeared. That's the name one you want.

Customizing Your JMRI Installation

You might want to have more than one configuration for DecoderPro or PanelPro preset. For example, you might to sometimes connect PanelPro to the command station on your layout, or other times have a configuration that doesn't use a layout connection so you can work with the program on a laptop away from the layout.

With Mac OS X, JMRI makes this easy to do. PanelPro and DecoderPro save their preferences separately, so they can be configured independently.

On a Mac, the different preferences files take their name from the name of the application icon that's invoked. This lets you create multiple copies of e.g. DecoderPro that each use their own, separate preferences files. Let's say you want one called "CoolNewOne".

  • Duplicate the DecoderPro application icon (ctrl-click to get a popup menu and say duplicate, or select the icon and choose duplicate from the File menu in Finder).
  • Change the duplicate's name. (It's probably better to use a simple one-word name like "CoolNewOne")
  • Double click your new icon, and off you go.
It won't work to drag one of the JMRI application icons out of the JMRI folder, since they need the other files that can be found there. If you want an icon in some other place, like on your desktop:
  • Go to the JMRI folder and select the application icon.
  • From the file menu, select "Make Alias"
  • Drag that new alias icon to it's new location, and optionally rename it.
Note that renaming the alias alone does not cause the application icon to be renamed, so the alias will be using the same preferences as the original.