Setting up LegOS

Unlike the software provided by the Lego Corporation, LegOS requires a compiler for your code, compilation of the legOS kernel, and special download tools for the kernel and your programs. I will discuss each of the components in turn, including download sites and setup instructions.

Setting Up The Compiler Under Unix.

LegOS is compiled using the egcs compiler from Cygnus, along with the binutils package from the GNU project. While these are present on nearly every Linux system, they must be re-compiled in order to serve as a cross-compiler for the Hitachi H8300 chip in the RCX.

Linux and Other Unix-compatible Executables.

Normally, I prefer to compile my own. However, this is not a fool-proof solution, and can easily fail. If you don't want to try this, or have tried, and have had it fail, some pre-compiled binaries are available:

  • Redhat RPMs are available here. These were built against RedHat 6.2, and should install cleanly with the normal rpm tools on any version of RedHat greater than 6.0.

  • Debian, compiled against glibc 2.1These are just tarballs, that you should be able to use with Debian 2.1, 2.2, or Debian unstable. Anyone who wants to contribute .deb files is welcome to :)

At least some people have indicated success in building these tools on Solaris Unix. However, it would appear that because of differences in I/O, it may not be possible (without a great deal of work) to get the rest of the system running on Solaris. For more information, check out the following Lugnet threads:

It is important to recognize that even if you do not build your own compiler, and these pre-compiled tools work for you, you will still need the basic development tools (like make) installed on your system. Most Unix-compatible (which I will abbreviate *nix) systems should come with these. If you are using Linux, in Redhat, glint or gnome-rpm should have a directory called "C/C++ development tools", and in Debian, use dselect to get the Standard packages in the devel group.

Building *nix Executables.

If you want to build your own, here are some step by step instructions, adapted from Randal Loomis's linuxgcc-H8300-HOWTO.

  1. Get the necessary archive files: egcs and binutils. They are here for egcs and here for binutils. You'll need the file egcs-1.1.2.tar.bz2 and binutils-2.9.1.tar.gz. It is likely that these instructions will not work with gcc 2.95, because it uses different options for configuration. However, the bug that prevented the use of gcc 2.95 to build legOS has been fixed, so if you can convince 2.95 to compile, you should be able to use it to build legOS programs.

  2. Create the directory /usr/local/crossgcc. If you don't have space (roughly 130 megs) in /usr/local, use a symlink (on my machine, /usr/local/crossgcc is a link to /home/luis/crossgcc). Alternately, if you can't access /usr/local, use a directory of your own choice, but remember it for future use.

  3. In the directory you've downloaded binutils and egcs into, type
    tar xvzf egcs-1.1.2.tar.gz binutils-2.9.1.tar.gz
    to expand and untar the files.

  4. In the directory you used in step #3, create working directories for the build process with the following commands:
    		
    mkdir build-binutils
    mkdir build-egcs

  5. Build the binutils with the following commands:
    cd build-binutils
    ../binutils-2.9.1/configure --target=h8300-hitachi-hms --prefix=/usr/local/crossgcc --exec-prefix=/usr/local/crossgcc/h8300-hitachi-hms
    make all
    make install

  6. Add the new binutils to your PATH with one of these commands (which one works for you is shell-dependent):
    export PATH=/usr/local/crossgcc/h8300-hitachi-hms/bin:$PATH
    or
    setenv PATH /usr/local/crossgcc/h8300-hitachi-hms/bin:$PATH

  7. Configure the cross-compiler with the following commands:
    		
    cd ../build-egcs
    ../egcs-1.1.2/configure
    --target=h8300-hitachi-hms --prefix=/usr/local/crossgcc --exec-prefix=/usr/local/crossgcc/h8300-hitachi-hms --enable-target-optspace

  8. At this point, you must edit the Makefile for the cross-compiler. Opening it in your editor of choice, find the line which starts with CFLAGS. After the options that are already there, add the string "-Dinhibit_libc" at the end.

  9. Now, type the command:
    make cross LANGUAGES="c c++"

  10. At this point, the compilation will procede for quite some time. On my Pentium 166, it takes about 20-25 minutes. The following error message should then be generated:

    		
    checking whether the C compiler (/home/luis/build-egcs/gcc/xgcc -B /home/luis/build-egcs/gcc -g -Os ) works
    configure: error: installation or configuration problem:
    C compiler cannot create executables.

  11. The compilation fails at this point because it cannot find an appropriate standard C library. You can safely ignore this error, since LegOS provides the necessary replacements. Proceed to step 11. If you get another message which refers to libgcc.a, it indicates that you have a bad path. Check to make sure you executed step 6 correctly, and then execute the command "make clean" and re-do steps 7 and 8.

  12. Install the compiler with the command:
    		
    make LANGUAGES="c c++" install

This should create a cross-compiler in /usr/local/crossgcc, or the directory you have passed using --prefix.

If your attempt at compilation generates an error that is not covered in this section, the folks on the crossgcc mailing list have been more than helpful to me. This is a majordomo type mailing list- if you don't subscribe, please remind them to cc: you a copy of their replies.

Setting Up The Compiler Under Windows.

Running legOS under Windows is the longest ongoing saga in the legOS community. By my count, at least six different people have given a substantial amount of time to various attempts to explain and control legOS under windows.

There are two current solutions. Each are based on the same GNU tools that are used on Linux, however, one runs within DOS while the other runs within the cygwin environment (which itself runs in DOS.) Instructions for the first (and generally simpler) solution can be found at the page of Rossz Vamos-Wentworth. His page is pointed at from this Sourceforge page: http://legOS.sourceforge.net/files/windows/djgpp/. Be aware that this doesn't run on W2K.

The second option, which is more complex to get running but probably also slightly more powerful, is based on the cygwin tools. Following in the "long" tradition of cygwin users, Paolo Masetti has provided instructions for 0.2.4 that can be found at this sourceforge page.

Both of these pages are kept reasonably up-to-date and should give solid advice. Unfortunately, at the moment, DJGPP only works with legOS 0.2.3, but we are working on it for 0.2.4 and cleaning up a lot of code in the process.

Setting up LegOS itself.

Getting LegOS.

The files which comprise LegOS are available here. The current version is 0.2.4. If you'd like to get a more current version from CVS, there are instructions on how to do that later in the HOWTO, at the Section called Getting legOS Development Versions From CVS. If you do choose to get legOS from CVS, remember that it is (as of this publication) in pretty heavy development, and so it may be unusable on any given day (though we try very hard to prevent this.)

Using LegOS Without Your Own Compiler.

Once upon a time, there were two web-based compilers for LegOS. You could cut and paste your code into their webpage, and they'd post a URL where you can download the .srec file. Unfortunately, they both use legOS 0.1.x, so I include them here only as possible inspiration for others who might want to do the same with legOS 0.2.x. In fact, if you have the time to write the code in php, drop me a line and we can get it set up at sourceforge (maybe ;)

Here is the remaining historic URL:

Dave Madden's web compiler

Both of these sites were basically the same, using the 990330 snapshot of 0.1.7. The one that is gone gave you the option of getting the s-record emailed to you. You will still need to compile firmdl or find another method to download the outputted .srec file to the RCX.

Testing your compiler by compiling a simple program

Before I go any further, I should point out that this process assumes youhave actually built a robot :-). The example code I give in the Section called Sample Code assume a simple design, with motors (and presumably wheels or treads) attached to output ports A and C, a touch sensor on input port 1, and a light sensor on input 2. Since this is mainly a LegOS document, I have no formal advice on construction here. The Constructopedia that comes with the Mindstorm kit has several good basic robots, from which more complicated structures can be built. You may also want to check out the 6.270 homepage at MIT, which includes these notes on building solid structures and creating drivetrains. A related course at the University of West Florida has similar instructions with pictures.

Putting a kernel into the RCX

Once the kernel has been compiled, firmdl3 is used to download the kernel to the robot itself. Firmdl3 is pretty straightforward, and you should only need to use it occasionally, since it is only used for the kernel. To test it, run it to get the kernel into the RCX. While in your legOS directory, type util/firmdl3 boot/legOS.srec. If your tower is positioned correctly, and the RCX is turned on, you should see a series of numbers flash by on the LCD of the RCX. When done, you'll see a - on the right side of the screen. (As a pseudo-historical aside, the .srec extension indicates that the legOS kernel is stored as an s-record. In legOS 0.1.x, this was the standard file type for all legOS programs.)

Possible firmdl3 errors.

I've tried to show the exact error messages outputted by firmdl3. Since the actual errors aren't quite perfect, I won't correct them.

Downloading the .lx to the robot using dll

First, make sure you have the legOS kernel in your RCX. If you've been following my instructions, you've already done this. If not, go back to section 2.6 and use firmdl3 to download the kernel to the RCX.

Once you've got the kernel installed, to download the .lx file you have just created, go to the util/ directory, and type ./dll ../code/demo.lx This will begin the download process, which shouldn't take too long. You'll note that the download protocol is very fault tolerant- you should be able to move the bot or temporarily block the download, and still have it recover.

dll is a flexible tool with lots of useful options. The two more important are -p and -e. -pX allows the user to specify a program slot from 0-7. In this way, you can store multiple programs in your RCX. Once downloaded, use the "PRGM" button to rotate between the various programs you have downloaded. If you don't use -p, then dll defaults to downloading the program to the first program slot (which is numbered 0, of course). The -e flag automatically runs the program as soon as it is downloaded. To see the rest of the commands available, just type "dll" without any arguments.

Under Linux, I find it useful to add a symbolic link from my working directory to dll, so that I don't have to change directories or use sets of ../../ to download code once it is compiled in my working directory.