brickOS is an alternative operating system for the Lego Mindstorms RCX Controller. It also provides a C/C++ development environment for RCX programs using gcc and g++ (the GNU C and C++ cross compilation tool chain) and the necessary tools to download programs to the RCX. For more information on brickOS please visit the  brickOS-Homepage.

This HOWTO describes how to compile and install brickOS, with patches and tools for LNP and our ultra-sonic positioning system, on a Linux based system. Maybe it works on other systems, like Windows with Cygwin or Solaris, too, but this has not been tested yet.

This is an exact copy-and-paste instruction set to install all needed things. Copy and paste the corresponding commands to your shell exactly as they are written here, unless you really understand what you are doing'''

Please make sure, that your Lego tower is supported by your system. If you have a serial tower there should be no problems. With problems on an USB-tower, please refer to the Lego USB-Tower HOWTO.

The following installation can be done without any root-access, but ensure that you have access to the tower as a user.

Please create a folder for your installation in some directory:

mkdir /home/<user>/lego

To simplify the installation steps, we create an environment variable to this directory. So you can simply copy and paste all shell commands here. In the following all paths are absolute paths, so you can call the commands from any directory you want!

For simple copy-and-paste instructions in the following, declare an environment variable to set the target directory:

export D=/home/<user>/lego

In later commands we will use a <tt>(cd $D ; <command>)</tt> style. This will execute the <command> exactly in the specified absolute path given by $D. So you do not need to consider your current dir, you execute the commands in.

Now create a temp dir to download and build all necessary stuff:

mkdir $D/temp

Now, you are ready to install brickOS.

Creating a GCC-cross-compiler for the RCX

To compile brickOS you first need a cross-compiler which produces code for the Hitachi H8 microcontroller which is built in the Lego RCX. So you have to build a GCC for your intention.

First of all, I want to mention that I've already tried many different versions of the GCC and its dependencies, but no newer version of these, which are described here, worked properly! So, if you want a running brickOS without problems, try the versions mentioned here. However, if you get newer versions running, please tell us!

Installation of binutils

At first, you need to install binutils. Download  binutils-2.11.2.tar.gz to the temp directory and unpack it:

(cd $D/temp ; wget  http://rtsys.informatik.uni-kiel.de/~lego/src/binutils-2.11.2.tar.gz) (cd $D/temp ; tar -xzvf binutils-2.11.2.tar.gz)

Then you have to configure it for the H8 microcontroller and your installation directory. The first command will patch a bug in the configure script, that causes an error at executing on a newer version of the bash shell:

(cd $D/temp/binutils-2.11.2 ; cp configure configure.backup ; cat configure.backup | sed -e 's#trap 0#trap - 0#' > configure) (cd $D/temp/binutils-2.11.2 ; ./configure --target=h8300-hms --prefix=$D)

Compile and install:

(cd $D/temp/binutils-2.11.2 ; make) (cd $D/temp/binutils-2.11.2 ; make install)

(Note: If you have just set the prefix correctly for the configure script, you'll need no root-access to make install. The tools will be installed to $D, e.g. $D/bin will be the directory for any binaries)

Now you have to set your PATH variable to access the just created binaries easily:

export PATH=$D/bin:$PATH

Maybe it's a good idea to add this to your .bashrc.

Building the cross-compiler

Download the newlib libraries  newlib-1.9.0.tar.gz and unpack them:

(cd $D/temp ; wget  http://rtsys.informatik.uni-kiel.de/~lego/src/newlib-1.9.0.tar.gz) (cd $D/temp ; tar -xvzf newlib-1.9.0.tar.gz)

Download  gcc-3.0.1.tar.bz2 and unpack it:

(cd $D/temp ; wget  http://rtsys.informatik.uni-kiel.de/~lego/src/gcc-3.0.1.tar.bz2) (cd $D/temp ; tar xvjf gcc-3.0.1.tar.bz2)

So because this gcc is a little buggy, you need a patch. Download  h8300-hms-gcc-3.0.1-1.patch and apply the patch:

(cd $D/temp ; wget  http://rtsys.informatik.uni-kiel.de/~lego/src/h8300-hms-gcc-3.0.1-1.patch) (cd $D/temp/gcc-3.0.1 ; patch -p1 <$D/temp/h8300-hms-gcc-3.0.1-1.patch)

Fix the configure script at the gcc, too:

(cd $D/temp/gcc-3.0.1 ; cp configure configure.backup ; cat configure.backup | sed -e 's#trap 0#trap - 0#' > configure)

Now, copy the needed libraries of newlib to the gcc-sources:

cp -v -r $D/temp/newlib-1.9.0/newlib/ $D/temp/gcc-3.0.1 cp -v -r $D/temp/newlib-1.9.0/libgloss/ $D/temp/gcc-3.0.1

You need an extra build-dir for the gcc:

mkdir $D/temp/build-gcc

Configure your gcc as a cross-compiler for the Hitachi H8 and install it to your local installation directory:

(cd $D/temp/build-gcc ; $D/temp/gcc-3.0.1/configure --target=h8300-hms --prefix=$D --enable-languages=c,c++ --with-gnu-as --with-gnu-ld --with-newlib)

Finally build and install the cross-compiler. Meanwhile, you've got time to drink a cup of coffee...

(cd $D/temp/build-gcc ; make && make install)

Now, your cross-compiler is ready to use.

Installation of brickOS

Download  brickos-0.9.0.tar.gz and unpack it:

wget  http://rtsys.informatik.uni-kiel.de/~lego/src/brickos-0.9.0.tar.gz tar xvzf brickos-0.9.0.tar.gz

To use the RCX with our ultra-sonic positioning system and LNP you need to apply the following patch. This patch is also recommended for all other users because of some added advantages to the brickos-kernel.

Download the patch  brickos-0.9.0.patch and apply it:

cd brickos-0.9.0 patch -p1 <../brickos-0.9.0.patch

Before the configuration, it is recommended to edit the configuration script to save some time in the configuration process. I'm using the simple editor nano, but you're welcome to use your favourite one.

nano configure

Edit the TOOL_PATH-line to match your installation:

TOOL_PATH="/home/<user>/lego/bin"

Save the file and do the configuration:

./configure

Now, you are ready to compile brickOS:

make

You don't need to run make install because it would only copy some binaries to /usr/local/bin, furthermore you would need root-access.

Finally it is time to test your installation. Plug your Lego Infrared Tower, place your RCX against it and switch it on. Type the following command in the brickOS-directory to replace the firmware on the RCX with brickOS:

util/firmdl3 --tty=/dev/usb/legousbtower0 boot/brickOS.srec

If you plugged your tower into serial connector take the corresponding device, for example:

util/firmdl3 --tty=/dev/ttyS0 boot/brickOS.srec

Now load a demo program to the RCX:

util/dll --tty=/dev/usb/legousbtower0 demo/sound.lx

After a succesful transfer and pressing the Run-button the RCX should play some music.

You may also define a local variable in which you specify your device for the tower, so that you don't need to add --tty=... to your commands:

export RCXTTY=/dev/usb/legousbtower0

Maybe it is reasonable to add this to your .bashrc, but if you want to use the comfortable Makefile from the lnp-utils, described in the following, the variable RCXTTY might be obsolete.

Installation of some extra utilities

There is a package of some little tools, basically for using LNP to get feedback from the RCX. It also includes a more comfortable Makefile to compile code for the RCX. These tools won't be described in detail, but a few examples will be given.

First, download the package  lnp-utils.tar.gz and unpack it:

wget  http://rtsys.informatik.uni-kiel.de/~lego/src/lnp-utils.tar.gz tar xvzf lnp-utils.tar.gz

Compile the tools:

cd lnp-utils make

A comfortable Makefile can be found in the directory Test. You have to customize it to work properly. Then you can move it anywhere you want to compile and upload code to the RCX. So use your favourite editor and correct the path to your brickOS-installation. Here, I'm using nano.

cd Test nano Makefile

Correct this line in the beginning:

BRICKOS_ROOT=/home/<user>/lego/brickos-0.9.0

If you have your Lego tower already plugged in and brickOS has already been transferred, you can skip the next step.

The new Makefile provides a simple way to transfer brickOS. It should also detect your tower device. Just type:

make kernel

To upload the demo, type:

make lnp_test.dll

This should compile and afterwards upload a little test program for LNP. With this demo, you can test two further tools: lnpdump and lnpshow.

lnpdump is to show everything that the RCX sends via its infrared interface. lnpshow only shows, what the RCX prints with a method called lnp_printf(). For more details, see the source code of the demo, and simply try out these tools!

So, try lnpdump:

cd .. ./lnpdump

After pressing the RUN-button on the RCX, the following ahould appear in your console:

Addressing layer message (10 bytes from 00:00 to 05:01) [LNPA] 0000 50 31 C1 08 05 74 65 73 74 0A P1...test.

Then, after pressing the PRGM-button on the RCX, the following should appear:

Integrity layer message (100 bytes) [LNPI] 0000 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 ................ [LNPI] 0010 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 ............... [LNPI] 0020 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F 30 !"#$%&'()*+,-./0 [LNPI] 0030 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40 123456789:;<=>?@ [LNPI] 0040 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F 50 ABCDEFGHIJKLMNOP [LNPI] 0050 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F 60 QRSTUVWXYZ[\]^{_` [LNPI] 0060 61 62 63 64 abcd}

The program on the RCX will terminate itself. To abort lnpdump press Ctrl-C.

If you haven't seen anything on your terminal, try to start lnpdump with the -d option to specify the device:

./lnpdump -d /dev/usb/legousbtower0

Now, everything should be fine.

Try the same with lnpshow:

./lnpshow

If you have had to call lnpdump with the -d option in the example above, you'll have to do the same here again:

./lnpshow -d /dev/usb/legousbtower0

After pressing the RUN-button on the RCX, the following should appear in your console:

test

Then, after pressing the PRGM-button on the RCX, nothing will happen, because the RCX sends nothing via the method lnp_printf().

Ok, that's it! Have fun!