Roomba Open Interface (ROI)

From MCS Wiki
Jump to: navigation, search

The Roomba Open Interface (ROI), originally called the Serial Communications Interface (SCI) is the serial protocol used to control a Roomba or Create robot from an external device like a PC. [1]

NOTE: There is also a full description of a newly released open-interface for the Create itself, the Create Open Interface (COI). The opcodes that constitute the COI are actually a superset of ROI. Definitely worth a look. [2]

Each ROI command is begun with a single byte command opcode whose value is between 128 (0x80) and 143 (0x8F) (16 opcodes have been published, though more may actually be available). Certain commands will also have a certain number of bytes that will be taken as arguments (DRIVE, LED, etc.).

Below, we give the list of all known 16 opcodes. We also will discuss the data byte arguments that the "DRIVE" command expects. A more complete coverage of ROI is given in the book Hacking Roomba by Tod E. Kurt and on the books companion website: [3]

Command Opcodes and Data Bytes
Command Opcode Hexadecimal Value Number of Data Bytes Comments
START 128 0x80 0 Primes the roomba for accepting ROI commands
BAUD 129 0x81 1 Sets speed of data transferal in bps
CONTROL 130 0x82 0 Puts the robot in safe mode (enables control of Roomba)
SAFE 131 0x83 0 Returns the Roomba to safe mode
FULL 132 0x84 0 Put the robot in full mode
POWER 133 0x85 0 Puts roomba in sleep mode (virtual button push)
SPOT 134 0x86 0 Starts the spot cleaning algorithm
CLEAN 135 0x87 0 Starts the regular cleaning algorithm
MAX 136 0x88 0 Starts the MAX clean cleaning algorithm
DRIVE 137 0x89 4 See Below
MOTORS 138 0x8A 1 Controls Roomba's 3 cleaning motors (Main Brush, Vacuum, Side brush)
LEDS 139 0x8B 3 Allows setting the 3 LEDs
SONG 140 0x8C 2+2N Defines a song
PLAY 141 0x8D 1 Plays the stored song
SENSORS 142 0x8E 1 Allows identification of sensor packets to return
DOCK 143 0x8F 0 Causes roomba to immediately seek the docking station

The DRIVE opcode

The DRIVE opcode accepts 4 bytes of data as an argument: two for velocity and two for direction (each is treated as 16-bit signed values using two's compliment.

* Velocity: from -500 to 500 mm/s (0xFE0C to 0x01F4)
* Direction: Either a radius or some special purpose values (see below)

Possible Direction Values

* Turn on Radius: -2000 to 2000 mm (0xF830 to 0x07D0
* Straight: 32768 (0x8000)
* Spin counter-clockwise: 1 (0x0001)
* Spin clockwise: -1 (0xFFFF)

Example Over Serial

#!/bin/sh
stty -F /dev/ttyS0 57600 raw -parenb -parodd cs8 -hupcl -cstopb clocal
printf "\x80" > /dev/ttyS0                     # ROI START
sleep 2
printf "\x82" > /dev/ttyS0                     # ROI CONTROL
sleep 2
printf "\x89\x00\xc8\x80\x00" > /dev/ttyS0     # ROI DRIVE: straight
sleep 5
printf "\x89\x00\xc8\x00\x01" > /dev/ttyS0     # ROI DRIVE: spin counter-clockwise
sleep 5
printf "\x89\x01\x00\x00\xff" > /dev/ttyS0     # ROI DRIVE: faster at radius of 255mm
sleep 10
printf "\x80" > /dev/ttyS0                     # ROI START
sleep 2
printf "\x85" > /dev/ttyS0                     # ROI POWER: send to "sleep" mode
Personal tools