Hacking Roomba

(originally from pcmag, and the formatting got mostly lost in the transcoding)

Hacking Roomba

By Tod E. Kurt, excerpt from the book Hacking Roomba (Wiley Publishing, ExtremeTech)

iRobot has produced a dizzying array of Roomba devices since the original version was introduced in 2002. They now even have the Scooba, a robot that not only vacuums but also washes floors. The good news is that the Roomba is a robotic vacuum cleaner that’s hackable by design.

If you’re already familiar with Roomba, you know it’s compatible with the ROI interface. That’s what enables the hacks you’ll find here. There is some confusion as to which Roombas are easily hackable via ROI. This is complicated by the fact that iRobot doesn’t make obvious the model numbers and firmware versions of the different Roombas. All currently for sale new Roombas currently have the ROI protocol built-in and ready to use. These are “third generation” Roombas. The two most common models, the Roomba Discovery and the Roomba Red will be used in the examples here. In addition to the material here, you’ll find a RoombaCommTest program at http://www.roombahacking.com/, which will help you try out some sample hacks.

About the Roomba Open Interface

The ROI appears to originally have been a diagnostic port used by iRobot to test the Roomba before shipment and as a way to release firmware upgrades if bugs were ever discovered. The ROI protocol is fairly simple but is complicated by a few factors that make using it not totally trivial. At the most basic level, the ROI is a serial protocol similar to the serial protocol that is spoken between a computer and a modem. It is much simpler than Ethernet or Wi-Fi.

The full ROI spec released by iRobot is available at: http://irobot.com/images/consumer/hacker/Roomba_ROI_Spec_Manual.pdf

What can be done via the ROI?

The ROI offers an almost complete view of the Roomba’s internals. It abstracts certain functions, making them easier to use. Much of the low-level hard work dealing with motors and sensors have been taken care of inside the Roomba itself, so users of the ROI don’t have to deal with it. However, some of these abstractions make certain types of hacks difficult.

Sensing

The Roomba contains many sensors to observe the real world and the ROI allows access to all of them. They include:

* Bump sensor (left,right)

* Cliff sensor (left, right, left-front, right-front)

* Wall sensor

* Dirt sensor (left, right)

* Wheel drop sensor (left, right, caster)

* Button presses (power, spot, clean, max)

* Virtual wall, home base, and remote control sensor

Control

The Roomba also contains several actuators and annunciators that can be controlled via the ROI:

* Drive wheel motors

* Vacuum motor

* Main brush motor

* Side brush motor

* Status LEDs

* Piezoelectric beeper

Internal State

Additionally, the ROI makes available certain internal states of the Roomba:

* Battery state and charge level

* Motor over-current

* Distance traveled

* Angle turned

ROI Command Structure

All ROI commands start with a “command opcode”, a single byte with a value between 128 (0x80) and 143 (0x8F), inclusive. There may be more, unpublished opcodes. Only 15 opcodes have been published, but these 15 allow almost complete control.

In addition to the command opcode byte, an ROI command may include one or more data bytes that are arguments to the command. Many commands, like the START command, consist of only the command opcode byte and no data bytes. The PLAY SONG command is an example of a command that takes one extra command byte, a data byte with the number 1-16 of the song to play.

Since a command can take a varying number of arguments, a buggy program sending ROI commands may run into the problem where it’s sending bytes in the wrong sequence, with the Roomba interpreting a data byte as a command byte or vice-versa. The only way around this is to either power off-and-on the Roomba or to send the same single-byte command (like START) enough times to ensure the Roomba really did interpret the byte as a START command. In practice, especially when using an API library like RombaComm, this isn’t a big concern unless the serial connection is severed in the middle of a command sequence.

The largest possible command is a full SONG command at 37 bytes long. This is a rare command usually. The second largest command is the DRIVE command at five bytes.

ROI Mode Commands

These commands are the ones that alter the operating mode of the Roomba. The START command is required for any Roomba hacking via ROI and the CONTROL command is required for any meaningful hacking.

Values in parentheses like (0x85) are the hexadecimal representation of the value. Hex values are useful since each hex digit represents exactly four bits, so two hex digits exactly represent 8 bits, or one byte.

START — opcode: 128 (0x80) — number of data bytes: 0

The START command starts the ROI. The Roomba must be in the on mode via either the Power button or toggling the DD line. If the Roomba is in an unknown state or it’s desired to reset the Roomba, send the START command a few times to put the Roomba in a known state. This command puts the Roomba in the passive mode.

BAUD — opcode: 129 (0x81) — number of data bytes: 1

The BAUD command sets the baud rate in bits per second (bps). The data byte is the baud code (0-11) of the baud rate to use. See the ROI specification for getting the right baud code for a baud rate. The default rate is 57600 bps, which has a baud code of 10. This is speed is well-supported and fast enough for most every use. Changing the baud rate can lead to the age-old problem of never being sure what speed each side is at. In general do not change the baud rate unless 57600 bps will not work for your application.

CONTROL — opcode: 130 (0x82) — number of data bytes: 0

The CONTROL command enables control of the Roomba. It is almost always sent immediately after the START command. This command puts the Roomba in the safe mode.

SAFE — opcode: 131 (0x83) — number of data bytes: 0

The SAFE command returns the Roomba to the “safe” mode if it isn’t already. Only relevant if the Roomba was in the full mode. This command puts the Roomba in the safe mode.

FULL — opcode: 132 (0x84) — number of data bytes: 0

The FULL command puts the Roomba in the full mode if it isn’t already. The Roomba must have been in the safe mode for this command to work. This command puts the Roomba in the full mode.

POWER — opcode: 133 (0x85) — number of data bytes: 0

This is a virtual button-press command. It is equivalent to pushing the “Power” button on the Roomba. This command puts the Roomba in the sleep mode.

SPOT — opcode: 134 (0x86) — number of data bytes: 0

This is a virtual button-press command. It is equivalent to pushing the “Spot” button on the Roomba. It starts the “Spot” cleaning algorithm.

CLEAN — opcode: 135 (0x87) — number of data bytes: 0

This is a virtual button-press command. It is equivalent to pushing the “Clean” button on the Roomba. It starts the “Clean” cleaning algorithm

MAX — opcode: 136 (0x88) — number of data bytes: 0

This is a virtual button-press command. It is equivalent to pushing the “Max” button on the Roomba. It starts the “Max” cleaning algorithm

DOCK — opcode: 143 (0x8F) — number of data bytes: 0

This turns on the “force-seeking dock” algorithm of the Roomba. It is equivalent to simultaneously pressing both “Spot” and “Clean” buttons. The Roomba stops whatever it was doing and tries to find the charging dock.

ROI Movement Commands

DRIVE — opcode: 137 (0x89) — number of data bytes: 4

This command controls the drive wheels. It takes four bytes of data: two for velocity and two for direction, each treated as 16-bit signed values using twos-complement. The velocity is simply the speed, forward or back at which the Roomba should move. The direction is a bit trickier, as seen below.

* Velocity: from -500 to 500 mm/sec (0xFE0C to 0x01F4)

* Direction: either a radius or some special purpose values

* Turn on a radius: -2000 to 2000 mm (0xF830 to 0x07D0)

* Straight: 32768 (0x8000)

* Spin counter-clockwise: 1 (0x0001)

* Spin clockwise: -1 (0xFFFF)

The straight and spin values for direction are self-explanatory. The radius is the radius in millimeters of an imaginary circle upon whose edge the Roomba would drive along. So, larger radii make the Roomba drive straighter, shorter radii make the Roomba turn more quickly. When going forward, a positive radius turns the Roomba to the right, and a negative radius turns the Roomba to the left.

It’s interesting that iRobot chose to expose the drive functionality as a velocity + direction instead of the presumably simpler velocity of each wheel. Apparently it was presented this way because this is how the Roomba’s algorithms use the drive wheels. The typical spiral the Roomba does is certainly easier with the above abstraction: set the drive speed once, then slowly increment the radius value over time.

MOTORS — opcode: 138 (0x8A) — number of data bytes: 1

This command controls the Roombas three cleaning motors. Unlike the drive motors, only on/off control is available for them. Each motor’s state is represented by a bit in the single data byte:

* Main brush: bit 2 (0x04)

* Vacuum: bit 1 (0x02)

* Side brush: bit 0 (0x01)

To turn on a motor, set the bit. To turn off the motor, clear the bit. All other bits of the data byte are not used and should be set to zero.

ROI Indicator Commands

The Roomba has two types of indicators it uses to let humans know what it is up to: LED lights on its control panel, and a piezoelectric beeper to play status melodies. These melodies are particularly useful when the Roomba gets stuck somewhere hidden. It will forlornly play it’s “uh-oh” melody in an attempt to get attention.

LEDS — opcode: 139 (0x8B) — number of data bytes: 3

The LEDS command is one of the more complex ones. The first data byte of the command is a bit field for turning on/off the LEDs:

* Status (green) bit 5 (0x20)

* Status (red) bit 4 (0x10)

* Spot (green) bit 3 (0x08)

* Clean (green) bit 2 (0x04)

* Max (green) bit 1 (0x02)

* Dirt detect (blue) bit 0 (0x01)

To turn on an LED, set the corresponding bit, to turn it off, clear the corresponding bit. Notice how the Status light has both a red and a green LED. Both can be used at the same time to create an amber light. Bits 6 and 7 of the first data byte are not used and should be set to zero.

The second and third data bytes of the LEDS command represent the color (byte 2) and intensity (byte 3) of the Power LED.

* Power color 0=green, 255=red, values in the middle are mix of those two colors

* Power intensity 0=off, 255=full on, intermediate values are intermediate intensities

So to create a medium amber light, use color,intensity = 128,128 (0x80,0x80).

When charging the Roomba sets the Power color to be the percentage charged, and pulses the Power intensity about once per second to indicate charging.

SONG — opcode: 140 (0x8C) — number of data bytes: 2+2N

The SONG defines a song to be played with the PLAY command. The Roomba can remember up to 16 songs, and each song can be up to 16 notes long. Each note in a song is specified by two bytes: a note number for pitch, and a note duration. There is no way to specify a musical rest or change note loudness.

This command is the most complex one in the ROI as it has a varying number of data bytes, dependent on the length of the song being defined. The first data byte specifies which song is being defined. The second data byte specifies how long the song being defined is, e.g. “N”. Every pair of data bytes after that defines a note.

The shortest song is one note long. To define a one note song would take four bytes. The longest song is 16 notes long and to define that song would take 34 bytes. This makes for the largest possible command in the ROI at 37 bytes (1 command + 1 byte song num + 1 byte song length + 34 bytes song data).

Note numbers are very much like note numbers in MIDI. A note number of 36 (0x24) defines the note C in the first octave (denoted “C1”). Numbers increase sequentially (e.g. C#1 =37, D1=38, and so on). The familiar middle C (“C3”) is note number 60 (0x3C). The standard “A440” pitch (the first A above middle C) is note number 69 (0x45). The smallest note number is 32 (0x1f) corresponding to G0, and the highest pitch is note number 127 (0x7f) corresponding to G8. The Roomba has an eight-octave range, better than any opera star.

Note durations are specified in units of 1/64ths of a second. Thus, a half-second long note would have a duration value of 32 (0x20), and a three-second long note would have a duration value of 192 (0xC0). The longest duration that can be specified is 255*1/64 = 3.984 seconds.

PLAY — opcode: 141 (0x8D) — number of data bytes: 1

Once a song has been defined with the SONG command, it can be triggered to play with the PLAY command. The PLAY command takes one data byte, the song number to play. The song plays immediately and does not repeat.

Building a Roomba Serial Interface Tether

When attempting to communicate with a new device for the first time, always go for the simplest, most direct communication path. We’ll begin with a simple serial cable. The serial tether is the simplest method of verifying computer-to-Roomba connectivity.

The serial tether circuit is simple, but we’ll go into more detail on describing and building it than one might expect. This extra detail is to give explanations as to why the parts of circuit are designed the way they are and to show some of the rules-of-thumb hackers use everyday when designing circuits.

Safety

This project entails building electronic circuits. Doing so exposes you to heat hot enough to burn your skin, electricity that may zap you or your projects, and lead that can poison you. Stay safe at all times.

Parts and Tools

You will need the following parts for this project:

* Mini-DIN 8-pin cable, Jameco part number 10604

* 10 ft long serial cable with DB-9 female connector, Jameco part number 155521

* General-purpose circuit board, Radio Shack part number 276-150

* 78L05 +5VDC voltage regulator IC, Jameco part number 51182

* MAX232 RS-232C transceiver IC, Jameco part number 24811

* 220-ohm resistor (red-red-brown color code), Jameco part number 107941

* Six 1µF polarized electrolytic capacitors, Jameco part number 94160PS

And you will need these tools:

* Soldering iron, stand, and solder, Jameco part numbers 170587CK, 192153CK, 141795

* Hot glue gun and hot glue

* Wire cutters / wire strippers

* IC Hook test leads, Jameco part number 135298

* “Third-hand” tool, Jameco part number 26690

* Digital multimeter

* DC power supply (wall wart) between +9V and +24V, Jameco part number 199566PS

* Mini DIN 8-pin socket, Jameco part number 207722

* Keyspan USA-19H or similar USB-to-serial adapter

* PC (Mac OS X, Windows, Linux) capable of running Java programs

* RoombaComm software package downloaded from http://www.roombahacking.com/

* Terminal emulation program (ZTerm for Mac OS X, RealTerm for Windows, minicom for Linux)

The Circuit

Now let’s get to the circuit to be built. There are essentially three circuits to know about: a power supply, an RS-232 transceiver, and an LED lamp. The power supply converts the unregulated approximately +16VDC Vpwr power line from the Roomba into the +5VDC needed by the RS-232 transceiver. The RS-232 transceiver converts the 0-5VDC signaling used by the Roomba into the +/-10VDC used in RS-232. And the LED circuit is there to let you know that power exists and, besides, everything needs an LED.

Understanding Voltage Regulators

The voltage regulator circuit is the same voltage regulator circuit seen in countless hobbyist projects. The 78L05 voltage regulator takes any voltage input between 7 and 35 VDC and converts it to 5VDC. And it can supply up to 100mA (0.1 Amp) of current. Its brother, the 7805, can supply up to 1A of current. Why 100mA of current? Why are the capacitors there? And why were those particular capacitor values chosen?

Capacitor values for voltage regulators

In circuit design if you can make something not work as hard as it needs to, you do it, because it means your circuit will be more efficient and more reliable. In this case the input capacitor C3 is added to reduce any noise or dropouts on the input voltage coming from the Roomba. A common source of noise is RF interference caused by other electronics or the motors. A common source of dropouts is some device like a motor quickly pulling too much power from the power supply. The power supply cannot keep up so its output voltage sags. The capacitor gives the voltage regulator a more steady power supply to work from, filtering out noise and smoothing out small dropouts. It does this by acting like a little charge reservoir for the dropouts and helps filter out noise by averaging out small variations in the voltage.

The output capacitor C2 is performs a similar role for the users of the +5VDC power it creates. Since this output voltage is used as the positive supply voltage to an IC (specifically the RS-232 transceiver IC), it’s historically called Vcc, Vdd, or V+. Vcc will be used here.

Capacitor voltage ratings

Another parameter of capacitors is their voltage rating. This is often 16V, 50V, or 100V. There’s no great trick to choosing this value: the general rule-of-thumb is to pick a voltage rating about twice the maximum voltage the capacitor will see. In this circuit, the maximum voltage is around 16V, double that is 32V, so the 50V capacitors will work fine.

Understanding LEDs

The next sub-circuit is the status LED, seen in Figure 3-5. Its simple purpose is to shine when there is power present. This sub-circuit is not strictly necessary to make the serial tether function, but it does provide a bit of visual indication. Also, always follow the general rule: if an LED can be added to a circuit without otherwise affecting its functionality, add it!

In an LED circuit, in order to light an LED you must pass current through it. The amount of current determines the brightness of the LED, up to some maximum current. Beyond that maximum, the LED blows up. This is entertaining once or twice but doesn’t really solve the problem of letting you know when your circuit functioning.

If an LED is just connected directly to a power supply, it would draw as much current as possible, because it acts like a short-circuit. Standard LEDs have a max current of around 50 milliamps (mA). You want to be below that, let’s say 25mA. To control the amount of current so it doesn’t go rushing around in a short-circuit, add a resistor. Resistors like all electrical components obey Ohm’s Law: V = I*R, or flipping around to solve for the resistor value: R = V/I.

We know ‘I’ from above: 25 mA. So what is ‘V’ then? You may think “+5V” since that’s the power supply, but that’s not quite it. An LED (or any diode) “drops” some amount of voltage because of how it is made. This voltage drop is different for every diode, but is usually around 1.4V. You can measure it with a multi-meter that has a “diode” setting, or measure it yourself by picking some resistor value you think may be correct, making the LED circuit and measuring the voltage drop across the LED.

Because the LED drops 1.4V, that means that 5V – 1.4V = 3.6V goes across the resistor. So the R=V/I equations for the resistor becomes: R = 3.6/0.025 = 144 ohms. Resistors come in certain fixed values and often the getting the exact correct value isn’t important. In this case, since we want to err on the side of safety, we choose a value greater than 144 ohms. A common value is 220 ohms and is often the smallest value hobbyists have on hand. So it becomes a common value for LED circuits. That makes the current thru the LED be: I = V/R = (5-1.4)/220 = 16 mA.

LED Orientation

LEDs only conduct current in one direction, so their orientation is very important. In a schematic, an LED’s “bar” is the negative side of the LED and its “arrow” should always point towards ground. (think: minus sign == bar) When physically laying out an LED, the flat part on side of the LED corresponds to the “bar” part of the schematic. (think: flat == bar)

Understanding MAX232 RS-232 Transceivers

The MAX232 transceiver IC originally developed by Maxim (not the men’s magazine, but the creator of some of the coolest interfacing ICs out there) performs the magic of converting the 0-5V positive logic signals from the microcontroller in the Roomba to the +/-10V negative logic signals that are part of the RS-232 standard. Instead of accomplishing this conversion with a tricky circuit using several transistors, resistors and capacitors, just plop down the MAX232 and a few capacitors and the problem is solved. Maxim will even help you use their parts by sending you free samples. Just go to the Maxim website (maxim-ic.com), find the part you want and click “sample”. This is really handy if you’re a starving student and want to try out a few interesting parts. If you’re in a hurry or need many of Maxim parts, it’s quicker and easier to buy them from a place like Digikey or Jameco. Most of their parts are only a few bucks.

Virtually every microcontroller has a serial port on it so many hackers are familiar with the MAX232. If you want your little gadget to talk to your computer, chances are you’ve used a MAX232. There are many circuit schematics on the Net and in books with the MAX232, but many are a little different with regards to which value capacitors are used. Some use 10 µF capacitors, some use 1 µF, some use 0.1 µF. Which is the right value? Why do people use different values?

The pedantic but true answer is that the datasheet for the MAX232 tells what capacitor values to use. The trick is that there are slightly different versions of these transceivers that can take different capacitors. One variant, the MAX233, has internal capacitors so no extra parts are needed. Some parts are MAX232 clones and are called “MAX232” but are slightly redesigned. If you have the datasheet for the exact part being used, use the capacitors described in the datasheet. If unsure, use 1µF capacitors.

The MAX232 works by using the capacitors to create a “charge pump” that boosts the input voltage from 5V to either -10V or +10V. The capacitors store the charge needed to make this voltage. Since it takes more charge to drive long serial cable lines, generally the larger the capacitors will be. And in RS-232, “long” means ”several hundred feet”, not the ~10 feet we’ll be using here.

Building the Hardware

Now that we have some understanding of the circuit, it’s time to build it.

Caution

It’s easy to burn yourself with a soldering iron. Be careful, always know where it’s at and always make sure to turn it off when done. Also be sure to be properly grounded so you don’t zap anything.

The Parts and Tools

There is a difference between the Mini DIN cable (round ends) and the DB9 cable (flat ends). Among our parts, the 1 µF capacitors are the five blue cylinders and the 10 µF one is the smaller black cylinder. The voltage regulator is the little three pin thing and the MAX232 chip is the black square with 16 pins. The green LED is pretty obvious with its little resistor barely visible next to it. Many of these components, particularly the capacitors, may look different when you build this project, as there are many different styles of parts. As long as the values are correct everything’s fine.

Step 1: Prepare the Cables

The Mini DIN 8-pin cable and the DB-9 cable must first be prepared. Cut the Mini DIN cable six inches from the plug, and cut the DB-9 as far from the female DB-9 end as possible. To get at the wires, strip off about two inches of the big plastic sheath from each cable and then strip off about 1/4″ of the plastic insulation from all the wires inside.

It usually helps to put the cables in the third-hand clamp tool before continuing. Using the soldering iron, lightly tin each wire with solder. Perform a continuity test on each wire to figure out which colored wire goes to which pin on the jack. It seems every cable has had a different color-to-pin mapping, which is why this is necessary. The DB-9 cables seem to have a more standard color scheme, but you should always test to be sure. A bit of wire a few inches long used to poke into the DB-9 socket and using a Mini DIN 8-pin socket makes it easier to check continuity.

Figure 3-8 shows cables in the third-hand tool after being stripped and tinned. Notice how the Mini Din cable is only about 6 inches long and the DB-9 is about 15 feet long.

Step 2: Lay out the Parts

The prototyping boards often have holes that are joined together electrically. This is a great time saver since it means less soldering, but it also means a little more planning must be done to figure out how to use the more efficiently. These particular boards from Radio Shack are great for IC-based projects because they have 3 holes (or “pads”) connected together for every pin of an IC if the IC is inserted along the board’s axis, and two “buss” lines down the middle, between the pads for the IC. The pad connectivity can be seen from the top thanks to the useful printing around the holes.

With that in mind, lay out the parts according to how they’re connected in the schematic. To save space, cut the prototyping board in two, since only half the space is needed. (This means you have another board to build one for a friend) Place the MAX232 chip so it straddles the two big vertical bus lines, then start placing parts around it, using the connected pads to minimize the amount of wiring needed. Of course, a few jumper wires are always needed. For these small jumpers, use snipped leads from parts.

Also, create test points using snipped leads to check voltages. Sometimes the jumpers can double as test points. Test points for Vpwr, Vcc, and GND should be created.

Step 3: Soldering

With the parts placed, carefully bend the leads of the passive components (capacitors, resistors, LEDs) to hold them in place and solder them down. When bending the leads, bend them towards where they need to connect, it’s usually possible to use the leads as the connecting wire. Then insert and solder the MAX232 chip. Some people prefer to solder an IC socket instead and later insert the IC into the socket. Doing this is preferred, especially if you’re unsure of your soldering skills, but the MAX232 is a pretty tough chip and can take an amount of direct soldering.

On the reverse side of the board, with the parts soldered down, the IC straddles the buss lines and component leads are bent to form connecting wires.

Step 4: Checking Voltages

With the circuit built, it’s time to hook it up to power and see if it blows up. Actually this is one of the most important steps and should never be skipped. It’s easy to make soldering mistakes and this is the step where those mistakes are caught. For this circuit the worst case would be to have the Vpwr line connected to the serial lines of the Roomba. This +16V applied to the Roomba’s +5V-compatible lines would most certainly destroy them. But with a few quick checks you can be assured everything is okay.

Here we use a standard DC wall-wart of around +9V to +24V to emulate the +16V Vpwr line. The exact value isn’t that important since the whole point of the 78L05 voltage regulator is to turn whatever is on the input into +5VDC.

Using the test points created, hook up the multi-meter to Vcc and GND. Connect the wall wart power supply to the Vpwr and GND test points on the circuit. The LED should light up. If it doesn’t, disconnect power immediately and look to see why. Usually it’s because the LED is wired backwards. If the LED lights, the multi-meter should read 5V. Figure 3-11 shows the circuit being tested. Once Vpwr is verified, check all the pins of the IC to be sure that only the input of the voltage regulator is getting Vpwr.

Step 5: Soldering the Cables

Soldering the cables can be tricky because they’re so big compared to the circuit. To make it more manageable and to give some strain-relief to the cables in case they get pulled, hot glue them to the edge of the board. For an extra bit of added protection, before hot gluing, loop some stray insulated wire around the cables, into the holes, and twist tight. With the cables anchored securely, route them to the corresponding points in the circuit and solder them down.

Step 6: Test Connections

The circuit is officially finished and ready to use, but to be extra paranoid, check the connections again. Connect the wall wart power supply from Step 4 to the Mini DIN connector using the Mini DIN socket. The LED should still light. Now test all the pins of both cables, using the same techniques in the Step 1, but this time measure voltages. The main thing to watch for is that +16V is only on the two Vpwr pins of the Mini DIN cable that will plug into the Roomba.

Step 7: Putting it in an enclosure

While having a naked circuit looks pretty cool, in a nerdy way, it’s usually a good idea to put the circuit in some sort of enclosure. A simple enclosure should just be some electrical tape wrapped around it or a cardboard box. If you’re handy with a Dremel or similar hand tools, you can take everyday container objects and convert them into useful enclosures for your projects. Figure 3-13 is an example of putting the circuit in a floss container. The floss container has the benefit of being able to be opened and closed easily to inspect the circuit.

Once plugged into the Roomba, you may want to keep the circuit in place so the Roomba’s wheels don’t catch it. A small square of velcro fastener taped to the bottom of the circuit enclosure and the Roomba allows easy attachment and removal of the circuit to the Roomba’s surface.

Connecting to a Computer

The serial tether has a standard RS-232C DB-9 serial port connector on it and many PCs (older ones anyway) have these serial ports on their motherboards. It’s tempting to just plug in the tether and start going at it. But because we’re paranoid of breaking things this chapter, it’s instead prudent to use a USB serial adapter to guard against any bad voltages entering your computer. No-name USB serial adapters can be had for less than $10 online and so offer a cheap kind of protection for this and any future serial port-based projects you may build.

In this tutorial, the Keyspan US-19HS USB serial adapter will be used. Unlike some of the cheaper adapters, the Keyspan works on all OSes. All of the USB serial adapters require drivers to be installed. These are very minor drivers and won’t mess up your system.

Simple Echo Test

Before plugging the serial tether into the Roomba, let’s do one final test. This test will be an end-to-end test from the computer, through the USB serial adapter, through the circuit, to the Mini DIN cable and back again. This “end-to-end” test lets you check the entire communication path without worrying about the particulars of the Roomba protocol.

Using the Mini DIN jack connected to the Mini DIN cable, connect the DC wall wart power supply to the tether to emulate Vpwr like in Step 6. Using a test clip, connect pins 3 and 4 (RXD and TXD) of Mini Din jack together. That creates the loop that will echo back any data we send. This is called a “loopback” connection and is one of the most powerful debugging techniques for serial data transmission.

With the USB serial adapter installed on your computer, start up a terminal program that can speak to serial ports. Not all terminal programs can do this, as it’s not something that’s normally needed. To communicate with the Roomba we need to set our serial programs to 57600 bps with 8N1 and no hardware or software handshaking, and no local echo.

Note

Besides baud rate, turning off hardware and software handshaking is the most critical setting for serial-based projects. Handshaking (signals that indicate when it’s okay to send data) is rarely used. Unless explicitly mentioned, assume no handshaking when configuring a serial port.

Mac OS X

On Mac OS X, the otherwise wonderful built-in Terminal.app cannot speak to serial ports, but ZTerm can, and is the preferred terminal program. It’s free and available from http://homepage.mac.com/dalverson/zterm/

Once ZTerm is downloaded, launch it and hold down the shift key to select the port (see Figure 3-15) Pick the serial port that corresponds to your USB serial adapter (KeySerial1 if using the Keyspan adapter) and click OK. A blank terminal window will open. Go to Settings and set the data rate and other parameters to what we’ll use when talking to the Roomba. Click OK and you’re ready to echo.

Windows 2000/XP

In Windows, there is the built-in HyperTerminal program, but avoid it as it has some problems when dealing with non-modem devices. Instead the program RealTerm is great, also free, and available from http://realterm.sourceforge.net/

After downloading, installing and running the RealTerm program, you’ll be presented with a window. RealTerm automatically opened COM1, which is probably not the serial port you want opened. Click on the Port tab to adjust settings. Click the Open button so that it pops up to close the current port and click it again to open the correct port.

Echo…Echo…Echo…

With either ZTerm or RealTerm set up correctly, click on the terminal window and type a few characters. You should see what you type. Disconnect the test lead between pins 3 and 4 and type a few more characters. You should not see what you type. Reconnect the test lead and talk to yourself for a bit. Congratulations you’ve successfully sent serial data from the computer to the Roomba plug and back again.

RombaCommTest

Now that we’ve exhaustively tested this thing, let’s finally plug it into the Roomba. Close the terminal program from the previous test. Disconnect any test leads and the wall wart power supply. Plug the Mini DIN cable into the Roomba. Turn on the Roomba and press the “Clean” button. The Roomba should function normally. Reset the Roomba by turning it off and back on again. Now we’re ready to actually control the Roomba from the computer.

Download the RoombaComm software package from http://roombahacking.com/ and find the “RoombaCommTest” directory. This directory contains a Java program with a Mac OS X or Windows application wrapper around it, so it acts like a normal application. We’ll get into how to make these later. Double-click on the appropriate “RoombaCommTest” for your OS. You should see a screen. It will look slightly different on each OS, but will function the same.

Choose the same serial port as you chose for the echo test and click “connect”. In the display area messages will appear giving the results of the connect attempt. If all goes well, you’ll see “Roomba connected” and the Roomba will beep.

Note

On Mac OS X and Linux, the serial port may appear twice: once as a “/dev/cu.something” port and again as a “/dev/tty.something”. Always choose the “/dev/cu” version of the port.

Note

On Mac OS X, you may need to run the “macosx_setup_command” script contained in the RoombaCommTest directory. This makes a few minor changes that allows the Java serial library RXTX to work.

Once connected, the rest of the buttons in RoombaCommTest are ready to use.

Click the “Test” button and RoomabCommTest will play a few notes on the Roomba’s beeper, and move the Roomba in a little dance. Congratulations, you’ve just controlled your Roomba with your computer! If you like, play around with your Roomba using the other buttons. Whenever you want, quit the program.

Note

When the Roomba is being command via the ROI, the Roomba physical buttons no longer work. This means the Power button won’t turn off the Roomba. To turn off the Roomba, lift the Roomba to trigger the safety fault mode, then press the Power button, or click the “power-off” button in RoombaCommTest.

Commanding the Roomba

The RoombaCommTest program is a GUI wrapper around some very simple commands. Let’s take the first things it does when “connect” is clicked:

RoombaComm roombacomm = new RoombaCommSerial();

if( ! roombacomm.connect( portname ) ) {

System.err.println(“Could not connect”);

return;

}

roombacomm.startup();

roombacomm.control();

roombacomm.pause(30);

roombacomm.playNote( 72, 10 ); // C

roombacomm.pause( 200 );

The above code creates a RoombaComm object. The RoombaComm object contains all the protocol-independent methods for communicating with a Roomba. It is the ROI protocol embodied in code. Subclasses of RoombaComm implement a few low-level methods to send and receive data. One example of such a subclass is RoombaCommSerial, for dealing with serial ports. Another example is RoombaCommTCP, for talking to a TCP-connected Roomba.

Once an appropriate RoombaComm object is created, the next step is to try to connect to the Roomba with the connect() method. In RoombaCommSerial, connect() hides all the Java serial messiness that is needed. If the connect succeeds, then the START and CONTROL commands are sent to the Roomba via the startup() and control() methods. This puts the Roomba in safe mode, ready to be controlled.

The playNote() method plays a single note of a given duration. It does this by sending first a SONG command with a one-note song defined, and then a PLAY command to play that song. This is the first, albeit simple, example of the RoombaComm API building higher-level functions out of the basic ROI building blocks.

If the “forward” button were to be clicked, the command:

roombacomm.goForward();

is issued, which sends the Roomba forward at the current speed setting.

Feel free to delve into the internals of the RoombaComm library. If you are familiar with Java JAR files, there is a “roombacomm.jar” that contains the full library so you can write your own programs.

Summary

You have now created a Roomba serial interface tether, the foundation for all future Roomba robotics hacking. Now you can begin experimenting with the Roomba as a computer-controlled robot, using either the RoombaCommTest program (at http://www.roombahacking.com/)or writing your own code. You’ll find several demonstration hacks in the software. Have fun!

8 comments