BrickOS Linux Installation HOWTO

version 1.1 - 2005-03-03, by Matthias Ehmann, Bayreuth University, matthias.ehmann@uni-bayreuth.de

This HOWTO describes the configuration and installation of brickOS under Linux with kernel 2.6 and the LEGO USB Tower. It consists of the following parts:

1. Overview
2. Building a Cross Compiler
2.1. Building the Binutils
2.2. Building the GCC Cross Compiler
3. Installing brickOS
4. Testing the Installation
4.1. Downloading the Firmware
4.2. Starting a Demo Program
5. Adding the Tower Device Permanetly

1. Overview

brickOS is Markus L. Noga's alternative operating system for the Lego Mindstorms RCX controller. It enables the programmer to use gcc and g++ for programming of Mindstorms roboters. Further information about brickOS can be found at http://brickos.sourceforge.net

Using brickOS under Linux needs some prerequisites. The RCX Controller consists of a Hitachi H8300 series processor. So the binutils and a cross compiler for that platform are needed. This HOWTO refers to a standard Linux installation with kernel 2.6.8.

2. Building a Cross Compiler

2.1. Building the Binutils

The GNU Binutils are a collection of binary tools. Among other utilities they include the GNU linker (ld) and the GNU assembler (as). For further details take a look at the GNU Binutils site http://www.gnu.org/software/binutils. The current version of binutils is 2.15. The sources can be found at ftp.gnu.org/gnu/binutils. You can also use one of the mirrors for dowloading listed at http://www.gnu.org/order/ftp.html

Configuration and Installation

Download the latest version of the binutils and save them to /usr/local/src. Take the bz2 version it is smaller than the gz. (binutils-2.15.tar.bz2)
Open a shell, change to /usr/local/src and extract the sources by:
```
% tar -xjvf binutils-2.15.tar.bz2
```
Change to binutils path:
```
% cd binutils-2.15
```
Now you are ready to configure the binutils for the Hitachi H8300:
```
% ./configure --target=h8300-hms --prefix=/usr/local
```
After successful configuration start the compilation of the binutils:
```
% make
```
Become root and install the binutils:
```
% make install
```

Now everything is ready for building the cross compiler.

2.2. Building the GCC Cross Compiler

We use the latest version of the GNU Compiler Collection (GCC) as cross compiler. Visit the GCC homepage http://gcc.gnu.org for further information about GCC. The latest stable version of GCC is 3.4.3. The sources can be downloaded at ftp://ftp.gnu.org/gnu/gcc. You can also use one of the mirrors for dowloading listed at http://www.gnu.org/order/ftp.html

In addition to the GCC we use redhat's newlib - a conglomeration of several library parts for use on embedded systems. Visit http://sources.redhat.com/newlib for further details. The sources of newlib can be found under ftp://sources.redhat.com/pub/newlib.

Configuration and Installation

Download the sources of the latest version of GCC (i.e. gcc-3.4.3.tar.bz2) and save them to /usr/local/src.
Download the sources of the latest version of newlib (i.e. newlib-1.13.0.tar.gz) and save them to /usr/local/src.
If it isn't already done set your path to /usr/local/bin:
```
% export PATH=/usr/local/bin:$PATH
```
Extract the GCC sources again to /usr/local/src:
```
% tar -xjvf gcc-3.4.3.tar.bz2
```
Also extract newlib to /usr/local/src:
```
% tar -xzvf newlib-1.13.0.tar.gz
```

Copy the libraries into the GCC source directory:

% cp -r newlib-1.13.0/newlib gcc-3.4.3
% cp -r newlib-1.13.0/libgloss gcc-3.4.3

Create a build path for the GCC:
```
% mkdir build-gcc
```
Change to the build path:
```
% cd build-gcc
```

Now configure GCC as a H8300 cross compiler for C and C++ code:

% ../gcc-3.4.3/configure --target=h8300-hms --prefix=/usr/local --enable-languages=c,c++ --with-gnu-as --with-gnu-ld --with-newlib

The make process may take some time:
```
% make
```
The last step is the installation of the cross compiler as root:
```
% make install
```

3. Installing brickOS

The latest version of brickOS is 0.2.6.10.6. It can be found at http://sourceforge.net. Version 1.0 is announced but not available yet.

Up to now brickOS is not designed for GGC versions 3.3 or higher. Furthermore there is currently no build in support for the Lego USB Tower. Linux kernel 2.6.1 or higher includes usb support for the tower. By applying a patch to the brickOS sources it is possible to make it work under 2.6 kernel (tested with 2.6.8) and GCC 3.4. It took me some time to find out which patches posted on several groups or at sourceforge are necessary to make it all work. So I decided to write this little HOWTO and to prepare one patch that sets up the brickOS sources in the right way.

Configuration and Installation

Download the sources of the latest version of brickOS (i.e. brickos-0.2.6.10.6.tar.gz) and save them to /usr/local/src.
Download the patch for enabling GCC 3.4 and USB Tower support brickos-0.2.6.10.6-gcc-3.4-usb.patch and save it to usr/local/src.
Extract the sources to /usr/local/src:
```
% tar -xzvf brickos-0.2.6.10.6.tar.gz
```
Change to the brickOS sources:
```
% cd brickos-0.2.6.10.6
```

Apply the patch:

% patch -p1 <../brickos-0.2.6.10.6-gcc-3.4-usb.patch

Run the configure script:
```
% ./configure
```
If the Hitachi gcc is not found and you use another location for it as used in this HOWTO - the prefix is /usr/local - you can edit the configure script and add your path to the variable TOOL_PATH.
Now everything is setup to buildbrickOS:
```
% make
```
Now you can install the binaries as root:
```
% make install
```

4. Testing the Installation

After finishing the installation we are now able to test it.

4.1. Downloading the Firmware

The first step will be the download of the new firmware to the RCX. It depends on the type of your IR tower. If you are using the serial version you just have to know to which serial port it is connected (i.e. /dev/ttyS0). If you are using the USB variant the port should be something like /dev/usb/legousbtower0. Pluging your USB tower should cause the kernel to autoload the right module. Your /var/log/messages contains more information about the USB tower:

Sep 27 10:21:12 labor5 kernel: drivers/usb/misc/legousbtower.c: LEGO USB Tower #0 now attached to major 180 minor 160
Sep 27 10:21:12 labor5 kernel: drivers/usb/misc/legousbtower.c: LEGO USB Tower firmware version is 1.0 build 134
Sep 27 10:21:12 labor5 kernel: usbcore: registered new driver legousbtower
Sep 27 10:21:12 labor5 kernel: drivers/usb/misc/legousbtower.c: LEGO USB Tower Driver v0.95
Sep 27 10:21:14 labor5 udev[13133]: configured rule in '/etc/udev/rules.d/udev.rules' at line 111 applied, 'legousbtower0' becomes 'usb/%k'
Sep 27 10:21:14 labor5 udev[13133]: creating device node '/dev/usb/legousbtower0'

For downloading the firmware to the RCX we use the firmdl3 programm of brickOS. It is located in /usr/local/bin after the installation and should be accessible by your PATH. The firmware file is /usr/local/lib/brickos/brickOS.srec. Before downloading power on your RCX and put it in front of the tower.

% firmdl3 --tty /dev/usb/legotower0 /usr/local/lib/brickos/brickOS.srec

The tty option contains the related device, in the example the USB tower. Use the valid device for your configuration.
While downloading the firmware the status is shown on the brick's display.

4.2. Starting a Demo Program

The brickOS installation contains several demo programs. You can find them in /usr/local/share/doc/brickos/examples/demo. First you have to bulid the binaries.

Change to /usr/local/share/doc/brickos/examples/demo:
```
% cd /usr/local/share/doc/brickos/examples/demo
```
The Makefile in this directory contains everything (paths, compiler directives, ...) for building Mindstorm specific binaries. You can also use this Makefile for your own projects.
```
% make
```
The result of the make process are sveral compiled lx-files.

Now everything is ready to download a compiled program to the RCX. The tool dll (/usr/local/bin/dll) is used for doing that.

Power on the brick and put it in front of the USB tower.

Download the hello-world example

% dll --tty /dev/usb/legousbtower0 /usr/local/share/doc/brickos/examples/demo/helloworld.lx

Pressing the run button should start the example.

5. Adding the Tower Device Permanetly

It is not necessary to specify the device for the LEGO Tower everytime. It is possible to set the environment variable RCXTTY. Best way to do this is to add this line permanently to your /etc/profile file:

export RCXTTY=/dev/usb/legousbtower0