So you’re ready to try out ev3dev. Great! Here are step-by-step instructions to help you get ev3dev up and running on your EV3 or Raspberry Pi.

First, here are the things you need before starting:

The instructions on this page only apply to releases dated December 2015 or later. Older releases are no longer supported. There are many major changes in the December release, so if something seems broken or the documentation seems incorrect, please open an issue on GitHub.

Step 1: Download the latest ev3dev image file

Releases are posted on GitHub. Follow the link and download the latest Test Release image file for your hardware. Releases for LEGO MINDSTORMS EV3 start with ev3-, Raspberry Pi starts with rpi- and Raspberry Pi 2 starts with rpi2-.

Downloading the .zip file is recommended for Windows/Mac and the .xz file is recommended for Linux. The .xz is smaller, but it requires that you have additional software installed on Windows/Mac to decompress it (such as 7-Zip on Windows).

Step 2: Copy the image on to the SD card

This will erase everything on your SD card! Backup your files If you do not want to lose them!

There are a vast number of ways to do this, so pick the one from the list that sounds the easiest to you:

For more detailed information and more alternatives, check out this page for RaspberryPi. Much of the information there is applicable to ev3dev.
Raspberry Pi Only!

You must make some changes to config.txt to enable support for BrickPi or PiStorms before you put your SD card in your Raspberry Pi.

You may have to remove the SD card from your host computer and plug it back in after flashing it in order for it to be detected. In your file browser, open up EV3DEV_BOOT. This contains a file named config.txt. Open config.txt in your favorite text editor and follow the instructions in the file to enable either BrickPi or PiStorms.


When the boot is complete, the LEDs will turn green and you will see something like this on the screen

Step 3: Boot ev3dev

Put the SD Card in your EV3 and power it on. At first, you will see the MINDSTORMS boot splash and the red LEDs will be on. This is immediately followed by the ev3dev boot splash and the LEDs changing to orange. The LEDs indicate disk (SD card) activity.

Note: If you are using Raspberry Pi hardware without a screen, just wait for the Activity LED to stop flashing, then go to the next step.

After about one minute, the screen will go blank. This happens on the first boot only. The first boot takes longer than subsequent boots because the EV3 has to create a unique SSH host ids and take care of a few other housekeeping items. After another minute or two, you will see the brickman loading… screen. If nothing has happened after five minutes, something is not right - check the troubleshooting tips below.

You will notice the number in the battery in the upper right corner. This displays the remaining voltage of the power supply. It is not possible to calculate an accurate percent value of the remaining energy, so this value is chosen. If the voltage drops below 5V the brick will turn off. All not saved data may be lost. Keep in mind, that it may take a much longer time from 8V to 6.5V than from 6.5V down to 5V!

Troubleshooting tips if your EV3 won't boot
  • Make sure nothing is plugged into the EV3 (USB/sensors/motors/etc.)
  • Try writing the image to the SD card again.
  • You may have a bad/incompatible SD card - try a different SD card.
  • Check the condition of the EV3 batteries.

Step 4: Setup a network connection

There are lots of choices here. Your choice depends on what type of connection you want to use and on the OS of your host computer, so pick the one that applies:

For Raspberry Pi with no display, you must use the wired Ethernet port to connect for the first time. You can setup additional connections using the connmanctl command.

Step 5: Do something awesome

This will be where we tell you how to use the EV3’s main functions, and how to write programs. We are still learning, so everything here should be considered experimental and subject to major changes.

Using the EV3 hardware drivers

Here are some guides for using each of the major components.

Writing programs

There are a number of programming languages available to use. The brick can run almost all languages that any other Linux distro can, so your favorite language is probably supported. Language bindings have already been written for many languages. You can learn more about the available libraries here.

If the language you want isn’t listed, you still can use it, but you’ll have to do more of the heavy lifting yourself using the guides above. Once you get the hang of it, you can even write your own interface library and have it listed here!


The 'Shutdown...' dialog in Brickman

Step 6: Calling it a day

When you are ready to wish your EV3 goodnight, turn if off by pressing the back button from the main menu in brickman or pressing and holding the back button from any screen in brickman. This will open a dialog where you can select Power Off to turn off the EV3. (Running sudo poweroff in a terminal works too.)