�
�
�
AppleScripting a Roomba with an Arduino

"Professionally, I had used AppleScript Studio to create a multi-station shop floor information system for one of my clients, but this project was purely for fun."

The intent of this project was to use AppleScript Studio to create a Mac OS 10.4 - 10.5 application that would allow me to send instructions to a Roomba Vacuum Cleaner Robot while I was away from home. The robot was fitted with bluetooth and a wireless security camera and would be able to drive around my home, take pictures and upload those pictures to a remote server. Besides the usual security pictures of doors and windows, I wanted to be able to check potential water leaks around my refrigerator, commodes, and washing machine. As a side benefit, I wanted to be able to drive the robot around while at home and develop simple multi-player games such as hide and seek, indoor road rally , and sponge ball hockey. The resources used are noted at the end of this page.

After the initial success of operating the Roomba with the hardware described on the previous page (view it ), a flaw surfaced. If the Roomba traveled out of bluetooth range, it just kept going. Not even the normal bumpers would stop it. Unless it got in a position where a wheel dropped, it would just keep spinning its wheels even if trapped against a wall. Another annoyance was the constant physical contact of the Roomba with walls and other obstacles. I really wanted it to "stay on track". I added a Arduino Duemilanove between the bluetooth receiver and Roomba to provide the functionality I wanted.
Hardware (revised 11/25/09).
The Roomba used for this version of project is still a Model 400. (Note 1)
In order to have some sort of recovery from the situation described above, I added an on board processor in the form of an Arduino Duemilanove. (Note 2) My initial thought was to just have it be a watchdog timer so that if it did not get a signal from the bluetooth device it would issue a stop command to the Roomba and then try to find a way back into signal range or perhaps even to the charging station. While this did stop the Roomba from running away, it did not solve the torturous attempts to get back into bluetooth range, reconnect and find it's way back to the charger.

To remedy this, I added color sensing hardware to sense the color of the floor the Roomba was traversing. By applying blue painter's masking tape to the floor I was able to keep the Roomba on track, and in range.

Other than the Arduino, there have been a few other hardware changes since the last version. The the camera, digitizer, and reference book have not changed from the original version. (Notes 3 - 6)

The Rooving NetworkFirefly was replaced by a blueSMirf. (Note 7)

I added voltage regulators to power the color sensor, blueSMirf and Arduino in addition to the existing camera supply. Serial communications were routed through a DIP switch to allow for programming of the Arduino through the USB port. There are small relays (one is visible in the image above below the DIP switches) to turn off power to the camera and sensors when not needed. I also added a manual switch to turn all power from the battery off. An additional small relay directs the serial signal out of the Arduino to either the Roomba or the blueSMirf .

The floor color sensor array consists of red, green and blue LEDs and a light level sensor (Note 8). The array faces down and one LED is turned on at a time. The amount of reflection of the lit LED is read by the light sensor and the Arduino sends the information back through the blueSMirf. I had to experiment with providing shrouds around the LEDs and sensor to provide the best color differentiation. After this picture was taken I added a small rubber gromet around the sensor also. Works very well now.

The floor color sensor array was initially placed on the underside, center, of the Roomba. The array is protected in this spot and does not interfere with the docking algorithm resident in the Roomba itself. The companion software for this placement utilized the "Turn, Go, Check, Back Up Cycle" software scheme described below to stay on a path of Blue Painters Masking Tape. While it works, there is much wasted motion with searching for the tape in this configuration.

The sensor array has now been mounted in a measuring cup attached to an arm that overhangs the rear of the Roomba. The software scheme was changed to travel in reverse while looking for the blue tape. The Roomba can still dock forward as it normally does, however, missed attempts result in the cup hitting the dock when the Roomba does a 180 to go around and retry. Further work needs to be done to get the array out of the way prior to docking attempts.

Software (revised 11/25/09).
This page will summarize controling the Roomba with Applescript via the Arduino and the operation of the color sensor to follow a path of blue painter's tape. For discussion of Connecting, Driving Roomba, External Scripts and Capturing Images, refer back to the original "Applescripting the Roomba" page (view it).

The Roomba Control application window is laid out in functional areas. The top row provides information about the bluetooth or other communication port used to send commands to the Roomba. The second row provides 'messages' about the action experienced from the command sent. Any errors are reported there also. The third row provides sensor reading from the Roomba. 'mA' is the reported current flow. Positive flow occurs in the charger, negative when driving around. The right framed area provides driving controls and alternately, the area for displaying the video feed. The left frame provides connecting and other non-movement functions.

Please note that in order to send and receive serial data in AppleScript, the application uses SerialPort X.osax (Note 9).

Arduino
In the pre-Arduino version, commands flowed
  1. from the Applescript Studio Roomba Control application
  2. out of the Macintosh, over bluetooth
  3. into the Roomba
  4. from the Roomba
  5. over bluetooth, back to the Roomba Control application

Inserting the Arduino into the flow, commands can tell the Roomba or the Arduino to do something.

Roomba only actions

  1. from the Applescript Studio Roomba Control application
  2. out of the Macintosh, over bluetooth
  3. into the Arduino
  4. from the Arduino
  5. into the Roomba
  6. from the Roomba directly over bluetooth, back to the application

Arduino only actions

  1. from the Applescript Studio Roomba Control application
  2. out of the Macintosh, over bluetooth
  3. into the Arduino
  4. from the Arduino over bluetooth, back to the application

Arduino initiated actions

  1. from the Arduino to the Roomba
  2. from the Roomba directly over bluetooth, back to the application

The Arduino never receives information from the Roomba. It does send commands to the Roomba and it does send informtion to the Roomba Control application on the Macintosh.

The Roomba Control application expects the Arduino to pass all instructions on to the Roomba unless the instruction sent is a special one. The special instruction, "99", is not one needed normaly by the Roomba, so the fact that the Arduino never passes it on is OK. The next instruction sent after a "99" is also kept by the Arduino and it tells the Arduino's internal program to carry out a Arduino specific routine, such as checking the color of the floor and returning the values to the Macintosh.

Color Sensing - Undercarriage Mounting
The color sensor signal is proportional to the amount of light that is reflected back off of the floor. Less red light is reflected from blue tape then from a white floor. The Arduino digitizes the sensor level and either sends that signal back to the Macintosh or sends a command to the Roomba depending upon what instruction it received initialy. The color well surrounding the Roomba image in the application window changes color to match the information received from the Arduino.

The instruction set to follow the blue tape is contained in an external script "8-FollowBlueTape.scpt" that resides in the RoombaScripts folder.

The intructions flow something like this
  1. If the battery current is positive, calibrate the sensor to the floor back out of the dock, trun right 135 degrees, go foward 200 mm, stop and play a ready to go tune. If not originaly in the dock, begin at step  #2.
  2. Go foward and tell the Arduino to continually check for too much Red being reflected. If too much Red, stop the Roomba, send information to the Macintosh and go on to step  #3.
  3. Figure out if we are on the floor by checking the amount of Blue reflected. If there is a high enough Blue level we are on the white floor, continue below at  #4. If not enough Blue, then we have arrived at the Red square. Play a victory tune and ask for permission to dock.
  4. Back up 100 mm and turn about 5 degrees in the same direction as the last time we were at this step. Go foward 100 mm. If there is still too much Red, back up 100 mm and turn 5 degrees more then the last turn in the other direction. As illustrated below, keep doing the "turn more in the opposite direction, go foward, check, back up" cycle until the amount of Red is low enough. (The 5th cycle illustrated) When it is, play a happy tune and go back to Step  #2 above.

For deviations from a straight path, correction is usally made in the first or second cycle. The more acute the angle of the tape, the more cycles it takes to find it again.The amount of space needed for these course corrections is only about 250 mm in total, so maneuvering down a hallway and then through a doorway is pretty easy. Nothing gets bumped into.

Color Sensing - Arm Mounted

The instructions for the arm mounted sensor was changed in two significant ways. First, the basic routine is now

  1. Starting with the sensor array poised over a red square of paper, energize the blue LED and get a base "Home" blue reflectance.
  2. Start spinning clockwise, light the red LED and get a temporary "Floor" red reflectance.
  3. Keep spinning with the red LED energized until the reflectance drops well below the "Floor" value over the blue painter's tape.
  4. Store the base "Tape" red reflectance.
  5. Stop spinning and start driving in reverse with the red LED energized.
  6. If the reflectance exceeds the base "Tape" red value -- stop.
  7. Energize the blue LED and if close enough to the "Home" blue value - rejoice! otherwise....
  8. Energize the red LED, alternately spin back and forth until the red reflectance drops to near the "Tape" value.
  9. Go to #5 and continue.
Just as important, the routine is now fully in the Arduino code except for starting the process. I can sever the bluetooth connection without stopping the Roomba from finishing it's mission.

You can see a video of the "Armed Roomba" performing here.

You can use you imagination to extend this to other color tapes and paper squares. One time the Roomba might follow the "Blue-line" of tape and next time the "Red-line" of tape to a different destination. A "Green" square might mean turn 180 degrees and go back.

How to request a copy and source code
I am offering to send the compiled application, source code, Arduino code, and external scripts to anyone who wants them. Just read the Privacy and Disclaimer policies, check the agreement box and fill in an email address. You can e-mail any questions to me at the address displayed at the top of the page. Please note that the Applescript Studio RoombaControl application will run, but the source code will not compile in Snow Leopard without some extra effort.

If you just want the latest Arduino Script for the Armed Sensor version, use the appropriate text field and button.

Operations Improvement Web Site Privacy Statement

My web site privacy policy is:

  • I consider "personal information" to be: your name or a unique identifier (such as an IP address), your e-mail address, your mailing address, your telephone number, and any financial information relating to you or your accounts that you may provide.
  • The only personal information requested to receive this software is your e-mail address.
  • I will not contact you after sending the software to you unless you initiate further communication.
  • I will not sell any personal information to third parties.
  • I may transfer personal information to a third party only in the following cases:
    1. I suspect that you are attempting to change or otherwise damage this web site, or you are using it in violation of Federal or local laws, and I decide to provide personal information to legal authorities or the service hosting your IP address.
    2. This information is subpoenaed by Congress or a court.
  • I do not use cookies.
  • Requests, questions, comments, and other communications that I receive generally are retained by me for a maximum of seven years.

Disclaimer

This Disclaimer only applies to the software associated with "RoombaControl" on OperationsImprovement.net

  1. Liability Disclaimer
    • This Software is provided to you free of charge, "as is," by Operations Improvement US, a sole proprietorship.
    • OperationsImprovement.net Web Site and all content within are provided on an "as is" and "as available" basis without any warranties of any kind, whether expressed or implied, including, but not limited to the implied warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall Operations Improvement US be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortuous action, arising out of or in connection with the use or performance of the free software provided.
    • Any material downloaded or otherwise obtained through this Web Site is done at your own risk and discretion and you will be solely responsible for any damage to yourself or your computer system or loss of data that results from the downloading or use of any such material.
    • Operations Improvement US shall not be liable for any damages or injury resulting from your access to, or inability to access, this Web Site, or from any virus, bugs, tampering, omission, interruption, deletion, defect, delay, computer line failure, or any other technical malfunction related to this Software.
  2. Support:
    • Operations Improvement US is under no obligation to provide support, service, corrections, or upgrades to this free software program.
    • Operations Improvement US assumes no responsibility for errors or omissions in the software or documentation available from this web site.
    • Operations Improvement US assumes no responsibility for non-delivery of the software.

I have read and agree to the privacy statement and software disclaimer above.
Send RoombaControl, source code, Arduino Script and external scripts to the following e-mail address

     

I have read and agree to the privacy statement and software disclaimer above.
Send Arduino Script for Arm Mounted Sensor Only to the following e-mail address

     

Notes
  1. iRobot still lists the 400 as the least expensive Vacuum Cleaning Robot they have. It was $130 at the end of June 2009. It is easy to modify and has most of the LEDs and other components contained in the expensive models.

    http://store.irobot.com/corp/index.jsp

  2. New! DEV-00666 Arduino USB Board

    http://www.sparkfun.com     Arduino MacOSX Guide

  3. This the best reference available for building the hardware components needed to connect a Roomba to your Macintosh. The book is very Macintosh oriented and the author does an excellent job of explaining how it all works.

    http://hackingroomba.com/

  4. This is an alternate reference for "Hacking Roomba" and provides a download link for sample codes from the book.

    http://www.wiley.com/WileyCDA/WileyTitle/productCd-0470072717.html

  5. For the wireless camera I chose a Mini-Air. The size, mounting bracket and 9V power requirement all fit perfectly for the project. The receiver sits next to my Mac and feeds directly in to my digitizer.

    http://www.smarthome.com/76001A/Mini-Air-Watch-Wireless-Color-Camera-Kit-Channel-1/p.aspx

  6. Digitizing is provided by a TubeStick and accompanying The Tube software. Very Mac / AppleScript friendly. The picture displayed in RoombaControl is saved every time a recording is started by The Tube. In addition, this software, in it's own window, provides a live motion Roomba View as it is being driven around.

    http://www.equinux.com/us/products/tubestick/index.html

  7. Revised! The new bluetooth module on the Roomba is a WRL-00158 Bluetooth® Modem - BlueSMiRF RP-SMA

    http://www.sparkfun.com

  8. Super Bright 10mm LEDs - Blue, Red, Green, TEMT6000 Ambient Light Sensor Board

    http://www.sparkfun.com

  9. SerialPort X.osax must be placed in a Folder named "Scripting Additions" in your "Library" folder. It is not provided by me in the source code folder. You can get a copy here.

    http://osaxen.com/files/serialportx1.0.html