Lego Mindstorm with Linux Mini-HOWTO

Luis Villa

luge@users.sourceforge.net
Revision History                                                             
Revision 1.1        October 29th, 2000                                       


The Lego Group's Mindstorm Robotics Invention System (RIS) is probably the
best reasonably cheap robotics kit available. However, the standard software
is (unsurprisingly) MS Windows dependent. Don't despair- there are several
options that allow Linux users to use their Mindstorms from within Linux.
This Mini-HOWTO is intended to serve as a very brief introduction to the
options available, and as a gathering point for more information.

-----------------------------------------------------------------------------
Table of Contents
1. Introduction
    1.1. Acknowledgements
    1.2. Disclaimer
    1.3. Copyright
   
   
2. The Mindstorms Architecture
    2.1. The Basic Hardware
    2.2. Standard RCX Programming
    2.3. Where the Linux Tools Fit In
    2.4. Hardware Requirements for the Linux Host
    2.5. The CyberMaster and Scout
    2.6. Mindstorms Vision Command
    2.7. Important Note about the MS Windows CD
   
   
3. LegOS
    3.1. Homepage
    3.2. Author
    3.3. Type
    3.4. Language
    3.5. Platforms
    3.6. Description
   
   
4. Lego::RCX.pm
    4.1. Homepage
    4.2. Author
    4.3. Type
    4.4. Language
    4.5. Platforms
    4.6. Description
   
   
5. Not Quite C (NQC)
    5.1. Homepage
    5.2. Author
    5.3. Type
    5.4. Language
    5.5. Platforms
    5.6. Description
   
   
6. pbForth
    6.1. Homepage
    6.2. Author
    6.3. Type
    6.4. Language
    6.5. Platforms
    6.6. Description
   
   
7. TinyVM and leJOS
    7.1. Homepages
    7.2. Author
    7.3. Type
    7.4. Language
    7.5. Platforms
    7.6. Description
   
   
8. Remote Java APIs
    8.1. Homepages
    8.2. Type
    8.3. Language
    8.4. Platforms
    8.5. Description
   
   
9. TCL RCX
    9.1. Homepage
    9.2. Authors
    9.3. Type
    9.4. Language
    9.5. Platforms
    9.6. Description
   
   
10. Pylnp
    10.1. Homepage
    10.2. Author
    10.3. Type
    10.4. Language
    10.5. Platforms
    10.6. Description
   
   
11. Other Linux Tools
    11.1. LeoCAD
    11.2. POVRAY
   
   
12. Other sources of information
    12.1. LUGNET
    12.2. The Official Mindstorms Site
    12.3. The Hardware Sites
    12.4. Historic Lego Bots and Construction Guide
   
   

1. Introduction

If you've seen those cool Lego Mindstorms kits, but despaired at the big
"requires Windows" stickers on the side, don't despair: there is hope for you
yet. Not only is there software that allows you to program your RCX from GNU/
Linux, odds are you can do it in your favorite languages: C, Perl, Java and
Forth are all available for your use. This document is not intended as
documentation for all of these: rather, I hope to provide highlights and
contact information for each of the various Linux options, so that this
document can serve as a starting point for Linux users who are considering
purchasing Mindstorms kits, or for Mindstorms owners who are considering
switching to Linux and wonder whether or not they can continue to use their
most expensive toys :)

It is extremely important to note that while I try to keep a pretty good
finger on the pulse of the online Mindstorms community, I'm not omniscient:
it's quite possible that this list is incomplete. If you know of other
Mindstorms options that run on Linux, please drop me a note at [mailto:
luge@users.sourceforge.net] luge@users.sourceforge.netso that I can add to
the document and share the options with others who may be considering buying
a Mindstorms to use with their GNU/Linux computers.
-----------------------------------------------------------------------------

1.1. Acknowledgements

I'd like to thank the authors of the programs listed below, both for writing
them in the first place for all of us to use and also for giving the earliest
version of this document a once-over.

Additionally, I'd like to thank Dave Baum, who asked me to join with him in
writing the book "Extreme Mindstorms". Writing that let me spend a lot of
time with the Mindstorms that I wouldn't have had otherwise, including the
time that led to this HOWTO. If you are interested in exploring "power
programming" for the RCX, I'd strongly suggest this book. There are some
other good books out there (notably the O'Reilly book) but this one is
extremely up to date, and more importantly, just about every line of code in
it (as far as I know) will work with Linux. I know this is a pretty shameless
plug, but I'm pretty proud of it :) You can buy the book [http://
www.amazon.com/exec/obidos/ASIN/1893115844/tieguyorg] here.

Also, Steve Baker and Matthew Miller, and many others on Lugnet, provided
many helpful suggestions to several early versions of this text. Their
thoughts are present in several places throughout the text, and can be
assumed to be responsible for all the good stuff. :)

Finally, thought not direcly related, Michael Littman, formerly of Duke
University and now of AT&T actually paid me to play with LEGO last summer.
Without the opportunity that he gave me, I would not be as involved or as
knowledgeable with the online Mindstorms community as I now am.
-----------------------------------------------------------------------------

1.2. Disclaimer

The LEGO Company ([http://www.lego.com/] http://www.lego.com/) is very, very
protective of their trademarks. This document is not in any way authorized by
or associated with The LEGO Company, nor do I as the author claim to have any
relationship with The LEGO Company. To see more about their policy on legal
usage of their trademark, check out [http://www.lego.com/info/fair.asp] http:
//www.lego.com/info/fair.asp, particularly the part (about halfway down)
titled "How LEGO(r) Enthusiasts May Refer to LEGO Products on The Internet."
I have attempted to abide by those guidelines faithfully; like everything
else in this document, though, if you spot a violation of the guidelines,
please let me know by [mailto:luge@users.sourceforge.net] writing me.
-----------------------------------------------------------------------------

1.3. Copyright

This document is distributed under the LDP Copyright. You can find a copy of
it [http://www.linuxdoc.org/COPYRIGHT.html] here.
-----------------------------------------------------------------------------

2. The Mindstorms Architecture

2.1. The Basic Hardware

In case you don't know, the Lego Mindstorms Kit is a robotics kit from The
Lego Group that retails for about 200 US dollars. For that, you get a lot of
Lego pieces, a large brick containing a CPU, an LCD, and some connectors
(known as the RCX), a couple of motors, and some light and touch sensors that
allow you to interact with the outside world.

The current release of the RCX kit is version 1.5, which will be replaced in
spring 2001 by RCX 2.0. For the time being, any time I say "RCX" in this
document, I mean "RCX 1.x." The differences between 1.0 and 1.5 are minimal,
but the changes between 1.5 and 2.0 may be substantial- the exact extent of
the changes is not yet known.

If you want to learn about the hardware in more detail (think: excruciating
detail, from folks who have literally disassembled their RCX's in order to
see what makes them tick) there are two important web sites to visit: [http:/
/www.crynwr.com/lego-robotics/] Russell Nelson's Lego Mindstorms Internals
and [http://graphics.stanford.edu/~kekoa/rcx/] Kekoa Proudfoot's RCX
Internals. Without these two sites, it is unlikely that much of the software
below would exist.
-----------------------------------------------------------------------------

2.2. Standard RCX Programming

The key to understanding the various Linux options is to first understand how
the Mindstorms kit operates normally with MS Windows. In a nutshell, Lego
provides a MS Windows software tool that lets you (or, more likely, a 12-14
year old) graphically assemble programs for the Mindstorm, using a
building-block metaphor to create code. Once the program has been "assembled"
in this way, the software compiles your program into a byte-code. This
byte-code is then downloaded to the robot, where the firmware of the RCX
processes the byte-code and controls the machine based on the instructions in
the byte-code. Besides parsing byte-code, the RCX firmware has many OS-like
functions: it controls the hardware, threading, and in particular, controls
the IR port that is used to communicate with the robot. It also has the
ability to accept specific commands (as opposed to complete programs) from
the IR port or a special remote control, and move the robot based on those
commands.

The standard firmware is currently in version 1.0 (even if you buy it with
RIS version 1.5). It has pretty serious limitations- for example, since each
variable is stored in a register and not in RAM, there can be only 32
variables. However, you can still do some pretty cool stuff with it, and
version 2.0 of the firmware (which is available now for beta from [http://
www.legomindstorms.com/sdk2/] LEGO) will significantly reduce these
restrictions as well as be reverse compatible with 1.x hardware.
-----------------------------------------------------------------------------

2.3. Where the Linux Tools Fit In

The different Linux Mindstorms programs function as replacments for different
portions of the software chain discussed in the previous section. Some
completely replace the default firmware with their own OS-like system or
language interpreter. Others generate byte-code that matches the standard
Lego byte-code, and use the standard firmware to interpret the byte-code once
it has been generated. Finally, some merely generate the remote control codes
that allow you to control the robot from the host PC, without giving you the
option to run anything on the robot itself. These also use the standard Lego
firmware.
-----------------------------------------------------------------------------

2.4. Hardware Requirements for the Linux Host

Since most of these tools are command line based, hardware requirements are
minimal- basically any Linux system should run them.

The one exception is the serial port, which must be present and may not be on
some newer "legacy free" machines. All communication to the RCX is done via
the IR tower, which is connected to the machine via a serial port. As a
result, if you have no serial port connection, you will be unable to use the
RCX unless you can buy an adapter. Furthermore, under certain circumstances,
there may be problems with IRQs or serial port conflicts. This is
particularly likely if your modem uses /dev/ttyS0. There are three fixes to
this: first, attempt to use your second serial port for the IR tower. In most
cases, this should work. If that doesn't help, just don't use your modem and
your RCX at the same time. If that is unacceptable, then look in your kernel
compile options (under "extended dumb serial driver options") for "support
for sharing serial interrupts." Make sure it is on, and recompile.

Because Macs don't have standard serial ports, LinuxPPC users may have to get
an adapter and make some modifications in order to use these tools. Dave
Baum, NQC author and Mac user, has written [http://www.enteract.com/~dbaum/
nqc/doc/faq.html#irmac] instructions on how to do this.
-----------------------------------------------------------------------------

2.5. The CyberMaster and Scout

Besides the RIS, Lego makes two other robotics systems- the CyberMaster
(available only in Europe) and the Scout. Unfortunately, I believe that only
one of these tools (NQC, discussed in Section 5) will work with these other
tools. Generally speaking, if you are considering buying a Scout, unless you
are severely financially restrained, go ahead and buy an RCX- the additional
investment is worth it.
-----------------------------------------------------------------------------

2.6. Mindstorms Vision Command

The [http://mindstorms.lego.com/products/vision/index.asp] Vision Command kit
is a new addition to the Mindstorms line that uses a USB camera to do some
cool stuff. Unfortunately, because USB camera support (in particular, USB
Quickcam support) is still shaky under Linux, the product is not yet
supported under Linux. If you want to look into hacking it yourself, you may
want to look at [http://hotswap.in.tum.de/~acher/quickcam/quickcam.html] this
page which has a driver for a similar Quickcam.
-----------------------------------------------------------------------------

2.7. Important Note about the MS Windows CD

Because many of the programs discussed below use the official Lego firmware,
you may need your MS Windows CD. You won't need to ever boot MS Windows- your
uptime is safe :) However, (if you run NQC or RCX.pm, among others), you may
need to mount the CD to get the firmware when your batteries die. If you want
to minimize this, find the file firm0309.lgo on the CD and copy it to a safe
place on your Linux partition.
-----------------------------------------------------------------------------

3. LegOS

3.1. Homepage

[http://legOS.sourceforge.net] http://legOS.sourceforge.net
-----------------------------------------------------------------------------

3.2. Author

Markus L. Noga
-----------------------------------------------------------------------------

3.3. Type

Firmware replacement.
-----------------------------------------------------------------------------

3.4. Language

C, C++.
-----------------------------------------------------------------------------

3.5. Platforms

Developed on x86 GNU/Linux and tested on PPC Linux. It has also been ported
to Cygwin and DJGPP on MS Windows. Solaris and Irix ports have been attempted
but not all tools work.
-----------------------------------------------------------------------------

3.6. Description

LegOS is a pre-emptive multitasking POSIXish OS for the RIS. Programs are
written in standard C or C++, compiled on the PC using gcc (built as a
cross-compiler), and then downloaded to the RCX where they are executed.
Basically, anything you can write in C or C++ (and 32K of RAM, of course ;)
you can write in legOS. Interesting features include random(), floating point
emulation, threading with POSIX semaphores, and the ability to store multiple
programs. It also includes functionality for sending and receiving data from
Linux and MS Windows PCs. This power (legOS is almost definitely the most
powerful of the RCX alternative software systems) comes at a slight cost:
because it uses gcc, legOS is probably the most complex system to set up of
the various Linux alternatives, and requires the largest download of tools.
-----------------------------------------------------------------------------

4. Lego::RCX.pm

4.1. Homepage

[http://members.home.com/quillan/lego/rcx.pm.html] http://members.home.com/
quillan/lego/rcx.pm.html
-----------------------------------------------------------------------------

4.2. Author

John C. Quillan
-----------------------------------------------------------------------------

4.3. Type

Remote control library.
-----------------------------------------------------------------------------

4.4. Language

Perl.
-----------------------------------------------------------------------------

4.5. Platforms

GNU/Linux, MS Windows, and Solaris.
-----------------------------------------------------------------------------

4.6. Description

Lego::RCX.pm is basically a perl library for remote control of the RCX via
the IR tower. It takes over the IR tower and sends commands that the standard
firmware can interpret and act upon. If you already have perl installed (and
who doesn't?) this is a very quick and simple way to control your robot. No
installation is necessary: merely copy the files into the correct library
directories, and add "use RCX.pm" to the top of your perl script. I'm not
sure if this has been done yet, but it would make a ridiculously easy way to
interface a robot with a CGI script.
-----------------------------------------------------------------------------

5. Not Quite C (NQC)

5.1. Homepage

[http://www.enteract.com/~dbaum/nqc/index.html] http://www.enteract.com/
~dbaum/nqc/index.html

[http://nqc.mattdm.org/] NQC Linux page at mattdm.org- host for NQC rpms
-----------------------------------------------------------------------------

5.2. Author

Dave Baum
-----------------------------------------------------------------------------

5.3. Type

Native byte-code compiler.
-----------------------------------------------------------------------------

5.4. Language

A C-like language, called (of course) Not Quite C. Should be pretty easy to
learn for anyone with even minimal coding experience.
-----------------------------------------------------------------------------

5.5. Platforms

GNU/Linux, MS Windows, and Macintosh.
-----------------------------------------------------------------------------

5.6. Description

NQC is a byte-code compiler that takes programs written in a C-like syntax
and compiles it (on the PC) into byte-code that can be understood by the
standard Lego firmware. This approach has strengths and drawbacks: for
example, the standard firmware can handle only 32 variables and so NQC is
similarly limited. However, you can do a surprising amount within these
limitations. Setup is pretty simple and the project as a whole is very well
documented. This is also probably the most popular alternative programming
system, so there are a lot of people willing and ready to help out if you
start using NQC.

As already mentioned, NQC is the only option (right now) that supports the
Cybermaster and Scout products under Linux. Furthermore, a beta version of it
works with version 2.0 of the firmware, making it the first alternative
programming system to support the added functionality of the new firmware.
-----------------------------------------------------------------------------

6. pbForth

6.1. Homepage

[http://www.hempeldesigngroup.com/lego/pbFORTH/] http://
www.hempeldesigngroup.com/lego/pbFORTH/
-----------------------------------------------------------------------------

6.2. Author

Ralph Hempel
-----------------------------------------------------------------------------

6.3. Type

Firmware replacement.
-----------------------------------------------------------------------------

6.4. Language

Forth, a common script-like language usually used for embedded systems.
-----------------------------------------------------------------------------

6.5. Platforms

GNU/Linux, MS Windows.
-----------------------------------------------------------------------------

6.6. Description

pbForth is basically a complete Forth interpreter which replaces the standard
firmware. Once it is there, you download Forth scripts to the robot, and the
interpreter then interprets and runs the scripts. There are no limitations on
the number of variables, and there are a number of "libraries" that are
provided for functionality like interactive debugging. This is about the
ultimate in simplicity for tool setup: all you have to do is download a
binary, and then write code and download it. No other tools, compilers,
interpreters reside on the PC. That said, there is a cross-platform TCL GUI
available that simplifies downloading of scripts and interaction with the PC.
-----------------------------------------------------------------------------

7. TinyVM and leJOS

7.1. Homepages

[http://tinyvm.sourceforge.net] http://tinyvm.sourceforge.net

[http://sourceforge.net/projects/leJOS/] http://sourceforge.net/projects/
leJOS/
-----------------------------------------------------------------------------

7.2. Author

Jose Solorzano
-----------------------------------------------------------------------------

7.3. Type

Firmware replacement.
-----------------------------------------------------------------------------

7.4. Language

Java.
-----------------------------------------------------------------------------

7.5. Platforms

GNU/Linux, Win32
-----------------------------------------------------------------------------

7.6. Description

As the name implies, TinyVM is indeed a small Java Virtual Machine that is
downloaded to the RCX to replace the standard firmware. Java programs are
then written and byte-compiled on the PC and downloaded to the RCX. A TinyVM
program can use some standard Java libraries, and a library for control of
sensors, motors, and such on the Mindstorm is provided. TinyVM requires an
already functional java compiler.

leJOS is a similar project (in fact, it is a code fork) by the same author.
It is much higher footprint (currently about 5K additional size) but also
includes substantial additional functionality, including support for floating
point and String constants. Other planned features include garbage collection
and multiple program loading.
-----------------------------------------------------------------------------

8. Remote Java APIs

8.1. Homepages

[http://www.escape.com/~dario/java/rcx/] RCX Java API

[http://www.slewis.com/rcxport/] RCXPort Java Interface
-----------------------------------------------------------------------------

8.2. Type

Remote Control Libraries
-----------------------------------------------------------------------------

8.3. Language

Java.
-----------------------------------------------------------------------------

8.4. Platforms

GNU/Linux(?)
-----------------------------------------------------------------------------

8.5. Description

Both of these libraries are (theoretically) cross-platform Java libraries
that send signals that can be used to remotely control an RCX that is using
the original firmware. Neither have been tested with Linux, and neither are
even in active development, but they may be useful sources for someone, which
is why I've included them here.
-----------------------------------------------------------------------------

9. TCL RCX

9.1. Homepage

[http://www.autobahn.org/~peterp/rcx/] http://www.autobahn.org/~peterp/rcx/

[http://www.demailly.com/tcl/rcx/] http://www.demailly.com/tcl/rcx/
-----------------------------------------------------------------------------

9.2. Authors

Laurent Demailly and Peter Pletcher
-----------------------------------------------------------------------------

9.3. Type

Native byte-code compiler and remote control library.
-----------------------------------------------------------------------------

9.4. Language

TCL.
-----------------------------------------------------------------------------

9.5. Platforms

GNU/Linux, Win32
-----------------------------------------------------------------------------

9.6. Description

The TCL RCX compiler has double-edged functionality: it can either compile a
TCL script into RCX byte-code, or it can remotely control the robot via
either a script or an interactive TCL shell. If TCL is your language of
choice, this is the optimal solution. There are two versions available:
Laurent's (at demailly.com) appears to be the original of the two. However,
neither appear to have been updated since 1998.
-----------------------------------------------------------------------------

10. Pylnp

10.1. Homepage

[http://www.hare.demon.co.uk/lego/pylnp.html] http://www.hare.demon.co.uk/
lego/pylnp.html
-----------------------------------------------------------------------------

10.2. Author

Les Smithson
-----------------------------------------------------------------------------

10.3. Type

Remote control library.
-----------------------------------------------------------------------------

10.4. Language

Python.
-----------------------------------------------------------------------------

10.5. Platforms

GNU/Linux.
-----------------------------------------------------------------------------

10.6. Description

Pylnp is a unique remote control library, not only because of it's use of
Python, but also because instead of interfacing with the standard firmware,
it interfaces with legOS. Because of this, it provides a great deal of
customizability that the other remote control libraries may not have, since
it can be used to invoke custom functions on the legOS side of the robot. The
downside of this power, of course, is that you must learn legOS and write C
programs to access this superior functionality.
-----------------------------------------------------------------------------

11. Other Linux Tools

These programs aren't strictly Mindstorms related, but they may be of
interest to Linux/Lego fans.
-----------------------------------------------------------------------------

11.1. LeoCAD

LeoCAD is (as the name implies) a CAD program for constructing and renderging
Lego models. There is a usable GTK port, which can be found at [http://
leocad.gerf.org/linux.htm] http://leocad.gerf.org/linux.htm. The author
implies that it doesn't have full functionality, so this might make a fun
project for someone.
-----------------------------------------------------------------------------

11.2. POVRAY

Sets of Lego pieces have been created for use with the popular POVRAY 3-D
rendering program. You can find the pieces at [http://
www.kawo1.rwth-aachen.de/~witte/projekte/lego/lego.html] http://
www.kawo1.rwth-aachen.de/~witte/projekte/lego/lego.html and POVRAY at [http:/
/www.povray.org/] http://www.povray.org.
-----------------------------------------------------------------------------

12. Other sources of information

Now that you've read this, there are a number of other places on the web to
further explore the Mindstorms. Most of these are not Linux specific, but
most of them that have discussion forums probably have at least a few users
who use Linux. Hopefully, I've stimulated you enough to explore some more.
Enjoy!
-----------------------------------------------------------------------------

12.1. LUGNET

The LEGO User Group NETwork site, [http://www.lugnet.com/] http://
www.lugnet.com/, has long been the center of the online Lego universe. It has
great newsgroups with lots of people. In particular, the [http://
news.lugnet.com/robotics/] robotics forum has an avid group of very
knowledgeable readers and posters. In addition, several of the options above
have their own active newsgroups in the [http://news.lugnet.com/robotics/rcx
/] robotics/rcx/ hierarchy.
-----------------------------------------------------------------------------

12.2. The Official Mindstorms Site

The official Mindstorms site at [http://www.legomindstorms.com/] http://
www.legomindstorms.com/ has lots of neat ideas, and even accepts NQC source
for public distribution. However, don't expect gobs of info on Linux.
-----------------------------------------------------------------------------

12.3. The Hardware Sites

I've already mentioned these, but it can't hurt. These are the most
comprehensive and detailed looks at the RCX hardware that are available to
folks who aren't LEGO engineers. The "original" site is [http://
www.crynwr.com/lego-robotics/] http://www.crynwr.com/lego-robotics/ and the
second is [http://graphics.stanford.edu/~kekoa/rcx] http://
graphics.stanford.edu/~kekoa/rcx
-----------------------------------------------------------------------------

12.4. Historic Lego Bots and Construction Guide

As you may know, the RIS was partially inspired by work done at MIT. The
creator of the famous "Lego class" at MIT has a [http://
fredm.www.media.mit.edu/people/fredm/projects/6270/] home page that includes
not only links to the class (some seriously cool stuff in there!) but also to
his Robot Builder's Guide, which has lots of great suggestions about actually
building robots to execute all the great programs you've just learned how to
write.
