Skip to main content

JMRI Install Guide: Mac OS X

  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. Having 50MB of free disk space is sufficient.

  2. Determine if you have the needed hardware.

    No Macintosh that runs Mac OS X has built-in serial ports, so you're likely to have to use a USB to serial adapter.

    You will need Mac OS X drivers for the serial hardware you're using. 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".

    As of October, 2006, Belkin doesn't make a USB-to-serial adapter that works with Mac OS X. Their technical support has confirmed that they don't (yet) have Mac OS X drivers for their adapters.

    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.

    See our page on USB adapters for more information

  3. Install the serial communications libraries

    4. 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.5, download the installer for the default communications library from http://prdownloads.sourceforge.net/jmri/RXTX-Leopard.pkg.zip?download (This installer works for both PowerPC and Intel-based Macintoshes running Mac OS X 10.5 only. The file name will be RXT-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.4, download the installer for the default communications library from http://prdownloads.sourceforge.net/jmri/RXTX-for-Intel-Mac.pkg.zip?download (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're using Mac OS X 10.2 or 10.3, download the necessary installer for the default communications library from http://prdownloads.sourceforge.net/jmri/JavaCommInstaller2.hqx?download 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, either the latest production version, or a "test version". Since 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.

    The JMRI project is continuously adding features, bug fixes, examples and tutorials to the release, and so a new "test" versions appear every couple of weeks. You may find one of these has features that you really want. These are announced in the "jmriusers" Yahoo discussion group at http://groups.yahoo.com/group/jmriusers/.

  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. Connect your computer system to your command station hardware.
  7. Installation is complete.

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

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

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.