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

java.lang.Object
  extended by edu.cmu.ri.createlab.terk.application.TerkApplication
      extended by edu.cmu.ri.createlab.terk.robot.finch.BaseFinchApplication
          extended by 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.