Page 51 - Hacking Roomba

32 Part I — Interfacing

ROI Indicator Commands

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 particu-
larly useful when the robot gets stuck somewhere hidden. It will forlornly play its “uh-oh”
melody in an attempt to get attention.

Lights
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 LED 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 inten-
sity (byte 3) of the Power LED.

Power color: 0=green, 255=red, and values in the middle are mix of those two colors.
Power intensity: 0=off, 255=full on, and intermediate values are intermediate intensities.

So to create a medium amber light, the color and intensity data bytes would be 128,128
(0x80,0x80). Or, a full LEDS command to turn the Status and Spot light green and have the
power light be medium amber would be: 0x8B,0x28,0x80,0x80. To turn all the LEDS off,
the full command is: 0x8B,0x00,0x00,0x00.
When charging, Roomba sets the Power color to be the percentage charged, and pulses the
Power intensity about once per second to indicate charging.

Music
There are two types of music commands: SONG and PLAY. The SONG command defines a song
to be played with the PLAY command. 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 number for duration. To specify a musical rest, use a zero for pitch. There is
no way to change note loudness.