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

#include <Roomba.h>

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

◆ Baud

enum Roomba::Baud

Demo types to pass to Roomba::baud()

◆ ChargeState

enum Roomba::ChargeState

Values for sensor packet ID 21

◆ Demo

enum Roomba::Demo

Demo types to pass to Roomba::demo()

◆ Drive

enum Roomba::Drive

Special values for radius in Roomba::drive()

◆ EventType

enum Roomba::EventType

Values to pass to Roomba::waitEvent()

◆ IRCommand

enum Roomba::IRCommand

Values for sensor packet ID 27

◆ Mode

enum Roomba::Mode

Values for sensor packet ID 35

◆ Sensor

enum Roomba::Sensor

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

◆ StreamCommand

enum Roomba::StreamCommand

Values to pass to Roomba::streamCommand()

Constructor & Destructor Documentation

◆ Roomba()

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

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

Parameters

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

References baudCodeToBaudRate().

Member Function Documentation

◆ baud()

void Roomba::baud ( Baud baud )

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

References baudCodeToBaudRate().

◆ baudCodeToBaudRate()

uint32_t Roomba::baudCodeToBaudRate ( Baud baud )

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

Parameters

[in] baud Baud code, one of Roomba::Baud

Returns: baud rate in bits per second

Referenced by baud(), and Roomba().

◆ cover()

void Roomba::cover ( )

Starts the Cover demo Changes mode to Passive

◆ coverAndDock()

void Roomba::coverAndDock ( )

Starts the Cover and Dock demo Changes mode to Passive

◆ demo()

void Roomba::demo ( Demo demo )

Starts the requirested built-in demo

Parameters

[in] demo The demo number. One of Roomba::Demo

◆ digitalOut()

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] out Mask specifiying which outputs to enable. ORed value ROOMBA_MASK_DIGITAL_OUT_*

◆ dock()

void Roomba::dock ( )

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

◆ drive()

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

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

Parameters

[in]	velocity	Speed in mm/s (-500 to 500 mm/s)
[in]	radius	Radius 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

◆ driveDirect()

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]	leftVelocity	Left wheel velocity in mm/s (-500 to 500 mm/s)
[in]	rightVelocity	Right wheel velocity in mm/s (-500 to 500 mm/s)

◆ drivers()

void Roomba::drivers ( uint8_t out )

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

Parameters

[in] out Bitmask of putputs to enable. ORed value ROOMBA_MASK_DRIVER_*

◆ fullMode()

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

◆ getData()

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]	dest	Destination where the read data is stored. Must have at least len bytes available.
[in]	len	Number 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().

◆ getScript()

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]	dest	Destination where the read data is stored. Must have at least len bytes available.
[in]	len	The 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.

◆ getSensors()

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]	packetID	The ID of the sensor packet to read from Roomba::Sensor
[out]	dest	Destination where the read data is stored. Must have at least len bytes available.
[in]	len	Number 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().

◆ getSensorsList()

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]	packetIDs	Array of IDs from Roomba::Sensor of the sensor packets to read
[in]	numPacketIDs	number of IDs in the packetIDs array
[out]	dest	Destination where the read data is stored. Must have at least len bytes available.
[in]	len	Number 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().

◆ leds()

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

Controls the LEDs on the Create

Parameters

[in]	leds	Bitmask specifying which LEDs to activate. ORed combination of ROOMBA_MASK_LED_*
[in]	powerColour	The colour of the Power LED. 0 to 255. 0 = green, 255 = red, intermediate values are intermediate colours
[in]	powerIntensity	Power LED intensity. 0 to 255. 0 = off, 255 = full intensity

◆ playScript()

void Roomba::playScript ( )

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

◆ playSong()

void Roomba::playSong ( uint8_t songNumber )

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

Parameters

[in] songNumber The song number to play. 0 to 15

◆ pollSensors()

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]	dest	Destination where the read data is stored. Must have at least len bytes available.
[in]	len	Max 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.

◆ power()

void Roomba::power ( )

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

◆ pwmDrivers()

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]	dutyCycle0	Duty cycle for low side driver 0. 0 to 128.
[in]	dutyCycle1	Duty cycle for low side driver 1. 0 to 128.
[in]	dutyCycle2	Duty cycle for low side driver 2. 0 to 128.

◆ reset()

void Roomba::reset ( )

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

◆ safeMode()

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

◆ script()

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]	script	Array containing a sequence of Roomba OI commands.
[in]	len	Length of the script in bytes.

◆ sendIR()

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] data Data byte to transmit

◆ song()

void Roomba::song	(	uint8_t	songNumber,
		const uint8_t *	notes,
		int	len
	)

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

Parameters

[in]	songNumber	Song number for this song. 0 to 15
[in]	notes	Array 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]	len	Length of notes array in bytes, so this will be twice the number of notes in the song

◆ spot()

void Roomba::spot ( )

Starts the Spot Cover demo Changes mode to Passive

◆ start()

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

◆ stream()

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]	packetIDs	Array specifying sensor packet IDs from Roomba::Sensor to be sent.
[in]	len	Number of IDs in packetIDs

◆ streamCommand()

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] command One of Roomba::StreamCommand

◆ wait()

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] ticks The number of ticks to wait. Each tick is 15ms

◆ waitAngle()

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] degrees Angle to wait for in degrees

◆ waitDistance()

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] mm Distance to wait for in mm

◆ waitEvent()

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] type Event type to wait for. One of Roomba::EventType

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

Roomba.h
Roomba.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Baud

◆ ChargeState

◆ Demo

◆ Drive

◆ EventType

◆ IRCommand

◆ Mode

◆ Sensor

◆ StreamCommand

Constructor & Destructor Documentation

◆ Roomba()

Member Function Documentation

◆ baud()

◆ baudCodeToBaudRate()

◆ cover()

◆ coverAndDock()

◆ demo()

◆ digitalOut()

◆ dock()

◆ drive()

◆ driveDirect()

◆ drivers()

◆ fullMode()

◆ getData()

◆ getScript()

◆ getSensors()

◆ getSensorsList()

◆ leds()

◆ playScript()

◆ playSong()

◆ pollSensors()

◆ power()

◆ pwmDrivers()

◆ reset()

◆ safeMode()

◆ script()

◆ sendIR()

◆ song()

◆ spot()

◆ start()

◆ stream()

◆ streamCommand()

◆ wait()

◆ waitAngle()

◆ waitDistance()

◆ waitEvent()