- What is leJOS?
- Preliminiaries
- Compatibility
- Installation and Set Up
- Known limitations
- Known bugs
- Documentation
- License
- Questions and Problems

# What is leJOS?

leJOS (pronounced like the Spanish word "lejos" for "far") 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 has been forked out of the TinyVM project.
it contains a VM for Java bytecodes and additional software to load and run Java programs. These are some of the features offered:

- Object oriented language (Java)
- Preemptive threads (tasks)
- Arrays, including multi-dimensional ones
- Recursion
- Synchronization
- Exceptions
- Well-documented API

The features above are also provided by TinyVM. But in addition to these, leJOS also offers

- A Windows version, which doesn't require CygWin
- A MacOSX version
- 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.
- Additional APIs

TinyVM is still around simply as a low-footprint alternative to leJOS. TinyVM is about 7 Kb smaller in the RCX.

# Preliminaries

- You need a Java Development Kit (JDK) 1.4 or above
- Your PATH must contain the JDK's bin directory
- Make sure you have set JAVA_HOME properly to the root directory of the JDK
- For the vision parts, you need a Java Media Framework (JMF) 2.1 or above (will be brought along by the leJOS distribution)
- In case you want to build the distribution, your PATH must contain the ant binary (ant 1.6 or above)
- Add leJOS's bin directory to your PATH
- Set RCXTTY to your 'tower' device (e.g. usb,/dev/usb/legousbtower0 or COM1)
- Download firmware using firmdl
- Compile using lejosjc instead of javac
- Link and download programs to the RCX using lejos
- Emulate leJOS programs on the host using emulate_lejoslink and 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

# Compatibility

| RIS 1.0 | RIS 1.5 | RIS 2.0
RCX 1.0/2.0 | + | + | +
Serial IR Tower | + | + | -
USB IR Tower | - | - | +

# Installation and Set Up

Please download the leJOS documentation from the same location you downloaded this distribution from and consult the "First Steps" section of the Tutorial contained there.

1. Set your environment variable LEJOS_HOME to the directory you installed this distribution into
2. Set your environment variable RCXTTY to usb (for USB towers) or COM1 (for serial towers); on Linux, for USB towers RCXTTY might be required to be set to /dev/usb/legousbtower0
3. On Linux, depending on the privilege settings you might need to adjust the execution permissions in the bin folder

On Linux, you will have to build the distribution first. To do so, switch to the build folder and run `ant`.
Note that depending on the privilege settings you might need to adjust the the execution permissions in the release folder.

Download the firmware to the RCX with `firmdl`.

Check the installation by switching to the "check" folder of the leJOS distribution and run `checkDistribution.bat resp. checkDistributionCheck.sh`.
A very simple test program will be downloaded to the RCX. After the download has finished, press the RCX's 'RUN' button. The RCX's LCD should print the strings "SMOKE" and "TEST".

# Known limitations

Due to size constraints, some Java language features have been omitted. Others just haven't been implemented yet. Known limitations are:

- Garbage collection is not performed yet. Hence, the number of objects in your program should be limited
- 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. As a consequence, reflection is not supported by leJOS
- 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

Please download the leJOS documentation from the same location you downloaded this distribution from. The documentation contains the API docs and the tutorial. Online versions may be retrieved from http://lejos.sourceforge.net/.

# License

We are releasing under the Mozilla Public License (see the LICENSE file) 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.

# Questions and Problems

Please direct feedback to the lejos-discussion mailing list mailto:lejos-discussion@lists.sourceforge.net.
To subscribe, see http://lists.sourceforge.net/lists/listinfo/lejos-discussion.

Feel free to take a look at the Lejos website or its project page.