- What is leJOS?
- Preliminiaries
- Installation and Set Up
- Using lejos on the NXT
- Known limitations
- Known bugs
- Documentation
- License
- Questions and Problems

# What is leJOS?

leJOS (pronounced like the Spanish word "lejos" for "far") is a tiny Java-based operating system that has been ported to the following platforms:

- Lego Mindstorms NXT
- Lego Mindstorms RCX
- Unix (for emulation of lejos programs only)

leJOS was originally 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
- Java types including float, long, String, but with some restrictions
- Math class
- Well-documented Robotics API

# Preliminaries

- You need a Java Development Kit (JDK), preferably 1.5
- Your PATH must contain the JDK's bin directory
- Make sure you have set JAVA_HOME properly to the root directory of the JDK
- In case you want to build the distribution, your PATH must contain the ant binary (ant 1.6 or above)
- You need libusb installed. On Windows you should use the libusb-Win32 filter driver
- On Windows you will need the Lego Mindstorms NXT software installed, as its USB drivers are used

# Installation and Set Up

Please download the leJOS documentation from the same location you downloaded this distribution.

1. Set your environment variable LEJOS_HOME to the directory you installed this distribution into
2. Add leJOS's bin directory to your PATH
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.

# Using lejos on the NXT

- Compile using lejosjc instead of javac
- Link programs using lejoslink
- Download and run programs using lejosdl
- Emulate leJOS programs on the host using emu-lejosrun (currently Linux only)
- Exceptions: Use lejoslink --verbose. Exceptions are shown in the NXT as Method:XXXX, CLASS:YY, where XXXX = method_signature and YY = exception_class_index

Your NXT must be plugged into the USB, switched on, and in firmware update mode to run lejosdl.
To go into firmware update mode press the reset button (at the back of the NXT , upper left corner) for more than 4 seconds. Your NXT will audibly tick when it is firmware update mode, but is not running a lejos program.
To switch your NXT on, just press the orange button. It will start to audibly tick.
When you use lejosdl your program will download and run. You can stop a program by pressing the ENTER and ESCAPE (orange and grey square) buttons together. This powers down the NXT immediately. Press the ENTER (orange) button to wake it up again.
You can also power down the NXT with ENTER + ESCAPE, after an Exception occurs.

# 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.

# License

We are continuing to release under the Mozilla Public License (see the LICENSE file). The runjava utility using David Anderson's libnxt which is release under a GPL v2 license (see COPYING in the libnxt directory).

# 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.