edu.cmu.ri.createlab.terk.robot.finch
Class Finch

java.lang.Object
  edu.cmu.ri.createlab.terk.application.TerkApplication
      edu.cmu.ri.createlab.terk.robot.finch.BaseFinchApplication
          edu.cmu.ri.createlab.terk.robot.finch.Finch

public final class Finch
extends edu.cmu.ri.createlab.terk.robot.finch.BaseFinchApplication

Contains all methods necessary to program for the Finch robot

Author:

Tom Lauwers (tlauwers@birdbraintechnologies.com), Chris Bartley (bartley@cmu.edu)

Field Summary

Fields inherited from class edu.cmu.ri.createlab.terk.application.TerkApplication

CONNECTION_STRATEGY_CLASS_NAME_PROPERTY

Constructor Summary

Finch()

Method Summary

void	buzz(int frequency, int duration) Plays a tone at the specified frequency for the specified duration on the Finch's internal buzzer.
void	closeAccelerometerGraph() Closes the opened Accelerometer Graph
void	closeLightSensorGraph() Closes the opened Light sensor Graph
void	closeTemperatureGraph() Closes the opened temperature Graph
double[]	getAccelerations() Use this method to simultaneously return the current X, Y, and Z accelerations experienced by the robot.
int	getLeftLightSensor() Returns the value of the left light sensor.
int[]	getLightSensors() Returns a 2 integer array containing the current values of both light sensors.
boolean[]	getObstacleSensors() Returns the value of both obstacle sensors as 2 element boolean array.
int	getRightLightSensor() Returns the value of the right light sensor.
double	getTemperature() The current temperature reading at the temperature probe.
double	getXAcceleration() This method returns the current X-axis acceleration value experienced by the robot.
double	getYAcceleration() This method returns the current Y-axis acceleration value experienced by the robot.
double	getZAcceleration() This method returns the current Z-axis acceleration value experienced by the robot.
boolean	isBeakDown() This method returns true if the beak is pointed at the floor, false otherwise
boolean	isBeakUp() This method returns true if the beak is up (Finch sitting on its tail), false otherwise
boolean	isFinchLevel() This method returns true if the Finch is on a flat surface
boolean	isFinchUpsideDown() This method returns true if the Finch is upside down, false otherwise
boolean	isLeftLightSensor(int limit) Returns true if the left light sensor is less than the value specified by limit, false otherwise.
boolean	isLeftWingDown() This method returns true if the Finch's left wing is pointed at the ground
boolean	isObstacle() Returns true if either left or right obstacle sensor detect an obstacle.
boolean	isObstacleLeftSide() Returns true if there is an obstruction in front of the left side of the robot.
boolean	isObstacleRightSide() Returns true if there is an obstruction in front of the right side of the robot.
boolean	isRightLightSensor(int limit) Returns true if the right light sensor is less than the value specified by limit, false otherwise.
boolean	isRightWingDown() This method returns true if the Finch's right wing is pointed at the ground
boolean	isShaken() Returns true if the Finch has been shaken since the last accelerometer read
boolean	isTapped() Returns true if the Finch has been tapped since the last accelerometer read
boolean	isTemperature(double limit) Returns true if the temperature is less than the value specified by limit, false otherwise.
void	playClip(String fileLocation) Plays a wav file over computer speakers at the specificied fileLocation path.
void	playTone(int frequency, int duration) Plays a tone over the computer speakers or headphones at a given frequency (in Hertz) for a specified duration in milliseconds.
void	playTone(int frequency, int volume, int duration) Plays a tone over the computer speakers or headphones at a given frequency (in Hertz) for a specified duration in milliseconds at a specified volume.
void	quit() This method properly closes the connection with the Finch and resets the Finch so that it is immediately ready to be controlled by subsequent programs.
void	saySomething(String sayThis) Takes the text of 'sayThis' and synthesizes it into a sound file and plays the sound file over computer speakers.
void	saySomething(String sayThis, int duration) Takes the text of 'sayThis' and synthesizes it into a sound file and plays the sound file over computer speakers.
void	setLED(Color color) Sets the color of the LED in the Finch's beak using a Color object.
void	setLED(Color color, int duration) Sets the color of the LED in the Finch's beak using a Color object for the length of time specified by duration.
void	setLED(int red, int green, int blue) Sets the color of the LED in the Finch's beak.
void	setLED(int red, int green, int blue, int duration) Sets the color of the LED in the Finch's beak for the length of time specified by duration.
void	setWheelVelocities(int leftVelocity, int rightVelocity) This method simultaneously sets the velocities of both wheels.
void	setWheelVelocities(int leftVelocity, int rightVelocity, int timeToHold) This method simultaneously sets the velocities of both wheels.
void	showAccelerometerGraph() Displays a graph of the X, Y, and Z accelerometer values.
void	showLightSensorGraph() Displays a graph of the left and right light sensor values.
void	showTemperatureGraph() Displays a graph of the temperature value.
void	sleep(int ms) This method uses Thread.sleep to cause the currently running program to sleep for the specified number of seconds.
void	stopWheels() Stops both wheels.
void	updateAccelerometerGraph(double xVal, double yVal, double zVal) updates the accelerometer graph with accelerometer data specified by xVal, yVal, and zVal.
void	updateLightSensorGraph(int leftSensor, int rightSensor) Updates the light sensor graph with the left and right light sensor data.
void	updateTemperatureGraph(double temp) Updates the temperature graph with the most recent temperature data.

Methods inherited from class edu.cmu.ri.createlab.terk.robot.finch.BaseFinchApplication

getAccelerometerService, getAudioService, getBuzzerService, getFullColorLEDService, getOpenLoopVelocityControllableMotorService, getPhotoresistorService, getSimpleObstacleDetectorService, getThermistorService

Methods inherited from class edu.cmu.ri.createlab.terk.application.TerkApplication

addConnectionStrategyEventHandler, cancelConnect, connect, disconnect, getServiceManager, isConnected, isConnecting, shutdown

Methods inherited from class java.lang.Object

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

Constructor Detail

Finch

public Finch()

Method Detail

setLED

public void setLED(Color color)

Sets the color of the LED in the Finch's beak using a Color object.

Parameters:

color - is a Color object that determines the beaks color

setLED

public void setLED(int red,
                   int green,
                   int blue)

Sets the color of the LED in the Finch's beak. The LED can be any color that can be created by mixing red, green, and blue; turning on all three colors in equal amounts results in white light. Valid ranges for the red, green, and blue elements are 0 to 255.

Parameters:

red - sets the intensity of the red element of the LED

green - sets the intensity of the green element of the LED

blue - sets the intensity of the blue element of the LED

setLED

public void setLED(Color color,
                   int duration)

Sets the color of the LED in the Finch's beak using a Color object for the length of time specified by duration.

Parameters:

color - is a Color object that determines the beaks color

duration - is the length of time the color will display on the beak

setLED

public void setLED(int red,
                   int green,
                   int blue,
                   int duration)

Sets the color of the LED in the Finch's beak for the length of time specified by duration. The LED can be any color that can be created by mixing red, green, and blue; turning on all three colors in equal amounts results in white light. Valid ranges for the red, green, and blue elements are 0 to 255.

Parameters:

red - sets the intensity of the red element of the LED

green - sets the intensity of the green element of the LED

blue - sets the intensity of the blue element of the LED

duration - is the length of time the color will display on the beak

stopWheels

public void stopWheels()

Stops both wheels.

setWheelVelocities

public void setWheelVelocities(int leftVelocity,
                               int rightVelocity)

This method simultaneously sets the velocities of both wheels. Current valid values range from -255 to 255; negative values cause a wheel to move backwards.

Parameters:

leftVelocity - The velocity at which to move the left wheel

rightVelocity - The velocity at which to move the right wheel

setWheelVelocities

public void setWheelVelocities(int leftVelocity,
                               int rightVelocity,
                               int timeToHold)

This method simultaneously sets the velocities of both wheels. Current valid values range from -255 to 255. If timeToHold is positive, this method blocks further program execution for the amount of time specified by timeToHold, and then stops the wheels once time has elapsed.

Parameters:

leftVelocity - The velocity in native units at which to move the left wheel

rightVelocity - The velocity in native units at which to move the right wheel

timeToHold - The amount of time in milliseconds to hold the velocity for; if 0 or negative, program execution is not blocked and the wheels are not stopped.

sleep

public void sleep(int ms)

This method uses Thread.sleep to cause the currently running program to sleep for the specified number of seconds.

Parameters:

ms - - the number of milliseconds to sleep for. Valid values are all positive integers.

getXAcceleration

public double getXAcceleration()

This method returns the current X-axis acceleration value experienced by the robot. Values for acceleration range from -1.5 to +1.5g. The X-axis is the beak-tail axis.

Returns:

The X-axis acceleration value

getYAcceleration

public double getYAcceleration()

This method returns the current Y-axis acceleration value experienced by the robot. Values for acceleration range from -1.5 to +1.5g. The Y-axis is the wheel-to-wheel axis.

Returns:

The Y-axis acceleration value

getZAcceleration

public double getZAcceleration()

This method returns the current Z-axis acceleration value experienced by the robot. Values for acceleration range from -1.5 to +1.5g. The Z-axis runs perpendicular to the Finch's circuit board.

Returns:

The Z-axis acceleration value

getAccelerations

public double[] getAccelerations()

Use this method to simultaneously return the current X, Y, and Z accelerations experienced by the robot. Values for acceleration can be in the range of -1.5g to +1.5g. When the robot is on a flat surface, X and Y should be close to 0g, and Z should be near +1.0g.

Returns:

a an array of 3 doubles containing the X, Y, and Z acceleration values

isBeakUp

public boolean isBeakUp()

This method returns true if the beak is up (Finch sitting on its tail), false otherwise

Returns:

true if beak is pointed at ceiling

isBeakDown

public boolean isBeakDown()

This method returns true if the beak is pointed at the floor, false otherwise

Returns:

true if beak is pointed at the floor

isFinchLevel

public boolean isFinchLevel()

This method returns true if the Finch is on a flat surface

Returns:

true if the Finch is level

isFinchUpsideDown

public boolean isFinchUpsideDown()

This method returns true if the Finch is upside down, false otherwise

Returns:

true if Finch is upside down

isLeftWingDown

public boolean isLeftWingDown()

This method returns true if the Finch's left wing is pointed at the ground

Returns:

true if Finch's left wing is down

isRightWingDown

public boolean isRightWingDown()

This method returns true if the Finch's right wing is pointed at the ground

Returns:

true if Finch's right wing is down

isShaken

public boolean isShaken()

Returns true if the Finch has been shaken since the last accelerometer read

Returns:

true if the Finch was recently shaken

isTapped

public boolean isTapped()

Returns true if the Finch has been tapped since the last accelerometer read

Returns:

true if the Finch was recently tapped

playTone

public void playTone(int frequency,
                     int duration)

Plays a tone over the computer speakers or headphones at a given frequency (in Hertz) for a specified duration in milliseconds. Middle C is about 262Hz. Visit http://www.phy.mtu.edu/~suits/notefreqs.html for frequencies of musical notes.

Parameters:

frequency - The frequency of the tone in Hertz

duration - The time to play the tone in milliseconds

playTone

public void playTone(int frequency,
                     int volume,
                     int duration)

Plays a tone over the computer speakers or headphones at a given frequency (in Hertz) for a specified duration in milliseconds at a specified volume. Middle C is about 262Hz. Visit http://www.phy.mtu.edu/~suits/notefreqs.html for frequencies of musical notes.

Parameters:

frequency - The frequency of the tone in Hertz

volume - The volume of the tone on a 1 to 10 scale

duration - The time to play the tone in milliseconds

playClip

public void playClip(String fileLocation)

Plays a wav file over computer speakers at the specificied fileLocation path. If you place the audio file in the same path as your source, you can just specify the name of the file.

Parameters:

fileLocation - Absolute path of the file or name of the file if located in some directory as source code

saySomething

public void saySomething(String sayThis)

Takes the text of 'sayThis' and synthesizes it into a sound file and plays the sound file over computer speakers. sayThis can be arbitrarily long and can include variable arguments. Example: myFinch.saySomething("My light sensor has a value of "+ lightSensor + " and temperature is " + tempInCelcius);

Parameters:

sayThis - The string of text that will be spoken by the computer

saySomething

public void saySomething(String sayThis,
                         int duration)

Takes the text of 'sayThis' and synthesizes it into a sound file and plays the sound file over computer speakers. sayThis can be arbitrarily long and can include variable arguments. The duration argument allows you to delay program execution for a number of milliseconds. Example: myFinch.saySomething("My light sensor has a value of "+ lightSensor + " and temperature is " + tempInCelcius);

Parameters:

sayThis - The string of text that will be spoken by the computer

duration - The time in milliseconds to halt further program execution

buzz

public void buzz(int frequency,
                 int duration)

Plays a tone at the specified frequency for the specified duration on the Finch's internal buzzer. Middle C is about 262Hz. Visit http://www.phy.mtu.edu/~suits/notefreqs.html for frequencies of musical notes. Note that this is different from playTone, which plays a tone on the computer's speakers. Also note that buzz is non-blocking - so if you call two buzz methods in a row without an intervening sleep, you will only hear the second buzz (it will over-write the first buzz).

Parameters:

frequency - Frequency in Hertz of the tone to be played

duration - Duration in milliseconds of the tone

getLeftLightSensor

public int getLeftLightSensor()

Returns the value of the left light sensor. Valid values range from 0 to 255, with higher values indicating more light is being detected by the sensor.

Returns:

The current light level at the left light sensor

getRightLightSensor

public int getRightLightSensor()

Returns the value of the right light sensor. Valid values range from 0 to 255, with higher values indicating more light is being detected by the sensor.

Returns:

The current light level at the right light sensor

getLightSensors

public int[] getLightSensors()

Returns a 2 integer array containing the current values of both light sensors. The left sensor is the 0th array element, and the right sensor is the 1st element.

Returns:

A 2 int array containing both light sensor readings.

isLeftLightSensor

public boolean isLeftLightSensor(int limit)

Returns true if the left light sensor is less than the value specified by limit, false otherwise.

Parameters:

limit - The value the light sensor needs to exceed

Returns:

whether the light sensor exceeds the value specified by limit

isRightLightSensor

public boolean isRightLightSensor(int limit)

Returns true if the right light sensor is less than the value specified by limit, false otherwise.

Parameters:

limit - The value the light sensor needs to exceed

Returns:

true if the light sensor exceeds the value specified by limit

isObstacleLeftSide

public boolean isObstacleLeftSide()

Returns true if there is an obstruction in front of the left side of the robot.

Returns:

Whether an obstacle exists in front of the left side of the robot.

isObstacleRightSide

public boolean isObstacleRightSide()

Returns true if there is an obstruction in front of the right side of the robot.

Returns:

Whether an obstacle exists in front of the right side of the robot.

isObstacle

public boolean isObstacle()

Returns true if either left or right obstacle sensor detect an obstacle.

Returns:

Whether either obstacle sensor sees an obstacle.

getObstacleSensors

public boolean[] getObstacleSensors()

Returns the value of both obstacle sensors as 2 element boolean array. The left sensor is the 0th element, and the right sensor is the 1st element.

Returns:

The values of left and right obstacle sensors in a 2 element array

getTemperature

public double getTemperature()

The current temperature reading at the temperature probe. The value returned is in Celsius. To get Fahrenheit from Celsius, multiply the number by 1.8 and then add 32.

Returns:

The current temperature in degrees Celsius

isTemperature

public boolean isTemperature(double limit)

Returns true if the temperature is less than the value specified by limit, false otherwise.

Parameters:

limit - The value the temperature needs to exceed

Returns:

true if the temperature exceeds the value specified by limit

showAccelerometerGraph

public void showAccelerometerGraph()

Displays a graph of the X, Y, and Z accelerometer values. Note that this graph does not update on its own - you need to call updateAccelerometerGraph to do so.

updateAccelerometerGraph

public void updateAccelerometerGraph(double xVal,
                                     double yVal,
                                     double zVal)

updates the accelerometer graph with accelerometer data specified by xVal, yVal, and zVal.

Parameters:

xVal - The X axis acceleration value

yVal - The Y axis acceleration value

zVal - The Z axis acceleration value

closeAccelerometerGraph

public void closeAccelerometerGraph()

Closes the opened Accelerometer Graph

showLightSensorGraph

public void showLightSensorGraph()

Displays a graph of the left and right light sensor values. Note that this graph does not update on its own - you need to call updateLightSensorGraph to do so.

updateLightSensorGraph

public void updateLightSensorGraph(int leftSensor,
                                   int rightSensor)

Updates the light sensor graph with the left and right light sensor data.

Parameters:

leftSensor - Variable containing left light sensor value

rightSensor - Variable containing right light sensor value

closeLightSensorGraph

public void closeLightSensorGraph()

Closes the opened Light sensor Graph

showTemperatureGraph

public void showTemperatureGraph()

Displays a graph of the temperature value. Note that this graph does not update on its own - you need to call updateTemperatureGraph to do so.

updateTemperatureGraph

public void updateTemperatureGraph(double temp)

Updates the temperature graph with the most recent temperature data.

Parameters:

temp - variable containing a temperature value

closeTemperatureGraph

public void closeTemperatureGraph()

Closes the opened temperature Graph

quit

public void quit()

This method properly closes the connection with the Finch and resets the Finch so that it is immediately ready to be controlled by subsequent programs. Note that if this method is not called at the end of the program, the Finch will continue to act on its most recent command (such as drive forward) for 5 seconds before automatically timing out and resetting. This is why we recommend you always call the quit method at the end of your program.