Page 58 - Hacking Roomba

Chapter 2 — Interfacing Basics 39

Introducing the RoombaComm API

When first experimenting with the ROI, it’s common to use some sort of a serial terminal pro-
gram that can send binary sequences to try out various ROI commands. However, this quickly
gets tiresome. The next thing to try is to write a small program to send these commands. This,
too, proves problematic because typos can slip in and wrong commands can be sent. And with
all these random serial bytes flying, it’s not uncommon to “wedge” the Roomba, getting it into
a state where it seems like it doesn’t work any more. This can be remedied by rebooting Roomba
by removing and re-inserting its battery, but that’s a pain and destroys the hacking groove.
It would be a lot easier if there was a library to codify the exact recipe needed to make some-
thing work. The RoombaComm API is just such an encapsulation of the ROI binary com-
mands into a more easy-to-use Java class. The following chapters show you how to build up
the RoombaComm API. Specifically, Chapters 3 and 4 discuss starting communication with
Roomba, Chapter 5 covers driving Roomba around, and Chapter 6 is all about reading Roomba
sensors. The full version of the RoombaComm API and example programs using it can be
downloaded from www.wiley.com/go/extremetech and http://roombahacking.com/.

Instead of coding something like:
// start up, drive straight at 400mm/s
serialport.send(0x80);
serialport.send(0x82);
serialport.send({0x89,01,0x90,80,00});

you would do something like:
// start up, drive straight at 400mm/s
roombacomm.startup();
roombacomm.driveStraight(400);
The obvious benefit is more human-readable code. This becomes even more evident when
dealing with reading sensor packets, as you will see in Chapter 6.
The other main benefit is how the ROI commands are then used as “primitives” to create more
complex behaviors. A good example of an added complex behavior would be implementing the
task “at a speed of 100 mm/s, go forward 150 mm, then spin 90 degrees right.” Using basic
RoombaComm commands, that becomes:
roombacomm.goForwardAt(100); // go forward at 100mm/sec
roombacomm.pause(1500); // wait 1.5 seconds,to get 150 mm
roombacomm.spinRightAt(100); // spin right at 100mm/sec
float ptime = 45.0 * roombacomm.millimetersPerDegree / 100.0;
roombacomm.pause(ptime); // wait to spin thru the angle

However, when using more complex RoombaComm commands, that becomes simply:
roombacomm.setSpeed(100); // set speed to 100 mm/sec
roombacomm.goForward(150); // go forward 150 mm
roombacomm.spinRight(45); // spin 45 degrees right