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.

A Note About C++

The compilers described and linked to below will not be able to use legOS's new C++ support. To use that, you'll have to build and compile gcc 2.95 instead of the older egcs. To see more on the use of C++ in legOS, check out the section called C++ under legOS.

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.

Historical Windows URLs.

These are here because I haven't had the chance to test these yet, and because I feel like I ought to have them around somewhere if they are still good.

Lego page - original Cygwin page

Brian Stormont- howto build compiler for Cygwin

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

Makefile and Tool Configuration.

Once you have the cross-compilers compiled and installed as per section2.1 or 2.2, the file Makefile.common (in the legOS directory) may have to be modified to reflect the location of the compiler on your system. If you are running Cygwin or DJGPP, and have made the modifications to your PATH specified in those instructions, you can safely skip the next paragraph.

In the file Makefile.common, line 23 (which starts with "TOOLPREFIX=") should be set to the location you passed to [egcs-1.1.2]$./configure, plus the string "h8300-hitachi-hms/bin/h8300-hitachi-hms-." In my system (and the example used in Section 2.1.2) this would be /usr/local/crossgcc/h8300-hitachi-hms/bin/h8300-hitachi-hms-.

You are now set up to compile the kernel and associated tools. To do this, type make in your legOS directory. This should create a legOS kernel in the legOS/boot directory. To find it, look for the filename legOS.srec. The util/ directory should also have firmdl3 and dll, assuming that gcc is correctly configured on your system. If those aren't built, then you'll need to fix gcc and build them before proceeding.

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.

Compiling a legOS program into a .lx file

Unlike version 0.1.x, legOS 0.2.x has it's own file format- .lx. Instead of downloading the entire OS everytime you want to test a new program, you just download a .lx file.

Compiling a .lx is pretty simple. Under your legOS directory, create a sub-directory. I call mine "code", but "projects" or some such would also work fine. Copy the Makefile from the legOS/demo/ directory into your new directory, and put your code into the same directory. Then type make demo.lx (where demo is your the name of your .c file) and voila- you should get demo.o and demo.lx files.

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.

  • "delete firmware failed" Because of a limitation in the Lego firmware, firmdl3 cannot delete LegOS. Instead, before downloading the new firmware, you must first stop the old LegOS program, and then hold down the Prgm button while hitting the On/Off switch. This will delete the old LegOS firmware, allowing a new download. Alternately, if you see no green light on the IR box and get this error message, it may indicate you have a dead battery in the IR tower.

  • "/dev/ttyS0: Permission denied", "com1: Permission denied", or a similar message. The first part of the error message is the output port that firmdl3 is trying to use. This can mean two things. Either you have specified the wrong device or you have specified the correct device but do not have permission to access it. If it is an access problem, speak to your sysadmin. If not, you can use the --tty argument to specify another device. For example, to specify the standard device under linux, try "firmdl3 --tty /dev/ttyS0". Under cygwin, you probably probably want to use "firmdl3 --tty com1". If you discover that this is the case, you may wish to recompile firmdl3 to make your setting the default.

  • "/dev/ttyS0: Input/output error" or a similar message.You forgot to plug the tower in, most likely.

  • "unlock firmware failed" This indicates that there was a slight corruption in the download. Clear legOS and download it again.

  • "no response from RCX" This error should be called "you forgot to turn on your RCX, moron." If I hadn't done it about 10 million times, I'd submit the patch to change the error myself.

  • If firmdl3 gives you repeated problems, you may want to try using the --slow argument, which will make your download much slower but can correct for certain errors caused by ambient light.

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.

dll error messages

Unfortunately, there is basically only one dll error message, and it applies to most possible errors, including a disconnected IR tower, an RCX that is turned off, an RCX that doesn't have legOS, and an RCX that has legOS and is already running a program. So, check all those things when dll fails.