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

• 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).

• 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

• 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).

• 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.

	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...	

• 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

>>> r.toSafeMode()

>>> r.toFullMode()

>>> r.start()

>>> r.close()

Basic commands at the interpreter

>>> 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

>>> 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