JMRI on the Raspberry Pi

A number of people have pioneered using JMRI on the Raspberry Pi for embedded layout control systems. A Raspberry Pi is a very simple computer that costs about US$65 once you add a power supply and memory card (and assuming you don’t have a keyboard, mouse or monitor connected once you finish setting it up). It’s also about the size of a deck of playing cards, and can easily be installed on a layout and left there. If you need to update it, just pop out the memory card and take it to another Pi to work on it, than put the updated card back.

This page documents my preferred method for installing JMRI on a Raspberry Pi using Raspbian Jessie as of Spring 2016. It’s not the only method, but it’s what I use. There is also a page on the JMRI site explaining the installation of that software, but it includes a number of obsolete steps with some confusing instructions about what to skip. It also doesn’t discuss preparing the Pi for the software to run as a user other than pi or root (I prefer to run it as user jmri).

Note: always power off the Pi before removing or inserting a memory card, and be sure to keep a backup.

On a related note, if you want to use a Raspberry Pi with JMRI to connect wireless throttle apps running on smartphones, see this how-to post.

After doing my first JMRI install (in the fall of 2015) I came across this post, which provides a fairly good overview. Note that it is describing the 4.3.x release of JMRI, which is still the development release when I write this in the spring of 2016. I don’t recommend using development software for something important (bugs are much more likely) and I’m presently running 4.2.1 as described below.

Installing JMRI

There is a script available online that installs JMRI on a Raspberry Pi for “headless” operation (i.e., without a screen connected), but I’ve read that it no longer works and it doesn’t appear to have been updated, so that’s probably true. I haven’t tried it, although I did use it as a guide for my first JMRI install. (the script can be found here if you are curious).

Among other things, the scrip installs a version of VNC, allowing remote access to the JMRI display from another computer using standard remote desktop tools. That’s very useful, and it’s one of the things I adopted from it.

Because I did things manually, my install is somewhat different, so I’ve assembled my notes on that onto this page.

Installing JMRI is fairly easy. First, start with an up-to-date memory card with the version of Raspbian that you want to use. You can use other versions of Linux compatible with the Pi as well, but I’m using Raspbian so that’s what these notes are about.

Before you can install anything, your Pi needs a network interface (the built-in Ethernet or an added Wi-Fi USB interface) and a connection to the Internet. You also need to change the password of user “pi” from the default of “raspberry”. Once you connect a Pi to the Internet, someone else may be able to access it if you don’t change the password. This depends on something like SSH or VNC running, but that can happen by default depending on how your memory card was configured. So, change that password!

Now, log in as user “pi” (via an attached monitor or SSH). If you have a monitor but are at the command line, enter “startx” (without the quotes) to start the GUI. Then click on the icon of a computer screen to open a terminal window. You could just stay at the command line, but it’s helpful to have more than one terminal window sometimes, so I do recommend using a monitor and GUI during setup.

Make sure your Pi is up to date, by entering the following commands:

sudo apt-get update
sudo apt-get upgrade

These can take a few minutes to an hour or more to run. If the second one needs to install anything, it will stop and ask you to approve that so don’t just start it and walk away. To approve, type a capital “Y” followed by pressing the return key to continue.

Some sites will tell you to also run “rpi-update”. DO NOT. That command is only for dealing with specific problems (if you have such a problem and someone tells you to use it, fine, but that’s not common). It installs not-yet-final software that is as likely to create problems as fix them. For normal use, a stable Pi is more important, so skip it.

If you are using an older memory card, it’s probably a good idea to also run:

sudo apt-get dist-upgrade

That’s also recommended if you use an older memory card in the new Raspberry Pi 3.

Install the Pi4J Library

JMRI is written in the Java programming language, so to use it you need both Java (which now comes pre-installed) and the Pi4J library that provides an interface for Java programs to work with the Pi.

To install this, enter the following at the command prompt (as user “pi”):

curl -s | sudo bash

The “-s” causes curl to run “silent” and the vertical bar “pipes” the file fetched by curl into a script processing shell (“bash”) that’s running with “root” permissions (“sudo”), which are needed to install the library.

The script will install the Pi4J library in the /opt/pi4j directory.

Once installed, you can update it in the future (if necessary) by typing:

sudo apt-get install pi4j

However, the site notes that this library is relatively stable. Updates are likely only if new versions of the OS change something, or a new model of Pi comes out.

Create a JMRI username

This isn’t strictly necessary, as today JMRI has to run as root due to a limitation in its GPIO access library. If you aren’t using the pins (e.g., if you set up JMRI only for use with something like LocoNet) you may be able to run it as some other user than root, and that’s generally considered good practice since it’s running network-accessible services and it’s generally safer if those aren’t run as “root”. Still, I’m going to use this username as owner of the files and possibly in the future use it for actually running JMRI. If you don’t want to, you can skip this step and install the files as owned by root (the default).

Enter the following at the command prompt:

sudo useradd -m -s /bin/bash -G adm,dialout,cdrom,sudo,audio,video,plugdev,games,users,netdev,input,gpio,i2c,spi jmri
sudo passwd jmri

That long string of names separated by commas needs to be entered without any blanks, but the “jmri” at the end is the username, and it needs a blank in front of it. The “sudo passwd” command will prompt you for a password for the new username. Pick something easy to remember, but not easy for someone else to guess (again, network access means someone else can access your Pi if they guess the password).

Install the JMRI files

I’m assuming you do this as user “jmri”, but it can also be done as user “pi”, if so just log in as “pi” instead of “jmri”.

First, set up the Pi to require you to log in (so you can choose a username other than “pi”). You can do this through menus in the GUI, but there have been problems with those not working correctly in recent releases. I prefer to use the command-line menu system, so open a terminal window and type:

sudo raspi-config

and then use the arrow keys to select “Boot Options” and then either “Console” (command line) or “Desktop” (the GUI). Now log out (if you’re using the GUI, just use the Shutdown menu to reboot the Pi, it’s faster) and enter “jmri” when prompted to log in.

The following instructions assume you store source files you are working on in a directory named “src” under user “jmri”. Type the following commands to create this directory the first time (after that you can just enter the “cd ~/src” command after you log in as that user to go to it).

mkdir src
cd ~/src

Now download the file. This is correct as of early 2016, but the version name will change in the future (likely sometime this summer).

As of July 2016 the new version, 4.4-R1, has been released. I have not yet updated this section to reflect that version. JMRI usually releases a .1 update after they fix initial bugs, so I may wait for that one to update my software.

To find the current one, go to the JMRI Download page and hover your cursor over the link to download the Linux version, and you will see an “https” string, which is what you should use on the curl command. Don’t forget to put single quotes around it (and make sure they are apostrophe straight quotes, not the curly kind; the Pi won’t recognize curly quotes, but if you cut/paste this command you may get curly quotes). If the file name (the part that starts with the capital “JMRI” changes, be sure to change the command to use the same name after the “>”.

curl -L ‘ files/JMRI.4.2.1-R6b484b4.tgz/download’ >JMRI.4.2.1-R6b484b4.tgz

Note: you can probably just cut/paste the name from the link on the JMRI Download page. It’s the same thing with the blank converted to “%20”, which should work.

Be aware that the “-L” is required to follow the link properly; if you omit it you’ll get a very short file that isn’t what you need. If it works, it’s going to take a bit of time as you’re downloading about 89 megabytes of files.

With the file downloaded, run the following commands to extract the individual files and install them in /opt/JMRI (again I’m complicating this a bit to have the files owned by “jmri”, or “pi” if you install as that user, rather than root). And if you changed the file name up above, change it again here.

cd /opt
sudo chmod 777 .
tar zxf /home/jmri/src/JMRI.4.2.1-R6b484b4.tgz
sudo chmod 755 .

Notice the “.” at the end of the two “sudo chmod” lines, that has to have a blank in front of it (those two commands allow the user to temporarily add files to /opt, which is normally protected from modification by ordinary users).

If installing from user pi, change “/jmri/” above to be “/pi/“.

JMRI is now installed, and we’re done.

Running JMRI

You can run JMRI as either root or a normal user. If you run as a normal user, you cannot select “Raspberry Pi Foundation” in Preferences as the “Connection”, and you won’t be able to use the GPIO pins. The program won’t tell you that nicely. It will just crash with a bunch of error messages. No harm done, but a bit scary the first time you do it.

There might be a way to fix this. In the current (Jessie) release, there are some provisions for user-level access to GPIO. I need to look into this more deeply, and see if there’s something I missed configuring. So far, however, the JMRI folks still show running as root to be required.

The command needed to run JMRI, assuming you have a directly connected monitor, is:


or one of the other utilities of JMRI such as DecoderPro. To run this as root, just stick a “sudo ” on the front:

sudo /opt/JMRI/PanelPro

As is usual with the Pi, software defaults to UK English. If you want US English (or something else), go into Preferences in PanelPro and set the Display Locale.