This page will guide you through preparing and installing leJOS on your Lego EV3 brick, as well as provide some troubleshooting help for the most common issues.

Prerequisites

You will need a few things before you can get started.

  1. A Lego EV3 brick.
  2. A microSD card and a way to plug it into your computer. I use this IOGEAR adapter with great success.
    1. The card needs to be formatted as FAT32 and no larger than 32 GB.
  3. The latest version of leJOS (0.9.1-beta as of this writing).
  4. The Java JDK installed on your computer.
  5. The Java SE for embedded devices (8u111 as of this writing).
    1. Note: this is a download, not something to install on your computer.
  6. Some knowledge of command-line usage.

Getting Started

Assuming that you already have the hardware components (the EV3 brick and the SD card), the rest of this page will focus on getting leJOS up and running. We will use Java 8 for this, as it includes some nifty new features compared to Java 7.

Step 1: Download and Unpack leJOS

The website for the leJOS project is one of the best sources of information. Make sure you look at the Wiki and API sections there. The latest version of leJOS can be found on SourceForge. We’ll be using version 0.9.1-beta, which is the latest version at the time of this writing.

  1. Download the file named leJOS_EV3_0.9.1-beta.tar.gz from here.
  2. Unpack the archive.
    1. Double-click it, or
    2. tar -xzf leJOS_EV3_0.9.1-beta.tar.gz
  3. Inside the new directory you will see a file named lejosimage.zip. This is the core of the firmware. Unzip it to its own directory.
    1. Double-click it (which will create a directory for it), or
    2. unzip lejosimage.zip -d lejosimage

Step 2: Download and Prepare Java SE Embedded

Acknowledgements: most of the credit for this section goes to Dr. Gabriel Ferrer and his insightful post on the subject.

The place to find Java SE for embedded devices is here. (You may have to create a free Oracle account.) We need the file ending in -sflt. (The reason for this is that the EV3 uses an ARMv4T core which needs the floating point emulated.) Currently this is the ejdk-8u111-linux-arm-sflt.tar.gz file.

  1. Download the appropriate Java SE Embedded file from the above link.
  2. Unpack the archive (same steps as above).
  3. Navigate to the new directory, and then to the bin directory inside it.
  4. There should be a file named jrecreate.sh (among others).

Now we are going to create our JRE to use with the EV3. The full documentation of the options can be found here, if you are curious. For our purposes, we need four things:

  1. Set the JAVA_HOME global variable.
    1. This can be done in your shell startup file (different for each shell) or manually. We are going to set it manually here just to run the jrecreate.sh script, but you should consider taking the time to set up your environment for future development. The Java installation on my Mac includes a java_home command which will provide the full path to the currently active JRE, but the java_home binary lives in /usr/libexec and that directory is not part of PATH. We’ll just have to run the command with a full path.
      1. If you’re using Linux or similar, you can run which java to see which binary gets run when you execute a command, then follow the symlinks from there to determine the proper path for JAVA_HOME. More information can be found online.
    2. Running /usr/libexec/java_home should return the proper path.
    3. Set the global JAVA_HOME variable using the java_home command.
      1. export JAVA_HOME=`/usr/libexec/java_home`
      2. Pay attention to the backticks in the above command. That line sets JAVA_HOME to the result of running the java_home command, and not to the path /usr/libexec/java_home.
  2. Decide on a destination directory for the embedded JRE.
    1. We’ll use ../../ejre_8u111_linux_arm so it will be created two directories above the bin directory where we’re working.
  3. Specify an API profile for the JRE.
    1. We’ll use compact2 because that’s what leJOS requires.
  4. Specify a JVM for the JRE.
    1. We’ll use client, for the same reason.

So, with all this in mind, the command to create our JRE is thus:

./jrecreate.sh --dest ../../ejre_8u111_linux_arm --profile compact2 --vm client

When the process completes, the JRE will be in the specified directory. We need to tarball it and compress it.

  1. cd ../..
  2. tar -cf ejre_8u111_linux_arm.tar ejre_8u111_linux_arm/
  3. gzip -9 ejre_8u111_linux_arm.tar

Now you should have a file named ejre_8u111_linux_arm.tar.gz. This is the Java 8 JRE for embedded devices that leJOS needs.

Installation

Now we will put it all together on the Lego EV3 brick.

  1. Find the directory you created in Step 1 above, containing the unzipped contents of the lejosimage.zip file.
  2. Copy the contents of this directory to the root of your SD card.
  3. Copy the file you created in Step 2 above to the root of your SD card.
  4. (Optional) If you are pedantic like me, delete all dotfiles from the card that the Mac stubbornly creates on all external devices. Running rm -r .* (the working directory should be the SD card’s root) should do it. Make sure you’ve closed all Finder windows that are displaying the contents of the card first, lest the Mac recreates the files immediately.
  5. Eject the card, insert it into the Lego EV3 brick, and boot the device.

If everything went well so far, you should see the EV3 boot leJOS and the install process begin. After a few minutes your EV3 should reboot and boot into leJOS.

Troubleshooting

The most common issue at this point, provided you encountered no other errors, is that your EV3 will boot into the stock Lego EV3 firmware and not into leJOS. This may happen even instead of the leJOS installer starting at all. The causes for this may be numerous, but the most likely one is that your FAT32 partition was not created quite to EV3’s liking. (For example, using the Mac Disk Utility causes this to happen sometimes.) I’m not familiar with the exact technical reasons, but there are a few things to try that are known to fix this particular issue.

You are advised to try them in this order.

Option 1: Use the Provided Disk Image

The compressed file you downloaded in Step 1 also contains a file named sd500.zip. Unzip this file, and you will end up with a file called sd500.img. This file contains a FAT32 partition image that is known to work consistently. You will need to write it to the SD card using the method of your choice. The example below uses the dd command.

Note: writing the image file to the SD card is not the same as copying it. If you’re not sure of what you’re doing, stick with the dd command!

Note: most of these commands will need elevated privileges, so precede them with sudo or change to a root account before issuing them.

  1. On the command line, change to the directory that contains the sd500.img file.
  2. Unmount the SD card.
    1. Use diskutil list to list the attached devices, and identify the device name of your card. It’ll be something like /dev/disk1, /dev/disk2, etc. It should be obvious which one it is.
    2. Unmount the device. Assuming that it’s /dev/disk1, one of the following should work.
      1. umount /dev/disk1, or if that fails,
      2. diskutil unmountDisk /dev/disk1
    3. Write the image file to the device.
      1. dd if=sd500.img of=/dev/disk1
  3. When this is done, the card will automatically mount back and have the name SD500. Repeat the Installation step above.

When using dd, and especially if you’ll be doing it repetitively, there are a few things to try that might speed up writing data to Flash storage. Unfortunately, these do not produce a universal improvement because the results are dependent on many variables, including type of Flash storage, buffering, OS version, etc. However, it may be worth your time to benchmark the following, alone or in combination.

  1. On a Mac, use rdisk instead of disk when using dd. For example, /dev/disk1 would become /dev/rdisk1.
  2. Use a non-default number for the bs argument to dd. For example, adding bs=512, bs=1024, or bs=4096 after dd may speed up the transfer. Different values may have a different impact.

Option 2: Use Another OS or Tool to Format the Card

  1. You can use Windows to format the SD card. This is the most compatible option in this section. If you have messed up the partitions, you should start fresh with the whole device. This can be done with the diskpart utility in Windows.
    1. Open a Command Prompt with administrator privileges.
    2. Start the diskpart utility. It is interactive and command-driven.
      1. Use the built-in help (help) to navigate around.
    3. List the disks (list disk) and identify the SD card.
    4. Select the SD card (select disk X), where X is the disk number of the card.
    5. Issue the clean command.
    6. Create a primary partition (create partition primary).
    7. Exit and eject the drive. Unplug it, then plug it back in and you will be prompted to format it. Format as a FAT32 partition and select default values for the other options.
  2. Alternatively, on a Mac the command-line utility diskutil provides somewhat greater control over the formatting process. Running with elevated privileges (as usual), you can try running the following command, replacing /dev/disk1 with the identifier for your SD card.
    1. diskutil eraseDisk FAT32 EV3 MBRFormat /dev/disk1
    2. The EV3 part of the above line sets the name of the volume. Use whatever you want here, but for compatibility sake use only uppercase letters, numbers, and underscore.
  3. If you want to try using Linux or UNIX, or something else entirely, keep in mind that many of the other tools out there create FAT partitions that are not standard or compatible with all devices, or require extensive knowledge of the FAT filesystem in order to provide the correct arguments.
  4. Repeat the Installation step.

Option 3: Use a Different microSD Card

It could be the case that the Flash media you’re using has a problem. Try switching to another one, or another way to connect it to your computer.

Option 4: Ask for Help

When all else fails, my advice would be to post your issue on the leJOS forums and hope the knowledgeable people there can help you, after having done your own due troubleshooting.