Welcome to ev3dev’s documentation!¶
Introduction¶
ev3dev is a Debian Linux-based operating system that runs on several LEGO MINDSTORMS compatible platforms including LEGO MINDSTORMS EV3, Raspberry Pi, and BeagleBone.
Supported Hardware¶
- LEGO MINDSTORMS EV3
- Raspberry Pi with one of the following:
- BeagleBone Black/Green with:
Follow the links below for a side-by-side comparison of supported hardware devices as well as detailed ev3dev-specific information on each device.
Hardware Platforms¶
The following hardware platforms are supported by ev3dev.
FatcatLab EVB¶
EVB is a LEGO MINDSTORMS compatible daughterboard for BeagleBone produced by FatcatLab.
Setup¶
Since the EVB does not have an EEPROM to electronically identify it, some
manual configuration is required to enable it. This is done by editing the
uEnv.txt
file in the boot partition:
# FatcatLab EVB
cape=evb
Power¶
EVB is powered from 6 AA batteries (nominally 9V). It is possible to power the BeagleBone + EVB via USB or the 5V jack on the BeagleBone. However, the motors will not move because the motor controller chips are connected directly to the battery voltage.
Warning
When powering EVB from USB, it will shutdown because of low battery. See https://github.com/ev3dev/ev3dev/issues/989.
We are working on a workaround.
More information is available in the hardware driver documentation.
Sensors and Input Ports¶
The EVB input ports are basically the same as the input ports on LEGO MINDSTORMS EV3. There are some caveats though.
- A small number of NXT/I2C sensors require 9V (battery voltage) on input port pin 1 (e.g. the LEGO NXT Ultrasonic sensor and the Codatex RFID sensor). EVB does not provide this voltage.
- Due to a missing GPIO on pin 2, some NXT sensors cannot be automatically detected. These sensors can still be used by manually configuring the port.
More information is available in the hardware driver documentation.
Motors and Output Ports¶
The output ports on the EVB are virtually identical to LEGO MINDSTORMS EV3.
More information is available in the hardware driver documentation
Display¶
EVB has a 2.2” 220x176 pixel color display (16bpp). The backlight is always on.
Buttons¶
EVB has a small joystick for directional input (up, down, left, right) and center (enter) plus a separate button for back (backspace). Pressing more than one button at a time is not supported.
More information is available in the hardware driver documentation
Sound¶
EVB has a built-in speaker. It works just like the speaker on LEGO MINDSTORMS EV3.
More information is available in the hardware driver documentation
LEDs¶
EVB does not have any LEDs.
Bluetooth¶
EVB does not have Bluetooth capabilities. A USB Bluetooth dongle can be used if needed.
LEGO MINDSTORMS EV3¶
EV3 is a programmable LEGO brick produced by LEGO.
Todo
Add paragraph about CPU and RAM. Maybe flash memory too.
Power¶
EV3 is powered from 6 AA batteries (nominally 9V) or a rechargeable LiON battery pack (nominally 7.4V). The rechargeable LiON battery pack is automatically detected. Users of NiMH rechargeable batteries should manually configure the power supply driver to protect against over-discharge that could damage the batteries.
More information is available in the hardware driver documentation.
Sensors and Input Ports¶
Todo
Add documentation about sensor types and automatic detection.
More information is available in the hardware driver documentation.
Motors and Output Ports¶
Todo
Add documentation about motor types and automatic detection.
More information is available in the hardware driver documentation
Display¶
The EV3 has a 178x128 pixel monochrome display.
Tip
The display is also capable of operating in a 2bpp grayscale mode.
More information is available in the hardware driver documentation
Buttons¶
The EV3 has 6 buttons. These are mapped to keyboard keys (up, down, left, right, enter and backspace).
More information is available in the hardware driver documentation
Sound¶
The EV3 has a built-in speaker for sound playback. A standard Linux sound driver (ALSA) is provided so that it can be used with most Linux programs that support sound.
There are two modes of operation. The tone or beep mode, which drives the speaker with a square wave, can be very loud. The PCM playback mode, on the other hand, tends to be very quiet.
More information is available in the hardware driver documentation
LEDs¶
The EV3 has two red/green LEDs. With both red and green are lit at the same time, the colors mix and appear to be amber (orange/yellow). Unlike the official LEGO firmware, the left and right LEDs can be independently controlled in ev3dev.
More information is available in the hardware driver documentation
Bluetooth¶
The EV3 has a built-in Bluetooth chip.
Todo
Write some more about Blueooth and add some useful links on how to use it.
Wi-Fi¶
EVB does not have built-in Wi-Fi capabilities. A USB Wi-Fi dongle can be used if needed.
More information on USB Wi-Fi dongles is available on the wiki.
Firmware¶
The EV3 firmware resides in the built-in 16MB flash memory. Ev3dev runs entirely from a microSD card and never touches the firmware. To return to the official LEGO firmware after using ev3dev, simply power off the EV3 and remove the microSD card, then turn the EV3 back on.
There has also been some progress on developing a version of ev3dev that runs from the flash memory instead of from a microSD card. If you are interested in this, please have a look at https://github.com/ev3dev/ev3dev/issues/416.
Dexter Industries BrickPi and BrickPi+¶
BrickPi(+) is a LEGO MINDSTORMS compatible daughterboard for Raspberry Pi produced by Dexter Industries.
BrickPi and BrickPi+ are basically the same from the point of view of ev3dev. The only notable differences are:
- BrickPi+ can monitor battery voltage, BrickPi cannot.
- BrickPi has a 5th input port for I2C only, BrickPi+ does not.
BrickPi3, on the other hand, is significantly different.
Setup¶
Since the BrickPi(+) does not have an EEPROM to electronically identify it, some
manual configuration is required to enable it. This is done by editing the
config.txt
file in the boot partition:
# uncomment both if you are using BrickPi or BrickPi+
dtoverlay=brickpi
init_uart_clock=32000000
BrickPi+ additionally supports monitoring batter voltage, which must be enabled separately:
# uncomment only if you are using BrickPi+
dtparam=brickpi_battery=okay
Furthermore, if you are using a Raspberry Pi 3 Model 3, the built-in Bluetooth conflicts with the BrickPi(+), so there is more to configure:
# uncomment to disable Bluetooth on RPi 3
#dtoverlay=pi3-disable-bt
Power¶
BrickPi(+) is powered from 8 AA batteries (nominally 12V). Only the BrickPi+ is able to monitor the battery voltage (see Setup section above to enable).
It is possible to power the Raspberry Pi + BrickPi(+) via USB. However, the motors will not move because the motor controller chips are connected directly to the battery voltage.
Warning
When powering BrickPi+ from USB, it will shutdown because of low battery. See https://github.com/ev3dev/ev3dev/issues/989.
As a workaround, don’t enable dtparam=brickpi_battery=okay
.
More information is available in the hardware driver documentation.
Sensors and Input Ports¶
A major difference compared to LEGO MINDSTORMS EV3 is that the BrickPi(+) cannot automatically detect sensors. You must manually configure each input port to tell it what kind of sensor is attached.
Many LEGO MINDSTORMS sensors will work with BrickPi(+). There are some caveats though.
- A small number of NXT/I2C sensors require 9V (battery voltage) on input port pin 1 (e.g. the LEGO NXT Ultrasonic sensor and the Codatex RFID sensor). BrickPi(+) does not provide this voltage.
- Support for EV3/UART and EV3/Analog sensors is hard coded. As a result, only the LEGO brand EV3 sensors will work. 3rd party EV3 sensors, like the FatcatLAB sensors will not work. (This could be fixed in the BrickPi firmware).
- The EV3/UART sensor implementation in the BrickPi firmware is buggy. Your results may vary.
More information is available in the hardware driver documentation.
The BrickPi (not BrickPi+) has a 5th input port that can be used with I2C sensors. This port is connected to Raspberry Pi I2C pins.
Additional information about using port 5 is available in the hardware driver documentation.
Motors and Output Ports¶
A major difference compared to LEGO MINDSTORMS EV3 is that the BrickPi(+) cannot automatically detect motors. By default, each output port is configured for NXT motors.
Passive braking is not implemented in the BrickPi(+) firmware. (This is a seldom-used feature, most people use active braking).
Some other motor driver features may not be implemented or work the same as the LEGO MINDSTORMS EV3 motor drivers. Please check GitHub issues and open a new issue if you have questions.
More information is available in the hardware driver documentation
LEDs¶
BrickPi(+) has two LEDs that can be used for status indication.
Todo
Hardware driver documentation seems to be missing.
Sound¶
BrickPi(+) does not have any sound capabilities. However, the headphone jack
on the Raspberry Pi can be used for sound with an external speaker. The sound
driver is not enabled by default and must be turned on by editing config.txt
.
Display¶
BrickPi(+) does not have a display. However, it is possible to use the HDMI (or NTSC) connector on the Raspberry Pi to attach a display or to stack a small TFT display.
Buttons¶
BrickPi(+) does not have any buttons. You can use a USB or Bluetooth keyboard if needed. A USB numeric keypad with backspace is sufficient to navigate the Brickman user interface.
Bluetooth¶
BrickPi(+) does not have Bluetooth capabilities. The built-in Bluetooth on Raspberry Pi 3 Model B and Raspberry Pi Zero W can be used, but at reduced capacity. A USB Bluetooth dongle can be used if needed.
Wi-Fi¶
BrickPi(+) does not have Wi-Fi capabilities. The built-in Wi-Fi on Raspberry Pi 3 Model B and Raspberry Pi Zero W can be used. A USB Wi-Fi dongle can be used if needed.
More information on USB Wi-Fi dongles is available on the wiki.
Firmware¶
It is possible to upgrade the firmware on the BrickPi(+). However, it requires additional hardware, such as an Arduino UNO to do the flashing. Also, the documentation from Dexter Industries seems to have gone missing since they released the BrickPi 3. There is still some information available at https://github.com/DexterInd/BrickPi/tree/master/Firmware_BrickPi/.
Note
It is not clear in the Dexter Industries documentation, but firmware version 2.5 is for BrickPi+ only! It does not work on BrickPi. Likewise, older firmware versions are for BrickPi only and do not work on BrickPi+.
Dexter Industries BrickPi3¶
BrickPi3 is a LEGO MINDSTORMS compatible daughterboard for Raspberry Pi produced by Dexter Industries.
Setup¶
Since the BrickPi3 does not have an EEPROM to electronically identify it, some
manual configuration is required to enable it. This is done by editing the
config.txt
file in the boot partition:
# uncomment if you are using BrickPi3
dtoverlay=brickpi3
It is also possible to stack more than one BrickPi3 on one Raspberry Pi. In
order for this to work, the ID for each BrickPi3 needs to be configured in
config.txt
:
# uncomment only if you are stacking multiple BrickPi3s
# replace 0123... with actual id number of each BrickPi3
dtparam=id1=0123456789ABCDEF0123456789ABCDEF
dtparam=id2=0123456789ABCDEF0123456789ABCDEF
#dtparam=id3=0123456789ABCDEF0123456789ABCDEF
#dtparam=id4=0123456789ABCDEF0123456789ABCDEF
The ID can be found by first connecting each board individually and running ev3dev-sysinfo. Currently, ev3dev only supports stacking up to 4 BrickPi3s (although technically more is possible).
Tip
The ID configuration is not needed when using only one BrickPi3.
Power¶
BrickPi3 is powered from 8 AA batteries (nominally 12V).
It is possible to power the Raspberry Pi + BrickPi3 via USB. However, the motors will not move because the motor controller chips are connected directly to the battery voltage.
Warning
When powering BrickPi3 from USB, it will shutdown because of low battery. See https://github.com/ev3dev/ev3dev/issues/989.
We are working on a workaround.
More information is available in the hardware driver documentation.
Sensors and Input Ports¶
A major difference compared to LEGO MINDSTORMS EV3 is that the BrickPi3 cannot automatically detect sensors. You must manually configure each input port to tell it what kind of sensor is attached.
Many LEGO MINDSTORMS sensors will work with BrickPi3. There are some caveats though.
- A small number of NXT/I2C sensors require 9V (battery voltage) on input port pin 1 (e.g. the LEGO NXT Ultrasonic sensor and the Codatex RFID sensor). BrickPi3 does not provide this voltage.
- Support for EV3/UART and EV3/Analog sensors is hard coded. As a result, only the LEGO brand EV3 sensors will work. 3rd party EV3 sensors, like the FatcatLAB sensors will not work. (This could be fixed in the BrickPi3 firmware).
More information is available in the hardware driver documentation.
Motors and Output Ports¶
A major difference compared to LEGO MINDSTORMS EV3 is that the BrickPi3 cannot automatically detect motors. By default, each output port is configured for NXT motors.
Passive braking is not implemented in the BrickPi3 firmware. (This is a seldom-used feature, most people use active braking).
Some other motor driver features may not be implemented or work the same as the LEGO MINDSTORMS EV3 motor drivers. Please check GitHub issues and open a new issue if you have questions.
More information is available in the hardware driver documentation
LEDs¶
BrickPi3 has one LED that can be used for status indication.
More information is available in the hardware driver documentation
There is an additional LED for power indication. It is not user controllable.
Sound¶
BrickPi3 does not have any sound capabilities. However, the headphone jack
on the Raspberry Pi can be used for sound with an external speaker. The sound
driver is not enabled by default and must be turned on by editing config.txt
.
Display¶
BrickPi3 does not have a display. However, it is possible to use the HDMI (or NTSC) connector on the Raspberry Pi to attach a display.
Buttons¶
BrickPi3 does not have any buttons. You can use a USB or Bluetooth keyboard if needed. A USB numeric keypad with backspace is sufficient to navigate the Brickman user interface.
Bluetooth¶
BrickPi3 does not have Bluetooth capabilities. The built-in Bluetooth on Raspberry Pi 3 Model B and Raspberry Pi Zero W can be used. A USB Bluetooth dongle can be used if needed.
Wi-Fi¶
BrickPi3 does not have Wi-Fi capabilities. The built-in Wi-Fi on Raspberry Pi 3 Model B and Raspberry Pi Zero W can be used. A USB Wi-Fi dongle can be used if needed.
More information on USB Wi-Fi dongles is available on the wiki.
Firmware¶
The BrickPi3 firmware can be upgraded in place. Simply run the following command:
sudo update-brickpi3-fw
Mindsensors PiStorms¶
PiStorms is a LEGO MINDSTORMS compatible daughterboard for Raspberry Pi produced by mindsensors.com.
Setup¶
Since the PiStorms does not have an EEPROM to electronically identify it, some
manual configuration is required to enable it. This is done by editing the
config.txt
file in the boot partition:
# uncomment if you are using PiStorms
dtoverlay=pistorms
Power¶
PiStorms is powered from 6 AA batteries (nominally 9V). Powering via USB on the Raspberry Pi is not supported.
More information is available in the hardware driver documentation.
Sensors and Input Ports¶
A major difference compared to LEGO MINDSTORMS EV3 is that the PiStorms cannot automatically detect sensors. You must manually configure each input port to tell it what kind of sensor is attached.
Many LEGO MINDSTORMS sensors will work with PiStorms. There are some caveats though.
- Support for EV3/UART and EV3/Analog sensors is hard coded. As a result, only the LEGO brand EV3 sensors will work. 3rd party EV3 sensors, like the FatcatLAB sensors will not work. (This could be fixed in the PiStorms firmware).
More information is available in the hardware driver documentation.
Motors and Output Ports¶
A major difference compared to LEGO MINDSTORMS EV3 is that the PiStorms cannot automatically detect motors. By default, each output port is configured for NXT motors.
Some other motor driver features may not be implemented or work the same as the LEGO MINDSTORMS EV3 motor drivers. Please check GitHub issues and open a new issue if you have questions.
More information is available in the hardware driver documentation
LEDs¶
PiStorms has two RGB LEDs that can be used for status indication.
Warning
Some hardware revisions of the PiStorms only have one LED. Two LEDs will still be shown in ev3dev even though one is not physically present.
More information is available in the hardware driver documentation
Display¶
PiStorms has a 2.4” 320x240 pixel color display (16bpp) with a resistive touchscreen. The backlight is always on.
Warning
Touchscreen support is not yet implemented in the Brickman user interface. For the time being, you will need an external keyboard. A USB numeric keypad with backspace is sufficient to navigate the Brickman user interface.
Buttons¶
PiStorms has a single GO button that is mapped as the Enter button in ev3dev.
Sound¶
PiStorms does not have any sound capabilities. However, the headphone jack
on the Raspberry Pi can be used for sound with an external speaker. The sound
driver is not enabled by default and must be turned on by editing config.txt
.
Bluetooth¶
PiStorms does not have Bluetooth capabilities. The built-in Bluetooth on Raspberry Pi 3 Model B and Raspberry Pi Zero W can be used. A USB Bluetooth dongle can be used if needed.
Wi-Fi¶
PiStorms does not have Wi-Fi capabilities. The built-in Wi-Fi on Raspberry Pi 3 Model B and Raspberry Pi Zero W can be used. A USB Wi-Fi dongle can be used if needed.
More information on USB Wi-Fi dongles is available on the wiki.
Firmware¶
The PiStorms firmware is upgradeable. Currently, ev3dev does not have a package
to provide this functionality. Please see http://www.mindsensors.com/blog/how-to/how-to-upgrade-pistorms-firmware
for instructions. Be sure to disable PiStorms in config.txt
and reboot first
so that the hardware drivers are not trying to use the PiStorms at the same
time you are upgrading the firmware.
Tip
Instead of downloading the zip file to your computer and transferIng to your Raspberry Pi, you can download it directly on the Raspberry Pi from the command line. For example:
mkdir fwupgrader
cd fwupgrader
wget "http://www.mindsensors.com/index.php?controller=attachment&id_attachment=318" --content-disposition
unzip fwupgrader.zip
chmod +x fwupgrader
Warning
This information seems to be a bit out of date (it doesn’t mention PiStorms-V2). Please contact mindsensors.com if you have questions about upgrading the firmware.
Quest Institute QuestCape¶
QuestCape is a LEGO MINDSTORMS compatible daughterboard for BeagleBone produced by The Quest Institute to perform experiments on the International Space Station as part of their ISS program.
Note
The design is based on the FatcatLab EVB, so the hardware driver links on this page all point to the EVB docs.
Setup¶
Since the QuestCape does not have an EEPROM to electronically identify it, some
manual configuration is required to enable it. This is done by editing the
uEnv.txt
file in the boot partition:
# QuestCape
cape=quest
Power¶
QuestCape is powered from the 5V jack on the BeagleBone. The motors are powered separately via a connector on the QuestCape. There is no battery voltage indication (it is expected to be powered by a fixed power supply).
Motors can be powered from the 5V jack on the BeagleBone, but it is not recommended.
Sensors and Input Ports¶
The QuestCape input ports are basically the same as the input ports on LEGO MINDSTORMS EV3. There are some caveats though.
- It uses Molex connectors on the circuit board instead of the RJ11-style connectors used on the EV3.
- A small number of NXT/I2C sensors require 9V (battery voltage) on input port pin 1 (e.g. the LEGO NXT Ultrasonic sensor and the Codatex RFID sensor). EVB does not provide this voltage.
More information is available in the hardware driver documentation.
Motors and Output Ports¶
The output ports on the QuestCape are virtually identical to LEGO MINDSTORMS EV3. It uses Molex connectors on the circuit board instead of the RJ11-style connectors used on the EV3.
More information is available in the hardware driver documentation
Display¶
EVB has a 2.2” 220x176 pixel color display (16bpp). The backlight is adjustable.
The display board is separate from the main circuit board and can be detached.
Buttons¶
QuestCape has a small joystick for directional input (up, down, left, right) and center (enter) plus a separate button for back (backspace). Pressing more than one button at a time is not supported.
The joystick/button board is separate from the main circuit board and can be detached.
More information is available in the hardware driver documentation
Sound¶
QuestCape does not have a speaker.
LEDs¶
QuestCape does not have any user controllable LEDs.
There are LEDs for power indication (5V and battery voltage).
Bluetooth¶
EVB does not have Bluetooth capabilities. A USB Bluetooth dongle can be used if needed.
This table provides a detailed comparison of all of the supported platforms and their features.
Manufacturer | LEGO | Dexter Industries | mindsensors.com | FatcatLab | Quest Institute | |||
---|---|---|---|---|---|---|---|---|
Website | mindstorms.lego.com | dexterindustries.com | mindsensors.com | fatcatlab.com | questforspace.com | |||
Model Name | EV3 | BrickPi | BrickPi+ | BrickPi3 | PiStorms | EVB | QuestCape | |
Model Number(s) |
|
|
|
|
|
|
|
|
Compatible CPU Board | N/A |
|
||||||
Display | Resolution | 178x128 pixels [4] | N/A [6] [7] | N/A [6] | 320x240 pixels | 220x176 pixels | 220x176 pixels | |
Color Depth | 1 bpp [5] | 16 bpp | 16 bpp | 16 bpp | ||||
Backlight | No | Yes, always on | Yes, always on | Yes, adjustable | ||||
Touchscreen | No | Yes | No | No | ||||
Buttons | Count | 6 | 0 | 0 | 1 | 6 [8] | 6 [8] | |
Center | Yes | No | No | Yes | Yes | Yes | ||
Up | Yes | No | No | No | Yes | Yes | ||
Down | Yes | No | No | No | Yes | Yes | ||
Left | Yes | No | No | No | Yes | Yes | ||
Right | Yes | No | No | No | Yes | Yes | ||
Back | Yes | No | No | No | Yes | Yes | ||
LEDs | 2 - Red/Green | 2 - Blue | 1 - Yellow (Amber) | 2 [9] - Red/Green/Blue | None | None | ||
Speaker | Yes | No [10] | No [10] | No [10] | Yes | No | ||
Input Ports | Count | 4 | 4 + 1 I2C only | 4 | 4 + 1 Grove I2C | 4 | 4 | 4 |
Automatic Detection | Yes | No | No | No | Yes [11] | Yes | ||
EV3 Sensors | Yes | Yes [12] | Yes [13] | Yes [14] | Yes | Yes | ||
NXT Sensors | Yes | Yes [15] | Yes | Yes [16] | Yes | Yes | ||
Output Ports | Count | 4 | 4 | 4 | 4 | 4 | 4 | |
Automatic Detection | Yes | No | No | No | Yes | Yes | ||
Battery Indication | Voltage | Yes | No | Yes | Yes | Yes | Yes | No |
Current | Yes | No | No | No | No | Yes | No | |
Bluetooth [17] | 2.1 + EDR [18] | N/A [19] | N/A [19] | N/A [19] | N/A | N/A | ||
Wi-Fi [20] | N/A | N/A [21] | N/A [21] | N/A [21] | N/A | N/A |
[1] | The version number is not actually printed on the BrickPi circuit board. |
[2] | The Grove sensor ports are not usable with EVB or QuestCape because of shared I/O pins. |
[3] | BeagleBone Green Wireless is not supported because of I/O pin conflicts. |
[4] | It is possible to replace the display in the EV3. Video. The color screen is 160x128 pixels, 16 bpp, with adjustable backlight. |
[5] | The EV3 display is capable of 2bpp grayscale. We’re working on it. |
[6] | (1, 2) It is possible to attach an HDMI (or NTSC) display to the Raspberry Pi. |
[7] | It is possible to stack a display on top of BrickPi. Blog. |
[8] | (1, 2) EVB and QuestCape cannot detect simultaneous button presses. |
[9] | Some hardware revisions of the PiStorms only have 1 physical LED. However, 2 LEDs will still appear in sysfs. |
[10] | (1, 2, 3) The headphone jack on Raspberry Pi can be used for sound. Sound is not enabled by default. |
[11] | The EVB cannot automatically detect some NXT sensors. NXT sensors can still be used, but the input port must be manually configured for them. |
[12] | BrickPi(+) only supports the LEGO EV3 sensors (Color, Infrared, Ultrasonic, Gyro, Touch). 3rd party EV3 sensors will not work. The UART sensor implementation is buggy in the BrickPi(+) firmware. |
[13] | BrickPi3 only supports the LEGO EV3 sensors (Color, Infrared, Ultrasonic, Gyro, Touch). 3rd party EV3 sensors will not work. |
[14] | PiStorms only supports the LEGO EV3 sensors (Color, Infrared, Ultrasonic, Gyro, Touch). 3rd party EV3 sensors will not work. |
[15] | BrickPi(+) has limited I2C sensor support. Most sensors do work, but there may be some limitations. |
[16] | PiStorms shares a single I2C communication bus with all four input ports, so each sensor must have a unique I2C address. |
[17] | Bluetooth (include Bluetooth Low Energy) support can be added to any device via a USB Bluetooth dongle. |
[18] | Newer models of the EV3 technically have a Bluetooth 4.0 chip. However, the new chip does not have Bluetooth Low Energy (LE) capabilities. |
[19] | (1, 2, 3) Raspberry Pi 3 Model B and Raspberry Pi Zero W have built-in Bluetooth + LE (Low Energy). |
[20] | Wi-Fi support can be added to any device via a USB Wi-Fi dongle. |
[21] | (1, 2, 3) Raspberry Pi 3 Model B and Raspberry Pi Zero W have built-in Wi-Fi. |
Versions¶
ev3dev-buster is the current development version. It is currently in alpha, meaning that it may or may not actually be usable. Use this version if you like the cutting edge and making good bug reports.
ev3dev-stretch is the current stable version. It only receives important bug fixes and security updates. It is the recommended version for new users.
ev3dev-jessie is no longer supported.
Where to Start¶
For ev3dev-jessie, getting started instructions and additional documentation are on the main ev3dev.org website.
For ev3dev-stretch, pick the getting started guide based on your device.
Getting Started¶
By Platform¶
Getting Started with LEGO MINDSTORMS EV3¶
Hardware Requirements¶
You will need all of the following:
- LEGO MINDSTORMS EV3 intelligent brick
- MicroSDHC memory card [1]
- Windows, macOS or Linux computer with an Internet connection [2]
- SD card reader for your computer
[1] | Look for the SDHC logo on the card. Cards larger than 32GB are not supported and will likely have data corruption issues. Some users with 32GB cards have also reported data corruption issues. |
[2] | Administrative privileges are needed for installing software and flashing the microSD card. |
Communication Requirements¶
You will need one of the following to establish communication to the EV3:
- The USB cable that comes with the EV3
- A Bluetooth capable computer
- A USB Wi-Fi dongle attached to the EV3 [3]
[3] | A list of known working Wi-Fi dongles can be found on the wiki |
Installing Ev3dev¶
Ev3dev is distributed as a disk image that is flashed to your microSD card.
Download and install Etcher.
Download the latest ev3dev image for LEGO MINDSTORMS EV3 from the ev3dev downloads page.
Note
Follow the link on that page for ev3dev-stretch snapshot images.
Run Etcher and flash the image to the microSD card. Click here if you need detailed instructions on using Etcher.
Put the microSD card in the EV3 and turn it on.
Tip
Create a pull tab to make the microSD card easy to remove.
Establishing a Connection¶
USB
Simply connect the USB cable and you are good to go.
Bluetooth
Todo
Link to BrickMan docs on how to pair with Bluetooth.
Wi-Fi
Todo
Link to BrickMan docs on how to setup Wi-Fi.
Getting Started with Dexter Industries BrickPi¶
Hardware Requirements¶
You will need all of the following:
- Dexter Industries BrickPi, BrickPi+ or BrickPi3
- Raspberry Pi Model B, B+, 2 or 3
- A 12V power source [1]
- A compatible SD or MicroSD memory card [2]
- Windows, macOS or Linux computer with an Internet connection [3]
- SD card reader for your computer
[1] | The power source can be batteries or an AC/DC adapter. Powering via USB on the Raspberry Pi will work, but you will not be able to run any motors. |
[2] | Refer to Raspberry Pi SD Card FAQ |
[3] | Administrative privileges are needed for installing software and flashing the microSD card. |
Communication Requirements¶
Since the BrickPi does not have a display, we will be using the wired Ethernet connection to begin with. A Wi-Fi connection can be setup later.
Installing Ev3dev¶
Ev3dev is distributed as a disk image that is flashed to your microSD card.
Download and install Etcher.
Download the latest ev3dev image for Raspberry Pi from the ev3dev downloads page.
Note
Follow the link on that page for ev3dev-stretch snapshot images.
Run Etcher and flash the image to the microSD card. Click here if you need detailed instructions on using Etcher.
When the flashing is complete, open the
EV3DEV_BOOT
drive of the SD card on your computer.Tip
You may need to remove the SD card and plug it back in to the computer before you see the
EV3DEV_BOOT
drive.Open the
config.txt
file and follow the instructions. There are various lines that need to edited depending on which models of BrickPi and Raspberry Pi you have, so be sure to read carefully.Save the changes to
config.txt
and close the text editor.Safely eject the SD card from your computer.
Put the SD card in the Raspberry Pi and turn it on.
Tip
If all goes well, the two blue LEDs on the BrickPi or BrickPi+ should turn on. On BrickPi3, the single LED should stop blinking and be on solid.
Establishing a Connection¶
Wired Ethernet
Connect an Ethernet cable from your Raspberry Pi to your router or network switch.
Tip
The connection should be automatically configured. You can confirm this by running
ping ev3dev.local
in a terminal window on your computer.
Getting Started with FatcatLab EVB¶
Hardware Requirements¶
You will need all of the following:
- FatcatLab EVB
- BeagleBone Black or Green
- A 9V power source [1]
- MicroSDHC memory card [2] [3]
- Windows, macOS or Linux computer with an Internet connection [4]
- SD card reader for your computer
[1] | The power source can be batteries or an AC/DC adapter. |
[2] | Look for the SDHC logo on the card. Cards larger than 32GB are not supported and will likely have data corruption issues. Some users with 32GB cards have also reported data corruption issues. |
[3] | It is not possible to use the built-in eMMC on the BeagleBone because of pin conflicts with the EVB cape. |
[4] | Administrative privileges are needed for installing software and flashing the microSD card. |
Communication Requirements¶
You will need one of the following to establish communication to the EVB:
- A USB Wi-Fi dongle attached to the BeagleBone [5]
- An Ethernet cable
[5] | A list of known working Wi-Fi dongles can be found on the wiki |
Installing Ev3dev¶
Ev3dev is distributed as a disk image that is flashed to your microSD card.
Download and install Etcher.
Download the latest ev3dev image for BeagleBone from the ev3dev downloads page.
Note
Follow the link on that page for ev3dev-stretch snapshot images.
Run Etcher and flash the image to the microSD card. Click here if you need detailed instructions on using Etcher.
When the flashing is complete, open the
EV3DEV_BOOT
drive of the SD card on your computer.Tip
You may need to remove the microSD card and plug it back in to the computer before you see the
EV3DEV_BOOT
drive.Open the
uEnv.txt
file and follow the instructions. You will need to edit a line to enable the EVB cape:cape=evb
Save the changes to
uEnv.txt
and close the text editor.Safely eject the microSD card from your computer.
Put the microSD card in the BeagleBone and turn it on.
Tip
Create a pull tab to make the microSD card easy to remove.
Establishing a Connection¶
Wi-Fi
Todo
Link to BrickMan docs on how to setup Wi-Fi.
Wired Ethernet
Connect an Ethernet cable from your Raspberry Pi to your router or network switch.
Getting Started with Mindsensors PiStorms¶
Hardware Requirements¶
You will need all of the following:
- Mindsensors PiStorms-v2
- Raspberry Pi Model B, B+, 2 or 3
- A 9V power source [1]
- A compatible SD or MicroSD memory card [2]
- Windows, macOS or Linux computer with an Internet connection [3]
- SD card reader for your computer
[1] | The power source can be batteries or an AD/DC adapter. |
[2] | Refer to Raspberry Pi SD Card FAQ |
[3] | Administrative privileges are needed for installing software and flashing the microSD card. |
Communication Requirements¶
You will need one of the following to establish communication to the PiStorms:
- A USB Wi-Fi dongle attached to the Raspberry Pi [4]
- The built-in Wi-Fi on Raspberry Pi 3
- An Ethernet cable
[4] | A list of known working Wi-Fi dongles can be found on the wiki |
Installing Ev3dev¶
Ev3dev is distributed as a disk image that is flashed to your microSD card.
Download and install Etcher.
Download the latest ev3dev image for Raspberry Pi from the ev3dev downloads page.
Note
Follow the link on that page for ev3dev-stretch snapshot images.
Run Etcher and flash the image to the microSD card. Click here if you need detailed instructions on using Etcher.
When the flashing is complete, open the
EV3DEV_BOOT
drive of the SD card on your computer.Tip
You may need to remove the SD card and plug it back in to the computer before you see the
EV3DEV_BOOT
drive.Open the
config.txt
file and follow the instructions. There is a line that needs to be edited to enable PiStorms.Save the changes to
config.txt
and close the text editor.Safely eject the SD card from your computer.
Put the SD card in the Raspberry Pi and turn it on.
Establishing a Connection¶
Wi-Fi
Todo
Link to BrickMan docs on how to setup Wi-Fi.
Wired Ethernet
Connect an Ethernet cable from your Raspberry Pi to your router or network switch.
Additional Information¶
Using Etcher to Flash an SD Card¶
Todo
Make this page pretty with screenshots and stuff.
- If you have not already, download and install Etcher.
- Start Etcher.
- Open the ev3dev disk image that you downloaded.
Tip
You don’t need to unzip the image.
Plug the SD card into your computer. Etcher should automatically detect it.
Click the flash button. Etcher will tell you when it is done an it is safe to remove the SD card.
Tip
If Etcher tells you that the validation failed, you probably have a defective SD card and should try an different one.
Additional Documentation¶
General information on programming using ev3dev:
Programming¶
Fundamentals¶
The following information applies to all programming languages. These are the basic things you need to know to create and run programs on ev3dev.
File Permissions¶
Linux (and other Unix-like operating systems) have a special file permission setting to make a file executable. If this permission is not set, then you cannot run a file directly. Instead, you will get a “Permission denied” error when you try to run the file.
In the Brickman file browser, executable files have a *
after the file name.
If this *
is missing, you will not be able to run the file from Brickman.
Tip
The ev3dev Visual Studio Code extension automatically takes care of setting permissions for you, so you don’t need to do anything special in that case and you can skip reading this section.
If you are transferring files a different way, then you need to need to know how to set the executable bit.
Command Line¶
One way to set file permissions is to use a remote terminal to get command prompt on your device, then run:
chmod +x my.file
Of course, replace my.file
with the actual name of your file. This tells
the OS to change the mode of the file by setting the executable
bit globally for the file. This can be verified by running:
ls -l my.file
This tells the OS to list some basic information about this file. You should see something like this:
-rwxr-xr-x 1 robot robot 0 Oct 28 19:39 my.file
As you can see, x
is actually listed three times in the file permissions
(-rwxr-xr-x
). This is because each file has three sets of permissions, one
for the user (i.e. robot
), one for the group (also robot
)
and one for others (everyone).
In terms of ev3dev, the really important one is the first one, the user.
WinSCP¶
Todo
Add screenshots that show how to set file permissions using WinSCP.
Filezilla¶
Todo
Add screenshots that show how to set file permissions using Filezilla.
Scripts¶
A script is a text file that can be run as a program. There are many scripting languages available on ev3dev, such as Bash, Lua, Python and Perl. There are a few things you need to watch out for when writing scripts.
Although it is possible to run scripts by invoking the interpreter directly, such as:
python3 my_script.py
…we don’t usually do this in ev3dev. Instead, we do a few things to make the file work as a stand-alone executable file.
The Shebang¶
In Linux (and other Unix-like operating systems), there is a special syntax used in the first line of a file to tell the operating system which interpreter to use to run the file. It looks like this:
#!/usr/bin/env python3
When you run the script, the operating system runs /usr/bin/env python3
, which
finds python3
and then runs python3 $0
where $0
is the filename of
your script.
You can also just write the path to the interpreter directly instead of using
/usr/bin/env
, like this:
#!/bin/bash
Without a shebang, Linux will fall back to trying to run file as a shell script. So, if you forget this in your Python program, you will see strange errors about commands not found and whatnot.
Tip
Using /usr/bin/env
is considered best practice for Python, since it
is more flexible (e.g. when using virtualenv
, the Python interpreter in your
virtual environment may not be the same as the one at /usr/bin/python
).
Furthermore, according to PEP 394, if your script is Python 3.x only, you
should use python3
in your shebang. If your script is Python 2.x only,
you should use python2
. Using python
with no number after it should
only be used if your script was designed to run with both 2.x and 3.x.
Note
The name shebang comes from the characters #!
. In computer-speak,
#
is sometimes refered to as a sharp or a shell prompt and !
is often called bang.
Line Endings¶
Line endings are the hidden characters at the end of each line in a text file.
Windows and Linux use different line endings, which can cause problems. Windows
uses two character, a carriage return and a line feed (also written CRLF or
\r\n
). Linux only uses a single character, a line feed (also written LF
or \n
).
Most interpreters for scripts don’t care about line endings. But, Windows line
endings will break the magic shebang line we talked about above.
For example, Linux will try to run python3\r
instead of just python3
and
you will get a “File not found” error.
If your program runs when you type python3 my_file.py
but not when you type
./my_file.py
, this is probably why it is not working.
So, if you are using Windows, be sure to change the line endings in your text editor to Unix or CRLF when writing a script for ev3dev. On Linux and macOS, Unix line endings are the default, so you generally don’t have to worry about this.
Executable Bit¶
Linux will not let you run just any file directly. The last step needed to make the magic shebang work is to set the executable bit of the file. See the File Permissions section above for details.
Running Programs¶
Although you can just run a program from a terminal directly, like this:
./my_script.py
…you generally don’t want to do this. Why? Well, if your program crashes, for example, the motors won’t stop and your robot might try to destroy itself.
Instead, start your programs using the brickrun command. This takes care of
some tricky things in ev3dev/Linux, like console switching, and will clean up
after your program when it exits (or crashes). Just add brickrun
before
your program like this:
brickrun ./my_script.py
Note
Brickman and the Visual Studio Code extension both use brickrun
behind the scenes too, so using brickrun
from the command line will
ensure that your program runs the same no matter how your start it.
Todo
Add links to Brickman docs and Visual Studio Code extension docs about running programs.
Standard I/O¶
All computer programs have standard input and output streams commonly called
stdin
, stdout
and stderr
. Normally, these read from/write to the
terminal that started the program, but they can also be redirected from/to files
or other programs. When you run programs using ev3dev tools
these streams are handled in a special way.
stdin¶
If you run a program in a remote terminal, the usual behavior is for stdin
to read whatever is typed into the remote terminal while the program is running.
However, when programs are run with brickrun
, stdin
comes from the active
console on the remote device itself. This means you need to press the built-in
buttons on the device or use a keyboard attached to the device instead of typing
into the remote terminal where the program was launched.
The behavior is the same when the program is started without a remote terminal,
e.g. when the program is started from the Brickman user interface, stdin
will
still come from the device itself.
stdout¶
If you run a program in a remote terminal, the usual behavior is for stdout
to print to the remote terminal while the program is running.
However, when programs are run with brickrun
, stdout
prints to the active
console on the remote device itself. In other words, it prints to the screen on
the remote device.
The behavior is the same when the program is started without a remote terminal,
e.g. when the program is started from the Brickman user interface, stdin
will
still print to the screen on the device itself.
stderr¶
If you run a program in a remote terminal, the usual behavior is for stderr
to print to the remote terminal while the program is running (just like stdout
).
Likewise, when programs are run from a remote terminal with brickrun
,
stderr
will still print to the remote terminal instead of on the remote device
(unlike stdout
).
When running programs from the Brickman user interface, there is no remote terminal,
so stderr
is saved to a file with the same name as your program plus the file
extension .err.log
added to the end. You can read this file to see any errors
from your program. If nothing was printed to stderr
, this file will not be
created.
When using the Visual Studio Code extension, stderr
is printed in the OUTPUT
pane of Visual Studio Code.
Note
stderr
is a second output stream, like stdout
that is used for
error messages (at least in well-behaved programs). Most of the time, you
don’t notice the difference between the two because they both print to the
same place. But, they are designed so that you can redirect one but not the
other if needed.
Tip
You can print debug messages to stderr
to help troubleshoot your program.
Languages and Libraries¶
Todo
Migrate information from http://www.ev3dev.org/docs/programming-languages/
Development Environments¶
Visual Studio Code + the ev3dev browser extension is the officially supported programming environment for ev3dev. There are plenty of other programming tools out there, so if you want to use them instead, it is your choice (we won’t be able to provide as much help though).
Visual Studio Code¶
Todo
Detailed instructions on installing VS Code and the extension.
We have “hello world!” tutorials for several programming languages. Follow one of the links below for step-by-step instructions:
Open Roberta Lab¶
Open Roberta Lab is a web-based programming environment that is compatible with ev3dev. Currently, only LEGO MINDSTORMS EV3 is supported (it is an open-source project, so if you want to see other platforms added, you know what to do…).
Todo
A screenshot would be nice here.
On-Device Options¶
It is possible to write programs directly on ev3dev devices without any external tools needed. For example, ev3dev ships with two text editors, nano and vim.
Either use a remote SSH terminal or plug in a keyboard and press Alt+Ctrl+F6
to get a terminal on the device, then run nano my.file
to start editing a file.
The following are links to documentation for various ev3dev sub-projects:
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line