leJOS NXJ is a tiny Java-based operating system that allows you to run Java programs on the LEGO Mindstorms NXT brick. Before leJOS was ported to the NXT, it was available for the LEGO Mindstorms RCX and for Unix (for emulation of leJOS programs only).
leJOS (sometimes pronounced like the Spanish word "lejos" for "far") 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 by leJOS NXJ:
leJOS NXJ, the version of leJOS for the LEGO Mindstorms NXT, is based on a greatly enhanced Java Virtual Machine based on the RCX version which has been substantially enhanced to support the latest Java bytecode versions and 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. Compared to the RCX Motors, the built-in tachometers in the NXT motors offer 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.
Note that there is a tutorial on how to install and use leJOS NXJ which contains more detailed information than is included in this document. Refer to that if you need help with installing or running leJOS or want to learn about specific features.
libusb must be installed on Linux and can be obtained from http://libusb.sourceforge.net. It is pre-installed with many Linux distributions, or is available as an optional package. 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.
On Microsoft Windows you can you the .exe installer to install leJOS NXJ. This is a GUI installer that leads you through all the steps detailed below. On other systems, or if you use the .zip distribution on Microsoft Windows, you need to do the following:
leJOS_NXJ directory.On Linux systems, you will have to build the native library for USB support. To do so,
switch to the leJOS_NXJ/build folder and run ant. You will need to ensure that the
packages that leJOS NXJ is dependent on are on your system. The native library for USB support
depends on libusb-0.1 or libusb-compat. You need the Development files
for libusb. Typically the package is called libusb-devel.
Note that the library is not compatible with the new libusb-1.0.
nxjflash or nxjflashg command.nxjc instead of javac.nxj or alternatively with nxjlink and nxjupload.nxj --verbose or nxjlink --verbose to get information on methods and special classes used by your program.Your NXT must be plugged into the USB, and switched on 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
or using nxjflash -b "LEGO MINDSTORMS NXT Firmware VX.YY.rfw".
Note that there is also a GUI utility, nxjflashg that can be used to flash the leJOS NXJ firmware. This utility is run as part of the installer on Microsoft Windows systems.
If you have an old version of leJOS on your NXT, or another third-party operating system, you may need to put the NXT brick be in firmware update mode. To put the next in firmware upload, press the reset button with a paper clip for 4 seconds or more. The NXT brick will start to tick. The reset button is hidden on the bottom side of the NXT brick, inside the hole near the USB port.
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.
When the flash procedure has finished, leJOS NXJ will start up and a menu will be displayed.
You can return to the start-up menu when a program is running, by pressing the orange and dark gray buttons (ENTER + ESCAPE) together. If your NXT freezes at any time, remove and re-insert the battery.
The following is a step by step guide to your first Java program running on the NXT:
import lejos.nxt.Button;
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello World");
Button.waitForAnyPress();
}
}nxjc HelloWorld.java to compile HelloWorld.javanxj -r HelloWorld will upload the program to the NXT and start itWhen you switch your NXT back on, select "Files" and press ENTER and you will see "HelloWorld.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.
leJOS NXJ also comes with a lot of samples for you to try. To obtain them, locate the samples.zip file which is part of your leJOS installation, download the seperate ZIP archive from the leJOS download page, or use the sample sources installed via the leJOS Installer on Microsoft Windows. Also, the Eclipse plug-in offers an import wizard to import the sample projects with a few clicks.
The ZIP archive contains four projects:
If you are not using any IDE like Eclipse, we recommend using Ant to run and build the samples.
Change the current workdir to the samples or pcsamples folder, and run the ant
command. It is also possible to run the samples using the leJOS Eclipse plug-in.
There is more information on this in the
tutorial.
The following tools are part of the leJOS NXJ distribution:
-od optionTools like 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 driver for USB on Windows and MAC OSX is NXTCommFantom which uses the LEGO fantom API and on Linux systems, it is NXTCommLibnxt, which uses the jlibnxt library and the libusb open source library. All systems use NXTCommBluecove as the Bluetooth comms driver. This uses libraries from the Bluecove open source project. A properties file lejos_nxt/bin/nxj.properties can be created to select different comms drivers.
leJOS NXJ programs that run on the PC and use the PC API, should be compiled by nxjpcc rather than nxjc. They can be be run using nxjpc. There are examples of these in the pcsamples project.
nxjbrowse lists the files on the NXT and includes their size. 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 defragment 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.
nxjcontrol is a GUI tool that allows you to control multiple NXTs. It has all the functions of nxjbrowse, but also allows you to control and monitor your NXT. It includes the function of nxjconsoleviewer and nxjdataviewer and some of the function of nxjmonitor.
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).
nxjconsoleviewer is a GUI version of nxjconsole
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.
nxjimage can be used to convert a PNG image to the leJOS NXJ image format. The format is understood by our
implemenation of javax.microedition.lcdui.Image. Further more, it can be used to convert an image to a string
representation, that allows efficient storage of images within a leJOS Java program.
nxjchartinglogger visualizes and displays the data logged using the data
being logged via the lejos.util.NXTDataLogger class.
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:
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.
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:
The following bugs and limitations apply to the current version of leJOS NXJ:
The API docs for leJOS NXJ is included in the download. They are in the docs subfolder, unless they have been deselected during installation. You can also browse them online on the leJOS web site.
We are continuing to release under the Mozilla Public License (see the LICENSE file). The nxjflash utility uses code derived from David Anderson's libnxt library, which is released under a GPL v2 license (see COPYING in the jlibnxt directory). Bluecove on Linux uses a GPL v3 license. See the LEGAL and ACKNOWLEDGMENTS files for more detail.
Please direct feedback to the leJOS forums.
Feel free to take a look at the leJOS website or the leJOS project page at sourceforge.