Installing legOS on Debian GNU/Linux Systems

Stephen M Moraco

Version 1.0,  8 October, 2002
Revision History
Revision 1.0 08 October 2002 Revised by: smm
Initial Release to accompany legOS 0.2.6

If you have problems related to these instructions, you can write to Stephen M Moraco.
Caution These instruction work for me (on both the Debian 2.x and 3.x releases).  This page is written for the legOS package and is not yet tuned for the brickOS package (the current name of this project).  This page will be adjusted to current brickOS installation as soon as the first brickOS release is packaged for Debian.
These instructions give you a fully functional legOS 0.2.6 (and newer versions) and the cross compilation tool chain. You will be able to compile, download and run your own programs. If you want to specially configure the legOS kernel you also will want to download the Debian source package.  Instructions for this are found later in this page in Section 4.

Debian GNU/Linux supports many architectures. legOS as part of the Debian distribution is also supported on these platforms.  The legOS packaging was first done for Debian 2.2 so it is not yet supported on all of the Debian 3.0 architectures.  Our intent is to have it support all architectures at the brickOS 1.1.0 release.

The Debian 3.0 supported architectures are: Alpha, Arm, HP PA, I386, IA64, Motorola 68000, MIPS, MIPS-EL, PowerPC, S390, Sparc.  legOS is not yet supported on Arm, HP PA, and IA64.  This is due to specific compiler versions being needed by the newer platforms. I will be packaging the newer tool chain after our upcoming brickOS 1.0.0 release.  After the new tools are packaged, we will update brickOS to run with the new tools and will then support all of the platforms.  Currently this is intended to be the focus of the brickOS 1.1.0 release.

Step by step instructions:

These instructions are divided into four sections:

  1. Install legOS and GNU cross compilation tool chain for the Hitachi H8/300 microcontroller. (The computer in the RCX)

  2. Getting Started - build demos, download and run them.

  3. Your own projects - write your own programs, build, download and run them.

  4. Setup to customize legOS - get the legOS source so you can modify it, build it and run your programs using it.

1. Install legOS and GNU cross compilation tool chain for the Hitachi H8/300 microcontroller.

There are three packages which need to be installed:

  Name Description
1 binutils-h8300-hms_2. GNU Assembler, linker, loader, etc.
2 gcc-h8300-hms_2. GNU C and C++ compilers
3 legos_0.2.6-1 The legOS kernel, libraries, headers, utilities and demo programs

Use one of the following install techniques: (1) install using apt-get, or (2) download the .deb files then install by hand. Each should get you setup equally well.  If you are already setup for it method (1) is easiest.

1.1 Install using apt-get

This method assumes you have apt-get configured to install packages from one of the Debian mirrors. Running a single command will install all three packages.

(As root) run:
$ sudo apt-get install legos

After this succeeds, everything you need is now installed.
Move on to Section 2 to build the demos and finish the setup and testing of your development environment.

1.2  Download the .deb files and install by hand

Download three packages from Debian Site. Click on the "download" link at each the following pages:
  1. binutils-h8300-hms
  2. gcc-h8300-hms
  3. legos
You'll probably have choices for installing versions from stable, testing, or unstable. Unstable is equivalent to the legOS testing releases. So you should be fine using the versions in unstable.

Install the packages in the proper order: binutils-h8300-hms, gcc-h8300-hms, then legos.  If you don't follow this order the install will not succeed.
$ cd {download-dir}   # cd to where you placed the downloaded files
$ sudo dpkg --install binutils-h8300-hms_2.
$ sudo dpkg --install gcc-h8300-hms_2.
$ sudo dpkg --install legos_0.2.6-1_i386.deb
NOTE: the _i386 in the above package names is changed to indicate the platform you are using. For example, here is the list of legos .deb filenames for each of the currently supported architectures:

  • legos_0.2.6-1_alpha.deb
  • legos_0.2.6-1_i386.deb
  • legos_0.2.6-1_m68k.deb
  • legos_0.2.6-1_mips.deb
  • legos_0.2.6-1_mipsel.deb
  • legos_0.2.6-1_powerpc.deb
  • legos_0.2.6-1_s390.deb
  • legos_0.2.6-1_sparc.deb
After these three installs are completed, everything you need is now installed.
Move on to Section 2 to build the demos and finish the setup and testing of your development environment.

2. Getting Started

You've just finished the install. At this point, the cross compilation tool chain, RCX download utilities, legOS libraries and headers, legOS kernel and demos have all been installed and are ready for use.  This section takes you though simple steps to verify that everything is working as installed.

2.1 Quick walkthrough

(Example commands for this walkthrough are in section 2.2)

a. Download legOS operating system to the RCX

The utilities are already in your PATH. Set RCXTTY if you use a non-standard port for the IR tower. [example: 'export RCXTTY=/dev/ttyS1']

Use firmdl3 to download /usr/lib/legos/legOS.srec to your RCX.

b. Build a demo program, download it the the RCX and run it

Copy the /usr/share/doc/legos/examples/demo/ directory contents to a directory of your choosing. (If you wish to use c++ copy the files from the demo/c++ subdirectory, instead.) NOTE: you may have to uncompress some of the example files. Simply do a one-time: gzip -d *.gz

Type 'make' in this new directory to compile the demos.

Type "dll demo/helloworld.lx" (where demo is the directory in which you just made the demos). If all is well, it should be automatically relocated and transmitted to program slot 0. Press the RUN key to run. The program stops automatically.

Type "dll -p1 demo/rover.lx" to transmit another demo to program slot 1.

Use the PRGM key to select the desired program. Try RUN.
- NOTE: A 'make realclean' will remove all built files.

Stop your program with the RUN or ON/OFF key. Programs are preserved over
ON/OFF now. Press ON/OFF and PRGM simultaneously to erase legOS.

2.2 Example walkthrough

a. Download legOS operating system to the RCX

Example of loading the operating system. (Our IR Tower is on COM1, the RCX is powered on not currently running a program and is within range of the IR tower ready to receive the download.)
$ export RCXTTY=/dev/ttyS0      # our Serial IR Tower is on com1
$ firmdl3 /usr/lib/legos/legOS.srec

b. Build a demo program, download it the the RCX and run it

Example of the building and downloading demos.  We'll build the C language demos in the 'mybots/demos' directory within our home directory:
$ mkdir -p ~/mybots/demos	# make our directory
$ cd ~/mybots/demos		# cd to or new directory
$ cp /usr/share/doc/legos/examples/demo/* .	# copy files into directory
$ gzip -d *gz			# uncompress any compressed files
$ make all			# build the demos
$ dll helloworld.lx		# download helloworld demo to slot 0
$                               #  program slot 0 is default
$ dll -p1 rover.lx              # download rover to program slot 1

Press PRGM to select program 0 (helloworld).
-NOTE: this is due to legOS having selected the last downloaded program (program 1).

Press RUN to see the program helloworld run.  It will display on the RCX LCD and then stop by itself.

If all of this has worked, you are setup and running.  Congratulations!

Feel free to solicit help at  lugnet.robotics.rcx.legos on .if you have any problems with this.  There are many users of legOS there as well as the legOS development team.


3. Your own projects

Now you've installed legOS and the tool chain.  You've tested the installation by building and downloading a couple of the demos. You really want to get on with writing your own programs for the RCX.  Here are simple steps to accomplish this.

  • Make a directory in a location of your choosing
  • Copy 'Makefile' from the /usr/share/doc/legos/examples directory to this new directory.
  • Put your main routine into myproject.c. (or myproject.C if using C++)
  • Type "make myproject.lx && dll myproject.lx" to build and download your new code.
Pretty simple, really.  The Makefile has rules in it which already know how to build .lx files from .c or .C files.  This is why this works without modifying the Makefile..

If you wish to experiment with multiple source files compiling into one .lx file then you will have to modify the Makefile itself before you can build your new .lx file.

(Example here - TBD)


4. Setup to customize legOS

Ok, you've had fun writing programs, downloading them and such.  Now you've decided to enable some of the alternate capabilities of legOS or you'd like to tweak the kernel in some way.  Maybe you'd even like to add some new capability to the kernel. It's beyond the scope of this document to lead you through all of this, but here are instructions for getting the legOS source and building it.  (Oddly enough, building it requires some of the tools you've already installed! ;-)
Caution This is first draft material so may not yet be complete and is experimental in nature.  If you have advice for adjusting this content, please send your suggestions to the author. [See email link at top of this page]

Download the source package using apt-get (assumes you have properly configured apt).
$ mkdir ~/legos-work	# make our new working directory
$ cd ~/legos-work	# move to our new directory
$ apt-get source legos	# download and unpack the source package

This has created a legos-0.2.6 directory within your new working directory.

Change into this legos-0.2.6 directory to get ready to build

Type 'make depend' and then 'make all' to build legOS

NOTE: this builds the demos found in the legos-0.2.6/demos directory.  You can use these newly compiled demos to test your modifications to the kernel.

Reset the RCX so you can download a new version of legOS (simultaneously press ON-OFF and PRGM buttons, maybe, a couple of times).

Run 'firmdl3 ./boot/legOS.srec' to download the new legOS kernel

Use dll to download a newly built demo and run it.

(Better detail - TBD)


Final Notes

If any of this doesn't work, consult lugnet.robotics.rcx.legos on .

Every command indicated is executed from the bash shell. In the examples (the grey insets), the "$" is the prompt bash gives you.


Initial Release: Stephen Moraco 09/10/2002.

This site generously hosted by  SourceForge Logo