Getting Started on Linux


Getting Started on Linux

This version of the tutorial is for the 0.85 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://java.sun.com/. Follow the instructions for installing it. leJOS NXJ works has been tested with JDK versions 1.5 and 1.6, but will not work with earlier versions. JDK 1.6 is recommended as some PC samples do not work with JDK 1.5. Note that leJOS has only been tested with the official Sun JDK.

You will need to add the JDK bin directory to your system or user PATH, so that commands such as javac and java can be called from a command prompt. If you do not know how to do this, see Setting up environment variables below.

It is also a good idea to set the environment variable JAVA_HOME to the folder where you installed the JDK, as it is necessary if you use the ant build system.

libusb

In order to use a USB connection to your NXT brick on Linux, you will need libusb installed on your sysyem. leJOS requires the legacy 0.1.12 release. On most Linux distributions the 0.1.12 version of the libusb package will normally be installed, but the libusb development package may not be.. You can get more information from http://libusb.sourceforge.net

Package Dependencies

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 (libusb-devel). Note that leJOS NXJ uses libusb (legacy release 0.1.12), not libusb1. To build the jbluez library, you need the Development Libraries for Bluetooth applications (bluez-libs-devel). jbluez is only needed if you use the NXTCommBluez comms driver instead of the default NXTCommBluecove. If you do not need jbluez, you can remove the build of it from the build/build.xml file. Note that package names and descriptions may differ with different Linux distributions.

Accessing USB devices

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. 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
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 reload the rules or restart udev. On some Linux systems, the command to reload the rules is 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. By default leJOS uses Bluecove with is included in the distribution, but there is an option to use the Linux BlueZ API directly.

You can use leJOS NXJ without Bluetooth.

Back to top

Downloading the software

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

On Linux, leJOS is distributed as a .tar.gz file.

Back to top

Installing leJOS

Unpacking the release

Unpack the release a directory of your choice, e.g. /opt/lejos/

Setting up environment variables

You need to set:

Variable Value Example
NXJ_HOME The folder you installed leJOS NXJ into /opt/lejos
JAVA_HOME The folder where you installed the JDK /usr/java/
PATH Add the bin folders for the JDK and leJOS $PATH:$JAVA_HOME/bin:$NXJ_HOME/bin

Setting JAVA_HOME is not always necessary, but is good practice. The bin directory for the JDK may already be on your PATH.

With most Linux distributions, you can set these environment variables for the current user in .bash_profile or for all users in /etc/profile. If you use Eclipse and the Eclipse plugin, you will also need to add $NXJ_HOME/bin to LD_LIBRARY_PATH so that the Eclipse plugin can access the leJOS NXJ JNI libraries. This should normally be done in /etc/profile, but this may differ for different Linux distributions.

Building the release

To build the release, change directory to lejos_nxj/build and type ant. If you have all the dependent packages installed the release should build without errors.

If you do not need jbluez, and you do not have the package dependices for it, you can remove it from the build.xml file.

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.85 release changes the amount of flash memory reserved for the firmware and the startup menu, so when you first flash the 0.85 firmware any existing files will be lost

Make sure your NXT is attached to the PC by its USB cable, and switch it on by pressing the orange button.

You can either use the command line nxjflash command or the nxjflashg GUI program.

Using the command line:

Type nxjflash to flash the leJOS NXJ firmware. If your NXT is in firmware update mode, the firmware will be updated. You will see some messages on your command window, and the NXT should show the leJOS splash screen and then the leJOS NXJ menu. 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. If your NXT has other firmware on it, or if nxjflash fails, you must put your NXT into firmware update mode. Press the reset button (at the back of the NXT , upper left corner) 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.

Using the GUI version:

To run the GUI version type nxjflashg. 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.

Back to top

Testing your Installation

You can check that you have successfully installed leJOS NXJ on your PC and your NXT by compiling and running your first program.

Compiling and running your first program

Java programs need to be compiled to class files before they can be run. For leJOS NXJ, all the class files that are to be run on the NXT needed to be linked to produce a binary file (with the extension .nxj) and this must then be uploaded to the NXT.

To run a sample program, such as the View.java sample, follow these steps:

Start a shell session, and change directory to the lejos_nxj/projects/samples/View folder:

Compile the program with the nxjc command:

 nxjc View.java 

Then link, upload and run it with the nxj command:

 nxj -r View 

You should see the menu of the View sample on your NXT.

Back to top