RepRapLinuxSoftware

Downloading and installing the RepRap software under Linux or Unix

RepRap uses a large number of open-source software packages for development, and quite a few when it runs. This page describes how to take a standard Linux/Unix installation and prepare it for RepRap development. It then describes how to download and set up all the RepRap software.

Note that for many of these installations you will need the superuser password for your machine.

When I wrote this page I took a raw Linux PC and set it up, logging everything I did. The Linux I used was Debian. The only packages loaded when I started were X Windows and associated software that Debian installs when you ask it to build a desktop environment. It should be easy to adapt the descriptions below for other Unix systems.

To do most of the following work it is useful to have three windows open on your computer:

• A terminal window,
• A terminal window where you are logged in as the superuser, and
• A web browser with this page displayed.

Then you can copy-and-paste the commands below into the appropriate terminal window. Be careful what you type in the superuser window, especially if you are not a Unix expert - you can damage your system with an ill-judged command...

When you have finished each section below close all windows and programs that you have opened except those three.

Where does stuff go?

This depends on your system and its conventions. You will probably want to install everything system-wide (that is, not just in your own space) so everyone who uses your computer can work with RepRap. On Linux systems this means creating directories in /usr/local to put installation files in. Some Unix systems also install files in /opt.

When you create directories in /usr/local (or /opt) start them with capital letters. Then it's easy to keep track of everything as all other directories in there start with lower case.

Initial packages

Here is the first list of packages to install, linked to their home pages:

• minicom (for talking directly to serial ports)
• zip and unzip (file compression)
• xpdf (for electronic data sheets)
• gputils (GNU PIC microcontroller utilities)
• subversion (version control)
• libsdl (multimedia library needed by Kicad below)
• Qt (needed by Pikdev below)
• KDEbase (needed by Pikdev below)

You may find that your Linux distribution already has some or all of these installed. The reason for that list is that everything on it can be very simply added to a Debian system using the Synaptic Package Manager (Applications -> System tools -> Synaptic Package Manager); that will handle where all the files go - for this section you don't need to worry about that. Just copy and paste these one by one into the search option and mark them for installation:

    minicom (for serial port testing / communication)
    gputils (various tools for PIC programming)
    subversion (just select subversion - other things it needs will be fetched automatically)
    libsdl (select libsdlx.y.dev - the development files for the current version: x.y)
    libqt3-mt-dev (development libraries for QT)
    kdebase-dev (development libraries for KDE)
    libgtk-java (development libraries for GTK+)
    libgcj7-awt (development libraries for the AWT toolkit)

then click on "Apply".

Java

RepRap's controlling software is written in Java, and also the Art of Illusion design package for three dimensional objects uses it, so next we need a Java development environment. The following method of getting one should be clean, in that it is easy to separate it from any Java that you already have on your system.

Java Development Kit (JDK) on Ubuntu

Install the sun-java6-jdk package as the sun-java6-jre package does not contain all the bits needed to build the RepRap applications.

sudo apt-get install sun-java6-jdk
sudo update-java-alternatives --set java-6-sun

If you see errors involving "gij" or "gcj" it may be necessary to run:

sudo update-alternatives --config java

to replace the GNU Java environment with the Sun one.

If Ubuntu's Sun Java packages are installed as above, do not do the Generic Linux install detailed below.

Java Development Kit (JDK) on Generic Linux

Go to the Sun Java Downloads Page. To start with you want The J2SE Java Runtime Environment (JRE). Click on the "Accept Licence" button (you can even read the licence, if you like, but remember: Life Is Short...), then click on the Linux self-extracting file (which will be called something like j2re-1_4_2_13-linux-i586.bin; the numbers will change as the versions change) and save it as a file in your home directory.

Next, as the superuser, create a directory to put Java downloads in and move the file you just got into it:

    # cd /usr/local
    # mkdir Java
    # cd Java
    # mv ~your-id/j2re-1_4_2_13-linux-i586.bin .     (Don't forget the . !)

Where your-id is your user ID on your system, and the j2re-1_4_2_13-linux-i586.bin file is the one you just downloaded.

Make sure the file is executable, then run it:

    # chmod +x j2re-1_4_2_13-linux-i586.bin
    # ./j2re-1_4_2_13-linux-i586.bin

This will ask you to genuflect before the licence (again), and will then extract the files into a subdirectory that will end up being called something like /usr/local/Java/j2re1.4.2_13.

Finally, the file /usr/local/Java/j2re1.4.2_13/bin/java needs to be in the search path for executables. The simplest way to do this is to create a symbolic link to it from /usr/local/bin:

    # cd /usr/local/bin
    # ln -s /usr/local/Java/j2re1.4.2_13/bin/java

Eclipse: the Java development platform

Installing Eclipse on Ubuntu

Ubuntu provides Eclipse as a maintained package, which means things get updated and upgraded as part of the automatic maintenance processes. Install it using the package manager, or with the following command line typed at a console:

sudo apt-get install eclipse

If Ubuntu's Eclipse package is installed as above, do not do the Generic Linux install detailed below. You will however need to do the Subclipse install.

Installing Eclipse on Generic Linux

Next you need the Eclipse Java development platform. Follow the Download link from that page. This should be smart enough to spot what sort of computer you are on, and to give you the option of downloading the Eclipse SDK 3.2.1 for Linux (the numbers may change if they're up to a different version). Click on that, and then on a mirror site that is geographically close to you. Save the resulting compresed tarball (which will be called something like eclipse-SDK-3.2.1-linux-gtk.tar.gz) in your home directory.

Next, as the superuser once more, move the file to the /usr/local/Java directory and unpack it:

    # cd /usr/local/Java
    # mv ~your-id/eclipse-SDK-3.2.1-linux-gtk.tar.gz .
    # tar -xvzf eclipse-SDK-3.2.1-linux-gtk.tar.gz

This will create a subdirectory under /usr/local/Java called eclipse and put lots of files in it.

The file /usr/local/Java/eclipse/eclipse needs to be run to get Eclipse working, but it likes to be in its own directory when it does so. Consequently type the following:

    # cd /usr/local/bin
    # cat > eclipse
    #!/bin/sh
    cd /usr/local/Java/eclipse
    ./eclipse

Finish with <CTRL> C on a new line. This is a little shell script that moves to where you need to be then runs Eclipse. Note that the # before the exclamation mark is part of the file.

Finally make sure it has the right permissions:

    # chmod +x eclipse

To test it, as you (not the superuser) just type the eclipse command, which will run the script you just created:

    $ eclipse

This should produce a blue I-am-starting-up window, then ask you if you want to create a workspace in your home directory (say yes), then give you the development platform window.

Subclipse: version control under Java

All of RepRap is maintained under the Subversion version-control system. This allows easy updating of source code, and also roll-back to previous versions should that be needed. The section of Subversion that works in Eclipse is called Subclipse, and it installs itself from within Eclipse.

First, run eclipse as root (to install Subclipse system-wide):

    # sudo eclipse

Then, follow the instructions on the Subclipse webpage, then close eclipse.

Note: In Step 6 of those instructions, be careful to only select Subclipse, not any other plugins such as Mylar which may be visible on that screen.

Note: If you are behind a firewall or use an HTTP proxy server you may need to configure Eclipse so that it knows about that before you install Subclipse. In Eclipse go to the menu: Window -> Preferences -> Install/update and enter the location of the HTTP proxy machine on your network and its port number (usually 3128, but check with your network manager if you are not sure about this). If you are a private individual on broadband you should have a direct connection and this won't be needed.

The RepRap Java programs

Now (finally...) you can download part of the RepRap project - all the RepRap Java source code.

As you (not the superuser) run eclipse.

In Eclipse go to the menu: Window -> Open Perspective -> Other... and you will get a menu containing (among other things) SVN Repository Exploring. Select that and click on OK. It should open a window called SVN Repository. Right mouse click in that window and select New -> Repository location.

Type the URL for the RepRap project at SourceForge:

    https://reprap.svn.sourceforge.net/svnroot/reprap/trunk

You may be asked to accept an encryption signature, and it will then enter the main part of the RepRap project in the SVN Repository window.

If you open this (the little triangle on the left) you will see all the sections of the RepRap project. Select reprap then host, right-mouse-click, and select checkout. It will ask you if you want to put this in Reprap in your main workspace (say yes), and it will then download all the RepRap software for driving the RepRap machine from your computer as a host.

Top right in the Eclipse window is a tag that says SVN (this is telling you that you are using Subversion at the moment) and a >> symbol. Click on that >> symbol and select Java. This takes you back to the Java language view, in which you should now have installed the RepRap host software. Open it up; the source code is under src. Explore...

You still can't run the RepRap software yet because you haven't got...

3D graphics in Java

The host RepRap software uses three-dimensional graphics to allow you to interact with the RepRap machine, so you need a copy of Java3D to permit that to work. Click on that link and download the appropraite file for your machine into your home directory; for Linux on a PC that file will be called something like java3d-1_4_0_01-linux-i586.bin. Note that, at the time of writing, Java3D version 1.5 does not work with the rest of the software, so you will need to click the previous versions link on the Sun site. Version 1.4.0.01 definitely works.

Then, as the superuser, move the file to your Java directory, cd to the Java run-time environment (JRE) directory, then run the downloaded file:

    # cd /usr/local/Java
    # mv ~your-id/java3d-1_4_0_01-linux-i586.bin .
    # chmod +x java3d-1_4_0_01-linux-i586.bin
    # cd j2re1.4.2_13 ### Your JRE directory
    # ../java3d-1_4_0_01-linux-i586.bin

This will add extra files to your Java lib directory where Eclipse will be able to find them. If you have problems, check the README in the download folder, and see WhereIsMyJRE.

Now you can run the RepRap software. As you, not the superuser, open Eclipse, open the RepRap project, go to src -> org.reprap and right-mouse-click on Main.java. Select Run as -> Java application. This should open a window that looks like this:

This is a representation of the build-base of the RepRap machine. You will load objects to be made here, move them to where you want them built, then build them.

For the moment experiment with the tilt, zoom and pan controls (left, middle and right mouse buttons respectively).

Annoyingly, if you have an Nvidia graphics card on your system, a bug in the Nvidia drivers may become aparent here, and the software will give a Java exception rather than giving you graphics. To fix that, see here.

USB and serial-port communications from Java

The host computer (that is, the computer on which you're installing all this stuff) talks to the RepRap machine using either an RS232 serial port (/dev/ttyS0 or /dev/ttyS1 on most machines) or via a USB-to-serial converter (/dev/ttyUSB0). Most laptops and some desktop PCs don't have a serial interface, so - if you have one of those - you will need to buy such a converter; they normally only cost a few pounds. (RepRap 2.0 "Mendel" will be driven directly via USB.)

Java, therefore, needs to know how to talk to these interfaces. There is a Java API that implements this. There are two implementations of it, one by Sun and one open source equivalent called RXTX.

Installing the RXTX Serial Library

As of early June 2007, RepRap now uses the RXTX serial libraries. The current version of them being used is 2.1.7-r2. Check the RXTX site to see if there is a newer one at the time you read this, and download the appropriate Linux binary .zip file, currently [[1]]. Save this file in your home directory. Now unzip the three files you need from it:

$ unzip -j -o rxtx-2.1-7-bins.zip rxtx-2.1-7-bins-r2/RXTXcomm.jar rxtx-2.1-7-bins-r2/Linux/i686-unknown-linux-gnu/*.so

Now as root, copy those files underneath your JRE so Java will find them. In this example your JRE directory is /usr/lib/jvm/java-1.5.0-sun-1.5.0.11/jre. See WhereIsMyJRE.

$ JREDIR=/usr/lib/jvm/java-1.5.0-sun-1.5.0.11/jre # See WhereIsMyJRE. $ sudo cp -vp RXTXcomm.jar $JREDIR/lib/ext/ $ sudo cp -vp librxtx*.so $JREDIR/lib/i386/

Granting yourself permissions on your serial ports

Finally, ordinary users may not have access to the serial port(s) on your machine. So, add yourself to the dialout group (in Ubuntu), or take whatever other action you need to so you can access those devices.

{| border="1" |- $ sudo moduser -G `groups ||sed 's/ /,/g'`,dialout `whoami` |}

A more manual approach is to edit your groups database by hand, perhaps by $ sudo vigr -s

or similar. The moduser approach should work in both Debian and Ubuntu, and probably also in Red Hat based Linux distributions like Fedora and RHEL and CentOS. Serial port permissions are very distribution specific, so if you have issues with them, please read the documentation for your distribution carefully for clues.

-- Main.JonathanMarsden - 05 Jun 2007

Art of Illusion

RepRap uses Art of Illusion as a 3D design tool. Click on that link and go to downloads then to Linux. Download Art of Illusion into a file in your home directory (the file will be called something like ArtOfIllusion24-Linux.zip).

As the superuser make a directory to put AoI in, move it there, and unzip it:

    # cd /usr/local
    # mkdir <noautolink>AoI</noautolink>
    # cd <noautolink>AoI</noautolink>
    # mv ~your-id/ArtOfIllusion24-Linux.zip .
    # unzip aoi231.zip

This will create a directory called something like ArtOfIllusion and put some files in it. Move to that directory and unzip the launcher:

    # cd <noautolink>ArtOfIllusion</noautolink>
    # chmod +x aoisetup.sh
    # ./aoisetup.sh

As with Eclipse, AoI likes to be in its own directory when it is run. So create a shell script:

    # cd /usr/local/bin
    # cat > aoi
    #!/bin/sh
    cd /usr/local/ArtOfIllusion
    ./aoi.sh

Finish with <CTRL> C on a new line and set the permissions of the resulting file:

    # chmod 755 aoi

RepRap uses a number of additional scripts in AoI, so you need to run it in order to download them too. You must do this as the superuser so that AoI can install these scripts on your machine. Run it:

    # aoi

and go to the Tools -> Scripts and Plugins Manager menu. Select the Install tab. (Note that if you are behind a firewall you may first have to click on the Setup... button and enter details of your http proxy.) AoI will scan for scripts and plugins (this might look as if it has found nothing as sometimes no files appear in the window; ignore this absence and do the next thing anyway). Click Select all and then on Install selected files. AoI will get all the available plugins and enhancements and install them on your system.

If you want to use AoI to design or modify parts for your RepRap machine to make (and that's the whole point...) then you may care to look at this RepRap page on using it for engineering design.

Picp, Gpicp and <noautolink>PiKdev</noautolink>

Picp and Gpicp are a couple of small utilities for dealing with PIC programming, and so it's useful to have them. You can install them via your linux distribution's package manager, i.e. "apt-get install picp gpicp" for Debian and Ubuntu, "emerge picp gpicp" for Gentoo, or "rpm --install picp gpicp" for Redhat and SuSE.

If you wish to install them by hand, click on that link and download the files:

    picp-0.6.8.tar.gz
    gpicp-0.1.1.tar.gz

(as usual, the numbers may differ if the version has been updated). As the superuser, make a directory for them, and install them:

    # cd /usr/local
    # mkdir PIC
    # cd PIC
    # mv ~your-id/picp-0.6.8.tar.gz .
    # mv ~your-id/gpicp-0.1.1.tar.gz .
    # tar -xvzf picp-0.6.8.tar.gz
    # tar -xvzf gpicp-0.1.1.tar.gz

This will create directories picp-0.6.8 and gpicp-0.1.1 and put the files in them. To build them do:

    # cd picp-0.6.8
    # make
    # make install
    # cd ../gpicp-0.1.1
    # make
    # make install

To test them, as you (not the superuser) type:

    $ gpicp

You should get a window containing a table of hexadecimal zeros (what will be programmed into the PIC) with a menu bar across the top.

PiKdev is another suport package for the PIC microcontroller.

It is easiest if you simply follow the instructions on their site.

Run the command pikdev.

This should open the <noautolink>PiKdev</noautolink> window. It may complain about lack of permission on your serial and/or parallel ports, in which case do what it says.

Developer Documentation

This is for the extra stuff that most people wont need. Circuit boards, firmware compiling, etc.