This version of the tutorial is for the 0.9 release of leJOS NXJ.

Prerequisites

Java Development Kit

You will also need a Java Development Kit (JDK) on your PC. Note that a Java Runtime Environment (JRE) is not sufficient as it does not allow you to compile Java programs. You can download the latest JDK from http://www.oracle.com/technetwork/java/javase/downloads/. Follow the instructions for installing it. leJOS NXJ works has been tested with JDK versions 1.5, 1.6, and 1.7, and will not work with earlier versions. JDK 1.6 or 1.7 is recommended. Note that leJOS has only been tested with the official Oracle JDK. It is likely to work with the Open JDK, but not with gcj.

leJOS NXJ needs to know the locations of java.exe and javac.exe. There are several possibilities to achieve that: (1) add the bin directory of the JDK to your PATH environment variable so that commands such as java and javac can be called from a command prompt or (2) set the LEJOS_NXT_JAVA_HOME environment variable to the directory of an installed JDK. The JAVA_HOME environment variable can also be used instead of LEJOS_NXT_JAVA_HOME. If you do not know how to modify environment variables, read the "Setting up environment variables" section below.

USB Driver

In order to use a USB connection to your NXT brick on Linux, libusb must be installed. It can be obtained from http://libusb.sourceforge.net. It is pre-installed with many Linux distributions, or is available as an optional package.

You will need to ensure that the packages that leJOS NXJ is dependent on are on your system. To build the jlibnxt JNI library, which is used for USB access, you need the Development files for libusb. The package is usally called something like libusb-devel. Note that either libusb-0.1 or libusb-compat is required. The newer libusb-1.0 will not work.

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. You can temporary allow access to certain USB decives using the following command:

sudo chmod a+w /dev/bus/usb/xxx/yyy

The xxx and yyy numbers need for you NXT to be determined beforehand. The number will change each time the NXT is disconnected and reconnected or turned off and on again.

A better solution is to use udev rules. How to do this may vary with different Linux systems. 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 brick in normal mode
SUBSYSTEM=="usb", DRIVER=="usb", ATTRS{idVendor}=="0694", ATTRS{idProduct}=="0002", GROUP="lego", MODE="0660"
# Lego NXT brick in firmware update mode (Atmel SAM-BA mode)
SUBSYSTEM=="usb", DRIVER=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="6124", GROUP="lego", MODE="0660"

These rules rely on your username being in the lego usergroup. You may have to create this usergroup via sudo groupadd lego and then add your username to the group via sudo gpasswd -a <username> lego. You can also modify the file to your requirements. On recent Linux system, the rules are reloaded automatically by udev. The rules can be reloaded manually using the command sudo udevadm control --reload-rules.

Bluetooth

If you want to communicate with the NXT over Bluetooth, you will need a Linux supported Bluetooth dongle or built-in support on your PC. leJOS uses the Bluecove libraries which are included in the distribution. You can use leJOS NXJ without Bluetooth.

Back to top

Installing leJOS

Downloading the software

You can download the leJOS NXJ software from The leJOS NXJ download page.

The Linux edition of leJOS is distributed as a .tar.gz file. Untar the archive to a location of your choice, e.g. /opt/leJOS_NXJ

Back to top

Setting up environment variables

leJOS NXJ needs to know the locations of java.exe and javac.exe. There are several possibilities to achieve that: (1) add the bin directory of the JDK to your PATH environment variable so that commands such as java and javac can be called from a command prompt or (2) set the LEJOS_NXT_JAVA_HOME environment variable to the directory of an installed JDK. Note that you can use JAVA_HOME instead of LEJOS_NXT_JAVA_HOME, however setting JAVA_HOME might intefere with other applications.

Furthermore, the NXJ_HOME variable should be set to the directory where leJOS NXJ is installed. It allows other applications, e.g. the Ant scripts, to locate the leJOS Development Kit. Also, for easy exececution of the leJOS commands on the command line, the bin folder of the leJOS distribution should be added to the PATH variable.

Examples:

The bin directory for the JDK may already be on your PATH. In that case, it is unnecessary to set LEJOS_NXT_JAVA_HOME or JAVA_HOME, unless you want to have multiple JDKs on your system and want to select a specific JDK for use with leJOS.

With most Linux distributions, you can set these environment variables for the current user in .bash_profile or for all users in /etc/profile.

Building the release

In order to use USB communications, you have to build the java native library first. In order to do that, change directory to $NXJ_HOME/build and type ant. If you have the dependent packages installed the release should build without errors.

Flashing the Firmware

As leJOS NXJ is a firmware replacement, you will need to flash the firmware to your NXT. Note that this will overwrite any existing firmware. If you have the standard LEGO firmware or other third-party firmware on your NXT, existing files will be lost.

Note that the 0.9 release changes the amount of flash memory reserved for the firmware and the startup menu, so when you first flash the 0.9 firmware any existing files will be lost

Make sure your NXT is attached to the PC via USB cable and switch it on by pressing the orange button. Open a command line prompt and either type the command nxjflash or nxjflashg. The latter starts the GUI version of nxjflash.

If you chose nxjflash to flash the leJOS NXJ firmware, you will see some messages on your command window. If the NXT brick is already in firmware update mode (it makes a ticking noise), then the firmware will be uploaded immediately. Otherwise, if your NXT has a previous version of the leJOS or LEGO firmware on it, a list of the NXTs connected to the USB will be shown and you will be asked to input the number in the list of the NXT you want updated - this will be 1 if a single NXT is connected to your PC. After the flashing procedure has finished, you should see the leJOS logo on your NXT and hear the leJOS startup sound. If your NXT has other firmware on it, or if nxjflash fails, you must manually put your NXT into firmware update mode. Press the reset button (at the back of the NXT, hidden in the hole near the USB port) for more than 4 seconds. A straightened paper clip could be useful for this. Your NXT will audibly tick when it is firmware update mode. Then try nxjflash again.

If you chose nxjflashg, the GUI version of nxjflash will start. When the program window opens, click on Start Program and follow the instructions. A more complete explanation is in the PC GUI Tools tutorial page.

Note that at the time of writing, the LEGO firmware has serious problems with talking to a computer running Linux via USB. Therefore it is recommened to manually put the NXT brick in firmware update mode as described above. The leJOS firmware does not have any problems of that kind.

Back to top

Testing your Installation

You can test your installation by following the steps for writing your first leJOS Program which are the next part of this tutorial.

Back to top