iRobot Roomba 500 Open Interface (OI) Specification

iRobot

Page 1

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Table of Contents
iRobot Roomba Open Interface Overview......................................................................................... 3 Physical Connections ........................................................................................................................ 3 Roombas External Serial Port Mini-DIN Connector Pinout................................................................. 3 Serial Port Settings........................................................................................................................... 4 Roomba Open Interface Modes ......................................................................................................... 5 Open Interface Command Reference ................................................................................................. 6 Getting Started Commands............................................................................................................ 6 Mode Commands.......................................................................................................................... 7 Cleaning Commands ..................................................................................................................... 8 Actuator Commands.................................................................................................................... 10 Input Commands ........................................................................................................................ 17 Roomba Open Interface Sensor Packets........................................................................................... 19 Roomba Open Interface Commands Quick Reference ........................................................................ 29 Roomba Open Interface Sensors Quick Reference............................................................................. 33

iRobot

Page 2

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

iRobot Roomba Open Interface Overview

The Roomba Open Interface (OI) is a software interface for controlling and manipulating Roombas behavior. The software interface lets you manipulate Roombas behavior and read its sensors through a series of commands, including mode commands, actuator commands, song commands, and sensor commands that you send to the Roombas serial port by way of a PC or microcontroller that is connected to the Mini-DIN connector.

Physical Connections
To use the OI, a processor capable of generating serial commands such as a PC or a microcontroller must be connected to the external Mini-DIN connector on Roomba. This connector provides two-way, serial communication at TTL (0 5V) levels. The connector also provides an unregulated direct connection to Roombas battery, which you can use to power the OI applications. The Mini-DIN connector is located on the top of Roomba, beneath the snap-on decorative cover.

Roombas External Serial Port Mini-DIN Connector Pinout

This diagram shows the pinout of the top view of the female connector in Roomba. Note that pins 5, 6, and 7 are towards the bottom of Roomba.

Pin 1 2 3 4 5 6 7

Name Vpwr Vpwr RXD TXD BRC GND GND

Description Roomba battery + (unregulated) Roomba battery + (unregulated) 0 5V Serial input to Roomba 0 5V Serial output from Roomba Baud Rate Change Roomba battery ground Roomba battery ground

Since the RXD and TXD pins use 0 5V logic voltage and the PC serial ports use different voltages (rs232 levels), it is necessary to shift voltage levels. To do this, use an iRobot Roomba serial cable rather than a normal serial cable, as the iRobot Roomba serial cable contains all of the necessary hardware to shift the voltage levels, whereas the normal serial cable does not.

iRobot

Page 3

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Serial Port Settings

Baud: 115200 or 19200 (see below) Data bits: 8 Parity: None Stop bits: 1 Flow control: None By default, Roomba communicates at 115200 baud. If you are using a microcontroller that does not support 115200 baud, there are two ways to force Roomba to switch to 19200: Method 1: When powering on Roomba, hold down the Clean/Power button. After about 10 seconds, Roomba plays a tune of descending pitches. Roomba will communicate at 19200 baud until the power is turned off, the battery is removed and reinserted, the battery voltage falls below the minimum required for processor operation, or the baud rate is explicitly changed by way of the OI. Method 2: Use the Baud Rate Change pin (pin 5 on the Mini-DIN connector) to change Roombas baud rate. After turning on Roomba, wait 2 seconds and then pulse the Baud Rate Change low three times. Each pulse should last between 50 and 500 milliseconds. Roomba will communicate at 19200 baud until the processor loses battery power or the baud rate is explicitly changed by way of the OI.

iRobot

Page 4

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Roomba Open Interface Modes

The Roomba OI has four operating modes: Off, Passive, Safe, and Full. After a battery change or when power is first turned on, the OI is in off mode. When it is off, the OI listens at the default baud rate (115200 or 19200 - see Serial Port Settings above) for an OI Start command. Once it receives the Start command, you can enter into any one of the four operating modes by sending a mode command to the OI. You can also switch between operating modes at any time by sending a command to the OI for the operating mode that you want to use. Passive Mode Upon sending the Start command or any one of the cleaning mode commands (e.g., Spot, Clean, Seek Dock), the OI enters into Passive mode. When the OI is in Passive mode, you can request and receive sensor data using any of the sensor commands, but you cannot change the current command parameters for the actuators (motors, speaker, lights) to something else. To change how one of the actuators operates, you must switch from Passive mode to Full mode or Safe mode. While in Passive mode, you can read Roombas sensors, watch Roomba perform a cleaning cycle, and charge the battery. Safe Mode When you send a Safe command to the OI, Roomba enters into Safe mode. Safe mode gives you full control of Roomba, with the exception of the following safety-related conditions: Detection of a cliff while moving forward (or moving backward with a small turning radius, less than one robot radius). Detection of a wheel drop (on any wheel). Charger plugged in and powered.

Should one of the above safety-related conditions occur while the OI is in Safe mode, Roomba stops all motors and reverts to the Passive mode. If no commands are sent to the OI when in Safe mode, Roomba waits with all motors and LEDs off and does not respond to button presses or other sensor input. Note that charging terminates when you enter Safe Mode. Full Mode When you send a Full command to the OI, Roomba enters into Full mode. Full mode gives you complete control over Roomba, all of its actuators, and all of the safety-related conditions that are restricted when the OI is in Safe mode, as Full mode shuts off the cliff, wheel-drop and internal charger safety features. To put the OI back into Safe mode, you must send the Safe command. If no commands are sent to the OI when in Full mode, Roomba waits with all motors and LEDs off and does not respond to button presses or other sensor input. Note that charging terminates when you enter Full Mode.

iRobot

Page 5

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Open Interface Command Reference

The following is a list of all of Roombas Open Interface commands. Each command starts with a onebyte opcode. Some of the commands must be followed by data bytes. All of Roombas OI commands including their required data bytes are described below. NOTE: Always send the required number of data bytes for the command, otherwise, the processor will enter and remain in a waiting state until all of the required data bytes are received.

Getting Started Commands

The following commands start the Open Interface and get it ready for use. Start Opcode: 128 Data Bytes: 0

This command starts the OI. You must always send the Start command before sending any other commands to the OI. Serial sequence: [128]. Available in modes: Passive, Safe, or Full Changes mode to: Passive. Roomba beeps once to acknowledge it is starting from off mode. Opcode: 129 Data Bytes: 1

Baud

This command sets the baud rate in bits per second (bps) at which OI commands and data are sent according to the baud code sent in the data byte. The default baud rate at power up is 115200 bps, but the starting baud rate can be changed to 19200 by holding down the Clean button while powering on Roomba until you hear a sequence of descending tones. Once the baud rate is changed, it persists until Roomba is power cycled by pressing the power button or removing the battery, or when the battery voltage falls below the minimum required for processor operation. You must wait 100ms after sending this command before sending additional commands at the new baud rate. Serial sequence: [129][Baud Code] Available in modes: Passive, Safe, or Full Changes mode to: No Change Baud data byte 1: Baud Code (0 - 11)

iRobot

Page 6

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Mode Commands
Roomba has four operating modes: Off, Passive, Safe, and Full. Roomba powers on in the Off mode. The following commands change Roombas OI mode. Safe Opcode: 131 Data Bytes: 0

This command puts the OI into Safe mode, enabling user control of Roomba. It turns off all LEDs. The OI can be in Passive, Safe, or Full mode to accept this command. If a safety condition occurs (see above) Roomba reverts automatically to Passive mode. Serial sequence: [131] Available in modes: Passive, Safe, or Full Changes mode to: Safe

Note: The effect and usage of the Control command (130) are identical to the Safe command. Full Opcode: 132 Data Bytes: 0

This command gives you complete control over Roomba by putting the OI into Full mode, and turning off the cliff, wheel-drop and internal charger safety features. That is, in Full mode, Roomba executes any command that you send it, even if the internal charger is plugged in, or command triggers a cliff or wheel drop condition. Serial sequence: [132] Available in modes: Passive, Safe, or Full Changes mode to: Full

Note: Use the Start command (128) to change the mode to Passive.

iRobot

Page 7

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Cleaning Commands
The following are commands to start Roombas built-in cleaning modes and set the clock and schedule. Clean This command starts the default cleaning mode. Serial sequence: [135] Available in modes: Passive, Safe, or Full Changes mode to: Passive Opcode: 136 Data Bytes: 0 Opcode: 135 Data Bytes: 0

Max This command starts the Max cleaning mode. Serial sequence: [136] Available in modes: Passive, Safe, or Full Changes mode to: Passive

Spot This command starts the Spot cleaning mode. Serial sequence: [134] Available in modes: Passive, Safe, or Full Changes mode to: Passive

Opcode: 134

Data Bytes: 0

Seek Dock This command sends Roomba to the dock. Serial sequence: [143] Available in modes: Passive, Safe, or Full Changes mode to: Passive

Opcode: 143

Data Bytes: 0

Schedule

Opcode: 167

Data Bytes: 15

This command sends Roomba a new schedule. To disable scheduled cleaning, send all 0s. Serial sequence: [167] [Days] [Sun Hour] [Sun Minute] [Mon Hour] [Mon Minute] [Tue Hour] [Tue Minute] [Wed Hour] [Wed Minute] [Thu Hour] [Thu Minute] [Fri Hour] [Fri Minute] [Sat Hour] [Sat Minute] Available in modes: Passive, Safe, or Full. If Roombas schedule or clock button is pressed, this command will be ignored. Changes mode to: No change Times are sent in 24 hour format. Hour (0-23) Minute (0-59)

iRobot

Page 8

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Days

Example: To schedule the robot to clean at 3:00 PM on Wednesdays and 10:36 AM on Fridays, send: [167] [40] [0] [0] [0] [0] [0] [0] [15] [0] [0] [0] [10] [36] [0] [0] To disable scheduled cleaning, send: [167] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] [0] Set Day/Time This command sets Roombas clock. Serial sequence: [168] [Day] [Hour] [Minute] Available in modes: Passive, Safe, or Full. If Roombas schedule or clock button is pressed, this command will be ignored. Changes mode to: No change Time is sent in 24 hour format. Hour (0-23) Minute (0-59) Code 0 1 2 3 4 5 6 Power Day Sunday Monday Tuesday Wednesday Thursday Friday Saturday Opcode: 133 Data Bytes: 0 Opcode: 168 Data Bytes: 3

This command powers down Roomba. The OI can be in Passive, Safe, or Full mode to accept this command. Serial sequence: [133] Available in modes: Passive, Safe, or Full Changes mode to: Passive

iRobot

Page 9

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Actuator Commands
The following commands control Roombas actuators: wheels, brushes, vacuum, speaker, LEDS, and buttons. Drive Opcode: 137 Data Bytes: 4

This command controls Roombas drive wheels. It takes four data bytes, interpreted as two 16-bit signed values using twos complement. The first two bytes specify the average velocity of the drive wheels in millimeters per second (mm/s), with the high byte being sent first. The next two bytes specify the radius in millimeters at which Roomba will turn. The longer radii make Roomba drive straighter, while the shorter radii make Roomba turn more. The radius is measured from the center of the turning circle to the center of Roomba. A Drive command with a positive velocity and a positive radius makes Roomba drive forward while turning toward the left. A negative radius makes Roomba turn toward the right. Special cases for the radius make Roomba turn in place or drive straight, as specified below. A negative velocity makes Roomba drive backward. NOTE: Internal and environmental restrictions may prevent Roomba from accurately carrying out some drive commands. For example, it may not be possible for Roomba to drive at full speed in an arc with a large radius of curvature. Serial sequence: [137] [Velocity high byte] [Velocity low byte] [Radius high byte] [Radius low byte] Available in modes: Safe or Full Changes mode to: No Change Velocity (-500 500 mm/s) Radius (-2000 2000 mm) Special cases: Straight = 32768 or 32767 = hex 8000 or 7FFF Turn in place clockwise = -1 Turn in place counter-clockwise = 1 Example: To drive in reverse at a velocity of -200 mm/s while turning at a radius of 500mm, send the following serial byte sequence: [137] [255] [56] [1] [244] Velocity = -200 = hex FF38 = [hex FF] [hex 38] = [255] [56] Radius = 500 = hex 01F4 = [hex 01] [hex F4] = [1] [244]

iRobot

Page 10

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Drive Direct

Opcode: 145

Data Bytes: 4

This command lets you control the forward and backward motion of Roombas drive wheels independently. It takes four data bytes, which are interpreted as two 16-bit signed values using twos complement. The first two bytes specify the velocity of the right wheel in millimeters per second (mm/s), with the high byte sent first. The next two bytes specify the velocity of the left wheel, in the same format. A positive velocity makes that wheel drive forward, while a negative velocity makes it drive backward. Serial sequence: [145] [Right velocity high byte] [Right velocity low byte] [Left velocity high byte] [Left velocity low byte] Available in modes: Safe or Full Changes mode to: No Change Right wheel velocity (-500 500 mm/s) Left wheel velocity (-500 500 mm/s) Opcode: 146 Data Bytes: 4

Drive PWM

This command lets you control the raw forward and backward motion of Roombas drive wheels independently. It takes four data bytes, which are interpreted as two 16-bit signed values using twos complement. The first two bytes specify the PWM of the right wheel, with the high byte sent first. The next two bytes specify the PWM of the left wheel, in the same format. A positive PWM makes that wheel drive forward, while a negative PWM makes it drive backward. Serial sequence: [146] [Right PWM high byte] [Right PWM low byte] [Left PWM high byte] [Left PWM low byte] Available in modes: Safe or Full Changes mode to: No Change Right wheel PWM (-255 255) Left wheel PWM (-255 255) Opcode: 138 Data Bytes: 1

Motors

This command lets you control the forward and backward motion of Roombas main brush, side brush, and vacuum independently. Motor velocity cannot be controlled with this command, all motors will run at maximum speed when enabled. The main brush and side brush can be run in either direction. The vacuum only runs forward. Serial sequence: [138] [Motors] Available in modes: Safe or Full Changes mode to: No Change Bits 0-2: 0 = off, 1 = on at 100% pwm duty cycle Bits 3 & 4: 0 = motors default direction, 1 = motors opposite direction. Default direction for the side brush is counterclockwise. Default direction for the main brush/flapper is inward.

iRobot

Page 11

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Example: To turn on the main brush inward and the side brush clockwise, send: [138] [13] PWM Motors Opcode: 144 Data Bytes: 3

This command lets you control the speed of Roombas main brush, side brush, and vacuum independently. With each data byte, you specify the duty cycle for the low side driver (max 128). For example, if you want to control a motor with 25% of battery voltage, choose a duty cycle of 128 * 25% = 32. The main brush and side brush can be run in either direction. The vacuum only runs forward. Positive speeds turn the motor in its default (cleaning) direction. Default direction for the side brush is counterclockwise. Default direction for the main brush/flapper is inward. Serial sequence: [144] [Main Brush PWM] [Side Brush PWM] [Vacuum PWM] Available in modes: Safe or Full Changes mode to: No Change Main Brush and Side Brush duty cycle (-127 127) Vacuum duty cycle (0 127) Opcode: 139 Data Bytes: 3

LEDs

This command controls the LEDs common to all models of Roomba 500. The Clean/Power LED is specified by two data bytes: one for the color and the other for the intensity. Serial sequence: [139] [LED Bits] [Clean/Power Color] [Clean/Power Intensity] Available in modes: Safe or Full Changes mode to: No Change LED Bits (0 255)

Home and Spot use green LEDs: 0 = off, 1 = on Check Robot uses an orange LED. Debris uses a blue LED. Clean/Power uses a bicolor (red/green) LED. The intensity and color of this LED can be controlled with 8-bit resolution. LED Bits (0-255)

Clean/Power LED Color (0 255) 0 = green, 255 = red. Intermediate values are intermediate colors (orange, yellow, etc). Clean/Power LED Intensity (0 255) 0 = off, 255 = full intensity. Intermediate values are intermediate intensities.

iRobot

Page 12

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Example: To turn on the Home LED and light the Clean/Power LED green at half intensity, send the serial byte sequence [139] [4] [0] [128]. Scheduling LEDS Opcode: 162 Data Bytes: 2

This command controls the state of the scheduling LEDs present on the Roomba 560 and 570. Serial sequence: [162] [Weekday LED Bits][Scheduling LED Bits] Available in modes: Safe or Full Changes mode to: No Change Weekday LED Bits (0 255) Scheduling LED Bits (0 255) All use red LEDs: 0 = off, 1 = on

Weekday LED Bits

Scheduling LED Bits

Digit LEDs Raw This command controls the four 7 segment displays on the Roomba 560 and 570. Serial sequence: [163] [Digit 3 Bits] [Digit 2 Bits] [Digit 1 Bits] [Digit 0 Bits] Available in modes: Safe or Full Changes mode to: No Change Digit N Bits (0 255) All use red LEDs: 0 = off, 1 = on. Digits are ordered from left to right on the robot 3,2,1,0.

Opcode: 163

Data Bytes: 4

Digit N Bits

Opcode: 164

Data Bytes: 4

Digit LEDs ASCII

This command controls the four 7 segment displays on the Roomba 560 and 570 using ASCII character codes. Because a 7 segment display is not sufficient to display alphabetic characters properly, all characters are an approximation, and not all ASCII codes are implemented. Serial sequence: [164] [Digit 3 ASCII] [Digit 2 ASCII] [Digit 1 ASCII] [Digit 0 ASCII]
Page 13 www.irobot.com

iRobot

iRobot Roomba Open Interface (OI) Specification

Available in modes: Safe or Full Changes mode to: No Change Digit N ASCII (32 126) All use red LEDs. Digits are ordered from left to right on the robot 3,2,1,0.

Example: To write ABCD to the display, send the serial byte sequence: [164] [65] [66] [67] [68] Table of ASCII codes:

Buttons

Opcode: 165

{ }

Data Bytes: 1

This command lets you push Roombas buttons. The buttons will automatically release after 1/6th of a second. Serial sequence: [165] [Buttons] Available in modes: Passive, Safe, or Full Changes mode to: No Change Buttons (0-255) 1 = Push Button, 0 = Release Button

Buttons

iRobot

Page 14

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Song

Opcode: 140 Data Bytes: 2N+2, where N is the number of notes in the song

This command lets you specify up to four songs to the OI that you can play at a later time. Each song is associated with a song number. The Play command uses the song number to identify your song selection. Each song can contain up to sixteen notes. Each note is associated with a note number that uses MIDI note definitions and a duration that is specified in fractions of a second. The number of data bytes varies, depending on the length of the song specified. A one note song is specified by four data bytes. For each additional note within a song, add two data bytes. Serial sequence: [140] [Song Number] [Song Length] [Note Number 1] [Note Duration 1] [Note Number 2] [Note Duration 2], etc. Available in modes: Passive, Safe, or Full Changes mode to: No Change Song Number (0 4) The song number associated with the specific song. If you send a second Song command, using the same song number, the old song is overwritten. Song Length (1 16) The length of the song, according to the number of musical notes within the song. Song data bytes 3, 5, 7, etc.: Note Number (31 127) The pitch of the musical note Roomba will play, according to the MIDI note numbering scheme. The lowest musical note that Roomba will play is Note #31. Roomba considers all musical notes outside the range of 31 127 as rest notes, and will make no sound during the duration of those notes. Song data bytes 4, 6, 8, etc.: Note Duration (0 255) The duration of a musical note, in increments of 1/64th of a second. Example: a half-second long musical note has a duration value of 32.

iRobot

Page 15

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Play

Opcode: 141

Data Bytes: 1

This command lets you select a song to play from the songs added to Roomba using the Song command. You must add one or more songs to Roomba using the Song command in order for the Play command to work. Serial sequence: [141] [Song Number] Available in modes: Safe or Full Changes mode to: No Change Song Number (0 4)

The number of the song Roomba is to play.

iRobot

Page 16

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Input Commands
The following commands let you read the state of Roombas built-in sensors and some internal state variables. Roomba updates these values internally every 15 ms. Do not send these commands more frequently than that. Sensors Opcode: 142 Data Bytes: 1

This command requests the OI to send a packet of sensor data bytes. There are 58 different sensor data packets. Each provides a value of a specific sensor or group of sensors.

Packets.

For more information on sensor packets, refer to the next section, Roomba Open Interface Sensors Serial sequence: [142] [Packet ID] Available in modes: Passive, Safe, or Full Changes mode to: No Change Packet ID: Identifies which of the 58 sensor data packets should be sent back by the OI. A value of 100 indicates a packet with all of the sensor data. Values of 0 through 6 and 101 through 107 indicate specific subgroups of the sensor data. Opcode: 149 Data Bytes: N + 1, where N is the number of packets requested.

Query List

This command lets you ask for a list of sensor packets. The result is returned once, as in the Sensors command. The robot returns the packets in the order you specify. Serial sequence: [149][Number of Packets][Packet ID 1][Packet ID 2]...[Packet ID N] Available in modes: Passive, Safe, or Full Changes modes to: No Change

Example: To get the state of the bumpers and the virtual wall sensor, send the following sequence: [149] [2] [7] [13] Stream Opcode: 148 Data Bytes: N + 1, where N is the number of packets requested.

This command starts a stream of data packets. The list of packets requested is sent every 15 ms, which is the rate Roomba uses to update data. This method of requesting sensor data is best if you are controlling Roomba over a wireless network (which has poor real-time characteristics) with software running on a desktop computer. Serial sequence: [148] [Number of packets] [Packet ID 1] [Packet ID 2] [Packet ID 3] etc. Available in modes: Passive, Safe, or Full Changes mode to: No Change

iRobot

Page 17

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

The format of the data returned is: [19][N-bytes][Packet ID 1][Packet 1 data][Packet ID 2][Packet 2 data][Checksum] N-bytes is the number of bytes between the n-bytes byte and the checksum. The checksum is a 1-byte value. It is the 8-bit complement of all of the bytes between the header and the checksum. That is, if you add all of the bytes after the checksum, and the checksum, the low byte of the result will be 0. Example: To get data from Roomba's left cliff signal (packet 29) and virtual wall sensor (packet 13), send the following command string to Roomba: [148] [2] [29] [13]
NOTE:

The left cliff signal is a 2-byte packet and the virtual wall is a 1-byte packet. Roomba starts streaming data that looks like this: 19 header
NOTE:

5 n-bytes

29 packet ID 1

25

13 packet ID 2

0 packet data 2 (1 byte)

182 Checksum

Packet data 1 (2 bytes)

Checksum computation: (5 + 29 + 2 + 25 + 13 + 0 + 182) = 256 and (256 & 0xFF) = 0. In the above stream segment, Roombas left cliff signal value was 549 (0x0225) and there was no virtual wall signal. It is up to you not to request more data than can be sent at the current baud rate in the 15 ms time slot. For example, at 57600 baud, a maximum of 86 bytes can be sent in 15 ms: 15 ms / 10 bits (8 data + start + stop) * 57600 = 86.4 If more data is requested, the data stream will eventually become corrupted. This can be confirmed by checking the checksum. The header byte and checksum can be used to align your receiving program with the data. All data chunks start with 19 and end with the 1-byte checksum. Pause/Resume Stream Opcode: 150 Data Bytes: 1

This command lets you stop and restart the steam without clearing the list of requested packets. Serial sequence: [150][Stream State] Available in modes: Passive, Safe, or Full Changes modes to: No Change Range: 0-1

An argument of 0 stops the stream without clearing the list of requested packets. An argument of 1 starts the stream using the list of packets last requested.

iRobot

Page 18

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Roomba Open Interface Sensor Packets

Roomba sends back one of 58 different sensor data packets, depending on the value of the packet data byte, when responding to a Sensors command, Query List command, or Stream commands request for a packet of sensor data bytes. Some packets contain groups of other packets. Some of the sensor data values are 16 bit values. Most of the packets (numbers 7 58) contain the value of a single sensor or variable, which can be either 1 byte or 2 bytes. Two byte packets correspond to 16-bit values, sent high byte first. Some of the packets (0-6, 100-107) contain groups of the single-value packets.

Bumps and Wheel Drops

Packet ID: 7

Data Bytes: 1, unsigned

The state of the bumper (0 = no bump, 1 = bump) and wheel drop sensors (0 = wheel raised, 1 = wheel dropped) are sent as individual bits. Range: 0 15

Packet ID: 8

Wall

Data Bytes: 1, unsigned

The state of the wall sensor is sent as a 1 bit value (0 = no wall, 1 = wall seen). Range: 0 1 Cliff Left Packet ID: 9 Data Bytes: 1, unsigned

The state of the cliff sensor on the left side of Roomba is sent as a 1 bit value (0 = no cliff, 1 = cliff). Range: 0 1 Cliff Front Left Packet ID: 10 Data Bytes: 1, unsigned

The state of the cliff sensor on the front left of Roomba is sent as a 1 bit value (0 = no cliff, 1 = cliff).

iRobot

Page 19

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Range: 0 1 Cliff Front Right Packet ID: 11 Data Bytes: 1, unsigned

The state of the cliff sensor on the front right of Roomba is sent as a 1 bit value (0 = no cliff, 1 = cliff) Range: 0 1 Cliff Right Packet ID: 12 Data Bytes: 1, unsigned

The state of the cliff sensor on the right side of Roomba is sent as a 1 bit value (0 = no cliff, 1 = cliff) Range: 0 1 Virtual Wall Packet ID: 13 Data Bytes: 1, unsigned

The state of the virtual wall detector is sent as a 1 bit value (0 = no virtual wall detected, 1 = virtual wall detected). Range: 0 1 Wheel Overcurrents Packet ID: 14 Data Bytes: 1, unsigned

The state of the four wheel overcurrent sensors are sent as individual bits (0 = no overcurrent, 1 = overcurrent). There is no overcurrent sensor for the vacuum on Roomba 500. Range: 0 31

Dirt Detect The level of the dirt detect sensor. Range: 0-255 Unused Byte

Packet IDs: 15

Data Bytes: 1

Packet IDs: 16

Data Bytes: 1

Unused bytes: One unused byte is sent after the dirt detect byte when the requested packet is 0, 1, or 6. The value of the unused byte is always 0. Range: 0 Infrared Character Omni Packet ID: 17 Data Bytes: 1, unsigned

This value identifies the 8-bit IR character currently being received by Roombas omnidirectional receiver. A value of 0 indicates that no character is being received. These characters include those sent by the Roomba Remote, the Dock, Roomba 500 Virtual Walls, Create robots using the Send-IR command, and user-created devices. Range: 0 255

iRobot

Page 20

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Infrared Character Left

Packet ID: 52

Data Bytes: 1, unsigned

This value identifies the 8-bit IR character currently being received by Roombas left receiver. A value of 0 indicates that no character is being received. These characters include those sent by the Roomba Remote, the Dock, Roomba 500 Virtual Walls, Create robots using the Send-IR command, and usercreated devices. Range: 0 255 Infrared Character Right Packet ID: 53 Data Bytes: 1, unsigned

This value identifies the 8-bit IR character currently being received by Roombas right receiver. A value of 0 indicates that no character is being received. These characters include those sent by the Roomba Remote, the Dock, Roomba 500 Virtual Walls, Create robots using the Send-IR command, and usercreated devices. Range: 0 255 Characters sent by iRobot devices: Dock beam configuration

Force Field

Green Buoy

Red Buoy

Lighthouse beam configuration

iRobot

Page 21

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Force Field

Green Buoy

Red Buoy

Fence
Character Value 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 240 248 244 242 252 250 246 254

Sent by iRobot Device IR Remote Control

Scheduling Remote Roomba Discovery Driveon Charger

Character Name Left Forward Right Spot Max Small Medium Large / Clean Stop Power Arc Left Arc Right Stop Download Seek Dock Reserved Red Buoy Green Buoy Force Field Red Buoy and Green Buoy Red Buoy and Force Field Green Buoy and Force Field Red Buoy, Green Buoy and Force Field

iRobot

Page 22

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Sent by iRobot Device Roomba 500 Drive-on Charger

Character Value 160 161 164 165 168 169 172 173 162 0LLLL0BB

Roomba 500 Virtual Wall Roomba 500 Virtual Wall Lighthouse

Character Name Reserved Force Field Green Buoy Green Buoy and Force Field Red Buoy Red Buoy and Force Field Red Buoy and Green Buoy Red Buoy, Green Buoy and Force Field Virtual Wall LLLL = Virtual Wall Lighthouse ID (assigned automatically by Roomba 560 and 570 robots) 1-10: Valid ID 11: Unbound 12-15: Reserved BB = Which Beam 00 = Fence 01 = Force Field 10 = Green Buoy 11 = Red Buoy Data Bytes: 1, unsigned

Buttons

Packet ID: 18

The state of the Roomba buttons are sent as individual bits (0 = button not pressed, 1 = button pressed). The day, hour, minute, clock, and scheduling buttons that exist only on Roomba 560 and 570 will always return 0 on a robot without these buttons. Range: 0 255

Distance

Packet ID: 19

Data Bytes: 2, signed

The distance that Roomba has traveled in millimeters since the distance it was last requested is sent as a signed 16-bit value, high byte first. This is the same as the sum of the distance traveled by both wheels divided by two. Positive values indicate travel in the forward direction; negative values indicate travel in the reverse direction. If the value is not polled frequently enough, it is capped at its minimum or maximum. Range: -32768 32767 Angle Packet ID: 20 Data Bytes: 2, signed

The angle in degrees that Roomba has turned since the angle was last requested is sent as a signed 16bit value, high byte first. Counter-clockwise angles are positive and clockwise angles are negative. If the value is not polled frequently enough, it is capped at its minimum or maximum. Range: -32768 32767

iRobot

Page 23

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Charging State

Packet ID: 21

Data Bytes: 1, unsigned

This code indicates Roombas current charging state. Range: 0 5 Code 0 1 2 3 4 5 Voltage Charging State Not charging Reconditioning Charging Full Charging Trickle Charging Waiting Charging Fault Condition Packet ID: 22 Data Bytes: 2, unsigned

This code indicates the voltage of Roombas battery in millivolts (mV). Range: 0 65535 mV Current Packet ID: 23 Data Bytes: 2, signed

The current in milliamps (mA) flowing into or out of Roombas battery. Negative currents indicate that the current is flowing out of the battery, as during normal running. Positive currents indicate that the current is flowing into the battery, as during charging. Range: -32768 32767 mA Temperature Packet ID: 24 Data Bytes: 1, signed

The temperature of Roombas battery in degrees Celsius. Range: -128 127 Battery Charge Packet ID: 25 Data Bytes: 2, unsigned

The current charge of Roombas battery in milliamp-hours (mAh). The charge value decreases as the battery is depleted during running and increases when the battery is charged. Range: 0 65535 mAh Battery Capacity Packet ID: 26 Data Bytes: 2, unsigned

The estimated charge capacity of Roombas battery in milliamp-hours (mAh). Range: 0 65535 mAh Wall Signal Packet ID: 27 Data Bytes: 2, unsigned

The strength of the wall signal is returned as an unsigned 16-bit value, high byte first. Range: 0-1023. Cliff Left Signal Package ID: 28 Data Bytes: 2, unsigned

The strength of the cliff left signal is returned as an unsigned 16-bit value, high byte first.

iRobot

Page 24

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Range: 0-4095 Cliff Front Left Signal Package ID: 29 Data Bytes 2, unsigned

The strength of the cliff front left signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Cliff Front Right Signal Package ID: 30 Data Bytes 2, unsigned

The strength of the cliff front right signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Cliff Right Signal Package ID: 31 Data Bytes 2, unsigned

The strength of the cliff right signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Unused Range: 0 Charging Sources Available Packet ID: 34 Data Bytes 1, unsigned Packet ID: 32-33 Data Bytes, 3

Roombas connection to the Home Base and Internal Charger are returned as individual bits, as below. Range: 0-3 1 = charging source present and powered; 0 = charging source not present or not powered.

OI Mode

Packet ID: 35

Data Bytes 1, unsigned

The current OI mode is returned. See table below. Range: 0-3

Song Number The currently selected OI song is returned. Range: 0-15 Packet ID: 36 Data Bytes 1, unsigned

iRobot

Page 25

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Song Playing

Packet ID: 37

Data Bytes 1, unsigned

The state of the OI song player is returned. 1 = OI song currently playing; 0 = OI song not playing. Range: 0-1 Number of Stream Packets The number of data stream packets is returned. Range: 0-108 Requested Velocity Packet ID: 39 Data Bytes 2, signed Packet ID: 38 Data Bytes 1, unsigned

The velocity most recently requested with a Drive command is returned as a signed 16-bit number, high byte first. Range: -500 - 500 mm/s Requested Radius Packet ID: 40 Data Bytes 2, signed

The radius most recently requested with a Drive command is returned as a signed 16-bit number, high byte first. Range: -32768 - 32767 mm Requested Right Velocity Packet ID: 41 Data Bytes 2, signed

The right wheel velocity most recently requested with a Drive Direct command is returned as a signed 16-bit number, high byte first. Range: -500 - 500 mm/s Requested Left Velocity Packet ID: 42 Data Bytes 2, signed

The left wheel velocity most recently requested with a Drive Direct command is returned as a signed 16bit number, high byte first. Range: -500 - 500 mm/s Right Encoder Counts Packet ID: 43 Data Bytes 2, unsigned

The cumulative number of raw right encoder counts is returned as an unsigned 16-bit number, high byte first. This number will roll over to 0 after it passes 65535. Range: 0 - 65535 Left Encoder Counts Packet ID: 44 Data Bytes 2, unsigned

The cumulative number of raw left encoder counts is returned as an unsigned 16-bit number, high byte first. This number will roll over to 0 after it passes 65535. Range: 0 - 65535

iRobot

Page 26

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Light Bumper

Package ID: 45

Data Bytes 1, unsigned

The light bumper detections are returned as individual bits.

Range: 0-127 Light Bump Left Signal Package ID: 46 Data Bytes 2, unsigned

The strength of the light bump left signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Light Bump Front Left Signal Package ID: 47 Data Bytes 2, unsigned

The strength of the light bump front left signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Light Bump Center Left Signal Package ID: 48 Data Bytes 2, unsigned

The strength of the light bump center left signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Light Bump Center Right Signal Package ID: 49 Data Bytes 2, unsigned

The strength of the light bump center right signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Light Bump Front Right Signal Package ID: 50 Data Bytes 2, unsigned

The strength of the light bump front right signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Light Bump Right Signal Package ID: 51 Data Bytes 2, unsigned

The strength of the light bump right signal is returned as an unsigned 16-bit value, high byte first. Range: 0-4095 Left Motor Current Packet ID: 54 Data Bytes: 2, signed

This returns the current being drawn by the left wheel motor as an unsigned 16 bit value, high byte first. Range: -32768 32767 mA

iRobot

Page 27

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Right Motor Current

Packet ID: 55

Data Bytes: 2, signed

This returns the current being drawn by the right wheel motor as an unsigned 16 bit value, high byte first. Range: -32768 32767 mA Main Brush Motor Current Packet ID: 56 Data Bytes: 2, signed

This returns the current being drawn by the main brush motor as an unsigned 16 bit value, high byte first. Range: -32768 32767 mA Side Brush Motor Current Packet ID: 57 Data Bytes: 2, signed

This returns the current being drawn by the side brush motor as an unsigned 16 bit value, high byte first. Range: -32768 32767 mA Stasis Packet ID: 58 Data Bytes: 1

The stasis caster sensor returns 1 when the robot is making forward progress and 0 when it is not. This always returns 0 when the robot is turning, driving backward, or not driving. Range: 0 1

iRobot

Page 28

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Roomba Open Interface Commands Quick Reference

LED Data Bytes 1: LED Bits (0 255) Home and Spot use green LEDs: 0 = off, 1 = on Check Robot uses an orange LED. Debris uses a blue LED.

iRobot

Page 29

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Clean/Power LED The Clean/Power LED uses a bicolor (red/green) LED. The intensity and color of this LED can be controlled with 8-bit resolution. Clean/Power LED Color (0 255) 0 = green, 255 = red. Intermediate values are intermediate colors (orange, yellow, etc). Clean/Power LED Intensity (0 255) 0 = off, 255 = full intensity. Intermediate values are intermediate intensities. Weekday LED Bits

Scheduling LED Bits

Digit N Bits

Buttons

Table of ASCII codes

\ { }

iRobot

Page 30

www.irobot.com

Baud Codes

Note Frequencies

Set Schedule Days

iRobot

Page 31

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Motors State

iRobot

Page 32

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Roomba Open Interface Sensors Quick Reference

Roomba sends back one of 58 different sensor data packets in response to a Sensors command, depending on the value of the packet ID data byte. Some packets contain groups of other packets. The sensor values are specified below in the order in which they will be sent. Some of the sensor data values are 16 bit values. These values are sent as two bytes, high byte first. Group Packet Sizes and Contents

Bumps and Wheel Drops

Buttons

Charger Available

Overcurrents

Charging State Codes Code 0 1 2 3 4 5 Charging state Not charging Reconditioning Charging Full Charging Trickle Charging Waiting Charging Fault Condition

Open Interface Modes

iRobot

Page 33

www.irobot.com

Light Bumper

iRobot

Page 34

www.irobot.com

iRobot Roomba Open Interface (OI) Specification

Sensor Packet Membership Table

www.irobot.com

iRobot

Page 35