Page 52 - Hacking Roomba

Chapter 2 — Interfacing Basics 33

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 many notes are in the song. Every pair of
data bytes after that defines a note: note number and note duration.
The shortest song is one note long. To define a one-note song would take four data bytes. The
longest song is 16 notes long and to define that song would take 32 data bytes. This makes for
the largest possible command in the ROI at 35 bytes (1 command + 1 byte song num + 1 byte
song length + 32 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 (for example, 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) correspon-
ding to G8. 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 note would have a duration value
of 192 (0xC0). The longest duration that can be specified is 255 × 1/64 = 3.984 seconds.
For example, a complete SONG command to program into song slot #3 a one-note song that
plays a C3 for three seconds would be: 0x8C,0x03,0x01,0x3C,0xC0.
After 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. To play the above defined song, the full ROI command
would be: 0x8D,0x03.

ROI Sensors
Of all the ROI commands, only one returns data. There is no need to get sensor data from the
Roomba. Roomba will react appropriately to all other ROI commands regardless of whether
the SENSORS command is used. In fact, operating Roomba in such an “open-loop” manner may
be a preferred mode if external sensors with better performance have been added through an
external microcontroller, as you do in Chapter 13.
The SENSORS command takes one data byte as an argument, the packet code. This packet code
determines how much and what group of sensor data is being retrieved.
The different groups of sensor data are:

Physical sense: Sensors that detect the environment, like bump, cliff, and wall sensors
Buttons and internal sense: The state of the panel and remote buttons, and the com-
puted distance and angle values
Power sense: The state of the battery and charging systems
All: All of the above data