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

There are three packages which need to be installed:
 

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.9.5.0.37.5_i386.deb $ sudo dpkg --install gcc-h8300-hms_2.95.2.2.1_i386.deb $ 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 lugnet.com .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! ;-)

 

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

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