EDU.gatech.cc.is.abstractrobot
Interface SimpleInterface

All Known Subinterfaces:

Capture, CommN150, MultiForageN150, RescueVan, SimpleN150, SocSmall

All Known Implementing Classes:

Simple

public interface SimpleInterface

Defines the basic capabilites all robot classes should provide. A simple robot can detect obstacles, its position, and turn and move. The intention is for this interface to be implemented for several types of physical robots (e.g. Nomad 150s, Hummers, Dennings, etc.).

Frames of reference
We use a standard cartesian coordinate system in meters and radians. Pretend you are looking down on the robot: +x goes out to your right (East), +y goes up (North). When the robot is initialized, it is facing the +x direction. Headings are given in radians, with East=0, North=PI/2 and so on CCW around to 2*PI. Some methods return "egocentric" vectors. An egocentric vector is given relative to the center of the robot in the same heading reference frame as global coordinates. An object one meter east of the robot is at (1,0) egocentrically.

Sensors
The Simple robot can sense it's location and obstacles.

Timestamps
Many of the sensor and motor command methods (e.g. get* and set*) require a timestamp as a parameter. This is to help reduce the amount of I/O to the physical robot. If the timestamp is less than or equal to the value sent on the last call to one of these methods, old data is returned. If the timestamp is -1 or greater than the last timestamp, the robot is queried, and new data is returned. The idea is that during each control cycle the higher level software will increment the timestamp and use it for all calls to these methods. Copyright (c)1998 Tucker Balch

Method Summary

java.awt.Color	getBackgroundColor() Gets the background color of the robot.
TBDictionary	getDictionary() Gets the TBDictionary holding parameters defined using the "dictionary" keyword in the dsc file.
java.awt.Color	getForegroundColor() Gets the foreground color of the robot.
int	getID() Get the unique ID of the robot.
int	getID(long timestamp) Get the unique ID of the robot (>=0).
Vec2[]	getObstacles(long timestamp) Get an array of Vec2s that point egocentrically from the center of the robot to the obstacles currently sensed by the robot's sensors
Vec2	getPosition(long timestamp) Get the position of the robot in global coordinates.
double	getSteerHeading(long timestamp) Get the current heading of the steering motor.
long	getTime() Gets time elapsed since the robot was instantiated.
void	quit() Quit the robot and release any resources it has reserved.
void	resetPosition(Vec2 position) Reset the odometry of the robot in global coordinates.
void	resetSteerHeading(double heading) Reset the steering odometry of the robot in global coordinates.
void	setBaseSpeed(double speed) Set the base speed for the robot (translation) in meters per second.
void	setDictionary(TBDictionary tbd) Sets the TBDictionary for the robots.
void	setDisplayString(java.lang.String s) Set the String that is printed on the robot's display.
void	setID(int id) Set the unique ID of the robot.
void	setObstacleMaxRange(double range) Set the maximum range at which a sensor reading should be considered an obstacle.
void	setSpeed(long timestamp, double speed) Set the desired speed for the robot (translation).
void	setSteerHeading(long timestamp, double heading) Set the desired heading for the steering motor.

Method Detail

quit

public void quit()

Quit the robot and release any resources it has reserved.

getTime

public long getTime()

Gets time elapsed since the robot was instantiated. This does not necessarily match real elapsed time since it may run faster than that in simulation. This is the appropriate source of time for timestamps.

getObstacles

public Vec2[] getObstacles(long timestamp)

Get an array of Vec2s that point egocentrically from the center of the robot to the obstacles currently sensed by the robot's sensors

Parameters:

timestamp - only get new information if timestamp > than last call or == -1.

Returns:

the sensed obstacles.

setObstacleMaxRange

public void setObstacleMaxRange(double range)

Set the maximum range at which a sensor reading should be considered an obstacle. Beyond this range, the readings are ignored. The default range on startup is 1 meter.

Parameters:

range - the range in meters.

getPosition

public Vec2 getPosition(long timestamp)

Get the position of the robot in global coordinates.

Parameters:

timestamp - only get new information if timestamp > than last call or timestamp == -1.

Returns:

the position.

setID

public void setID(int id)

Set the unique ID of the robot.

Parameters:

set - the robot's ID.

Returns:

the id.

getID

public int getID(long timestamp)

Get the unique ID of the robot (>=0). This number unique, but no other guarantees are made. It is possible for instance, for four robots to be numbered 8, 9, 11, 37. To get sequential numbers for a team, use methods in the KinSensor class.

Parameters:

timestamp - only get new information if timestamp > than last call or timestamp == -1.

Returns:

the id.

getID

public int getID()

Get the unique ID of the robot.

Returns:

the id.

resetPosition

public void resetPosition(Vec2 position)

Reset the odometry of the robot in global coordinates. This might be done when reliable sensor information provides a very good estimate of the robot's location. Do this only if you are certain you're right!

Parameters:

position - the new position.

See Also:

Simple.getPosition(long)

getSteerHeading

public double getSteerHeading(long timestamp)

Get the current heading of the steering motor.

Parameters:

timestamp - only get new information if timestamp > than last call or timestamp == -1.

Returns:

the heading in radians.

See Also:

Simple.setSteerHeading(long, double)

resetSteerHeading

public void resetSteerHeading(double heading)

Reset the steering odometry of the robot in global coordinates. This might be done when reliable sensor information provides a very good estimate of the robot's heading. Do this only if you are certain you're right!

Parameters:

heading - the new heading in radians.

See Also:

Simple.getSteerHeading(long), Simple.setSteerHeading(long, double)

setSteerHeading

public void setSteerHeading(long timestamp,
                            double heading)

Set the desired heading for the steering motor.

Parameters:

heading - the heading in radians.

timestamp - only get new information if timestamp > than last call or timestamp == -1.

See Also:

Simple.getSteerHeading(long)

setSpeed

public void setSpeed(long timestamp,
                     double speed)

Set the desired speed for the robot (translation). The speed must be between 0 and 1; where 0 is stopped and 1.0 is "full blast". It will be clipped to whichever limit it exceeds. Also, underlying software will keep the actual speed at zero until the steering motor is close to the desired heading. Use setBaseSpeed to adjust the top speed.

Parameters:

timestamp - only get new information if timestamp > than last call or timestamp == -1.

speed - the desired speed from 0 to 1.0, where 1.0 is the base speed.

See Also:

Simple.setSteerHeading(long, double), Simple.setBaseSpeed(double)

setDisplayString

public void setDisplayString(java.lang.String s)

Set the String that is printed on the robot's display. For real robots, this is printed on the console. For simulated robots, this appears printed below the agent when view "Robot State" is selected.

Parameters:

s - String, the text to display.

setBaseSpeed

public void setBaseSpeed(double speed)

Set the base speed for the robot (translation) in meters per second. Base speed is how fast the robot will move when setSpeed(1.0) is called. The speed must be between 0 and MAX_TRANSLATION. It will be clipped to whichever limit it exceeds.

Parameters:

speed - the desired speed from 0 to 1.0, where 1.0 is the base speed.

See Also:

Simple.setSpeed(long, double)

getDictionary

public TBDictionary getDictionary()

Gets the TBDictionary holding parameters defined using the "dictionary" keyword in the dsc file.

setDictionary

public void setDictionary(TBDictionary tbd)

Sets the TBDictionary for the robots.

Parameters:

tbd - the dictionary to set it to

getForegroundColor

public java.awt.Color getForegroundColor()

Gets the foreground color of the robot.

getBackgroundColor

public java.awt.Color getBackgroundColor()

Gets the background color of the robot.