roombacomm
Class RoombaComm

java.lang.Object
  roombacomm.RoombaComm

Direct Known Subclasses:

RoombaCommSerial

public abstract class RoombaComm
extends java.lang.Object

The abstract base for all Roomba communications.

Overview

This class contains the communications layer-independent parts of how to communicate with a Roomba. It does assume a very serial port-like interaction, as the only working subclass is for serial ports. Thus, this objects form may change in the future. Standard lifecyle of this object (and its subclasses)

   RoombaComm roomba = new RoombaCommSubClass();  // (e.g. RoombaCommSerial)
   roomba.listports();               // if implemented
   roomba.connect("someportid");
   roomba.startup();
   roomba.updateSensors();
   while( ... ) {
      roomba.sensors();
      roomba.playNote( 53, 12 );
      roomba.goForward( 400 );
      roomba.spinRight( 45 );
      if( roomba.bump() ) roomba.goBackward( 100 );
   }    
   roomba.disconnect();
 

API levels

Describe different API levels

Sensor Functions

Describe sensor functions

Sublass behavior

Describe subclassing strategries

Field Summary

boolean	debug turns on/off various debugging messages
static int	defaultSensorsUpdateTime default update time in ms for auto sensors update
static int	defaultSpeed default speed for movement operations if speed isn't specified
static float	millimetersPerDegree mm/deg is circumference distance divided by 360 degrees
static float	millimetersPerRadian mm/rad is a circumference distance divied by two pi
int	speed current speed for movement operations that don't take a speed
static java.lang.String	VERSION version of the library
static int	wheelbase distance between wheels on the roomba, in millimeters

Constructor Summary

RoombaComm()

RoombaComm(boolean autoUpdate)

RoombaComm(boolean autoUpdate, int updateTime)

Method Summary

short	angle() Angle traveled since last requested units: mm, diff in distance traveled by two drive wheels range: -32768 - 32767
float	angleInDegrees() angle since last read, but in degrees
float	angleInRadians() angle since last read, but in radians
java.lang.String	binary(int i)
boolean	bump() Did we bump into anything
boolean	bumpLeft() Left bump sensor
boolean	bumpRight() Right bump sensor
int	bumps_wheeldrops() lower-level func, returns raw byte
int	buttons() lower-level func, returns raw byte
int	capacity() Estimated charge capacity of battery units: mAh range: 0-65535
int	charge() Current charge of battery units: mAh range: 0-65535
int	charging_state() Charging state units: enumeration range:
void	clean() Send the CLEAN command
boolean	cleanButton() 'Clean' button pressed state
int	cliff_frontleft() lower-level func, returns raw byte
int	cliff_frontright() lower-level func, returns raw byte
int	cliff_left() lower-level func, returns raw byte
int	cliff_right() lower-level func, returns raw byte
boolean	cliffFrontLeft() front left cliff sensor
boolean	cliffFrontRight() front right cliff sensor
boolean	cliffLeft() left cliff sensor
boolean	cliffRight() right cliff sensor
boolean	computeSafetyFault() Compute possible safety fault.
abstract boolean	connect(java.lang.String portid) Connect to a port (for serial, portid is serial port name, for net, portid is url?)
boolean	connected() Returns current connected state.
void	control() Send CONTROL command
void	createSong(int songnum, int[] song) Make a song
void	createSong(int songnum, Note[] song) Make a song
short	current() Current flowing in or out of battery units: mA range: -332768 - 32767
void	delay(int millis) Alias to pause
int	dirt_left()
int	dirt_right()
boolean	dirt()
int	dirtLeft() amount of dirt seen by left dirt sensor
int	dirtRight() amount of dirt seen by right dirt sensor
abstract void	disconnect() Disconnect from a port, clean up any memory in use
short	distance() Distance traveled since last requested units: mm range: -32768 - 32767
void	drive(int velocity, int radius) Move the Roomba via the low-level velocity + radius method.
void	errorMessage(java.lang.String where, java.lang.Throwable e) General error reporting, all corraled here just in case I think of something slightly more intelligent to do.
void	full() Send FULL command
int	getSpeed() Get speed for movement commands
void	goBackward() Go backward at the current (negative) speed
void	goBackward(int distance)
void	goBackwardAt(int aspeed) Go backward at a specified speed
void	goForward() Go forward the current (positive) speed
void	goForward(int distance)
void	goForwardAt(int aspeed) Go forward at a specified speed
void	goStraight(int distance) Go straight at the current speed for a specified distance.
void	goStraightAt(int velocity) Go straight at a specified speed.
java.lang.String	hex(byte b)
java.lang.String	hex(int i)
abstract java.lang.String[]	listPorts() List available ports
void	logmsg(java.lang.String msg) just a little debug
void	max() Send the max command
boolean	maxButton() 'Max' button pressed state
int	mode() current SCI mode RoombaComm thinks the Roomba is in
java.lang.String	modeAsString() mode as String
int	motor_overcurrents() lower-level func, returns raw byte
boolean	motorOvercurrentDriveLeft() overcurrent on left drive wheel
boolean	motorOvercurrentDriveRight() overcurrent on right drive wheel
boolean	motorOvercurrentMainBrush() overcurrent on main brush
boolean	motorOvercurrentSideBrush() overcurrent on side brush
boolean	motorOvercurrentVacuum() overcurrent on vacuum
void	pause(int millis) Just a simple pause function.
void	playNote(int note, int duration) Play a musical note Does it via the hacky method of defining a one-note song & playing it Uses up song slot 15.
void	playSong(int songnum)
boolean	powerButton() 'Power' button pressed state
void	powerOff() Power off the Roomba.
void	println(java.lang.String s)
int	remote_opcode() lower-level func, returns raw byte
void	reset() Reset Roomba after a fault.
void	safe() Send SAFE command
boolean	safetyFault()
abstract boolean	send(byte[] bytes) Send given byte array to Roomba.
abstract boolean	send(int b) Send a single byte to the Roomba (defined as int because of stupid java signed bytes)
void	sensors() get all sensor data
void	sensors(int packetcode) Send the SENSORS command with one of the SENSORS_ arguments Typically, one does "sensors(SENSORS_ALL)" to get all sensor data
java.lang.String	sensorsAsString()
boolean	sensorsAutoUpdate()
int	sensorsUpdateTime()
boolean	sensorsValid()
void	setLEDs(boolean status_green, boolean status_red, boolean spot, boolean clean, boolean max, boolean dirt, int power_color, int power_intensity) Turns on/off the various LEDs.
void	setMotors(boolean mainbrush, boolean vacuum, boolean sidebrush) Turns on/off the non-drive motors (main brush, vacuum, sidebrush).
void	setSensorsAutoUpdate(boolean b)
void	setSensorsUpdateTime(int i)
void	setSpeed(int s) Set speed for movement commands
void	spin(int angle) Spin right or spin left a particular number of degrees
void	spinLeft() Spin in place anti-clockwise, at the current speed
void	spinLeft(int angle) Spin left a specified angle at a specified speed
void	spinLeftAt(int aspeed) Spin in place anti-clockwise, at the current speed.
void	spinRight() Spin in place clockwise, at the current speed
void	spinRight(int angle) Spin right the current speed for a specified angle
void	spinRightAt(int aspeed) Spin in place clockwise, at the current speed.
void	spot() Send the SPOT command
boolean	spotButton() 'Spot' button pressed state
void	start() Send START command
void	startAutoUpdate()
void	startup() Put Roomba in safe mode.
void	stop() Stop Rooomba's motion.
byte	temperature() temperature of battery units: degrees Celcius range: -128 - 127
static short	toShort(byte hi, byte lo)
static int	toUnsignedShort(byte hi, byte lo)
void	turn(int radius)
void	turnLeft()
void	turnRight()
abstract boolean	updateSensors() Query Roomba for sensor status and sync its state with this object's Subclasses should query Roomba and fill up 'sensor_bytes' with the full sensor data set If a RooombaComm object is constructed with 'autoUpdate' true, calling this method is not required because a separate thread is created to do sensor updating.
void	vacuum(boolean state) Turn all vacuum motors on or off according to state
int	virtual_wall() lower-level func, returns raw byte
int	voltage() Voltage of battery units: mV range: 0 - 65535
void	wakeup() Wake's Roomba up, if possible, thus optional To wake up the Roomba requires twiddling its DD line, often hooked up to the RS-232 DTR line, which may not be available in some implementations
boolean	wall() Can we see a wall?
boolean	wheelDropCenter() Center wheeldrop sensor
boolean	wheelDropLeft() Left wheeldrop sensor
boolean	wheelDropRight() Right wheeldrop sensor

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSION

public static final java.lang.String VERSION

version of the library

See Also:

Constant Field Values

debug

public boolean debug

turns on/off various debugging messages

wheelbase

public static final int wheelbase

distance between wheels on the roomba, in millimeters

See Also:

Constant Field Values

millimetersPerDegree

public static final float millimetersPerDegree

mm/deg is circumference distance divided by 360 degrees

See Also:

Constant Field Values

millimetersPerRadian

public static final float millimetersPerRadian

mm/rad is a circumference distance divied by two pi

See Also:

Constant Field Values

defaultSpeed

public static final int defaultSpeed

default speed for movement operations if speed isn't specified

See Also:

Constant Field Values

defaultSensorsUpdateTime

public static final int defaultSensorsUpdateTime

default update time in ms for auto sensors update

See Also:

Constant Field Values

speed

public int speed

current speed for movement operations that don't take a speed

Constructor Detail

RoombaComm

public RoombaComm()

RoombaComm

public RoombaComm(boolean autoUpdate)

RoombaComm

public RoombaComm(boolean autoUpdate,
                  int updateTime)

Method Detail

startAutoUpdate

public void startAutoUpdate()

listPorts

public abstract java.lang.String[] listPorts()

List available ports

Returns:

a list available portids, if applicable or empty set if no ports, or return null if list is not enumerable

connect

public abstract boolean connect(java.lang.String portid)

Connect to a port (for serial, portid is serial port name, for net, portid is url?)

Returns:

true on successful connect, false otherwise

disconnect

public abstract void disconnect()

Disconnect from a port, clean up any memory in use

send

public abstract boolean send(byte[] bytes)

Send given byte array to Roomba.

Parameters:

bytes - byte array of SCI commands to send

Returns:

true on successful send

send

public abstract boolean send(int b)

Send a single byte to the Roomba (defined as int because of stupid java signed bytes)

Parameters:

b - byte of an SCI command to send

Returns:

true on successful send

updateSensors

public abstract boolean updateSensors()

Query Roomba for sensor status and sync its state with this object's Subclasses should query Roomba and fill up 'sensor_bytes' with the full sensor data set If a RooombaComm object is constructed with 'autoUpdate' true, calling this method is not required because a separate thread is created to do sensor updating.

Returns:

true on successful sensor update, false otherwise

wakeup

public void wakeup()

Wake's Roomba up, if possible, thus optional To wake up the Roomba requires twiddling its DD line, often hooked up to the RS-232 DTR line, which may not be available in some implementations

startup

public void startup()

Put Roomba in safe mode. As opposed to full mode. Safe mode is the preferred working state when playing with the Roomba as it provides some measure of autonomous self-preservation if it encounters a cliff or is picked up If that happens it goes into passive mode and must be 'reset()'.

See Also:

reset()

reset

public void reset()

Reset Roomba after a fault. This takes it out of whatever mode it was in and puts it into safe mode. This command also syncs the object's sensor state with the Roomba's by calling updateSensors()

See Also:

startup(), updateSensors()

start

public void start()

Send START command

control

public void control()

Send CONTROL command

safe

public void safe()

Send SAFE command

full

public void full()

Send FULL command

powerOff

public void powerOff()

Power off the Roomba. Once powered off, the only way to wake it is via wakeup() (if implemented) or via a physically pressing the Power button

See Also:

wakeup()

spot

public void spot()

Send the SPOT command

clean

public void clean()

Send the CLEAN command

max

public void max()

Send the max command

sensors

public void sensors(int packetcode)

Send the SENSORS command with one of the SENSORS_ arguments Typically, one does "sensors(SENSORS_ALL)" to get all sensor data

Parameters:

packetcode - one of SENSORS_ALL, SENSORS_PHYSICAL, SENSORS_INTERNAL, or SENSORS_POWER

sensors

public void sensors()

get all sensor data

delay

public void delay(int millis)

Alias to pause

See Also:

pause(int)

pause

public void pause(int millis)

Just a simple pause function. Makes the thread block with Thread.sleep()

Parameters:

millis - number of milliseconds to wait

stop

public void stop()

Stop Rooomba's motion. Sends drive(0,0)

setSpeed

public void setSpeed(int s)

Set speed for movement commands

getSpeed

public int getSpeed()

Get speed for movement commands

goStraight

public void goStraight(int distance)

Go straight at the current speed for a specified distance. Positive distance moves forward, negative distance moves backward. This method blocks until the action is finished.

Parameters:

distance - distance in millimeters, positive or negative

goForward

public void goForward(int distance)

Parameters:

distance - distance in millimeters, positive

goBackward

public void goBackward(int distance)

Parameters:

distance - distance in millimeters, positive

turnLeft

public void turnLeft()

turnRight

public void turnRight()

turn

public void turn(int radius)

spin

public void spin(int angle)

Spin right or spin left a particular number of degrees

Parameters:

angle - angle in degrees, positive to spin left, negative to spin right

spinRight

public void spinRight(int angle)

Spin right the current speed for a specified angle

Parameters:

angle - angle in degrees, positive

spinLeft

public void spinLeft(int angle)

Spin left a specified angle at a specified speed

Parameters:

angle - angle in degrees, positive

spinLeft

public void spinLeft()

Spin in place anti-clockwise, at the current speed

spinRight

public void spinRight()

Spin in place clockwise, at the current speed

spinLeftAt

public void spinLeftAt(int aspeed)

Spin in place anti-clockwise, at the current speed.

Parameters:

aspeed - speed to spin at

spinRightAt

public void spinRightAt(int aspeed)

Spin in place clockwise, at the current speed.

Parameters:

aspeed - speed to spin at, positive

goStraightAt

public void goStraightAt(int velocity)

Go straight at a specified speed. Positive is forward, negative is backward

Parameters:

velocity - velocity of motion in mm/sec

goForward

public void goForward()

Go forward the current (positive) speed

goBackward

public void goBackward()

Go backward at the current (negative) speed

goForwardAt

public void goForwardAt(int aspeed)

Go forward at a specified speed

goBackwardAt

public void goBackwardAt(int aspeed)

Go backward at a specified speed

drive

public void drive(int velocity,
                  int radius)

Move the Roomba via the low-level velocity + radius method. See the 'Drive' section of the Roomba SCI spec for more details. Low-level command.

Parameters:

velocity - speed in millimeters/second, positive forward, negative backward

radius - radius of turn in millimeters

playNote

public void playNote(int note,
                     int duration)

Play a musical note Does it via the hacky method of defining a one-note song & playing it Uses up song slot 15. If another note is played before one is finished, the new note cuts off the old one.

Parameters:

note - a note number from 31 (G0) to 127 (G8)

duration - duration of note in 1/64ths of a second

playSong

public void playSong(int songnum)

createSong

public void createSong(int songnum,
                       int[] song)

Make a song

Parameters:

songnum - number of song to define

song - array of songnotes, even entries are notenums, odd are duration of 1/6ths

createSong

public void createSong(int songnum,
                       Note[] song)

Make a song

Parameters:

songnum - number of song to define

song - array of Notes

setMotors

public void setMotors(boolean mainbrush,
                      boolean vacuum,
                      boolean sidebrush)

Turns on/off the non-drive motors (main brush, vacuum, sidebrush). Sort of low-level.

Parameters:

mainbrush - mainbrush motor on/off state

vacuum - vacuum motor on/off state

sidebrush - sidebrush motor on/off state

setLEDs

public void setLEDs(boolean status_green,
                    boolean status_red,
                    boolean spot,
                    boolean clean,
                    boolean max,
                    boolean dirt,
                    int power_color,
                    int power_intensity)

Turns on/off the various LEDs. Low-level command. FIXME: this is too complex

vacuum

public void vacuum(boolean state)

Turn all vacuum motors on or off according to state

Parameters:

state - true to turn on vacuum function, false to turn it off

computeSafetyFault

public boolean computeSafetyFault()

Compute possible safety fault. Called on every successful updateSensors(). In normal use, call updateSensors() then check safetyFault().

Returns:

true if indicates we had an event that took the Roomba out of safe mode

See Also:

updateSensors()

connected

public boolean connected()

Returns current connected state. It's up to subclasses to ensure this variable is correct.

Returns:

current connected state

mode

public int mode()

current SCI mode RoombaComm thinks the Roomba is in

modeAsString

public java.lang.String modeAsString()

mode as String

sensorsAutoUpdate

public boolean sensorsAutoUpdate()

setSensorsAutoUpdate

public void setSensorsAutoUpdate(boolean b)

sensorsUpdateTime

public int sensorsUpdateTime()

setSensorsUpdateTime

public void setSensorsUpdateTime(int i)

safetyFault

public boolean safetyFault()

sensorsValid

public boolean sensorsValid()

sensorsAsString

public java.lang.String sensorsAsString()

Returns:

all sensor data as a string

bump

public boolean bump()

Did we bump into anything

bumpLeft

public boolean bumpLeft()

Left bump sensor

bumpRight

public boolean bumpRight()

Right bump sensor

wheelDropLeft

public boolean wheelDropLeft()

Left wheeldrop sensor

wheelDropRight

public boolean wheelDropRight()

Right wheeldrop sensor

wheelDropCenter

public boolean wheelDropCenter()

Center wheeldrop sensor

wall

public boolean wall()

Can we see a wall?

dirt

public boolean dirt()

Returns:

true if dirt present

dirtLeft

public int dirtLeft()

amount of dirt seen by left dirt sensor

dirtRight

public int dirtRight()

amount of dirt seen by right dirt sensor

cliffLeft

public boolean cliffLeft()

left cliff sensor

cliffFrontLeft

public boolean cliffFrontLeft()

front left cliff sensor

cliffFrontRight

public boolean cliffFrontRight()

front right cliff sensor

cliffRight

public boolean cliffRight()

right cliff sensor

motorOvercurrentDriveLeft

public boolean motorOvercurrentDriveLeft()

overcurrent on left drive wheel

motorOvercurrentDriveRight

public boolean motorOvercurrentDriveRight()

overcurrent on right drive wheel

motorOvercurrentMainBrush

public boolean motorOvercurrentMainBrush()

overcurrent on main brush

motorOvercurrentVacuum

public boolean motorOvercurrentVacuum()

overcurrent on vacuum

motorOvercurrentSideBrush

public boolean motorOvercurrentSideBrush()

overcurrent on side brush

powerButton

public boolean powerButton()

'Power' button pressed state

spotButton

public boolean spotButton()

'Spot' button pressed state

cleanButton

public boolean cleanButton()

'Clean' button pressed state

maxButton

public boolean maxButton()

'Max' button pressed state

bumps_wheeldrops

public int bumps_wheeldrops()

lower-level func, returns raw byte

cliff_left

public int cliff_left()

lower-level func, returns raw byte

cliff_frontleft

public int cliff_frontleft()

lower-level func, returns raw byte

cliff_frontright

public int cliff_frontright()

lower-level func, returns raw byte

cliff_right

public int cliff_right()

lower-level func, returns raw byte

virtual_wall

public int virtual_wall()

lower-level func, returns raw byte

motor_overcurrents

public int motor_overcurrents()

lower-level func, returns raw byte

dirt_left

public int dirt_left()

dirt_right

public int dirt_right()

remote_opcode

public int remote_opcode()

lower-level func, returns raw byte

buttons

public int buttons()

lower-level func, returns raw byte

distance

public short distance()

Distance traveled since last requested units: mm range: -32768 - 32767

angle

public short angle()

Angle traveled since last requested units: mm, diff in distance traveled by two drive wheels range: -32768 - 32767

angleInDegrees

public float angleInDegrees()

angle since last read, but in degrees

angleInRadians

public float angleInRadians()

angle since last read, but in radians

charging_state

public int charging_state()

Charging state units: enumeration range:

voltage

public int voltage()

Voltage of battery units: mV range: 0 - 65535

current

public short current()

Current flowing in or out of battery units: mA range: -332768 - 32767

temperature

public byte temperature()

temperature of battery units: degrees Celcius range: -128 - 127

charge

public int charge()

Current charge of battery units: mAh range: 0-65535

capacity

public int capacity()

Estimated charge capacity of battery units: mAh range: 0-65535

toShort

public static final short toShort(byte hi,
                                  byte lo)

toUnsignedShort

public static final int toUnsignedShort(byte hi,
                                        byte lo)

println

public void println(java.lang.String s)

hex

public java.lang.String hex(byte b)

hex

public java.lang.String hex(int i)

binary

public java.lang.String binary(int i)

logmsg

public void logmsg(java.lang.String msg)

just a little debug

errorMessage

public void errorMessage(java.lang.String where,
                         java.lang.Throwable e)

General error reporting, all corraled here just in case I think of something slightly more intelligent to do.