Download LeJOS Installation Instructions

LeJOS Installation Instructions
To install the leJOS software, follow these instructions. By the way, leJOS is a
concatenation of “lego” and “Jose”, the name of the original leJOS developer (Jose
Solorzano). It uses the Spanish pronunciation “lehose” which means “far”.
Gather the necessary parts
You’ll need three pieces of hardware. (1) The LEGO NXT. That’s the white and gray
“brick” that contains a microprocessor and functions as the brains of the robot. (2) The
USB cable that connects the robot to the computer. (3) The LEGO Mindstorms NXT cd.
(WARNING! Don’t accidentally grab one of the older RCX cd’s. Be sure you have a
NXT cd.)
The objective and some warnings
Our goal is to take the software that comes with the LEGO NXT and replace it with
Java. i.e., we will replace a cute but not very powerful LEGO programming
language with the full-fledged power of Java. Be aware, however, that the NXT has
VERY limited memory! Only 32kb. That means we cannot install all of the Java API.
So leJOS contains a very limited subset of the Java API. You will want to look carefully
at the leJOS API to see what is available. On your computer you can use any Java that
you like, but any classes downloaded to the NXT must be constrained to the leJOS API
(and any additional classes that you write). By the way, the leJOS API is available in the
“doc” folder where lejOS is installed (probably in the folder “C:\lejos_nxj\doc”).
Furthermore, be aware that the leJOS API does not implement garbage collection. Yikes!
This means that if you create lots of extra variables (for example, in a loop), they just pile
up. Sooner or later they will eat up all available memory and crash your NXT. Try very
hard to reuse variables and don’t create more than you need.
Seem annoying? Well, welcome to the world of small portable devices. Cell phones,
BlackBerries, etc. all have space constraints, although the memory available in these
devices in increasing all the time. However, there are a myriad of other very small
portable devises that have extremely limited memory (like devices that are embedded in
clothing). Essentially, you will be learning how to write software for portable
devices!
Another word of warning. The leJOS API is very poorly documented. In other words,
they have done a very poor job of documenting their code. (The API is built from code
comments using a cool tool called “javadoc”.) Obviously, they did not take any of my
classes! I always insist on excellent commenting, and after using their API, you will
never again doubt the value of commenting.
Another word of warning. Keep the names of your classes less than 20 characters. leJOS
has a bug that makes long class names fail.
Putting leJOS software on your computer
If you are in the computer lab, then this has already been done for you, so skip to the next
section (“Putting leJOS software on your NXT brick”) where you install the software on
the NXT brick.
(1) Download the latest version of leJOS from
http://lejos.sourceforge.net/p_technologies/nxt/nxj/downloads.php Make sure you
download for the NXT brick and not the RCX brick. The program is called
“leJOS NXJ”.
(2) The download is a zip file. Unzip it by right clicking and using the PKZIP
“Extract To…” command. Or use any other utility that unzips.
(3) Store the unzipped folder on your “C:” drive. Storing it elsewhere can cause
problems.
(4) Change the name of the folder to lejos_nxj.
(5) Now we’ll create a System environment variable. (Be sure to set a System
variables rather than a User variable so that everyone can use leJOS.) Create a
NXJ_HOME variable and assign it a value which is the path to the unzipped
folder (which should be C:\lejos_nxj).
(6) Now we’ll alter the “Path” environment variable. Do NOT erase anything that is
already there. Instead, at the end of the Path variable add
“;%NXJ_HOME%\bin”. Notice that it starts with a semicolon. (Why are we
doing this? This uses your previous environment variable to tell your computer
where the executable leJOS files live. In other words, this will let you run leJOS
from the command line.) Warning: if you are getting your directions from
elsewhere, they may incorrectly tell you to type “;%LEJOS_HOME%\bin”.
Don’t do that! It’s NXJ_HOME, not LEJOS_HOME.
(7) Now download the USB driver from http://libusbwin32.sourceforge.net/#downloads. Download the file that has bin in its name
(currently the file is called libusb-win32-filter-bin-0.1.12.1.exe and it is in the
“Filter Driver”; but this name and url may change). If you are using an XP or
Windows 7 operating system, then double click and it will self-install.
(WARNING: if you are using Vista, then right click, select properties, and install
in Windows Service Pack 2 compatibility mode – double clicking will trigger a
bug in the Vista OS that might delete all of your USB drivers. Aurgh!). In all
cases be sure to install the driver in a directory that has no spaces. In other
words, your “C:” drive is a good place to install (but “Program Files” will not
work). This program let’s the leJOS software communicate with the NXT brick
using your computer’s USB.
(8) Install the Mindstorms software that came with the NXT Brick. Most of this is
useless to us (we’re going to use Java!), but we need the USB drivers.
Putting leJOS software on your NXT brick
Note: If someone has already installed leJOS on your brick, then you will not need to do
this step, and you can skip to the next section. If you just unwrapped your NXT brick
(straight out of the box), then you will need to do this step.
(1) Open up a Command Prompt. Change directories to the lejos_nxj folder (at the
prompt, type “cd C:\lejos_nxj”).
(2) Turn on your NXT brick.
(3) Connect the NXT brick to your computer with the USB cable. (In the lab, the
USB ports on the monitors do not always work. Try the USB ports on the
computer itself.)
(4) Prepare your NXT brick to receive software. Use a paperclip to reset the NXT by
pressing the tiny hidden button that is inside the lego pin underneath the USB
port. Press for at least four seconds. Your NXT brick will make a quiet
clicking/pulsing sound.
(5) Now type “nxjflash” at the command line.
(6) If the firmware update is unsuccessful, then it will probably tell you that it can’t
find the NXT and that your USB connection my not be connected properly. In
that case, try the following. Remove and reinsert one of the batteries. Uninstall
the libusb-win32 application, and then reinstall. Press the NXT reset button
again. Try nxjflash again.
Running Java on your NXT brick
Let’s try some sample code that’s already been written. To run this program we
essentially use the “javac” and “java” commands, but we use them in a fancy way.
(1) Open a Command Prompt.
(2) Goto the folder lejos_nxj\samples\Tune by typing “cd lejos_nxj\samples\Tune”.
(3) Compile the Tune program by typing “nxjc Tune.java”. (This creates a
“Tune.nxj” file which is similar to javac creating a “.class” file.)
(4) Press the orange button to turn on the NXT.
(5) Now load the program onto the NXT. In the Command Prompt, type “nxj Tune”.
(This is similar to typing “java Tune”, but uses the leJOS compiler instead.)
(6) The Tune program is put into the file menu of the NXT. Select that file to run the
program.
(7) Turn off your NXT by pressing the orange and dark grey buttons simultaneously.
Problems?
(1) I find that it takes about 10 seconds to recognize Bluetooth from the moment that
you turn on your NXT. So turn it on, wait at least 10 seconds, then type “nxj
Tune”. I often have to retype “nxj Tune” several times.
(2) If you get a strange warning like “javac: invalid flag”, then open the nxjc.bat file.
Remove the text that says “%CLASSPATH%”. Try again.
Now let’s write our own simple Hello program that displays on the LCD of the NXT.
Type the following into a file and save as Hello.java.
import lejos.nxt.*;
/**
* This class prints "hello" on the NXJ.
*/
public class Hello
{
public static void main(String[] args)
{
LCD.clear();
LCD.drawString("hello", 0, 0);
LCD.refresh();
try
{
// this makes the program rest for a
// half second before continuing
Thread.sleep(500);
}
catch(Exception e)
{
}
LCD.drawString("how’s life?", 3, 3);
LCD.refresh();
}
}
To run your Hello program:
(1) Create a new folder to hold your code.
(2) Copy the Hello.java out of the Eclipse workspace and into your new folder.
Do not copy any .class files. Eclipse will automatically create .class files, but
they will not work with the NXT. So don’t copy them, and instead let the
NXT create its own .class files.
(3) To be safe, any time you update your code, you should remove the old .class
files and let leJOS recreate them.
(4) From the Command Prompt, goto the folder that contains your Hello.java file.
(5) Turn on your NXT brick.
(6) Compile with “nxjc Hello.java” (as before).
(7) Load onto the brick with “nxj Hello”. Again, you may have to retype “nxj
Hello” several times.
Setting up Eclipse
You will probably want to develop your NXT code within Eclipse. The process is the
same as always – create a project and write the code. But in order for Eclipse to
recognize the leJOS classes, you will need to load the relevant “.jar” files. For example,
if you use the import statement in the above Hello program, then you will need to tell
Eclipse to load “lejos_nxj\lib\classes.jar”.
(1)
(2)
(3)
(4)
(5)
(6)
Right click your Eclipse project and select Properties.
Select Java Build Path (in the lefthand frame).
Select the libraries tab.
Select Add External Jars.
If Eclipse asks for a CD, ignore it.
Browse to your lejos_nxj\lib folder and select the classes.jar file (or any other jar
that you need).
(7) Select OK.
(8) Now you can Debug your code, just as you always have. But don’t bother trying
to Run your NXT code from within Eclipse. Your computer is not the NXT, so
the commands are meaningless, and the program will crash.
(9) After debugging, you should compile and download your code from the command
prompt as show above.
If you really want to compile and download your NXT code from within Eclipse, you can
set this up for your project by right clicking Properties and selecting “External Tool
Builders” from the list. You will set the leJOS “.bat” files (like lejos_nxj\bin\nxjc.bat
and lejos_nxj\bin\nxj.bat) to be run from within the Eclipse build. See the Eclipse Help
pages on “External Tool Builders” for more info.
Building your robot
You may use any LEGO parts, but be aware that there are two generations of parts.
There are older RCX parts (which look “less rounded and less cool”) and newer NXT
parts. You can use older parts with the newer NXT robot. However, if you use the RCX
light sensor or an RCX Motor, then you will need to use leJOS Java classes that work
with those older parts. In particular, use RCXMotor and RCXLightSensor. (But stay
tuned, I will not let you use either the Motor or the RCXMotor classes because they are
poorly written. See upcoming homeworks…)
Notes:
(1) Only use the RCXLightSensor class when using an RCX light brick. Use regular
LightSensor otherwise.
(2) Use ports A, B, C for motors.
(3) Use ports 1, 2, 3, 4 for sensors. Any sensor can go in any port, despite LEGO
instructions. However, the light sensor does not always work in port 4. It’s a
leJOS bug.