koala
Class Koala

java.lang.Object
  koala.Koala

All Implemented Interfaces:

KoalaLongRangeSensors, KoalaMotors, KoalaSensors

public class Koala
extends java.lang.Object
implements KoalaMotors, KoalaSensors, KoalaLongRangeSensors

Class used to control Koala functionality either from the Korebot, using JNI and libjkoala.so, or from any platform using a direct serial connection (for which the RXTX library is required). Most methods are synchronised to prevent multiple threads interleaving commands to the Koala.

Field Summary

int	WHEELRADIUS

Method Summary

void	disconnect() Disconnect from the Koala hardware.
protected void	finalize()
double	getAngularVelocity() Compute the angular velocity based on the current wheel speeds, in degrees per second.
int	getBatteryCharge() Get the battery's charge in mAh.
int	getBatteryTemperature() Get the battery's temperature in degrees Celcius.
int	getBatteryTimeLeft() Estimate the time left (in minutes) before the battery is exhausted, based on the consumption current and the battery charge.
int	getBatteryVoltage() Get the battery's voltage in mV.
int	getConsumptionCurrent() Get the consumption current in mA.
static Koala	getInstance() Get a reference to the robot.
static Koala	getInstance(java.lang.String comPort) Get a reference to the robot.
int	getLeftMotorCurrent() Get the consumption current of the left motor in mA.
int	getLeftMotorPosition() Get the current position of the left motor.
int	getLeftMotorSpeed() Get the left motor's speed.
double	getRadiusOfRotation() Get the radius of the curve the robot is currently moving along, in millimetres.
int	getRightMotorCurrent() Get the consumption current of the right motor in mA.
int	getRightMotorPosition() Get the current position of the right motor.
int	getRightMotorSpeed() Get the right motor's speed.
java.lang.String	getSoftwareVersion() Request the Koala's OS and protocol version.
int	getTemperature() Get the robot's ambient temperature in degrees Celcius.
boolean	hasLongRangeSensors() Determine if this Koala has long-range proximity sensors.
boolean	isInitialised() Check the robot is initialised.
boolean	leftMotorError() Returns true if the motion controller reports a speed or position error on the left motor.
int	moveForward(double distance) Move forward the specified distance of mm.
void	printFP(double x) Prints a double to the standard output.
KoalaSensorReading	readAmbientSensors() Read the 16 infra-red ambient light sensors.
int	readAnalogueInput(int channel) Read one of the analogue inputs.
int	readDigitalInput(int channel) Read one of the digital inputs.
int	readFrontLeftLRSensor() Read the front left long-range proximity sensor.
int	readFrontRightLRSensor() Read the front right long-range proximity sensor.
int	readLeftSideLRSensor() Read the left side long-range proximity sensor.
KoalaSensorReading	readLongRangeSensors() Read the long-range infra-red proximity sensors.
KoalaSensorReading	readProximitySensors() Read the 16 infra-red proximity (reflected light) sensors.
int	readRightSideLRSensor() Read the right side long-range proximity sensor.
boolean	rightMotorError() Returns true if the motion controller reports a speed or position error on the right motor.
int	rotate(double angle) Rotate (on the spot) by the specified angle in degrees.
void	rotate(int radius, double angle) Move along an arc specified by the radius (millimetres) and angle (degrees).
int	setDigitalOutput(int channel, int state) Set one of the digital outputs.
int	setLEDState(int ledNumber, int state) Change the state of an LED.
int	setMotorPosition(int left, int right) Set the position of the motors (their rotational position).
void	setSpeed(int radius, double angularVelocity) Set the wheel speeds given a radius (millimetres) and a desired angular velocity (degrees per second).
int	setSpeed(int left, int right) Set the motor speed.
int	turnLEDOff(int ledNumber) Turn an LED off.
int	turnLEDOn(int ledNumber) Turn an LED on.

Methods inherited from class java.lang.Object

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

Field Detail

WHEELRADIUS

public final int WHEELRADIUS

See Also:

Constant Field Values

Method Detail

getInstance

public static Koala getInstance()

Get a reference to the robot. Obviously there can only be one instance of the robot. If the operating system is Windows, it will default to accessing the Koala hardware using the COM1 serial port. On other platforms, it will default to using libjkoala.so.

getInstance

public static Koala getInstance(java.lang.String comPort)

Get a reference to the robot. Obviously there can only be one instance of the robot. This accesses the robot using the specified serial port.

Parameters:

comPort - this is the name of the serial port (eg. "COM1") to connect to the Koala hardware

isInitialised

public boolean isInitialised()

Check the robot is initialised. If not, the user should not attempt to call further methods.

disconnect

public void disconnect()

Disconnect from the Koala hardware. This is necessary on platforms which use the serial port to access the hardware. When using JNI instead, calling this function is not necessary (though harmless). The user cannot call further methods after disconnecting.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getSoftwareVersion

public java.lang.String getSoftwareVersion()

Request the Koala's OS and protocol version.

Specified by:

getSoftwareVersion in interface KoalaSensors

getTemperature

public int getTemperature()

Get the robot's ambient temperature in degrees Celcius.

Specified by:

getTemperature in interface KoalaSensors

getBatteryTemperature

public int getBatteryTemperature()

Get the battery's temperature in degrees Celcius.

Specified by:

getBatteryTemperature in interface KoalaSensors

getBatteryCharge

public int getBatteryCharge()

Get the battery's charge in mAh. This reading depends on the battery's memory, and may be incorrect.

Specified by:

getBatteryCharge in interface KoalaSensors

getBatteryTimeLeft

public int getBatteryTimeLeft()

Estimate the time left (in minutes) before the battery is exhausted, based on the consumption current and the battery charge.

Specified by:

getBatteryTimeLeft in interface KoalaSensors

getBatteryVoltage

public int getBatteryVoltage()

Get the battery's voltage in mV. Usually around 12V.

Specified by:

getBatteryVoltage in interface KoalaSensors

getConsumptionCurrent

public int getConsumptionCurrent()

Get the consumption current in mA.

Specified by:

getConsumptionCurrent in interface KoalaSensors

getLeftMotorCurrent

public int getLeftMotorCurrent()

Get the consumption current of the left motor in mA.

Specified by:

getLeftMotorCurrent in interface KoalaMotors

getRightMotorCurrent

public int getRightMotorCurrent()

Get the consumption current of the right motor in mA.

Specified by:

getRightMotorCurrent in interface KoalaMotors

setLEDState

public int setLEDState(int ledNumber,
                       int state)

Change the state of an LED. LED number 0 is the left-hand LED on the back of the robot. LED number 1 is the right-hand LED. State 0 denotes the LED being off, state 1 denotes the LED being on.

Specified by:

setLEDState in interface KoalaSensors

Returns:

0 if successful, non-zero otherwise.

turnLEDOn

public int turnLEDOn(int ledNumber)

Turn an LED on. LED number 0 is the left-hand LED on the back of the robot. Number 1 is the right-hand LED.

Specified by:

turnLEDOn in interface KoalaSensors

Returns:

0 if successful, non-zero otherwise.

turnLEDOff

public int turnLEDOff(int ledNumber)

Turn an LED off. LED number 0 is the left-hand LED on the back of the robot. Number 1 is the right-hand LED.

Specified by:

turnLEDOff in interface KoalaSensors

Returns:

0 if successful, non-zero otherwise.

setSpeed

public int setSpeed(int left,
                    int right)

Set the motor speed. The left value denotes the speed of the left motor, and the right value denotes the speed of the right motor. The speed values may be negative and a magnitude of 1 denotes a speed of 4.5mm per second.

Specified by:

setSpeed in interface KoalaMotors

Returns:

0 if successful, non-zero otherwise.

getLeftMotorSpeed

public int getLeftMotorSpeed()

Get the left motor's speed. The speed values may be negative and a magnitude of 1 denotes a speed of 4.5mm per second.

Specified by:

getLeftMotorSpeed in interface KoalaMotors

getRightMotorSpeed

public int getRightMotorSpeed()

Get the right motor's speed. The speed values may be negative and a magnitude of 1 denotes a speed of 4.5mm per second.

Specified by:

getRightMotorSpeed in interface KoalaMotors

setMotorPosition

public int setMotorPosition(int left,
                            int right)

Set the position of the motors (their rotational position). A value of 1 on each wheel corresponds to moving forward by 0.045mm.

Specified by:

setMotorPosition in interface KoalaMotors

Specified by:

setMotorPosition in interface KoalaSensors

Returns:

0 if successful, non-zero otherwise

getLeftMotorPosition

public int getLeftMotorPosition()

Get the current position of the left motor.

Specified by:

getLeftMotorPosition in interface KoalaMotors

getRightMotorPosition

public int getRightMotorPosition()

Get the current position of the right motor.

Specified by:

getRightMotorPosition in interface KoalaMotors

readAnalogueInput

public int readAnalogueInput(int channel)

Read one of the analogue inputs. The channel parameter selects which input to read. Valid values are between 0 and 5. The result is a value between 0 and 1024 where 1024 denotes 4.09V.

Specified by:

readAnalogueInput in interface KoalaSensors

readDigitalInput

public int readDigitalInput(int channel)

Read one of the digital inputs. The channel parameter selects which input to read. Valid values are between 0 and 11. The result is a value 0 or 1.

Specified by:

readDigitalInput in interface KoalaSensors

setDigitalOutput

public int setDigitalOutput(int channel,
                            int state)

Set one of the digital outputs. The channel parameter selects which output to set. Channels 0 to 7 correspond to the open drain outputs, which channels 8 to 11 correspond to the CMOS outputs.

Specified by:

setDigitalOutput in interface KoalaSensors

Returns:

0 on success, non-zero otherwise

readProximitySensors

public KoalaSensorReading readProximitySensors()

Read the 16 infra-red proximity (reflected light) sensors. A reading of 1024 corresponds to a distance of 5cm. A reading of 0 corresponds to anything further than 20cm (the maximum range).

Specified by:

readProximitySensors in interface KoalaSensors

readAmbientSensors

public KoalaSensorReading readAmbientSensors()

Read the 16 infra-red ambient light sensors.

Specified by:

readAmbientSensors in interface KoalaSensors

leftMotorError

public boolean leftMotorError()

Returns true if the motion controller reports a speed or position error on the left motor.

Specified by:

leftMotorError in interface KoalaMotors

rightMotorError

public boolean rightMotorError()

Returns true if the motion controller reports a speed or position error on the right motor.

Specified by:

rightMotorError in interface KoalaMotors

moveForward

public int moveForward(double distance)

Move forward the specified distance of mm. Call blocks until motion is complete.

Specified by:

moveForward in interface KoalaMotors

Returns:

0 on success, non-zero otherwise

rotate

public int rotate(double angle)

Rotate (on the spot) by the specified angle in degrees. A positive value denotes anti-clockwise (left) turn. A negative value denotes a clockwise (right) turn. Call blocks until rotation is complete.

Specified by:

rotate in interface KoalaMotors

Returns:

0 on success, non-zero otherwise

rotate

public void rotate(int radius,
                   double angle)

Move along an arc specified by the radius (millimetres) and angle (degrees). An angle of 360 will cause the robot to move in a full circle. This method blocks. A positive radius turns the robot to the left, a negative radius to the right.

setSpeed

public void setSpeed(int radius,
                     double angularVelocity)

Set the wheel speeds given a radius (millimetres) and a desired angular velocity (degrees per second). A positive radius turns the robot to its left, a negative radius to the right.

getAngularVelocity

public double getAngularVelocity()

Compute the angular velocity based on the current wheel speeds, in degrees per second.

printFP

public void printFP(double x)

Prints a double to the standard output. Necessary because JamVM does not implement it properly.

getRadiusOfRotation

public double getRadiusOfRotation()

Get the radius of the curve the robot is currently moving along, in millimetres. If the left and right speeds are equal, then clearly it is not a curve, and this function returns Double.POSITIVE_INFINITY. Zero is returned if the robot is rotating on the spot.

readLongRangeSensors

public KoalaSensorReading readLongRangeSensors()

Read the long-range infra-red proximity sensors. Not all Koalas implement this function, so hasLongRangeSensors() should be used to check beforehand. Values are returned in elements 0 and 1 of the left and right arrays of KoalaSensorReading. Values range from 0 to 255.

Specified by:

readLongRangeSensors in interface KoalaLongRangeSensors

readFrontLeftLRSensor

public int readFrontLeftLRSensor()

Read the front left long-range proximity sensor.

Specified by:

readFrontLeftLRSensor in interface KoalaLongRangeSensors

readFrontRightLRSensor

public int readFrontRightLRSensor()

Read the front right long-range proximity sensor.

Specified by:

readFrontRightLRSensor in interface KoalaLongRangeSensors

readLeftSideLRSensor

public int readLeftSideLRSensor()

Read the left side long-range proximity sensor.

Specified by:

readLeftSideLRSensor in interface KoalaLongRangeSensors

readRightSideLRSensor

public int readRightSideLRSensor()

Read the right side long-range proximity sensor.

Specified by:

readRightSideLRSensor in interface KoalaLongRangeSensors

hasLongRangeSensors

public boolean hasLongRangeSensors()

Determine if this Koala has long-range proximity sensors. This is a heuristic method which may give incorrect results.

Specified by:

hasLongRangeSensors in interface KoalaLongRangeSensors