Learn EV3 Python‎ > ‎

Basics

Once again, let me stress that this site is not intended to teach you basic Python programming. There are hundreds of free courses to help you learn about standard Python and some are listed on the Learn Python page. This site exists to help people who already have a basic knowledge of standard Python to make the extra step of learning how to use the robotic functions that EV3 Python makes available.

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. I strongly recommend that you choose option 1 on that page: re-flash your SD card. However, be aware that you will lose any files that were stored in your ev3dev installation, including code and installed programs.

Start the Python 3 interpreter from the command line
If your PC is communicating with the EV3 via SSH (Secure SHell) then you can start up the Python 3 interpreter by typing python3 at the command line prompt. Then, when you see the Python prompt '>>>' you can run Python commands one by one. To exit the Python 3 interpreter type Ctrl+D.

Launch Python programs from the command line
To run a program called myprogram.py in the current folder in Python 3 (the only version used on this site) type python3 myprogram.py at the command line prompt. If you need to force a program to stop from the command line then type Ctrl+C. Note that sometimes motors will continue to turn even after your program has stopped - I keep a special program 'stop_motors.py' ready to run in such cases - see the Using Motors page. If your script writes to the EV3's LCD screen you need to run an additional command sudo chvt 6 before you run your Python script. This stops Brickman from fighting with your script for control of the LCD screen. Once your program has terminated, type sudo chvt 1 to give control of the LCD back to Brickman. See the bottom of the LCD screen page for more on this.

Stopping a program that was launched from the command line

Most programs will of course stop by themselves. If you launched a program that does not stop by itself, perhaps because you deliberately included an infinite loop, for example, or because something went wrong, force the program to stop with Ctrl-C.

Launch Python programs from the Brickman menu
Before you can launch a Python program from the Brickman interface on the brick you must do two things (once per Python program):
  • Make the program file executable
  • Include a special instruction called a 'shebang' as the first line of your program
Note that neither of these steps is necessary if you only ever want to launch your program from the command line, but it is a good idea to do both steps for each file anyway in case you (or someone else) later wants to run the program from the Brickman interface. To make a program file called myprogram.py in the current folder into an executable file type this at the command line prompt:
chmod +x myprogram.py
chmod is the Linux 'change mode' command, and +x is an option or 'switch' that changes the mode to make the program file executable.

You also need to include a special instruction called a 'shebang' as the first line of your program (it MUST be the first line in order to work). The shebang tells the compiler what program to use to open the program file. Since all the programs on this site are written in Python 3 (and you should do the same since Python 2 is obsolescent), we need the shebang for Python 3 which is this:  #!/usr/bin/env python3

I have included that shebang as the first line in every program on this site. Since the line begins with a hash character you could assume that this is simply a comment that will be ignored by the compiler when the program is run. This would be a false assumption because in fact lines beginning with #! are actually special instructions called 'shebangs' that DO effect how the program runs since they tell the compiler which program to use to open the file. You may also come across programs beginning with #!/usr/bin/python which is an instruction to use Python 2 to open the program but you should favour Python 3 since Python 2 is now obsolescent. All the Python programs on this site are written in Python 3 and use the Python 3 shebang.
A shebang is comparable to a file association in Windows. In Windows you can use 'Open with...' to specify that all files with a certain file extension are to be opened within a certain program. For example, you could specify that programs with the .txt extension are to be opened in MS Word. Shebangs have a similar effect as a file association but the shebang must be included in every file that is to be opened by a certain program.

Stopping a program that was launched from Brickman

Most programs will of course stop by themselves. If you launched a program that does not stop by itself, perhaps because you deliberately included an infinite loop, for example, or because something went wrong, force the program to stop by long-pressing the Back button.

ev3 or auto? As you come across EV3 Python programs on the internet, you will notice that some of them start with import ev3dev.ev3 as ev3 and others start with from ev3dev.auto import * 

Both these statements have similar aims: to make the robotic functions contained in the ev3dev.ev3 library available for use in your script. The difference between auto and ev3 (in bold above) is that ev3 works only on the ev3 whereas auto SHOULD automatically detect whether the code is running on the ev3 or on BrickPi (an interface that allows the Raspberry Pi to work with EV3 hardware) and automatically use the correct library. Therefore it's tempting to recommend that you always use auto rather than ev3 so that there is a good chance that your code will be compatible with the BrickPi as well as the ev3. HOWEVER David Lechner, a top contributor to the ev3dev project, says (as of September 2016) that 'auto' is actually broken and only works for EV3 and BrickPi on Raspberry Pi model 1. It will not work on any other combination of devices. Also, using auto means that autocomplete will not work in PyCharm, the Python IDE that I recommend, so until auto is fixed (if ever) I have to recommend that you use ev3 rather than auto. Users of non-EV3 hardware (PiStorms, BrickPi, EVB) will have to change the import line or else the program won't work. BrickPI users will use
from ev3dev.brickpi import *

Top ev3dev contributor Denis Demidov adds that other users (PiStorms, EVB...) will be restricted to core (universal) functionality and should use  
from ev3dev.core import * 

Another difference between the forms import ev3dev.ev3 as ev3
and from ev3dev.auto import * it that one statement uses the form import ???? as ???? while the other uses from ????? import *. In this site, aimed at beginners, I use and recommend the form from ????? import * since it allows one to write shorter, more legible code. For example, it allows you to write ts=TouchSensor() instead of having to write ts=ev3.TouchSensor(). Expert coders working on complex programs would often prefer the other form, for reasons that I will not explain here. To summarise, I recommend that you use the statement from ev3dev.ev3 import * in your programs, just as I always do on this site.
Comments