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:

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:

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.


The libusb filter driver for Microsoft Windows can be obtained from http://libusb-win32.sourceforge.net/#downloads. This does not currently work properly 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- (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 systems, is to create a file /etc/security/console.perms.d/60-libusb.perms with the two lines:

<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

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:

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.


The following tools are available with leJOS NXJ:

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. In this release, --name works for both Bluetooth and USB.

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 and MAC OS X, NXTCommBluecove, which uses the Bluecove open source library, is used. On Linux, NXTCommBluez, which uses the open source Bluez project, is used for Bluetooth. However, there is now a version of Bluecove that works on Linux, but it has not been officially released yet. A snapshot release of the two jar files needed on Linux, bluecove203.jar and bluecove-gpl.jar is included in the release. Bluecove uses Bluez, but provides a JSR-82 Java Bluetooth interface. To use Bluecove on Linux, set NXTCommBluetooth=lejos.pc.comm.NXTCommBluecove in the nxj.properties file (see below).

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

The properties file, lejos_nxt/bin/nxj.properties, can be modified to select different comms 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. .

nxjmonitor can be used to monitor a running program on the NXT. The program being monitored should run the LCPBTResponder thread and can output trace messages using LCP.messageWrite on message box 0 - see the MonitorTest sample. nxjmonitor produces a graphical display of the current values of sensors, the battery and motor tachometers as the program runs, as well as displaying the trace messages.

nxjconsole displays messages output by the RConsole class on the NXT. One way to use RConsole is to include a call to RConsole.openUSB(0) at the start of your leJOS program, and RConsole.close() at the end. A stream such as stderr can then be redirected to the remote console by System.setErr(new PrintStream(RConsole.openOutputStream()));. openBluetooth(0) can be used instead of openUSB(0).

nxjdataviewer views data log file produced by the Datalogger class - see the DLTest sample.

nxjproxyserver runs a proxy server that can be used to support Socket and SocketServer connections between programs running on the NXT and Java programs on a PC or across the Internet - see the SocketTest, SocketServer and TimeTest samples.

Using the debug monitor

At this release it is possible to include a debug monitor thread as part of the uploaded binary by specifying the --debug option on nxj or nxjlink.

The debug monitor is the start of a more fully featured remote debugging capability that will be added in a future release. The debug monitor gives a more details when an untrapped exception occurs including simple stack trace that shows methods called by method number, and allows you to interrupt a running program by pressing ENTER+ESCAPE.

When an interrupt occurs a thread dump is displayed. It lists the threads in you program in reverse order of priority. The thread number, state and the numbers of the last 3 executed methods is displayed for each thread. The thread states are:-

R - the thread is runnable
S - the thread is sleeping
D - the thread is dead
N - the thread is new (not yet started)
I - the thread has been started but not yet run
E - the thread is waiting for a synchronized section
W - the thread is waiiting on a monitor object
* this is the running thread (not the debug thread)

After a user interrupt or exception, ENTER+ESCAPE shuts down the brick, ESCAPE terminates the user program and restarts the menu. Any other key continues the user program.

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:

Known Bugs

The following bugs apply to all versions of leJOS:

Known Bugs and Limitations in leJOS NXJ

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


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


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.