leJOS (sometimes 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 is based on the same Java VM as the RCX version, but has new drivers for the NXT hardware, and has been substantially enhanced top support the latest Java bytecode definition.
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.
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 libusb, not libusb1 is required.
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. 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.
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:
On Linux systems, you will have to build the distribution. 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. 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, not libusb1.
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.
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 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.
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 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 a battery.
To compile, link and download the Tune sample:
If you used the Microsoft Windows Installer to set up leJOS NXJ, the projects folder will be leJOSNXJProjects in your home directory. Your home directory is C:\Users\username on Vista and Windows 7 systems and C:\Document and Settings\username on XP systems.
On other systems, of if you used the .zip distribution on Microsoft Windows, the projects folder is a subdirectory of lejos_nxj.
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 lots of other samples you can try in the samples project. You can import the samples project and other projects from the projects folder into your favorite IDE, such as Eclipse or Netbeans. You can then run the samples using the ant build files provided, or using a leJOS NXJ plugin for the IDE. There is more information on this in the tutorial.
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.
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.
The properties file, lejos_nxt/bin/nxj.properties, can be modified 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 these in the pcsamples project.
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.
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.
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. 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 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.