This document outlines the steps taken to install the JMRI suite on an OLPC XO.
The OLPC (One Laptop Per Child ) XO is a small, rugged, Linux based sub-notebook designed to bring a constructionist learning experience to the children of the world. Particularly to bring this to those living in less developed countries.
However, being a small, rugged Linux based sub-notebook, also makes it an excellent candidate for running JMRI.
XO Hardware Specification. XO Software Description.More information about OLPC and the XO can be found at the OLPC website, and the OLPC wiki.
I also hope that this document will provide guidance to others who are trying to install JMRI on other Linux machines.
The XO is a flash-based device running a version of Linux based on Fedora 7 and Linux kernel 2.6.22 with OLPC modifications. Because of the limited space available with the flash drive, some Linux kernel services and utilities are not installed. Space considerations are an issue with adding software to this device.
The XO has a GUI, Sugar, running over X which has been developed specifically for its intended use. Sugar runs an application in a single window, with the current application occupying the entire screen, with rapid switching between open applications.
To install applications such as JMRI which have multiple windows open requires that an alternative GUI be used. I installed XFCE. It is a lightweight windowing system, that has already been successfully installed on the XO. As you you will see in the section discussing the installation of XFCE, it is simple to switch between the two.
Any Linux installation of JMRI seems to be a matter of shooting at a moving target. These are the parameters of my installation:
A certain familiarity with using the Linux shell, executing commands in Linux, and editing files in Linux is assumed. I used vi as my editor. If you have an editor that you are comfortable with, use it instead.
The basic installation goes like this:
To install XFCE you need simply to follow the instructions on the XFCE page in the OLPC wiki.
One minor change that I'd suggest is that while following the instructions to make XFCE the default environment, to do this instead:
in /home/olpc/ create a copy of .xsession-example called .xsession-xfce.
cd cp .xsession-example .xsession-xfce
Edit the .xsession-xfce file to launch Xfce on startup. In your favorite editor find the commented line that reads #exec xterm - below that line, add the following line:
exec startxfce4
save and exit.
Then, you can enable XFCE by doing the following in a terminal window:
cp .xsession-xfce .xsession
followed by rebooting, while in the home directory. And
rm .xsession
and a reboot to switch back to Sugar.
Again some minor changes from the OLPC page. If you've installed XFCE and Firefox at this time, and have internet connectivity from inside XFCE, you can download the '.bin' file directly to your XO, rather than following the instructions requiring download to another machine and transferring the '.bin' file to the XO.
I installed JDK 1.5.0-13 rather than the JRE. When I first tried to install JMRI I thought I'd have to compile rxtx, so I installed the JDK. I haven't tried running JMRI with just the JRE at this time (see Issues below). I'm recommending JDK as a known successful path, so follow the 'Download JDK' link.
The XO has a very limited PATH environment. I ended up creating a soft link from the /usr/bin/ directory to the Java executable.
su - cd /usr/bin ln -s /usr/java/jdk1.5.0_13/jre/bin/java exit
at this point 'java -version' should return:
java version "1.5.0_13" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_13-b05) Java HotSpot(TM) Client VM (build 1.5.0_13-b05, mixed mode, sharing)
If this is what happened you have a successful Java install. Congratulations.
You can now discard the '.bin' and '.rpm' files to reclaim some space on your XO.
JMRI requires that the Sun commapi extension be added over Java to support communications. In addition, another library rxtx needs to be added to go from commapi's abstract support to actually supporting physical serial ports.
Get the rxtx.tar.gz file from the JMRI Users files here.
This has all the files you need for installing commapi and rxtx. I believe the 'comm.jar' file is Sun commapi version 2. The rxtx libraries are 2.0.7pre2, which work. The properties files provide the proper links from Java to the rxtx libraries from the rxtx libraries to your serial port.
Place this file in your home (/home/olpc) folder.
Despite being called 'rxtx.tar.gz' this is not a gzip file, but is simply a tar archive. Expand it by executing the command
tar xvf rxtx.tar.gz
This will create a folder 'lib' with the expanded contents of the library. Rename this directory, 'lib' is just too generic for safety.
mv lib rxtx-lib
Now copy the contents ot this folder to the approprite places within Java. The name of the rxtx serial library as delivered will not be found, so we need a link from the desired name too.
su cd rxtx-lib cp javax.comm.properties /usr/java/jdk1.5.0_13/jre/lib/ cp ext/* /usr/java/jdk1.5.0_13/jre/lib/ext cp i386/* /usr/java/jdk1.5.0_13/jre/lib/i386/ cd /usr/java/jdk1.5.0_13/jre/lib/i386/ ln -s librxtxSerial-2.0.7pre2.so librxtxSerial.so exit
You might also want to download the 3.0 commapi from Sun. This contains a suite of example programs for the commapi. I found that the Serial Demo program was useful for testing the installation of the commapi, rxtx, and USB to serial converter.
Keep the expanded rxtx-lib folder that you have, you will need it for one final step when installing JMRI.
The XO has no user accessible serial ports. It has 3 USB 2.0 ports. A USB to serial adapter is required for connection to most DCC systems.
There currently is somewhat limited support for USB to serial devices on the XO. ftdi_sio is supported, but I have been led to believe that there is a ftdi_sio related bug in the 2.6.22 kernel. Rather than having to deal with this I avoided these adapters. Keyspan adapters are not currently supported by the kernel. This is a known defect in the XO, and the fix is currently scheduled for 6/30/08.
So I chose to use an adapter that uses what seems to be the best supported chip set, the PL 2303.
The adapter I chose is the Dynex DX-UBDB9. This is Best Buy's private label adapter. Other PL 2303 based adapters should work.
The adapter should work by simply being plugged in. It's presence can be checked for by looking for the following device '/dev/ttyUSB0'. Checking should return something like:
ls -l /dev/ttyUSB0 crw-rw---- 1 root uucp 188, 0 2008-04-09 11:12 /dev/ttyUSB0
Proper operation can be checked using the Sun SerialDemo Program and shorting pin 2 to pin 3 for loopback. Note that you have do do this as root, because we haven't allowed user 'olpc' access to the serial port yet.
su cd commapi/examples/SerialDemo java SerialDemo
Should return something like:
Experimental: JNI_OnLoad called. Devel Library ========================================= Native lib Version = RXTX-2.0-7pre2 Java lib Version = RXTX-2.0-7pre2
and open the SerialDemo window. You should be able to select 'Port Name' /dev/ttyUSB0. Click 'Open Port'. Click in the upper frame to focus. Short pin 2 and 3 on your adapter. What you type should be echoed in the lower frame.
If this is the case, congratulations, you have a successful installation of the commapi and rxtx. If not, it's time to check your work and figure out what went wrong.
Now determine what version of JMRI you want to install and download the Linux version of it. Generally the latest release version is a good choice unless you have some specific reason for wanting to try something else.
Uncompress and expand the archive.
su gunzip JMRI.2.0.tgz (this file name will depend on what you downloaded) tar xvf JMRI.2.0.tar exit
You now should have a folder JMRI. If you want to, move it to another location. I put JMRI in /usr/share, which is where OLPC puts a lot of support files.
su mv JMRI /usr/share/JMRI exit
Move a copy of javax.comms.properties to your JMRI folder. This is necessary to allow JMRI to know about the commapi.
cd /home/olpc/rxtx-lib ( or wherever you put the rxtx you downloaded ) cp javax.comm.properties /usr/share/JMRI ( or wherever you put JMRI )
Having to have two copies of this file is bogus, but necessary. See below.
At this point your basic installation of JMRI is complete. You should be able to run JMRI as root from a terminal window.
su cd /usr/share/JMRI ./DecoderPro ( work inside of DecoderPo, eventually exiting ) exit
There are now a few finishing touches that you will want to do to allow yourself to run JMRI as user rather than root, and to open JMRI from the XFCE desktop, rather than from a terminal window.
This is necessary to allow the olpc user account to have access to the serial ports. Be very careful here, as messing up the user account group membership can have adverse effects, up to and including needing to reinstall the entire XO software install.
There are two ways of doing this, editing the /etc/group file or using the usermod command.
Execute the following:
su usermod -Gwheel,uucp,lock olpc
In either case, it is best to make sure that you did this correctly before logging out of the root account.
cat /etc/group | grep olpc
Should return:
wheel::10:root,olpc uucp::14:uucp,olpc lock::54:olpc olpc::x:500:If so, you can:
exit
The JMRI scripts like 'DecoderPro' are designed to be run while your are in their directory. A small change must de done to allow them to be run from another location -- like what you'll be doing when you connect controls in the XFCE dock to them.
Open the desired script file -- DeocderPro for example -- in an editor. You must do this as root.
su vi DecoderProFind the line
# cd /usr/local/JMRI
uncomment it, and change the cd to wherever you have JMRI installed --
cd /usr/share/JMRI
save the file and exit.
Set the script so that it can be executed by the user account and exit root.
chmod +x DecoderPro exit
Repeat this for whatever scripts you may want to run from the XFCE desktop.
Now you can add controls to a XFCE panel to run JMRI components.
If everything has gone right you should now be able to run JMRI simply by opening it in the dock.
Here is a long view showing pretty much the whole XO running DecoderPro.
Here is a tighter view of the screen. There's plenty of memory left.
XO running ruler activity, posed with an N scale locomotive to show how small it is. This is truly a N scale computer for N scale trains.
There are still some issues to be resolved before this installation can be considered optimal. They include:
Space is tight on the XO and JDK is obviously larger than JRE. It would be advantageous to install JRE rather than JDK. I see no reason that JRE 1.5.0_13 should not work. I simply have not gotten around to trying it.
I installed 1.5.0_13 on the strength of the recommendation on the XO wiki. It would be worthwhile to figure out what other versions work (and which do not).
I ended up installing the commapi version that was included in the rxtx lib posted to the JMRI Users group. I don't know its provenance. commapi 3.0 is the only version actively supported by Sun. Some sources have complained about the stability of version 3 of the Sun commapi.
I installed the JMRI suite in /usr/share/JMRI. Many resources are stored in /usr/share on the XO. However, the XO has a nasty habit of deleting items when updating -- and at this point updates are common. I don't know if this is the optimum or safe location for JMRI.
Having to have two copies of a configuration file in two different places is definitely a bad thing. This need to be resolved. Is there a common place they could be? Does an environment variable need to be tweaked? Could one be a soft link?
My install used a USB to serial adapter. A growing number of DCC command stations use direct USB connections. Connecting to these have not been investigated at this time.
There is no easy way of purchasing XOs at the time of this writing. They were available to the general public in the US and Canada directly from OLPC for a six week period at the end of 2007 as part of a charitible giving program. There are no current plans to repeat such a program or to make them available to international buyers.
OLPC has a program for mass purchases by non-profits. The current minimum order is for 100 units at $300 each.
There are usually XOs available on eBay (and likely other aftermarket vendors). A recent search of eBay showed over twenty available.
My thanks to:
Special thanks to: Francisco Athens for doing the original XFCE install on the XO, and making me aware of that path. Dick Bronson, and Bob Jacobsen (again) for support and advice during the sometimes frustrating install. My son for letting me play with his XO.
I hope that in some small way this document is giving back to those communities.
Any errors are mine alone.
Robert Myers, April 2008