Using Your Roomba Frequently Asked Questions

The iRobot Create is a programmable version of the Roomba robot vacuum cleaner. Users can use their personal computers to send numeric signals to control the robot. In EF230 you'll be programming the robot with MATLAB. A toolbox was developed in MATLAB to provide students a straightforward interface for manipulating the robot. In addition, a MATLAB simulator was developed to visualize the movements of the robot. The simulator will run any of the programs developed in the MATLAB toolbox. (see References below)

Robot Features- We will be using the following features:

Wi-Fi Control and Live Camera Feed - achieved through an integrated Raspberry Pi and camera on a 3D printed mount.
Robot outputs
- Movement – the Roomba can move in straight or circular paths, at specified velocities and angular velocities
- Sounds - piezo beeper with ability to play musical notes
- LED 4 digit display and dedicated LEDs
- Status variables including distance traveled, angle turned, battery level, etc.
Sensors
- Bump sensors – sensors that are depressed when a solid object is hit
- Cliff sensors on the underside of the bumper - have ability to read reflectivity (can distinguish contrast). Can identify black tape on a white surface for line following.
- IR "Light Bump" sensors - these sensors will allow you to determine a distance away from an obstacle.
- There are also commands to receive IR commands from a remote, and to allow you to determine where beacons and virtual walls are. If you wish to use these commands look in the roomba toolbox documentation.

Answers to common questions will be archived here. The discussion board is also a resource for information of this type.

We are having difficulty communicating with the Roomba robot.

Try the following troubleshooting methods:

Make sure you added your toolbox directories to your path. (right click - add to path - add folders and subfolders)
Hard reset the Roomba (press spot and dock buttons simultaneously for 10 seconds and then release) before and after you use Roomba every time, and when you are having difficulty connecting. Reconnect.
Check your wireless connection on your computer, deactivate and reactivate it. Connect to the Roomba wireless network: EFD Roomba Linksys with the password ef230bot.
If you are connecting wirelessly to a robot with a video feed, check the robot's video feed to see if it is active.
Ask your TA to request that everyone in the room not connected to a robot use UT Open or eduroam for their phone and laptop wi-fi. Wi-fi still sluggish and intermittent? Turning off ALL non-roomba wi-fi (phones and laptops off or wi-fi disabled) will improve the the signal.
Try closing and restarting MATLAB.
Try restarting your computer.
If you are getting an error that the tcpip function was not found and have not previously connected to the robot with your computer, you did not install all of the toolboxes when you installed MATLAB. Try installing the Instrument Control Toolbox.
Try tethered - instructions below. There are a limited number of cables due to the fragility of the pins. Please be careful when using the cables. This is a good option if you have access to a roomba at home that you want to experiment with.

Video Overview of past Roomba Projects

How do I connect

Laptop Use:

Each team is expected to have at least one laptop to be utilized for communicating with the robot for testing and for the project presentations. You will need a laptop for every project work day. You will need to download and install a local copy of MATLAB on each laptop you plan to use (instructions here).

Obtaining the toolboxes:

These m-files were developed in order for your control computer to communicate with the robots. These toolboxes contain the files that tell the robot to read its sensors and drive its wheels. A simulator is included for you to test your code when not connected to the hardware.

Open MATLAB and create a new project folder (in Documents/MATLAB) to keep all of your project files in
Download (right click on link, save as) and then unzip (right click on zip folder - Extract All) this folder containing the roomba files:
roomba toolbox zip folder
All the files should now be shown in your new folder in the current folder window.

DO NOT modify the roomba.m file or create another m-file called roomba. Create a new file for your work and name it something else.

Connect to your bot:

Connect your laptop to the wireless network 'EFD Roomba Linksys' the password is ef230bot.
Take your robot off its charger, using the handle to transport it. Carefully plug in the micro usb to the bottom port of your Raspberry Pi.
Hard reset the Roomba with the 2 finger salute - press spot and dock buttons simultaneously for 10 seconds until the light dims and then release. You should hear a short scale play after you release the buttons. Don't skip this step! Hard reset each time every time before and after you use the robot.
The clean button should be lit up with a solid green color, if not Press the clean button once.
Connect to the bot. We will be using object oriented programming for roombas. The file roomba.m is called a class, it defines an object and contains code with data and operations that can be performed on that data. You will create an object of the class roomba and store it as a variable. You can use any variable name you want, for these examples we will use 'r'. Use a bot name of the form 'xx', where xx is the robot's number.
Ex: To create an object r for communcating with robot 10, in the command window type:
```
r=roomba(10)
```
Now you can call methods (which are just like functions) by using the object variable and a dot before the method name:
Ex: To turn your bot 90 degrees at a speed of .2 m/s, in the command window type:
```
r.turnAngle(90)
```

Notes:

If you you get an error regarding the path or undefined functions, if you did not put your project folder in your Documents/MATLAB folder, in your current folder window navigate to the folder where you have the roomba toolbox stored, right click on them, and add them to your path. right click on your project folder containing your toolbox and select 'Add to Path' 'Selected Folders and Subfolders' to add that path to the list of directories where MATLAB looks for files. Hint: If you use the Set Path icon and add your path to the top, you can add the path permanently so you don't have to do this every time.
If everything is working you should hear the first few notes of Rocky Top and the LED on the robot will show the percentage of battery remaining.
When you reprogram the robot, the built in commands for it to turn away when the bump or cliff sensors reach a threshhold will no longer be active, so the robot will attempt to continue to follow whatever path you have programmed regardless of obstacles in its path. If your robot ever starts to escape or crash . . .
- Pick it up off its wheels by its handle and perform the hard reset with the 2 finger salute - press spot and dock buttons simultaneously for 10 seconds until the light dims and then release. If you hard reset, you will need to reconnect to the robot, i.e. r=roomba(xx)
- Or, quickly use ctrl-c to exit any currently running programs and use the command r.stop to stop the bot
When you are done using a robot...
- Hard reset the Roomba (press spot and dock buttons simultaneously for 10 seconds and then release)
- Make sure the Roomba is plugged in and charging

How do I see the Documentation?

Documentation for all the commands is within the file, and can be accessed with the command

doc roomba

and then clicking on the methods link.

This shows all of the commands. Look for a command. If you need help understanding a function you should look at code of the function.

What is the input to the function? The functions need to know what robot you want to send the command to. So once you initialize and store the object variable r, you must call the toolbox functions with that input variable r
What is the output of the function?
- Is there no output?
- Is the output a structure?
- Is the output a variable or a list of variables?

When you call the function, if you want to save the output, you must save it as a variable or multiple variables based on the correct syntax shown on the first line of the function header.

When you collect sensor data, remember it is for one moment in time. To continuously read data you need to read the sensor within a loop.

Info about Roomba Wi-fi Networking

All of the roombas connect to the local wifi EFD Roomba. The router is configured to assign each pi the correct IP address. (bot 1 gets address 192.168.1.201)
Students should connect their computer to EFD Roomba Linksys (password is ef230bot)
The roombas have 2 programs running. The first program is a controller program that sets up the connection type (bluetooth or WIFI) The second is a relay program that relays commands to/from Bluetooth or Wifi and the robot serial connection.

My robot battery is dead

If you have the robot type with plug-in charging, we have spare chargers you can put on an extension cord and run your robot "with a leash". However, it won't work if completely dead. Please work early (well ahead of deadline), and carefully charge your bot after each use so this doesn't happen. You may also use another bot - iff it is not during an EF230 class and it is not on a project fair day. (no bot use the morning before presentations)

References for Roomba Toolbox

Download and review the following references (see FAQ below). Note that some features have changed since the documentation was developed.

Toolbox instructions from the toolbox creator, Joel Esposito of the United States Naval Academy. Reference: Toolbox Resource website
Simulator documentation from the simulator creators, Cameron Salzberger, K-Y Daisy Fan and Hadas Kress-Gazit of Cornell University. Reference: Simulator Website
The Create2 API Manual

Running Toolbox Commands

View the documentation listing and explaining all the built-in methods (robot functions and commmands)
```
doc roomba
```
Try running these from the command window. To call roomba methods, always use the object variable (in this case, r) and a dot before the method name.
```
r.moveDistance(0.3, 0.2)
r.turnAngle(90)
r.setDriveVelocity(0.3,0.2)  and soon after r.stop
r.setDriveVelocityRadius(0.2,0)  and soon after r.stop
```
TRY THIS
On the command line type in the command
```
r.testSensors
```
Look at the initial values of the sensors. Alternately hold down and let go of the right front bumper. Notice what happens to the value of BumpRight. Try the left side, and watch BumpLeft. Try it again, this time monitoring LightBumpRightSignal and LightBumptFrontRightSignal. What is the difference between LightBumpRightSignal and BumpRight? Put the robot on a light colored surface. Note the value of the Cliff Signals. Now put the robot on a dark surface. These sensors are measuring the reflectivity of the surface.

How do I use the camera?

To get image data from your bot's camera, use this command.

img = r.getImage; imshow(img);

Alternately, when you first connect to your bot, you'll see the url for your robot's camera

% e.g. img=imread('http://efdroombaserver.engr.utk.edu:8001/cam_pic.php')

How do I compare mean RGB camera data?

One simple image processing ability is to determine if the image is mostly red, mostly green, or mostly blue. To get started, park your robot pointing toward a large red piece of paper. Retrieve the camera image to see what the camera is seeing.

	img=r.getImage; % reads the camera off of the robot
	image(img) % shows the image in a figure window

Move your paper close enough so that the color fills the entire field of view of the camera. Check average RGB values to compare a readings from a large red piece of paper to a large green piece of paper. Compare these to when the camera is pointing at the white wall. Realize that these values may change substantially based on the time of day due to the lighting in the room and based on the particular robot and camera. You may need to recalibrate your programs for the daily conditions.
You can run a program like this to see realtime RGB values. Remember, you need to run it in a loop if you want continuous feed.

function imagecalibrate(r)
    while true %start infinite loop for calibrating
	  img=r.getImage; % reads the camera off of the robot
	  image(img) % shows the image in a figure window
      red_mean = mean(mean(img(:,:,1)))% reads the mean amount of red pixels
      green_mean = mean(mean(img(:,:,2)))% reads the mean amount of green pixels
      blue_mean = mean(mean(img(:,:,3)))% reads the mean amount of blue pixels
    end
end

Once you are able to differentiate betweeen red and blue, you can to develop a program to produce some output based on the color it sees. The image processing toolbox has many other capabilities you may want to explore, such as focusing on a circular object within the field of view and ignoring the background colors.

Roomba Simulator

To run the Simulator for the iRobot Create, create an object of class roombaSim with the following command.

  r=roomba(0)

This will bring up the GUI window for the simulator, and initialize a roombaSim object to hold simulation data and perform the required functions. Use the commands and run your functions and scripts as you would for the robot.

How do I play a song?

Use the function songPlay. Look up the command on the documentation.

How do I do line following?

First, read throught the requirements found above under the topic Deliverables. To complete this task you will need to read the robot's cliff sensors within a loop. The cliff sensors helps prevent the roomba from tumbling down stairs, by reading the reflectivity of the ground. If there is no ground under the sensor, the amount of signal reflected back will be very low (usually 0%). If there is a black or dark surface under the sensor, reflectivity tends to be low (around 3%), and a lighter surface tends to reflect more (up to about 20%). Careful - the getCliffSensors toolbox function will return an absolutely reflectivity reading, whereas in testSensors the reading is shown as a percentage. If you are working in the simulator, load the Figure 8 Map from the righthand menu link in the simulator. Dashed lines in the map files represent taped lines. If you are working with the robots, use the line following test setup. One approach could be to set a reflectivity datum where black or dark surfaces reflect less than the datum, lighter surfaces reflect more. After initializing your robot, Put the robot's front right cliff sensor on the black line. Run the function S=r.getCliffSensors. Check the reading S.rightFront (This reading is for one moment in time, if you want to show continuous readings you need to put the command in a loop) Now put the sensor on the white. Run the command again.
Using those readings, you can try a program like this:

function Fig8(r)
  v=.2;      % sets forward velocity in m/s
  reflect_datum=??;   % from above test determine a good value for reflect_datum
   r.setDriveVelocity(v,v)     % go straight forward
  while true % nonterminating function
     S=r.getCliffSensors
     if  S.leftFront < reflect_datum;
      % do this correction i.e use r.setDriveVelocity(v1,v)
      % to specify velocity of left and right wheels OR
      % add ccw or cw angular velocity with r.SetDriveVelocityRadius
    % write more conditionals using the other Cliff sensors
    elseif ...
      % do this
    else
       r.setDriveVelocity(v,v)     % go straight forward
    end
  end  % end of while statement
end % end of function

Test your program on different robots to see if you need to make adjustments to your code. You may need to adjust the reflectivity datum based on time of day and the robot number.

How do I use the roomba's WIfiOSMO module?

go to this link

Can I use the MATLAB/iRobot toolboxes and programs from the internet?

For this class, these instructions relate only to the custom toolboxes and programs developed by EF Professor Will Schleter, although based off of the original Esposito Toolbox, they can not be used interchangeably. Prof Schleter added user-friendly functionality, wi-fi, image acquisition, and compatibility with the latest bots.

How do I write my own Google Home Action?

Link to Writing your own Google Home Action

How do I ....

The goal of the project is for you to determine how to perform tasks on your own.

We need ideas to build from.

Assume your code starts with the robot travelling at a constant speed. Your code could include a loop that stated that while time is less than 500,

If Left Bump sensor is hit - stop robot, increment LED display by one, turn 90 deg clockwise, and go forward
If camera detects a red ball - go forward. If red ball moves to right side of the field of view - go slightly right. If ball image becomes small - speed up
If robot comes close to a wall (read light bump sensors) - stop robot and play Rocky Top.
If cliff sensor sees a black line - stop robot, turn 180 degrees and go forward at high velocity

Tethered Drive

Without a pi, you can program any irobot (at home, etc) using tethered drive.

Connect your robot to your laptop using the "tethered drive cable" found in the container next to the robot storage. (Don’t rip the cable out of the raspberry pi).
Identify the serial port on your laptop. Method 1 - use the command
```
fopen(serial('nada'))
```
to help identify the available serial ports. On a PC you may get an error like this
Error using serial/fopen (line 72)
Open failed: Port: NADA is not available. Available ports: COM3.
The error message indicates the name of your available serial port. From this error message we know that the available serial port is 3. If no port is listed in the error message, than try method 2.
Method 2 On PCs, another way to detect a port is to open your Device Manager and expand the Ports (COM & LPT) list. Note the number on the USB Serial Port. e.g. 'USB Serial Port(COM*)' The port number is the * here.
Method 2 On MACs, another way to detect a port is to type on the MATLAB command line or MAC Terminal: 'ls /dev/*'
Note the port number listed for devtty.usbmodem* or devtty.usbserial* The port number is the * here.
If you don't have any available serial ports you will need to install the FTDI drivers, use this link install the drivers. Than use method 1 or method 2 above to identify the port.

Once you have identified the serial port associated with the cable, use the appropriate command below in the command window to connect to the robot.

r=RoombaInit(3) % Windows - connect to serial port COM3
r=RoombaInit('/dev/tty.usbserial-DA017Y9X') % Mac

References

Based off of the original toolbox by J Esposito
Esposito, Joel M., Barton, Owen, Koehler, Joshua, Lim, David, "Matlab Toolbox for the Create Robot", www.usna.edu/Users/weapsys/esposito/roomba.matlab/, Copyright 2008-2011
Esposito documentation: Matlab_Toolbox_iRobot_create_doc.pdf
Create handbook: create_2_Open_Interface_Spec.pdf