iRobot's Create: Python API introduction

Part 1. Connecting to Create

Preliminaries

Be sure you have python.
Be sure you have pyserial, a python module allowing control over the serial port (It requires the additional Win32All module under Windows.)
Be sure you have a bluetooth device and software. This is sometimes tricky under Windows, where the setup varies by device.

Setting up your bluetooth connection

Windows PC:

This can very quite a bit, depending on the particular device and bluetooth software you have. For the workshop, we have a number of devices that you may use, in case you don't have one.
Fundamentally, however, you will want to discover the RooTooth device (or ElementDirect's BAM! Bluetooth Adapter Module device). Then, set up a serial port connection to it. Some bluetooth software lists the serial port number created; it is often a good idea to check the COM port number in the control panel, under hardware devices - COM ports, as well.
The pairing passkey/password for the Rootooth devices is default. For the ElementDirect BAM modules, it is 0000 (four zeros).

Mac:

Start at the bluetooth icon
Choose "set up a bluetooth device..."
Select any device from the list
Wait until the bluetooth radio on the Roomba is discovered.
click Continue - it will gather service information
click Continue - it will ask for a passkey
- Connecting to the RooTooth: the pairing password is default
- Connecting to the BAM!: the pairing password is 0000 (four zeros)
click Continue - it will make the connection
It will say "there are no supported services on your device" in small red letters, but it is still connected...
click Continue and then Quit

Check your serial port

Windows PC:

You should be able to find this either in the configuration settings for your bluetooth software or within the control panel under "Hardware Devices" - "COM ports." For the PC, all you will need is the port number from the control panel, e.g., on mine it is 19 (COM19).

Mac/Linux:

You can look up the serial port name under the Bluetooth preferences panel or simply run ls /dev/tty.* to see the possible ports. Mine was /dev/tty.RooTooth-COM0-1. The serial port name will be that whole string, including the /dev/tty. at the beginning.

Start a terminal window and get connected!

The terminal line is the standard method to start python. If you're a fan of IDLE, a popular IDE for python, it should work. As an aside, in the CS 1 course at Harvey Mudd College, we believe that knowing how to use the command line -- whether on a Mac, Linux box, or in Windows -- is an important skill, and so we do our development there. In addition, IDLE does not work well for complex code, e.g., code involving multiple threads and some graphics.
Be sure you're in the directory with the pyCreate files, e.g., create.py
start python by typing python at the prompt (it will have to be in your path).
Type at the python prompt

>>> import create
Then run something similar to

r = create.Create('/dev/tty.RooTooth-COM0-1')

for the Mac, or

r = create.Create(19)

for the PC, replacing these serial port names with the appropriate ones for your machine.

If successful, the robot should report something to the effect of

	PORT is /dev/tty.RooTooth-COM0-1 (or your port name)
	Serial port did open, presumably to a roomba...
	Putting the robot into safe mode...

This "mode" is one of four internal states that the robot can be in. They are

off: when turned off
passive: when first turned on or running a demo
safe: under user control, but will stop if any safety alert is set off, e.g., a cliff sensor, wheel-drop sensor, or charging-safety sensor is triggered
full: under user control, and you can drive it off a cliff

You can read the current mode along with other sensors, as described a bit below. Note that you can change to safe mode via

>>> r.toSafeMode()

and to full mode via

>>> r.toFullMode()

You can even change to passive mode by running a demo or by running

>>> r.start()

So, if you are connected to the robot in safe mode and pick it up, remember that it will send you back to passive mode.

Turning off!

To shut down the connection to the robot cleanly, you should run

>>> r.close()

if the connections gets lost less cleanly, you may need to power-cycle the robot. In really bad cases, you may need to remove and reinsert the battery of the robot.

Basic commands at the interpreter

If you've never used python before, here are some simple examples to get you started.


>>> import math             # loads in the math module to the interpreter
>>> dir(math)               # you'll see the contents of the math module
>>> help(math.degrees)      # you'll see what math.degrees does
>>> math.degrees(math.e)    # should be about 155 or so

There are built-in lists and dictionaries:


>>> L = [42,43,44]          # a list (square braces)
>>> L[0]                    # should be 42
>>> D = { 'red': 42, 'green': 43 }  # a dictionary (curly braces)
>>> D['red']                # should also be 42

and much more that's probably better picked up on the fly.

Check out the tutorial at http://docs.python.org/tut/tut.html
The library reference is at http://docs.python.org/lib/lib.html

but dir and help go a long way, as well.