leJOS, a Java system for the Lego Mindstorms RCX Summary ------- -- You need a Java Development Kit (JDK). -- JDK 1.1 to 1.3 work, 1.4 works with option -target 1.1 for lejosc. -- Your PATH must contain the JDK's bin directory. -- In Unix, type 'make' to finish installation of leJOS. -- Add leJOS's bin directory to your PATH. -- Set RCXTTY to your 'tower' device (e.g. COM1 or USB or /dev/ttyS0). -- Download firmware using lejosfirmdl. -- Compile using lejosc (or lejosc1) instead of javac. -- Run programs in the RCX using lejos. -- Run programs in the host using emu-lejos. -- Exceptions: Use lejos -verbose. Exceptions are shown in the RCX as [XXXX Y], where XXXX = method_signature, and Y = exception_class_index MOD 10. What is leJOS? -------------- leJOS is a tiny (~ 16 Kb) Java-based operating system that has been ported to the following platforms: - Lego Mindstorms RCX, i.e. Hitachi H8300 - Unix (for emulation of RCX programs only) leJOS was forked out of the TinyVM project (http://tinyvm.sourceforge.net). leJOS contains a VM for Java bytecodes, and additional software to load and run Java programs. These are some of the features offered by leJOS: - Object oriented language (Java). - Preemptive threads (tasks). - Arrays, including multi-dimensional ones. - Recursion. - Synchronization. - Exceptions. - Well-documented API. The above are also provided by TinyVM. But in addition to these, leJOS also offers: - A Windows version, which doesn't require CygWin. - Floating point operations (doubles truncated to 32 bits). - String constants. - Casting of longs to ints and vice versa. - Marks references in the stack (which makes it feasible to implement garbage collection). - Multi-program downloading. - java.lang.Math class with sin, cos, tan, atan, pow, etc. - More APIs. TinyVM is still around simply as a low-footprint alternative to leJOS. TinyVM is about 7 Kb smaller in the RCX. Compatibility ------------- RCX 1.0/2.0 in RIS 1.0/1.5/2.0: yes Serial IR Tower in RIS 1.0/1.5: yes USB IR Tower in RIS 2.0: under Microsoft Windows, not under Linux How do you pronounce leJOS? --------------------------- I pronounce it like the Spanish word "lejos" (which means far). Requirements ------------ - A Java Development Kit Lejos is known to work with JDK1.1.x to 1.4.x from SUN (see http://java.sun.com). Other Java environments (for example jikes) may also work. - leJOS is known to work on Linux and Windows. It should work on Unix systems in general. Setup ----- Environment: - Your PATH is assumed to point to the JDK's bin directory. - You should also add $LEJOS_HOME/bin to your PATH. - RCXTTY must be defined to point to the IR device file. For example, in my Linux partition, it's /dev/ttyS1, which corresponds to COM2 under Windows. Building the Tools (UNIX ONLY): Simply go to the installation directory and type 'make'. Downloading the Firmware: Run the lejosfirmdl utility. When the firmware starts, the LCD shows the battery voltage, and you should hear a double beep. The firmware only needs to be downloaded once. It is also easy to replace, say, with the official Lego firmware. Simply run the Lego GUI and do what you would normally do to download the firmware. Example ------- A nice example to get started is the View example, which you can use later if you need to test sensors and motors. To run the View example, execute the following commands (assuming the current directory is the leJOS installation directory): LINUX WINDOWS ----- ------- lejosfirmdl -f lejosfirmdl -f (Wait for double-beep in RCX. This step doesn't have to be repeated to run the example again). cd examples/view cd examples\view export CLASSPATH=. set CLASSPATH=. lejosc *.java lejosc *.java lejos View lejos View (The last step will take about half a minute). Compiling, Linking and Running ------------------------------ To compile your Java classes, use lejosc instead of javac. If the JDK in your PATH is a 1.1 JDK, use lejosc1 instead. Note that lejosc is not a Java compiler. It's simply a small program that calls javac after setting an appropriate value for -bootclasspath. If you prefer another Java compiler to javac, define the JAVAC environment variable. The basic way to use the linker is to make sure that class files can be located in CLASSPATH, and execute 'lejos' as you would execute 'java', e.g. lejos MyMainClass The above links and resolves all classes that could be used by a program with entry point in MyMainClass. The resulting linked binary is downloaded to the RCX. (This is done by creating a temporary file, so the current directory should be writable). To simply create a binary file containing the linked program, use: lejos -o MyProgram.bin MyProgram You can download a previously linked program with: lejosrun MyProgram.bin You can also download multiple programs in one shot as follows: lejos Class1,Class2,... The programs will be linked together, and will replace any programs previously in the RCX. You can press Prgm to select which program to run. After the standing man figure appears in the RCX, you can press Run to start a program. If the program exits by itself, the standing man figure will appear again. To stop a running program, hold the Run button while you press On/Off. Switching off the RCX will also stop a running program. Emulation --------- You should be able to run linked programs in the host computer. All you need to do is use emu-lejos instead of lejos, and emu-lejosrun to run a linked binary, e.g. emu-lejos -o MyProgram.bin MyProgram emu-lejosrun MyProgram.bin To get more informative traces, use the -v option: emu-lejosrun -v MyProgram.bin NOTE: The above is fine for Intel x86 architectures. Under Sparc and other systems with big endian byte ordering, use lejos instead of emu-lejos, e.g. lejos -o MyProgram.bin MyProgram emu-lejosrun -v MyProgram.bin In some cases it might be easier to debug programs with the emulated VM, and you'll also get slightly more detailed exception information. But this emulation tool does not attempt to simulate an RCX graphically or anything like that. It simply dumps traces that allow you to check what your program is doing. Limitations ----------- Due to size constraints, some language features have been omitted. Others just haven't been implemented yet. The limitations that come to mind are: - Garbage collection is not performed yet. (The number of objects in your program should be bounded). - Switch statements are not supported. - Arithmetic operations on variables of type long are not supported, although you can cast ints to longs and vice versa. - Maximum array length is 511. - The instanceof operation will always be true for interfaces. In bytecode, CHECKCAST succeeds on all interface classes (which is a bit unsafe). - The instanceof and checkcast operations are rejected by the linker when they are performed on array classes (e.g. b instanceof byte[]). - There are no objects of type java.lang.Class, which means that the ".class" construct won't work. Class.forName() throws ClassNotFoundException at all times. - Most JDK APIs are unavailable. Known Bugs ---------- - MONITOREXIT ignores null objects (it assumes MONITORENTER has handled them). Furthermore, it doesn't check monitor validity. Until this bug is fixed (actually, at all times) all monitors should be constants. - Initializers (static or otherwise) are not implicitly synchronized. This could lead to access of statics before they are initialized, when multiple threads use a class. Documentation ------------- The latest API Reference should be available at http://lejos.sourceforge.net/. The API Reference for this release can be obtained with 'make javadoc'. About the License ----------------- We are releasing under the Mozilla Public License (see LICENSE) for now, since Kekoa Proudfoot's librcx is under that same license, and leJOS is linked against -lrcx and -lfloat, which are part of librcx. No changes have been made to those libraries, so they haven't been redistributed. They are only needed if you are planning to modify the native C source code. See docs/hacking. The founder of leJOS is Jose Solorzano. Jose has announced he will be leaving the leJOS project so he can spend more time with his other baby, Mark Humberto. Paul Andrews and Juergen Stuber will be taking over as project leaders. Questions/Problems ------------------ Please direct feedback to the lejos-discussion mailing list <lejos-discussion@lists.sourceforge.net>. To subscribe see http://lists.sourceforge.net/lists/ listinfo/lejos-discussion . Take a look at the Lejos website at http://lejos.sourceforge.net/ or its project page at http://sourceforge.net/projects/lejos . Finally, there is a newsgroup at LUGNET for Java on the RCX, see http://www.lugnet.com/robotics/rcx/java/ .