LegOS HOWTO

Luis Villa

luge@users.sourceforge.net

Revision History
Revision 0.2.4October 22nd, 2000

About LegOS

To quote the official LegOS homepage, maintained by the author, Markus L. Noga, LegOS is an

independent LEGO Mindstorms OS. Offers preemptive multitasking, energy saving, dynamic memory management, POSIX semaphores, native access to display, buttons, IR communication, motors and sensors.

In contrast to the standard Lego Group software, LegOS offers serious programmers the ability to write programs for the Lego Mindstorms in C and C++, with few significant limitations. Among the benefits cited by Markus (in comparison to the standard software):

I'll add:

However, there are certain limitations (which is why this is a programmer's tool for the Mindstorms!):

About this LegOS HOWTO

This is the second major revision of the legOS HOWTO. When I started playing with LegOS, I had no experience with LegOS, and was very rusty with what rudimentary C I had. At that time, there was no documenation for legOS, other than the API docs. As a result, it took me a while to get up to speed, particularly since I was learning both LegOS and the RCX at the same time. With that experience in mind, I wrote the HOWTO as an intro to legOS and the RCX.

This is not intended to be a full technical manual. The API documentation at http://legOS.sourceforge.net/API/ fills that role. In cases where the API documentation is lacking (it is auto-generated, and sometimes it shows), the code itself is very well documented for those who are more technically inclined. Rather, the HOWTO is directed squarely at an audience with no RCX experience, and only barely above intro-level C or C++ experience- i.e., a grasp of most programming concepts and data structures, but not necessarily more advanced topics like threading and semaphores. This pretty much describes a class of intermediate level CS students who have just had an RCX plopped in their lap for a class, or someone who is interested in the RCX but doesn't have access to a Windows machine to run the Lego Group software. I am a member of the Windows free group myself, and I hope that CPS 196 was not the last class of its type. My goal for this HOWTO is to serve as a "quick start" guide for these (and similar) groups, or a companion to the source for anyone who is more advanced.

Just because I've focused on beginners for now does not mean that I don't want the HOWTO to cover advanced topics. I'm very open to this, since I hope anyone who gets a start from this will use the time I've saved them to do more than just simple projects. Unfortunately, however, what little progress I had made was basically clobbered by the switch to 0.2.x. At the moment, my most glaring area of ignorance is the legOS Network Protocol, but there are other areas as well. Anyone who has done these things and wants to contribute for the more advanced reader (as well as my own edification) is welcome to.

About the Author

The author is a college student with not as much time on his hands to play with Lego as he would like :) He can be contacted at , except during college basketball season, when he can usually be found on or around ESPN.

I try to respond to all emails; however, this is not always possible. If you have a general legOS question (as opposed to one specifically about the HOWTO) then you are much better off asking the fine people at . I'm usually one of them, so you'll get me plus lots of other developers at the same time.

Development Platforms

This document and most of my code was written on various Linux systems.As a result, I should note that when dealing with system commands in the install section, I have assumed that the reader is on a Unix system of some type, with which the reader is familiar (i.e., the reader can use tar, gunzip, etc.)

If you are on a Windows system, please read section 2.2 to install LegOS, or section 2.4 look at another option. The rest of the documentation should be completely cross-platform- i.e., it should apply to whatever OS you are using to host legOS, since it is mostly legOS specific.

There are also many places in the text where files need to be opened tolook around. Again, I assume that whatever system you are working on has some type of text or code editor, so I leave the option of how to work with files up to the reader.

Current legOS version

The current version of the HOWTO has been written for legOS 0.2.4. However, it was originally written with legOS 0.1.7. I have done my best to remove anachronisms from the text, but I'm sure that effort is incomplete. Please e-mail me at if you find any.

Disclaimer/Legal/Technical Stuff

Like LegOS itself, this HOWTO is not in any way endorsed or supported or even authorized by The Lego Group.

I have written this under the Linux Documenation Project (LDP) Copying License. In short, this document can be copied and distributed freely, but cannot be modified in any way without permission from me. The full text of the LDP License is available at http://metalab.unc.edu/LDP/LDP-COPYRIGHT.html, and you can reach me at .

Document Source

This document is now maintained in the DocBook format. The DocBook source is available here. If you want to do serious work on the HOWTO, I suggest sending me patches against this source. To find out more about DocBook, I suggest reading DocBook: The Definitive Guide or (more concisely) the LDP Author's Guide.

Printable Version of This Document

A PostScript version of this document is available here.

Acknowledgements

  • Markus L. Noga, for writing LegOS.

  • Kekoa Proudfoot, for doing much of the early internals workthat allowed LegOS to be written. (Check out his RCX Internals Page.)

  • Dave Baum. Dave gave me the opportunity to spend a summer working mainly on legOS, which gave me the time to re-write the HOWTO and assume maintainership of the program. The outcome of this opportunity was the book Extreme Mindstorms, which you can now buy from Amazon. This is a pretty shameless plug, but I'm very proud of the book and it offers some serious insight into the kinds of things you can do with legOS.

  • Dr. Michael Littman (formerly of Duke, now at AT&T), who allowed me to fulfill a childhood dream by getting paid to play with Lego.

  • The entire community at lugnet.com, without whom there would have been only the smallest of audiences (and the most minimal of advice) on the writing of this HOWTO.

  • VA Linux, who sponsor sourceforge.net, which makes it possible for all legOS work to be housed (for free!) under one roof. If you run a Free Software project of your own, I strongly recommend looking into Sourceforge, especially if you want to distribute large binaries or data files and face charges for bandwidth use on your normal ISP.

Contributors

Because so many people have contributed to early versions of this documentation, and it is difficult to recognize them individually in the text, I've added this Contributors section. This doesn't replace or supplant the traditional CONTRIBUTORS file in any way; please make sure to read and remember that as well. There are also many names scattered throughout Section 8.1, the Changelog.

These people below have helped out in ways that were once specifically mentioned in the text, but have now been obsoleted. This doesn't lessen their contribution, though, so they get a mention here:

  • Phil Watt; Paolo Masetti; Gavin Smyth; Brian Stormont; for the Cygwin instructions for Windows in their various iterations.