Roomba
Public Types | Public Member Functions
Roomba Class Reference

Support for iRobot Roomba and Create platforms via serial port using the iRobot Open Interface (OI) protocol. More...

#include <Roomba.h>

List of all members.

Public Types

enum  Baud {
  Baud300 = 0, Baud600 = 1, Baud1200 = 2, Baud2400 = 3,
  Baud4800 = 4, Baud9600 = 5, Baud14400 = 6, Baud19200 = 7,
  Baud28800 = 8, Baud38400 = 9, Baud57600 = 10, Baud115200 = 11
}
enum  Demo {
  DemoAbort = -1, DemoCover = 0, DemoCoverAndDock = 1, DemoSpotCover = 2,
  DemoMouse = 3, DemoDriveFigureEight = 4, DemoWimp = 5, DemoHome = 6,
  DemoTag = 7, DemoPachelbel = 8, DemoBanjo = 9
}
enum  Drive { DriveStraight = 0x8000, DriveInPlaceClockwise = 0xFFFF, DriveInPlaceCounterClockwise = 0x0001 }
enum  StreamCommand { StreamCommandPause = 0, StreamCommandResume = 1 }
enum  EventType {
  EventTypeWheelDrop = 1, EventTypeFronWheelDrop = 2, EventTypeLeftWheelDrop = 3, EventTypeRightWheelDrop = 4,
  EventTypeBump = 5, EventTypeLeftBump = 6, EventTypeRightBump = 7, EventTypeVirtualWall = 8,
  EventTypeWall = 9, EventTypeCliff = 10, EventTypeLeftCliff = 11, EventTypeFrontLeftCliff = 12,
  EventTypeFrontRightCliff = 13, EventTypeRightCliff = 14, EventTypeHomeBase = 15, EventTypeAdvanceButton = 16,
  EventTypePlayButton = 17, EventTypeDigitalInput0 = 18, EventTypeDigitalInput1 = 19, EventTypeDigitalInput2 = 20,
  EventTypeDigitalInput3 = 21, EventTypeModePassive = 22
}
enum  IRCommand {
  IRCommandLeft = 129, IRCommandForward = 130, IRCommandRight = 131, IRCommandSpot = 132,
  IRCommandMax = 133, IRCommandSmall = 134, IRCommandMedium = 135, IRCommandLargeClean = 136,
  IRCommandPause = 137, IRCommandPower = 138, IRCommandArcForwardLeft = 139, IRCommandArcForwardRight = 140,
  IRCommandDriveStop = 141, IRCommandSendAll = 142, IRCommandSeekDock = 143, IRCommandReserved1 = 240,
  IRCommandRedBuoy = 248, IRCommandGreenBuoy = 244, IRCommandForceField = 242, IRCommandRedGreenBuoy = 252,
  IRCommandRedBuoyForceField = 250, IRCommandGreenBuoyForceField = 246, IRCommandRedGreenBuoyForceField = 254
}
enum  ChargeState {
  ChargeStateNotCharging = 0, ChargeStateReconditioningCharging = 1, ChargeStateFullChanrging = 2, ChargeStateTrickleCharging = 3,
  ChargeStateWaiting = 4, ChargeStateFault = 5
}
enum  Mode { ModeOff = 0, ModePassive = 1, ModeSafe = 2, ModeFull = 3 }
enum  Sensor {
  Sensors7to26 = 0, Sensors7to16 = 1, Sensors17to20 = 2, Sensors21to26 = 3,
  Sensors27to34 = 4, Sensors35to42 = 5, Sensors7to42 = 6, SensorBumpsAndWheelDrops = 7,
  SensorWall = 8, SensorCliffLeft = 9, SensorCliffFrontLeft = 10, SensorCliffFrontRight = 11,
  SensorCliffRight = 12, SensorVirtualWall = 13, SensorOvercurrents = 14, SensorIRByte = 17,
  SensorButtons = 18, SensorDistance = 19, SensorAngle = 20, SensorChargingState = 21,
  SensorVoltage = 22, SensorCurrent = 23, SensorBatteryTemperature = 24, SensorBatteryCharge = 25,
  SensorBatteryCapacity = 26, SensorWallSignal = 27, SensoCliffLeftSignal = 28, SensoCliffFrontLeftSignal = 29,
  SensoCliffFrontRightSignal = 30, SensoCliffRightSignal = 31, SensorUserDigitalInputs = 32, SensorUserAnalogInput = 33,
  SensorChargingSourcesAvailable = 34, SensorOIMode = 35, SensorSongNumber = 36, SensorSongPlaying = 37,
  SensorNumberOfStreamPackets = 38, SensorVelocity = 39, SensorRadius = 40, SensorRightVelocity = 41,
  SensorLeftVelocity = 42
}

Public Member Functions

 Roomba (HardwareSerial *serial=&Serial, Baud baud=Baud57600)
void reset ()
void start ()
uint32_t baudCodeToBaudRate (Baud baud)
void baud (Baud baud)
void safeMode ()
void fullMode ()
void power ()
void dock ()
void demo (Demo demo)
void cover ()
void coverAndDock ()
void spot ()
void drive (int16_t velocity, int16_t radius)
void driveDirect (int16_t leftVelocity, int16_t rightVelocity)
void leds (uint8_t leds, uint8_t powerColour, uint8_t powerIntensity)
void digitalOut (uint8_t out)
void pwmDrivers (uint8_t dutyCycle0, uint8_t dutyCycle1, uint8_t dutyCycle2)
void drivers (uint8_t out)
void sendIR (uint8_t data)
void song (uint8_t songNumber, const uint8_t *notes, int len)
void playSong (uint8_t songNumber)
void stream (const uint8_t *packetIDs, int len)
void streamCommand (StreamCommand command)
void script (const uint8_t *script, uint8_t len)
void playScript ()
void wait (uint8_t ticks)
void waitDistance (int16_t mm)
void waitAngle (int16_t degrees)
void waitEvent (EventType type)
bool getData (uint8_t *dest, uint8_t len)
bool getSensors (uint8_t packetID, uint8_t *dest, uint8_t len)
bool getSensorsList (uint8_t *packetIDs, uint8_t numPacketIDs, uint8_t *dest, uint8_t len)
bool pollSensors (uint8_t *dest, uint8_t len)
uint8_t getScript (uint8_t *dest, uint8_t len)

Detailed Description

Support for iRobot Roomba and Create platforms via serial port using the iRobot Open Interface (OI) protocol.

The iRobot Roomba and Create platforms support a serial port through which you can control and interrogate the device. The protocol implemented here conforms to the Open Interface protocol described in the iRobot Open Interface Command Reference. Not all commands are supported on both platforms. Differences are noted in the API

The Roomba and Create is equipped with a min-din serial port socket, while the Create is also equipped with a 25-pin D connector called the Cargo Bay Connector. The pins on the Cargo Bay Connector include the serial port, battery, digital inputs and outputs, and an analog input.

In order to communicate with a Roomba, you must create an instance of the Roomba class and then call its instance methods to send commmands and receive sensor messages. You can also request continuous streams of sensor data to be sent by the Roomba. The Roomba also emits messages on its serial port from time to time as described below.

Electrical Considerations

The serial port output TXD from the Roomba/Create is too weak to drive the RX serial port input of an Arduino properly. This is because of the USB-Serial converter on the Arduino: it also tries to drive the RX serial port input via a pullup resistor, but the Roomba does not have enough drive to pull the RX down below about 2.5 volts, which is insufficient to be reliably detected as a TTL serial input of 0.

Note:
Note that this problem does not affect the Serial1 Serial2 or Serial3 ports on the Mega: these ports do not have other circuitry connected to them and the Roomba can drive the serial port inputs of these ports without a problem. Its only the RX Serial port (ie the first Serial port) that is affected by this problem.

What this means is that if you intend to connect a Roomba to the standard (first) RX/TX serial port on an Arduino you MUST have additional circuitry to help drive RX on the Arduino low enough. We use a simple PNP emitter follower. Almost any small signal low power PNP will do. See the example circuit diagram. This will ensure the RX serial port input on the Arduino is pulled down to about 0.6V for reliable comms.

Other Roomba messages

When iRobot Create powers up and after a reset, it sends a message like this on its serial port:

bl-start
2006-09-12-1137-L
RDK by iRobot!
MC9S12E128
2006-11-20-1731-L
battery-current-quiescent-raw 524 battery-current-zero 510
2006-11-20-1731-L

While charging it will send a message like this each second:

bat: min 3 sec 21 mV 15558 mA 1491 deg-C 24

To enter the factory test menu for the IRobot Create, hold down the (>) and (>>|) buttons then press and hold the Power button until the assending and descending tones play and then stop. You wil see some messages emitted on teh serial port. Press the right-right arrow button to cycle through the tests.


Member Enumeration Documentation

Demo types to pass to Roomba::baud()

Values for sensor packet ID 21

Demo types to pass to Roomba::demo()

Special values for radius in Roomba::drive()

Values to pass to Roomba::waitEvent()

Values for sensor packet ID 27

Values for sensor packet ID 35

Values for sensor packet IDs to pass to getSensors() and getSensorsList()

Values to pass to Roomba::streamCommand()


Constructor & Destructor Documentation

Roomba::Roomba ( HardwareSerial *  serial = &Serial,
Baud  baud = Baud57600 
)

Constructor. You can have multiple simultaneous Roomba if that makes sense.

Parameters:
[in]serialPOinter to the HardwareSerial port to use to communicate with the Roomba. Defaults to &Serial
[in]baudthe baud rate to use on the serial port. Defaults to 57600, the default for the Roomba.

References baudCodeToBaudRate().


Member Function Documentation

void Roomba::baud ( Baud  baud)

Changes the baud rate Baud is on of the Roomba::Baud enums

References baudCodeToBaudRate().

uint32_t Roomba::baudCodeToBaudRate ( Baud  baud)

Converts the specified baud code into a baud rate in bits per second

Parameters:
[in]baudBaud code, one of Roomba::Baud
Returns:
baud rate in bits per second

Referenced by baud(), and Roomba().

void Roomba::cover ( )

Starts the Cover demo Changes mode to Passive

void Roomba::coverAndDock ( )

Starts the Cover and Dock demo Changes mode to Passive

void Roomba::demo ( Demo  demo)

Starts the requirested built-in demo

Parameters:
[in]demoThe demo number. One of Roomba::Demo
void Roomba::digitalOut ( uint8_t  out)

Sets the digital output pins on the Cargo Bay Connector of the Create Create only. No equivalent on Roomba.

Parameters:
[in]outMask specifiying which outputs to enable. ORed value ROOMBA_MASK_DIGITAL_OUT_*
void Roomba::dock ( )

Causes roomba to immediately seek the docking station. No equivalent for Create.

void Roomba::drive ( int16_t  velocity,
int16_t  radius 
)

Starts the Roomba driving with a specified wheel velocity and radius of turn

Parameters:
[in]velocitySpeed in mm/s (-500 to 500 mm/s)
[in]radiusRadius of the turn in mm. (-2000 to 2000 mm). Any of the special values in enum Roomba::Drive may be used instead of a radius value
void Roomba::driveDirect ( int16_t  leftVelocity,
int16_t  rightVelocity 
)

Starts the Roomba driving with a specified velocity for each wheel Create only. No equivalent on Roomba.

Parameters:
[in]leftVelocityLeft wheel velocity in mm/s (-500 to 500 mm/s)
[in]rightVelocityRight wheel velocity in mm/s (-500 to 500 mm/s)
void Roomba::drivers ( uint8_t  out)

Sets the low side drivers on or off. On the Romba, these control the 3 motors.

Parameters:
[in]outBitmask of putputs to enable. ORed value ROOMBA_MASK_DRIVER_*
void Roomba::fullMode ( )

Sets the OI to Full mode. In Full mode, the cliff and wheel drop detectors do not stop the motors: you are responsible

bool Roomba::getData ( uint8_t *  dest,
uint8_t  len 
)

Low level funciton to read len bytes of data from the Roomba Blocks untill all len bytes are read or a read timeout occurs.

Parameters:
[out]destDestination where the read data is stored. Must have at least len bytes available.
[in]lenNumber of bytes to read
Returns:
true if all len bytes were successfully read. Returns false in the case of a timeout on reading any byte.

Referenced by getSensors(), and getSensorsList().

uint8_t Roomba::getScript ( uint8_t *  dest,
uint8_t  len 
)

Reads a the contents of the script most recently specified by a call to script(). Create only. No equivalent on Roomba.

Parameters:
[out]destDestination where the read data is stored. Must have at least len bytes available.
[in]lenThe maximum number of bytes to place in dest. If the script is actually longer than len only len bytes will be written
Returns:
The actual number of bytes in the script, even if this is more than len. By calling getScript(NULL, 0), you can determine how many bytes would be required to store the script.
bool Roomba::getSensors ( uint8_t  packetID,
uint8_t *  dest,
uint8_t  len 
)

Reads the sensor data for the specified sensor packet ID. Note that different sensor packets have different lengths, and it is the callers responsibilty to make sure len agrees with the expected length of the sensor data. See the Open Interface manual for details on sensor packet lengths. Roomba.h defines various enums and defines for decoding sensor data. Blocks untill all len bytes are read or a read timeout occurs.

Parameters:
[in]packetIDThe ID of the sensor packet to read from Roomba::Sensor
[out]destDestination where the read data is stored. Must have at least len bytes available.
[in]lenNumber of sensor data bytes to read
Returns:
true if all len bytes were successfully read. Returns false in the case of a timeout on reading any byte.

References getData().

bool Roomba::getSensorsList ( uint8_t *  packetIDs,
uint8_t  numPacketIDs,
uint8_t *  dest,
uint8_t  len 
)

Reads the sensor data for the specified set of sensor packet IDs. Note that different sensor packets have different lengths, and it is the callers responsibilty to make sure len agrees with the expected length of the sensor data. See the Open Interface manual for details on sensor packet lengths. Blocks until all len bytes are read or a read timeout occurs. Create only. No equivalent on Roomba.

Parameters:
[in]packetIDsArray of IDs from Roomba::Sensor of the sensor packets to read
[in]numPacketIDsnumber of IDs in the packetIDs array
[out]destDestination where the read data is stored. Must have at least len bytes available.
[in]lenNumber of sensor data bytes to read and store to dest.
Returns:
true if all len bytes were successfully read. Returns false in the case of a timeout on reading any byte.

References getData().

void Roomba::leds ( uint8_t  leds,
uint8_t  powerColour,
uint8_t  powerIntensity 
)

Controls the LEDs on the Create

Parameters:
[in]ledsBitmask specifying which LEDs to activate. ORed combination of ROOMBA_MASK_LED_*
[in]powerColourThe colour of the Power LED. 0 to 255. 0 = green, 255 = red, intermediate values are intermediate colours
[in]powerIntensityPower LED intensity. 0 to 255. 0 = off, 255 = full intensity
void Roomba::playScript ( )

Executes a previously defined script, the last one specified by script() Create only. No equivalent on Roomba.

void Roomba::playSong ( uint8_t  songNumber)

Plays a song that has previously been defined by song()

Parameters:
[in]songNumberThe song number to play. 0 to 15
bool Roomba::pollSensors ( uint8_t *  dest,
uint8_t  len 
)

Polls the serial input for data belonging to a sensor data stream previously requested with stream(). As sensor data is read it is appended to dest until at most len bytes are stored there. When a complete sensor stream has been read with a correct checksum, returns true. See the Open Interface manual for details on how the sensor data will be encoded in dest. Discards characters that are not part of a stream, such as the messages the Roomba sends at startup and while charging. Create only. No equivalent on Roomba.

Parameters:
[out]destDestination where the read data is stored. Must have at least len bytes available.
[in]lenMax number of sensor data bytes to store to dest
Returns:
true when a complete stream has been read, and the checksum is correct. The sensor data (at most len bytes) will have been stored into dest, ready for the caller to decode.
void Roomba::power ( )

Puts a Roomba in sleep mode. Roomba only, no equivalent for Create.

void Roomba::pwmDrivers ( uint8_t  dutyCycle0,
uint8_t  dutyCycle1,
uint8_t  dutyCycle2 
)

Sets the duty cycle for PWM outputs on the low side drivers. These can be use for PWM driving of motors, lights etc. Create only. No equivalent on Roomba.

Parameters:
[in]dutyCycle0Duty cycle for low side driver 0. 0 to 128.
[in]dutyCycle1Duty cycle for low side driver 1. 0 to 128.
[in]dutyCycle2Duty cycle for low side driver 2. 0 to 128.
void Roomba::reset ( )

Resets the Roomba. It will emit its startup message Caution, this may take several seconds to complete

void Roomba::safeMode ( )

Sets the OI to Safe mode. In Safe mode, the cliff and wheel drop detectors work to prevent Roomba driving off a cliff

void Roomba::script ( const uint8_t *  script,
uint8_t  len 
)

Defines a command script which can later be executed with playScript(). You can clear the script by calling script(NULL, 0); Create only. No equivalent on Roomba.

Parameters:
[in]scriptArray containing a sequence of Roomba OI commands.
[in]lenLength of the script in bytes.
void Roomba::sendIR ( uint8_t  data)

Sends the requested byte out of the low side driver 1 (pin 23 on the Cargo Bay Connector). low side driver 1 can be used to drive an IR transmitter to send commands to other Roombas and Creates. Create only. No equivalent on Roomba.

Parameters:
[in]dataData byte to transmit
void Roomba::song ( uint8_t  songNumber,
const uint8_t *  notes,
int  len 
)

Defines a song which can later be played with playSong()

Parameters:
[in]songNumberSong number for this song. 0 to 15
[in]notesArray of note/duration pairs. See Open Interface manual for details. 2 bytes per note, first byte is the note and the second is the duration
[in]lenLength of notes array in bytes, so this will be twice the number of notes in the song
void Roomba::spot ( )

Starts the Spot Cover demo Changes mode to Passive

void Roomba::start ( )

Starts the Open Interface and sets the mode to Passive. You must send this before sending any other commands. Initialises the serial port to the baud rate given in the constructor

void Roomba::stream ( const uint8_t *  packetIDs,
int  len 
)

Requests that a stream of sensor data packets be sent by the Roomba. See the Open Interface manual for details on the resutting data. The packets will be sent every 15ms. You can use pollSensors() to receive sensor data streams. Create only. No equivalent on Roomba. See the Open Interface maual for more details and limitations.

Parameters:
[in]packetIDsArray specifying sensor packet IDs from Roomba::Sensor to be sent.
[in]lenNumber of IDs in packetIDs
void Roomba::streamCommand ( StreamCommand  command)

Pause or resume a stream of sensor data packets previously requested by stream() Create only. No equivalent on Roomba.

Parameters:
[in]commandOne of Roomba::StreamCommand
void Roomba::wait ( uint8_t  ticks)

Tells the Roomba to wait for a specified time. This command is intended for use in scripting only. Create only. No equivalent on Roomba.

Parameters:
[in]ticksThe number of ticks to wait. Each tick is 15ms
void Roomba::waitAngle ( int16_t  degrees)

Causes Roomba to wait until it has rotated through the specified angle. Roomba will not react to any inputs until the wait has completed. Note that this does not cause the host arduino to wait, it only sends the wait comman to the Roomba This command is intended for use in scripting only. Create only. No equivalent on Roomba.

Parameters:
[in]degreesAngle to wait for in degrees
void Roomba::waitDistance ( int16_t  mm)

Causes Roomba to wait until it has travelled the distance specified. Roomba will not react to any inputs until the wait has completed. Note that this does not cause the host arduino to wait, it only sends the wait comman to the Roomba This command is intended for use in scripting only. Create only. No equivalent on Roomba.

Parameters:
[in]mmDistance to wait for in mm
void Roomba::waitEvent ( EventType  type)

Cause the Create to wait for a specified event. Roomba will not react to any inputs until the wait has completed. Note that this does not cause the host arduino to wait, it only sends the wait comman to the Roomba Create only. No equivalent on Roomba.

Parameters:
[in]typeEvent type to wait for. One of Roomba::EventType

The documentation for this class was generated from the following files: