RepRapMacSoftware

Downloading and installing the RepRap software on a Mac

These are preliminary instructions not based (yet) on a complete installation

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 Mac OS X 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.

These instructions are based on the skeleton of the Linux standard install, and Mac-specific tips and links are substituted where applicable. So if you see something not quite right, Either I've overlooked it or that part isn't finished.

Much of this is based on using Darwinports, which is not (directly) related to the RepRap device 'Darwin'. Darwinports requires the installation of XCode, available for free from Apple, which enables the X11 development environment and enables running of many Linux packages.

While not the most efficient solution, it should work. Another suggestion would be to dedicate a hard drive or partition to a bootable Linux installation on your Mac. This way you should get optimal processing speed. That said, this documents the process of installing necessary RepRap support applications and design software:

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

   *  A Terminal window,
   *  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 Terminal 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?

(Again, this is modified from the Linux instructions.)

A standard Java Runtime Engine for the Mac OS has a folder /Library/Java that will gladly take the Eclipse installation, complete with its own Application to double-click. I have not encountered any priveledge requirements with Eclipse installed here.

The other important directory is %user/Documents/workspace, which is created by default when you first run Eclipse. 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. While these directories mostly exist on the Mac OS as well, they are in a protected part of the system and you will need to authenticate and/or login to make changes, and Eclipse might have trouble creating installation directories. So my suggestion is to use Library/Java/ as your base for the installation. Reality may vary.

Initial packages

Here is the first list of packages to install, linked to their home pages: These are the Linux versions; Use the second list for the Mac specific versions. These are just listed for reference, or you might have some way of correctly utilizing the Linux version on OS X. Darwinports or X11 may run one app more efficiently than the other, but I am trying to find the 'safest' method of getting the programs to run on the Mac. U

• 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 can get several packages from Apple which allow execution of Xcode via the X11 development package. This package is an optional install from your OS X installation disk, or you can download them from here.

Many additonal Linux applications and packages can run under OS X by using Darwinports , which will enable the installation of Darwin-compatible packages. Here is a list of the equivalent Mac/Darwin packages relevant to RepRap:

• minicom darwinports (communication with ports)
• zip & unzip are included in the basic Mac OS.
• xpdf pdf functions are included as well.
• gputils (GNU PIC microcontroller utilities(Linux Version- temporary link))
• subversion Version control
• libsdl (multimedia library needed by Kicad below)
• Qt (needed by Pikdev below)
• kdebase (needed by Pikdev below)

Once you have Darwinports installed, you can also obtain these packages directly in Terminal:

sudo port install minicom

for example.

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.

Standard Java 5.0 and Java3d are included in Apple's distribution of OS X. It is at the very least compatible with Art of Imagination, and the other RepRap software. Check for updates for Java on Apple's website.

Note: Mac OS X the most suitable directory for installing these Java packages should be /Library/Java/. Installing in /etc may lead to privilege issues and may complicate installation of packages.

Installing Eclipse on Mac OS X

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.2 for Mac OS X (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.2-macosx-carbon.tar.gz) in your home directory.

Mac OS X: the 3.2.2 package for Mac can be downloaded here.

Next, move the file to the /Library/Java/ directory and unpack it using Terminal:

Note:Programs such as Stuffit Expander will uncompress the whole archive, which is not necessarily what we want, so use this standard method as devised for Linux installs:

    # cd /Library/Java/
    # tar -xvzf eclipse-SDK-3.2.2-macosx-carbon.tar.gz

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

The file /Library/Java/eclipse/Eclipse is a Mac -ready executable. open it by double-clicking in Finder.

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.

(Java3d 1.5 comes with the standard Mac Java 5 Install. Check System/Library/Java for the presence of the Java files. You may need to set options to get the Java to run the older, more compatible Java3d 1.4 .)</font>

Careful- they're speaking Penguin!

This instruction IS NOT COMPLETE and everything below this is from the Linux instructions. As I update things, this topic will move down the page until it goes away.

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. It installs itself from within Eclipse, and instructions for doing that are available from this link.

As the superuser (Subclipse needs to install files on your sustem), run eclipse:

    # eclipse

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

Note that 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 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
    # ../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.

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:

File:RepRapMacSoftware-reprap-startup.png

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. Go back to the Sun Java site at the Java Communication API page, and go to download at the bottom. Slightly tediously, you need to register with Sun to do this, but it is free. Once you have done that and (Surprise!) accepted the licence yet again, download the file, which will be called something like comm3.0_u1_linux.zip. As the superuser move that to your Java directory and unzip it:

    # cd /usr/local/Java
    # mv ~your-id/comm3.0_u1_linux.zip .
    # unzip comm3.0_u1_linux.zip

This will create a directory call commapi and unpack a load of files into it.

We only need four of them:

    commapi/jar/comm.jar
    commapi/lib/libLinuxSerialParallel.so
    commapi/lib/libLinuxSerialParallel_g.so
    commapi/docs/javax.comm.properties

Copy them to the appropriate places in your Java run-time environment:

    # cp commapi/jar/comm.jar j2re1.4.2_13/lib/ext/
    # cp commapi/lib/* j2re1.4.2_13/lib/i386/
    # cp commapi/docs/javax.comm.properties j2re1.4.2_13/lib/

Finally, ordinary users may not have access to the serial port(s) on your machine. So type:

    # chmod 666 /dev/tty?

to give everyone read and write permissions on these ports.

Some paranoid Linux distributions (I think Red Hat is one) look at these permissions and reset them to the defaults on boot, so you may have to create a start-up script to redo that.

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.

<noautolink>KiCad</noautolink>

KiCad is the electronic and printed circuit design package that RepRap uses. It's homepage is here. If you are using any of the major linux distrbutions, install it via your usual package manager, i.e. "apt-get install kicad", "emerge kicad", or "rpm --install kicad", as appropriate.

If you need to install from source, follow the directions below:

 Select site iut (http) under Download and get the gzipped tarball (it will be called something like kicad-2006-08-28.tgz, depending on the date and version of the release).

Make a directory for it, move it, and unpack it:

    # cd /usr/local
    # mkdir <noautolink>KiCad</noautolink>
    # cd <noautolink>KiCad</noautolink>
    # mv ~your-id/kicad-2006-08-28.tgz .
    # tar -xvzf kicad-2006-08-28.tgz

Once again you need to create a script to run it:

    # cd /usr/local/bin
    # cat > kicad
    #!/bin/sh
    cd /usr/local/KiCad/kicad/linux
    ./kicad

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

    # chmod 755 kicad

As you, not the superuser, run KiCad by typing kicad at the command prompt. You should get a small window with the default circuit and pcb (called noname) ready to edit. Close the window.

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", "emerge picp gpicp", or "rpm --install picp gpicp".

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.

<noautolink>PiKdev</noautolink> is another suport package for the PIC microcontroller. The homepage is here. Follow the Download link on that page and the installation instructions for your platform. Here's what I did under Debian as the superuser after downloading the distribution (a tarball called something like pikdev-0.9.2-1.tar.gz). Start by moving the download to your PIC directory and unpacking it:

    # cd /usr/local/PIC
    # mv ~your-id/pikdev-0.9.2-1.tar.gz .
    # tar -xvzf pikdev-0.9.2-1.tar.gz

This will create a sub-directory called pikdev-0.9.2-1. Move to that, configure the package, make it, and install it. Note the non-obvious configure command for Debian (and Ubuntu) Linux; other distributions are more straightforward (see the PiKdev installation page on the website).

    # cd pikdev-0.9.2-1
    # ./configure --prefix=/usr --with-qt-dir=/usr/share/qt3 --with-qt-includes=/usr/include/qt3 --with-qt-libraries=/usr/lib/qt3 --with-extra-libs=/usr/lib/kde3 --enable-libsuffix=      (All one line)
    # make
    # make install

Now as you (not the superuser) type

    $ 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...

The rest of RepRap

You have already downloaded the host Java files. Now you need to get the rest:

    mechanics
    electronics
    firmware

These are pretty self-explanatory: mechanics contains all the mechanical design files of the RepRap machine; when you copy your machine or make spare parts for it, it is the files in here that you will load into your RepRap machine and build; electronics contains all the KiCad files for the electronic circuits in RepRap, together with printed circuit designs; firmware contains all the C code that is loaded into the PIC controllers in the RepRap machine.

As you, not the superuser, run Eclipse. Go to the >> symbol top right and select SVN Repository Exploring. Open the RepRap repository at <noautolink>SourceForge</noautolink> and right-mouse-click on mechanics and select Checkout. A menu will appear. Select the Checkout as a project in the workspace button, leave the Project Name (which should be mechanics) unchanged, and select Finish. Do the same for electronics and firmware. For firmware it will ask you what type of project you want (this is because there is a Makefile in the firmware root directory); tell it you want a general project.

(There is also a miscellaneous folder where we put stuff that we want to keep, but that is not part of the distribution. By all means download that too if you want, but you don't need it.)

You will now have four directories in your space (in ASCII alphabetical order):

    ~your-id/workspace/Reprap
    ~your-id/workspace/electronics
    ~your-id/workspace/firmware
    ~your-id/workspace/mechanics

Go back to Java (the >> symbol top right) and you should see the four projects listed. Only the Reprap [trunk/reprap/host] project contains Java, of course, but you can use Eclipse to explore the files in the others.

Finally, as you not the superuser, go to the firmware folder and make the PIC firmware:

    $ cd ~/workspace/firmware
    $ make

The first time you do this the Makefile will download the correct version of the Small Device C Compiler (SDCC), build it, and then use it to compile all the RepRap C code to go in the PICs. This takes quite a while. Subsequently it'll not bother with the SDCC download and build, of course.

Please note: RepRap firmware currently uses any sdcc version after 4590. This is true as of February 2007, and more recent firmware may need a more recent version of sdcc. Please check your version of sdcc, and upgrade if appropriate.

Congratulations! You now have the entire RepRap project on your computer plus all the software needed to build it, to run it, and to modify it.

-- Main.AdrianBowyer - 30 Oct 2006 -- Main.WozFan - 08 March 2007 (modified for Mac specifics)