Getting Started on OS X
Getting Started on OS X

This version of the tutorial is for the 0.9 release of leJOS NXJ and is compatible with OS X 10.4 or higher and both intel and ppc processors.


Java Development Kit

You will also need a Java Development Kit (JDK). Note that a Java Runtime Environment (JRE) is not sufficient as it does not allow you to compile Java programs. A full JDK already ships with OS X or it can be installer on demand. Try the java and javac commands in the termainal to see whether a JDK is already installed. On OS X Lion, the commands will also show the instructions on how to installed the JDK provided by Apple. leJOS NXJ has been tested with JDK versions 1.5 and 1.6, and will not work with earlier versions. JDK 1.6 is recommended. At the time of writing, official builds of Java 1.7 are not available for OS X.

Note that even if you have a 64-bit system, leJOS will always chose to run java in 32 Bit mode by automatically passing the -d32 parameter to the java command whenever necessary.

Back to top

USB Driver

To run leJOS NXJ on OS X you will need a suitable USB driver on your PC. If you have installed the standard LEGO Mindstorms NXT-G software, a suitable driver (the so-called Fantom driver) is already installed. If you do not wish to install the LEGO software on your PC or if you want to update the Fantom driver to the latest version, you can get an installer from The LEGO Mindstorms site. It is strongly recommended to update to the latest version (1.1.3 at the time of writing).

(Optional) 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.

Pairing the NXT with your Mac should be done by pair from the computer. Browse for the device and enter a passcode of 1234 on the mac.

Back to top

Installing leJOS

Downloading the software

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

The OS X edition of leJOS is distributed as a .tar.gz archive. Untar the archive to a location of your choice. You may delete the build subfolder, since it is required for Linux only.

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.


Variable Value Example
NXJ_HOME The folder you installed leJOS NXJ into /Users/me/leJOS_NXJ
LEJOS_NXT_JAVA_HOME The folder where the JDK is installed /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home
PATH Add the bin folders for the JDK and leJOS /Users/me/leJOS_NXJ/bin:$PATH

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.

You can set these environment variables either as user or system variables depending on whether you want leJOS NXJ to be available to just the current user or to all users.

To set the environment variables for the current user only, create and edit ~/.profile. The file should contain the following lines:

export NXJ_HOME="/Users/me/leJOS_NXJ"
export LEJOS_NXT_JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home"
export PATH="$NXJ_HOME/bin:$PATH"

To set the environment variables for all users, edit the file /etc/profile, and add the following lines:

if [ $(whoami) != "root" ]; then
  export NXJ_HOME="/Applications/leJOS_NXJ"
  export LEJOS_NXT_JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home"
  export PATH="$NXJ_HOME/bin:$PATH"

Note, that the above assumes that leJOS has been moved to /Applications/leJOS_NXJ so that it is available to all users.

Back to top

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.

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