- What is leJOS NXJ?
- Preliminiaries
- Installation and Set Up
- Using leJOS NXJ
- Compiling and running your first code
- LeJOS NXJ Tools
- Known limitations in leJOS
- Known bugs in leJOS
- Known bugs and limitations in leJOS NXJ
- Documentation
- License
- Questions and Problems

# What is leJOS NXJ?

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

leJOS NXJ is the version of leJOS for the LEGO Mindstorms NXT. It uses the same Java VM as the RCX version, but has new drivers for the NXT hardware.

leJOS NXJ adds lots of new capability to leJOS including a file system, a menu system, and support for I2C sensors, including those from third parties. The built-in tachometers in the NXT motors have enabled much improved control over speed, steering and navigation.

Bluetooth and USB communications are a great improvement over the infra-red link used by the RCX.

# Preliminaries

- You need a Java Development Kit (JDK), preferably 1.5 or later.
- Your PATH must contain the JDK's bin directory.
- Make sure you have set JAVA_HOME properly to the root directory of the JDK.
- On systems other than Microsoft Windows, you will need to build the distribution, so your PATH must contain the ant binary (ant 1.7 or above).
- You need libusb installed. On Microsoft Windows you should use the libusb-Win32 filter driver.
- On Microsoft Windows and MAC OS X you will need the LEGO Mindstorms NXT software installed, as its USB drivers are used.
- On MAC OS X systems, you will need the OS X developer tools installed.

The libusb filter driver for Microsoft Windows can be obtained from http://libusb-win32.sourceforge.net/#downloads. This does not currently work under Windows Vista - see "Known Bugs and Limitations in leJOS NXJ" below. However, it works if you install on Vista under Windows XP compatibility mode:

1. Download libusb-win32-filter-bin-0.1.12.1.exe (the version current @ 27/09/07)
2. Right click on this file. Select Properties | Compatibility Click the "Run this program in compatibility mode" box and select "Windows XP (Service Pack2)" from the drop down list.
3. Right click again and select "Run as Administrator". Follow the installation instructions. Run the test program will list the usb devices plugged into your computer, but not new devices.

libusb for other systems can be obtained from http://libusb.sourceforge.net.
On Linux systems, if you are running leJOS NXJ from a non-root user, you will need to ensure that you have read and write access the NXT USB device in /dev/bus/usb. If you can identify the device in /dev/bus/usb, you can do this by:
sudo chmod a+w /dev/bus/usb/xxx/yyy
However, the yyy number will count up each time the NXT is disconnected and reconnected.
A better solution is to use udev rules or pamcomsole. How to do this varies with different Linux systems. A pamconsole solution that works on Fedora Core 5, is to create a file /etc/security/console.perms.d/60-libusb.perms with the two lines:
`<usbdevices>=/dev/bus/usb/*/*
<console> 0600 <usbdevices> 0644 root`
To use udev rules, set up a file such as /etc/udev/rules.d/70-lego.rules and populate it with the following lines:
`# Lego NXT
BUS=="usb", SYSFS{idVendor}=="03eb", GROUP="lego", MODE="0660"
BUS=="usb", SYSFS{idVendor}=="0694", GROUP="lego", MODE="0660"
` This relies on the username you are using being in the lego group. You can modify the file to your requirements. The two vendors are LEGO and Atmel (for the samba driver used in firmware update mode). You may need to restart udev.

# Installation and Set Up

1. Extract the files from the distribution. A lejos_nxj subdirectory will be created.
2. Set the environment variable NXJ_HOME to the full path of the lejos_nxj directory.
3. Add the lejos_nxj/bin directory to your PATH.
4. On Linux and Unix systems, depending on your privilege settings you might need to adjust the execution permissions in the bin directory.

On Linux and Unix systems, you will have to build the distribution first. To do so, switch to the build folder and run `ant`. You will need to ensure that the packages that leJOS NXJ is dependent on are on your system. These include libusb-dev, gcj and libbluetooth-dev.

# Using leJOS NXJ

- Flash the leJOS NXJ firmware using nxjflash.
- Compile using nxjc instead of javac.
- Link, upload and run programs using nxj.
- Exceptions: Use nxj --verbose to get information on methods and special classes used by your program. Exceptions are shown on 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 nxjflash. Note that the standard LEGO firmware will be overwritten and all existing data lost. You can reinstall the LEGO firmware using the LEGO Mindstorms software.

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.

To run nxjflash, open a command window, and type nxjflash

nxjflash will write the Java VM and the leJOS NXJ start-up menu to the flash memory of your NXT. It will create an empty user flash area. When the flash procedure has finished, leJOS NXJ will start up and an empty menu will be displayed.

You can switch the NXT off at any time, including when a program is running, by pressing the orange and dark gray buttons (ENTER + ESCAPE) together.To switch it back on just press the orange button. The leJOS NXJ start-up menu will be displayed.

If your NXT freezes at any time, remove and re-insert a battery.

# Compiling and running your first code

To compile, link and download the Tune sample:

- Open a command window
- Check that java and lejos_nxj are on your PATH
- Check that the NXJ_HOME environment variable is defined
- Change to the lejos_nxj\samples\Tune directory
- Type nxjc Tune.java
- Check that your USB cable is connected
- Check that the NXT is turned on
- Type nxj -r Tune

After a few seconds, you should hear an ascending tone sequence indicating that the program uploaded OK. You will then hear a tune play. When it has finished the leJOS NXJ menu will be displayed.

When you switch your NXT back on, select "Files" and press ENTER and you will see "Tune.nxj" in the files menu

You can navigate through the leJOS NXJ menus using the left and right buttons. You select a menu item by pressing ENTER, and exit from a menu by pressing ESCAPE. There are 3 menus: Files, Bluetooth ands System. To select a program, go to the Files menu, scroll down to your program and press the ENTER button. You will then see a sub-menu that lets you execute or delete the program.

# LeJOS NXJ Tools

The following tools are available with leJOS NXJ:

- nxjflash - flashes the firmware
- nxjc - compiles a Java program for leJOS NXJ
- nxj - links, uploads and optionally runs a leJOS NXJ program
- nxjlink - links a program
- nxjupload - uploads and optionally runs a program
- nxjbrowse - explorer for NXJ files
- emu-lejosrun - emulate a leJOS NXJ program on Unix

nxj, nxjupload and nxjbrowse can be used over Bluetooth or USB. By default they try to use USB first, and if this fails, they try Bluetooth

Use the --usb flag to select usb only, or --bluetooth for Bluetooth only.

nxjbrowse displays a list of all the NXTs that it finds, and allows you to select one to connect to. nxj and nxjupload, try each NXT they find in turn until they successfully connect to one. To pick a specific NXT to connect to by name, use the --name flag.

You can connect to a specific NXT by address, using the --address flag. If you specify the address, a Bluetooth inquiry will not be done, and the connection will be much faster. Use nxjbrowse to list the addresses of your NXT devices. An address is 12 hex digits with optional colons between the hex pairs.

The leJOS NXJ tools can use different comms driver to connect to the NXT. The only driver available for USB is NXTCommLibnxt, which uses David Anderson's libnxt library and the libusb open source library. This works on all operating systems. For Bluetooth on Windows, NXTCommBluecove, which uses the Bluecove open source library, is used. On Linux and MAC OS X, NXTCommBluez, which uses the open source Bluez project, is used for Bluetooth.

A future version of leJOS NXJ is expected to support the LEGO Fantom API, which should work for both USB abd Bluetooth.

The properties file,lejos_nxt/bin/nxj.properties, can be modified to select different comms drivers, but for this release the defaults are the only available drivers.

nxjbrowse lists the files on the NXT and includes their size, and start and end pages. It can be used to delete, upload and download programs and other files. It can also run programs, change the name of the NXT and defrag the files, moving them all to the start of user flash memory. Changing the name of the NXT only works over USB.

# Known limitations

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

- 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

The following bugs apply to all versions of leJOS:

- 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

# Known Bugs and Limitations in leJOS NXJ

The following bugs and limitations apply to the current version of leJOS NXJ:

- Occasionally, after flashing the firmware with with nxjflash, the battery level reads as 0.0 and buttons do not respond. If this happens, a battery must be removed and re-inserted. It is not necessary to repeat the nxjflash.
- leJOS NXJ does not work out of the box on Windows Vista systems. This is due to limitations in libusb-win32 that the leJOS NXJ Windows USB tools, including nxjflash, rely on. Installing libusb in windows XP compatibility mode should cure the problem.
- Bluetooth does not work on MAC OS X systems, and the ant build files for MAC OS X are largely untested. See the forums on the leJOS web site for the latest state of leJOS on MAC OS X.
- Occasionally, after pressing the orange (ENTER) button to start leJOS NXJ, the LCD remains blank. If this occurs, and is not due to low batteries, it is necessary to shut down leJOS, by pressing the orange and dark gray buttons (ENTER + ESCAPE), and try again.
- Only one file can be open at a time.
- leJOS NXJ only supports program upload and download, tools such as nxjbrowse, and LEGO communications Protocol commands when the start-up menu is running, not when a user program is running, unless a user program explicitly starts the LCPBTResponder thread.
- The number of files that can be uploaded to lejos NXJ is limited by the fact that the whole file table must fit into two 256-byte pages. If the average filename length is 15 characters, approximately 20 files are supported.
- The maximum filename length is 20 characters.
- Not all LEGO Communications Protocol command are supported, and the semantics of some of them are different from that of the standard LEGO firmware. In particular only one file can be open at a time and the file handle is always 0.
- The leJOS NXJ USB driver does not return a unique serial number for each NXT, in the way that the standard LEGO software does. The effects of this are not known, but it may be the cause of lejos NXJ not working with the LEGO fantom API over USB.
- Java streams over USB are never closed down, and are always open.
- Reading buttons is not very reliable unless your code takes steps to wait for button readings to stabilize. See the TextMenu code for how to do this.
- The RCX limitations of the Java VM also apply to NXJ.
- Sound volume cannot be controlled when playing tones.
- Support for sound sample files is limited to 8-bit WAV files with a sample rate of 11k.
- Data aborts occur if there is a failure in the NXJ VM. If a data abort occurs, it is necessary to remove and re-insert a battery.
- leJOS NXJ does not work with the LEGO Mindstorms PC software, or the LEGO Mindstorms Fantom API.
- On Windows, using the Bluecove library, NXTs that have been paired with the PC are in the list of available NXTs, even when they are not switched on. This does not happen with Bluez on Linux.
- Is usually necessary to pair your NXT using the Operating System before it can be connected to by the lejOS NXJ PC tools and libraries.
- Discovery of Bluetooth devices is slow, taking at least 10 seconds. It is slower still with Bluez on Linux. For Java streams connections from user programs, you can connect directly by Bluetooth address, which is much faster.
- To get permissions to the lejos NXJ usb devices from non-root users on Linux, you typically need to user pamconsole or udev rules. The instructions for doing this are not very explicit.

# Documentation

The API docs for leJOS NXJ is included in the download. You can also access them on the leJOS web site.

# License

We are continuing to release under the Mozilla Public License (see the LICENSE file). The nxjflash 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.

There are forums on the web site that can be used to ask questions, share information on projects, etc.