khepera
Class Khepera

java.lang.Object
  |
  +--khepera.Khepera

All Implemented Interfaces:

KheperaConstants

public final class Khepera

extends java.lang.Object

implements KheperaConstants

Provides a simple representation of the Khepera-robot making it easy to read the sensors and control the behaviour of the motors. Currently a Khepera base whith a Gripper and K213 Vision turret is supported. Since this class is supposed to be a simple abstraction not all of the available commands to the base and turrets have been implemented.

The wheels (motors)
The Khepera has two wheels using one motor each. These motors are reffered to as left and right wheels in this text. The speed of the robot is set at one time and will then be used whenever a motion command is issued. Each motor also has a separate motion counter which is used to put the robot in a local coordinate system.

The LEDs
On the top of the base-unit are two LEDs. These can be turned on and off and are reffered to as frontal and lateral LEDs (see below) in this text.

The IR-sensors
The robot has eight IR-sensors of which six are placed in the front and two in the back (see below). These sensors can be used both to sense obstacles (called proxy sensors in this text) and to sense bright light in the vicinity (called light sensors in this text). These sensors all return real-values in the range [0..1] where the extreme values 1 indicates bright light or a very close obstacle and 0 darkness or no obstacle.
Note that the proximity sensors are sensitive to different colors and glossyness of the obstacle. Darker objects can reduce the distance of the first sensory reading to as low as ~10 mm. The figure below shows the readings obtained from the wooden blocks in the lab environment at Department of Computer Science at Lunds University.


The gripper turret
Mounted on top of the base is optional gripper extension turret which makes the robot able to grip and lift objects either in front of or behind it. The gripper turret consists of an arm and the gripper itself. The arm can be positioned using real-values in the range [0..1] as shown below. The gripper only has two positions, open or closed, also illustrated in the figure below. Between the gripper pads is a lightbeam which can be checked to see if there is an object currently in the gripper.


The linear camera
The optional vision turret is always placed top of the robot (note that this will make the camera see different things if the gripper is placed underneath because of the elevation) and produces 64 pixels of a B/W one-dimensional image. This image can easily be read after beeing downloaded from the robot. The returned pixel values are in the real-value range [0..1] where 0 is black and 1 is white. The pixels are numbered as shown below. The field of vision is 30 degrees and at a distance of 10 cm each pixel corresponds to 1 mm on the object in front.


Deriving this class
This class has been made final to encourage the use of the class only as an abstract representation of the actual robot. This makes the usage of the class look like a reverse plug-in architecture where the robot is plugged in to different controllers.

Example:

 class MyController {

	Khepera myRobot;

	public MyController(Khepera robot) {
		myRobot=robot;

		// set the speed at which the robot will move
		myRobot.setSpeed(20d);
	}

	public void start() {
		// make the robot go forward
		myRobot.moveForward();
	}

	public static void main(String args[]) {
		Khepera robot=new Khepera("Charlie");

		try {
			// establish connection to the robot			
			robot.connect();

			// create controller and assign the robot to it
			MyController controller=new MyController(robot);	
			controller.start();

			// wait 10 seconds
			try {
				Thread.sleep(10000);
			}
			catch (InterruptedException exception) {
			}

			// close connection to the robot
			robot.disconnect();
		}
		catch (KheperaException exception) {
			System.out.println(exception);
		}
	}

 }

As you can see the robot instance is plugged into the custom controller class. Use the above class as a template when you need to implement controllers.

Version:

1.6b

Author:

Pär Spjuth

Fields inherited from interface khepera.KheperaConstants

BL10, BR10, FL10, FL45, FL90, FLED, FR10, FR45, FR90, HEADING, LLED, LOWERED, OFF, ON, RAISED, RDIAMETER, RRADIUS, TOGGLE, UNCHANGED, XPOS, YPOS

Constructor Summary

Khepera(java.lang.String robotName)
Creates a new Khepera robot representation with the given name.

Khepera(java.lang.String robotName, KheperaConnection robotConnection)
Creates a new Khepera robot representation with the given name and. connection instance.
Example:
Khepera robot=new Khepera("Charlie",new SerialConnection("/dev/modem",19200));

Method Summary

boolean	cameraPresent() Checks if a linear camera turret is mounted on the robot.
void	closeGripper() Tries to close the gripper.
void	connect() Initializes the communication with the robot and must be called before all other commands.
void	disconnect() It is recommended to always call this method at the end of a controller program to end the communication with the robot and clean up.
double	getArmPosition() Checks the current position of the gripper arm.
java.lang.String	getBIOSVersion() Returns the BIOS version of the robot.
double[]	getCameraImage() Downloads the pixels of the linear camera (assumed to be) mounted on the top of the robot.
java.lang.String	getCameraRevision() Checks the revision of the camera software.
java.lang.String	getCameraVersion() Checks the version of the camera software.
java.lang.String	getGripperRevision() Checks the revision of the gripper software.
java.lang.String	getGripperVersion() Checks the version of the gripper software.
double[]	getLightReadings() Retreives the light sensor values by downloading the from the robot.
double[]	getLocation() Returns the current local positon and heading of the robot.
java.lang.String	getName() Simple method to ge the name of the robot.
java.lang.String	getProtocolVersion() Returns the protocol version of the robot.
double[]	getProxyReadings() Retreives the proximity sensor values by downloading them from the robot.
boolean	gripperIsOpen() Checks if the gripper is currently open
boolean	gripperPresent() Checks if the robot has a gripper turret mounted.
boolean	objectInGripper() Checks the light-beam between the grippers.
void	openGripper() Tries to open the gripper.
void	reset() Puts the robot in an initial stopped position where both wheels are stopped and with both LEDs off.
void	setArmPosition(double armPosition) Moves the arm to the corresonding position.
void	setLED(int ledNr, int status) Sets the status of a LED.
void	setLocation(double x, double y, double heading) Sets the local position and heading of the robot.
void	setSpeed(int leftWheelSpeed, int rightWheelSpeed) Sets the speed at which the robot will move when given a motion command.
void	stop() Stops the robot weels.

Methods inherited from class java.lang.Object

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

Constructor Detail

Khepera

public Khepera(java.lang.String robotName,
               KheperaConnection robotConnection)

Creates a new Khepera robot representation with the given name and. connection instance.
Example:

 	Khepera robot=new Khepera("Charlie",new SerialConnection("/dev/modem",19200));
 

Parameters:

robotName - The name of your robot.

robotConnection - An instance of KheperaConnection representing the connection to your robot.

See Also:

KheperaConnection, SerialConnection, RoboWorldConnection, TestConnection

Khepera

public Khepera(java.lang.String robotName)

Creates a new Khepera robot representation with the given name. It will communicate with the robot via the serial port configured to match the lab setup at Department of Computer Sience at Lunds University.

Parameters:

robotName - The name of your robot.

See Also:

Khepera(String,KheperaConnection)

Method Detail

connect

public void connect()
             throws KheperaException

Initializes the communication with the robot and must be called before all other commands. Note that this will also put the robot in its reset state.

Throws:

KheperaException - If a communications error with the robot occurs.

See Also:

reset()

disconnect

public void disconnect()
                throws KheperaException

It is recommended to always call this method at the end of a controller program to end the communication with the robot and clean up. Note that this will also put the robot in its reset state.

Throws:

KheperaException - If a communications error with the robot occurs.

See Also:

reset()

reset

public void reset()
           throws KheperaException

Puts the robot in an initial stopped position where both wheels are stopped and with both LEDs off. The local position of the robot is set to origo.

Throws:

KheperaException - If a communications error with the robot occurs.

getName

public java.lang.String getName()

Simple method to ge the name of the robot.

Returns:

The name of the robot.

setLocation

public void setLocation(double x,
                        double y,
                        double heading)

Sets the local position and heading of the robot. If a value should be unaffected by this method set the param to UNCHANGED.

Parameters:

x - The horizontal position in millimeters.

y - The vertical position in millimeters.

heading - New heading of the robot in radians.

See Also:

KheperaConstants.XPOS, KheperaConstants.YPOS, KheperaConstants.HEADING, KheperaConstants.UNCHANGED

getLocation

public double[] getLocation()
                     throws KheperaException

Returns the current local positon and heading of the robot. The values are returned as a three-element array with values stored in the order x-coordinate, y-coordinate and heading.
Example:

 	// get the location from the robot
	double location[]=robot.getLocation();

	// put the values in appropriate variables (this not
	// necessary, only here to show how it is done)
	double xPos=location[XPOS];
 	double yPos=location[YPOS];
 	double heading=location[HEADING];
 

Returns:

The position of the robot in millimeters and the heading in radians.

See Also:

KheperaConstants.XPOS, KheperaConstants.YPOS, KheperaConstants.HEADING

getBIOSVersion

public java.lang.String getBIOSVersion()
                                throws KheperaException

Returns the BIOS version of the robot.

Returns:

The version of the robot BIOS. Note that this need not to be a numerical value (eg. RoboWorld returns BIOS version RoboWorld).

Throws:

KheperaException - If a communications error with the robot occurs.

getProtocolVersion

public java.lang.String getProtocolVersion()
                                    throws KheperaException

Returns the protocol version of the robot.

Returns:

The version of the protocol. This is useful to test if your controller will work on a specific robot.

Throws:

KheperaException - If a communications error with the robot occurs.

setSpeed

public void setSpeed(int leftWheelSpeed,
                     int rightWheelSpeed)
              throws KheperaException

Sets the speed at which the robot will move when given a motion command. There is an imbuilt protection against setting the speed above 100 mm/s.

Parameters:

speed - The speed of the motors in mm/s (the speed will be rounded to the nearest 8 mm multiple).

Throws:

KheperaException - If a communications error with the robot occurs.

See Also:

#moveForward(), #moveBackward(), #spinLeft(), #spinRight(), #turnLeft(double), #turnRight(double)

stop

public void stop()
          throws KheperaException

Stops the robot weels.

Throws:

KheperaException - If a communications error with the robot occurs.

getProxyReadings

public double[] getProxyReadings()
                          throws KheperaException

Retreives the proximity sensor values by downloading them from the robot. The higher the value of a sensor the closer the obstacle. Use the sensor constants to map the array to the actual sensors.
Example:

	// download the sensor readings
 	double proxyReadings[]=robot.getProxyReadings();

	// act using the sensor data
	if (proxyReadings[FL10]>0.5&&proxyReadings[FL10]>0.5)
		robot.stop();
	...
 

Returns:

An array of eight double values in the range [0..1] with 0 being no obstacle and 1 an obstacle is near.

Throws:

KheperaException - If a communications error with the robot occurs.

See Also:

KheperaConstants.FL90, KheperaConstants.FL45, KheperaConstants.FL10, KheperaConstants.FR10, KheperaConstants.FR45, KheperaConstants.FR90, KheperaConstants.BL10, KheperaConstants.BR10

getLightReadings

public double[] getLightReadings()
                          throws KheperaException

Retreives the light sensor values by downloading the from the robot. The higher the value of the sensor the brighter the light. Use the sensor constants to map the array to the actual sensors.
Example:

	// download the sensor readings
 	double lightReadings[]=robot.getLightReadings();

	// act using the sensor data
	if (lightReadings[FL45]>0.5)
		robot.turnLeft(0.7);
	if (lightReadings[FR45]>0.5)
		robot.turnRight(0.7);
	...
 

Throws:

KheperaException - If a communications error with the robot occurs.

See Also:

KheperaConstants.FL90, KheperaConstants.FL45, KheperaConstants.FL10, KheperaConstants.FR10, KheperaConstants.FR45, KheperaConstants.FR90, KheperaConstants.BL10, KheperaConstants.BR10

setLED

public void setLED(int ledNr,
                   int status)
            throws KheperaException

Sets the status of a LED. Use the LEDs to indicate different modes of your robot controller.
Example:

	// turn on the frontal LED
	robot.setLED(FLED,ON);
 

Parameters:

ledNr - Selects the LED to be affected.

active - Sets the status of the selected LED.

Throws:

KheperaException - If a communications error with the robot occurs.

See Also:

KheperaConstants.FLED, KheperaConstants.LLED, KheperaConstants.ON, KheperaConstants.OFF, KheperaConstants.TOGGLE, LEDController

cameraPresent

public boolean cameraPresent()

Checks if a linear camera turret is mounted on the robot.

Returns:

true if the robot has a K213 linear camera mounted, false otherwise.

getCameraVersion

public java.lang.String getCameraVersion()
                                  throws KheperaException

Checks the version of the camera software.

Throws:

KheperaException - If a communications error with the robot occurs.

getCameraRevision

public java.lang.String getCameraRevision()
                                   throws KheperaException

Checks the revision of the camera software.

Throws:

KheperaException - If a communications error with the robot occurs.

getCameraImage

public double[] getCameraImage()
                        throws KheperaException

Downloads the pixels of the linear camera (assumed to be) mounted on the top of the robot.

Returns:

An array of 64 real values in the range [0..1] where 0 is pitch black and 1 is bright white.

Throws:

KheperaException - If a communications error with the robot occurs.

gripperPresent

public boolean gripperPresent()

Checks if the robot has a gripper turret mounted.

Returns:

true if a gripper extension turret is mounted on the robot, false otherwise.

getGripperVersion

public java.lang.String getGripperVersion()
                                   throws KheperaException

Checks the version of the gripper software.

Returns:

A string representing the version of the gripper software.

Throws:

KheperaException - If a communications error with the robot occurs.

getGripperRevision

public java.lang.String getGripperRevision()
                                    throws KheperaException

Checks the revision of the gripper software.

Throws:

KheperaException - If a communications error with the robot occurs.

openGripper

public void openGripper()
                 throws KheperaException

Tries to open the gripper. Use this command carefully since the motors will spin forever if the gripper can not reach its outer position (eg. when the gripper is pressed down to the ground).

Throws:

KheperaException - If a communications error with the robot occurs.

closeGripper

public void closeGripper()
                  throws KheperaException

Tries to close the gripper. Do not try to force a stronger grip by calling this method several times. Such an operation can cause physical damage to the gripper.

Throws:

KheperaException - If a communications error with the robot occurs.

objectInGripper

public boolean objectInGripper()
                        throws KheperaException

Checks the light-beam between the grippers.

Returns:

true if an object breaks the beam inside the gripper (which should mean there is something to grip), false otherwise.

Throws:

KheperaException - If a communications error with the robot occurs.

setArmPosition

public void setArmPosition(double armPosition)
                    throws KheperaException

Moves the arm to the corresonding position. Use this method carefully since some positions can cause damage to the gripper if used carelessly.
Example:

	// make the robot ready to pick up an object in front
	robot.setArmPosition(LOWERED);
 

Parameters:

armPosition - A value in the range [0..1] where 1 is all way in front and 0 is all the way back.

Throws:

KheperaException - If a communications error with the robot occurs.

See Also:

KheperaConstants.LOWERED, KheperaConstants.RAISED

gripperIsOpen

public boolean gripperIsOpen()
                      throws KheperaException

Checks if the gripper is currently open

Returns:

true if the gripper is open, false otherwise.

Throws:

KheperaException - If a communications error with the robot occurs.

getArmPosition

public double getArmPosition()
                      throws KheperaException

Checks the current position of the gripper arm.

Returns:

The current position of the gripper arm corresponding to a real-value in the range [0..1] where 1 is all way in front and 0 is all the way back.

Throws:

KheperaException - If a communications error with the robot occurs.