python-ev3dev 0.6.0.post132

Python language bindings for ev3dev

A Python3 library implementing an interface for ev3dev devices, letting you control motors, sensors, hardware buttons, LCD displays and more from Python code.

If you haven’t written code in Python before, you’ll need to learn the language before you can use this library.

Getting Started

This library runs on ev3dev. Before continuing, make sure that you have set up your EV3 or other ev3dev device as explained in the ev3dev Getting Started guide. Make sure that you have a kernel version that includes -10-ev3dev or higher (a larger number). You can check the kernel version by selecting “About” in Brickman and scrolling down to the “kernel version”. If you don’t have a compatible version, upgrade the kernel before continuing. Also note that if the ev3dev image you downloaded was created before September 2016, you probably don’t have the most recent version of this library installed: see Upgrading this Library to upgrade it.

Once you have booted ev3dev and connected to your EV3 (or Raspberry Pi / BeagleBone) via SSH, you should be ready to start using ev3dev with Python: this library is included out-of-the-box. If you want to go through some basic usage examples, check out the Usage Examples section to try out motors, sensors and LEDs. Then look at Writing Python Programs for Ev3dev to see how you can save your Python code to a file.

Make sure that you look at the User Resources section as well for links to documentation and larger examples.

Usage Examples

To run these minimal examples, run the Python3 interpreter from the terminal using the python3 command:

$ python3
Python 3.4.2 (default, Oct  8 2014, 14:47:30)
[GCC 4.9.1] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

The >>> characters are the default prompt for Python. In the examples below, we have removed these characters so it’s easier to cut and paste the code into your session.

Required: Import the library

import ev3dev.ev3 as ev3

Controlling the LEDs with a touch sensor

This code will turn the left LED red whenever the touch sensor is pressed, and back to green when it’s released. Plug a touch sensor into any sensor port and then paste in this code - you’ll need to hit Enter after pasting to complete the loop and start the program. Hit Ctrl-C to exit the loop.

ts = ev3.TouchSensor()
while True:
    ev3.Leds.set_color(ev3.Leds.LEFT, (ev3.Leds.GREEN, ev3.Leds.RED)[ts.value()])

Running a motor

Now plug a motor into the A port and paste this code into the Python prompt. This little program will run the motor at 500 ticks per second (around 0.4 rotations per second) for three seconds.

m = ev3.LargeMotor('outA')
m.run_timed(time_sp=3000, speed_sp=500)

Using text-to-speech

If you want to make your robot speak, you can use the Sound.speak method:

ev3.Sound.speak('Welcome to the E V 3 dev project!').wait()

To quit the Python REPL, just type exit() or press Ctrl-D .

Make sure to check out the User Resources section for more detailed information on these features and many others.

Writing Python Programs for Ev3dev

Every Python program should have a few basic parts. Use this template to get started:

#!/usr/bin/env python3
from ev3dev.ev3 import *

# TODO: Add code here

The first two lines should be included in every Python program you write for ev3dev. The first allows you to run this program from Brickman, while the second imports this library.

When saving Python files, it is best to use the .py extension, e.g. my-file.py.

User Resources

Library Documentation

Class documentation for this library can be found on our Read the Docs page . You can always go there to get information on how you can use this library’s functionality.

ev3dev.org

ev3dev.org is a great resource for finding guides and tutoials on using ev3dev.

Support

If you are having trouble using this library, please open an issue at our Issues tracker so that we can help you. When opening an issue, make sure to include as much information as possible about what you are trying to do and what you have tried. The issue template is in place to guide you through this process.

Demo Robot

Laurens Valk of robot-square has been kind enough to allow us to reference his excellent EXPLOR3R robot. Consider building the EXPLOR3R and running the demo programs referenced below to get familiar with what Python programs using this binding look like.

Demo Code

There are demo programs that you can run to get acquainted with this language binding. The programs are designed to work with the EXPLOR3R robot.

Upgrading this Library

You can upgrade this library from the command line as follows. Make sure to type the password (the default is maker) when prompted.

sudo apt-get update
sudo apt-get install python3-ev3dev

Developer Resources

Python Package Index

The Python language has a package repository where you can find libraries that others have written, including the latest version of this package.

The ev3dev Binding Specification

Like all of the language bindings for ev3dev supported hardware, the Python binding follows the minimal API that must be provided per this document.

The ev3dev-lang Project on GitHub

The source repository for the generic API and the scripts to automatically generate the binding. Only developers of the ev3dev-lang-python binding would normally need to access this information.

Python2.x and Python3.x Compatibility

The ev3dev distribution comes with both python2 and python3 installed but this library is compatible only with Python3.

Note that currently, the Python3 binding for ev3dev is not installed by default - this will be addressed in the next package we release.

Until then, you must follow the instructions at the top of this README to make sure that you have installed the newest version of the Python 3-based library.