JMRI Install Guide: Mac OS X
Note: These directions are for installing the latest
3.x/4.x releases of JMRI on OS X.
If you need to install an earlier release (such as 2.8, or even earlier), please see these Mac install instructions for old JMRI releases.
Now, on to the show:
Installing JMRI on your Mac OS X computer
- Determine if your system software supports JMRI: Find the current Mac OS X version number by choosing "About this Mac" from the Apple menu.
- Determine if you have the needed hardware drivers:
No Macintosh that runs Mac OS X has built-in Serial Ports, so if your layout hardware needs a serial connection, you'll have to use a USB-to-Serial adapter.
No matter if you have a USB-to-Serial adapter, or a device with a direct USB connection, you will need Mac OS X drivers (system software) for the hardware you're using. Most hardware won't need a separate driver; they're already present in Mac OS X. In some cases you will need to install a special driver, though, so check the manufacturer's web site to make sure.
Note: Mac OS X 10.11 El Capitan generally requires signed drivers. If you installed drivers for a previous version, particularly drivers that don't say they support Mac OS X 10.10 Yosemite, those older drivers may not work with 10.11 El Capitan. Go to the web site for your USB adapter, download the newest driver and install it before you update to El Capitan, or right after updating before trying to run JMRI.
We tested 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 is currently not possible to use a Digitrax MS100. Use a RR-CirKits LocoBuffer-USB or Digitrax PR3 instead. Please see our page on USB adapters for more information.
- Get the JMRI software...
- ...and install it.
- Depending on how your Mac is set up, you might need to
- Let's try the easy way first. Open the JMRI folder you just put in Applications, and double click on DecoderPro. If this starts up OK, you have Java installed. Move to the next step. If it opens a dialog box that offers to install Java, or takes you to the Java install web site, just follow those instructions.
- If that doesn't work, and you have a recent
MacOS X version, you can get the latest Java JRE installer as a free download at:
After that download is complete, follow the included instructions to run the Java installer.
More on Java versions and hardware requirements.
- If your Mac OS X version is so old that Oracle does not provide an installer, you can try to you can download an installer from Apple. In this case, you may not be able to run the most recent JMRI versions. Please go back to the top of the page for further information about older Mac OS X versions.
- Congratulations! Installation is complete.
JMRI System Requirements
Using JMRI requires a combination of hardware (in this case a Mac), Java software and a JMRI download for a specific version.
JMRI® version 4.2 requires Java 1.8.
Version 3.10.1 requires Java 1.6 or later.
Version 2.14.1 requires Java 1.5 (or 1.6 if you wish for drag & drop).
Version 2.12 requires Java 1.5 or later.
Mac OS X version 10.8.3 "Mountain Lion"/10.9 "Maverick/10.10 "Yosemite"/10.11 "El Capitan" can run the current JMRI test and production releases with Java 8.
If your computer runs one of these OS versions, just go to the next step.
Mac OS X version 10.7.3 "Lion" can run JMRI 3.10.1 using Java 1.7.
Mac OS X version 10.5.8 "Leopard" can run JMRI 2.14.1 using Java 1.6.
Mac OS X version 10.4 "Tiger" through 10.5.7 can run JMRI 2.14.1, because that's the last JMRI version that can run on Java 1.5, the last JVM available for "Tiger".
The JMRI install will take up about 120 MB of disk space, mostly for the Help pages.
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" version appears every month or so. You may find one of these has features that you really want. These are announced in the JMRI users Yahoo group at https://groups.yahoo.com/neo/groups/jmriusers/info.
Normally, the download will open a new Finder window showing a JMRI folder. If not, double-click the file you downloaded above. This should open a window with the "JMRI" folder. If that still doesn't open a window, look for a newly-mounted disk image (e.g. in Finder) and open that manually.
To install, you just have to move the downloaded 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.
If you already have JMRI installed and working, and want to update to a newer version, just:
- Download the new version
- Double-click on the downloaded file to open the disk image. That should open the contents in a new Finder window, but if not, open it.
- Drag the new JMRI folder to the Applications icon to replace your existing version. If asked whether you want to do that, say OK.
Connect your computer to your Command Station hardware.
You can run the program by double-clicking on the "DecoderPro" or "PanelPro" or other application icons in the JMRI folder.
Depending on your security settings, when you first try to run a new JMRI version (usually by double clicking on the icon for DecoderPro or PanelPro), you may get a warning dialog that it "can't be opened because it's from an unidentified developer". In that case, dismiss the dialog, then hold the Control key down and click the icon to get its contextual menu. Select the "Open" option. You'll be asked to confirm. Be sure to click the "Open" button, and not accept the default "Cancel".
Your next step will be to set the Preferences for your particular layout connection. More on this on the JMRI Setup help page. Go there next to complete your setup.
Mac OS 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.
DebuggingJMRI supports many different Mac computers, with several different kinds of processors, multiple Mac OS X versions, and various layout hardware. Some combinations can cause trouble. This section gives some debugging hints.
Communications and Mac OS X 10.4Mac OS X 10.4 was a transitional version, with lots of different structures in it depending on the specific sub-version (10.4.1 vs 10.4.2 vs 10.4.3). Certain combinations of sub-version and processor cause aren't properly handled by the standard libraries distributed with JMRI.
We handle this by making available some alternative libraries, at least one of which is going to make JMRI work.
If you've got Mac OS X 10.4 and are having a problem either getting JMRI
to start, or to see the attached layout hardware from within the program,
please see this
description of how to debug this.
Customizing your JMRI InstallationYou 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.
- 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.