Libraries.Robots.BirdBrain.Finch Documentation

The Finch class allows the user to control a single Finch robot from BirdBrain Technologies. Use of this class requires a Finch which is running BirdBrain Technologies' firmware and is connected to the computer over bluetooth via the BlueBird Connector app (firmware and software available at https://learn.birdbraintechnologies.com/install-shortcuts/).

Example Code

use Libraries.Robots.BirdBrain.Finch
class Main
action Main
   
   Finch finch

   //draw a square with the finch
   repeat 4 times
     finch:SetMove("forward", 10, 50)
     finch:SetTurn("right", 90, 50)
   end

   finch:Disconnect()

end
end

Inherits from: Libraries.Language.Object

Actions Documentation

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.

Parameters

Return

integer: The Compare result, Smaller, Equal, or Larger.

Example

Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)

Disconnect()

This action closes the http connection to save memory. It should be used at the end of every program.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
finch:Disconnect()

Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

Parameters

Return

boolean: True if the hash codes are equal and false if they are not equal.

Example

use Libraries.Language.Object
use Libraries.Language.Types.Text
Object o
Text t
boolean result = o:Equals(t)

Finch()

GetAcceleration(text axis)

This action returns the acceleration in the given direction (X, Y, or Z) in meters per second squared.

Parameters

  • text axis: The direction of which the acceleration will be returned.

Return

number: Acceleration in meters per second squared.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "X Acceleration: " + finch:GetAcceleration("x")
finch:Disconnect()

GetButton(text button)

This action checks whether the specified micro:bit button is pressed. The function prints an error if the inputs are not in the specified range.

Parameters

  • text button: The button that will be checked (Range: "A", "B", "LOGO").

Return

boolean: true if the button is pressed and false otherwise.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Button A: " + finch:GetButton("A")
finch:Disconnect()

GetCompass()

This action returns the direction in degrees from north.

Return

integer: The direction in degrees (Range: 0 to 360).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Compass: " + finch:GetCompass()
finch:Disconnect()

GetDistance()

This action gets the current value of the finch distance sensor in centimeters.

Return

integer: The distance to the closest obstacle in centimeters.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Distance Sensor: " + finch:GetDistance()
finch:Disconnect()

GetEncoder(text direction)

This action gets the current value of the right or left encoder.

Parameters

  • text direction: Encoder value to return ("right" or "left").

Return

number: The encoder value in rotations.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Right Encoder: " + finch:GetEncoder("right")
finch:Disconnect()

GetHashCode()

This action gets the hash code for an object.

Return

integer: The integer hash code of the object.

Example

Object o
integer hash = o:GetHashCode()

GetLight(text direction)

This action gets the current value of the specified finch light sensor.

Parameters

  • text direction: Light sensor value to return ("right" or "left").

Return

integer: Brightness as a value (Range: 0 to 100).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Right Light Sensor: " + finch:GetLight("right")
finch:Disconnect()

GetLine(text direction)

This action gets the current value of the specified finch line sensor. The return value is inverted (100 - value) so that more reflected light = bigger number.

Parameters

  • text direction: Line sensor value to return ("right" or "left").

Return

integer: Brightness as a value (Range: 0 to 100).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Left Line Sensor: " + finch:GetLine("left")
finch:Disconnect()

GetMagnetometer(text axis)

This action returns the magnetometer value in the given direction (X, Y, or Z) in microtesla.

Parameters

  • text axis: The direction of which the magnetometer value will be returned.

Return

integer: Magnetometer value in microtesla.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Z Magnetometer: " + finch:GetMagnetometer("z")
finch:Disconnect()

GetOrientation()

This action provides information about the finch's current orientation in the finch reference frame. Options include Beak up, Beak down, Tilt left, Tilt right, Level, and Upside down.

Return

text: The orientation of the finch (Beak up, Beak down, Tilt left, Tilt right, Level, or Upside down).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Finch Orientation: " + finch:GetOrientation()
finch:Disconnect()

GetSound()

This action returns the current sound level from the micro:bit sound sensor.

Return

integer: Sound level.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Sound: " + finch:GetSound()
finch:Disconnect()

GetTemperature()

This action returns the current temperature in degrees Celsius from the micro:bit temperature sensor.

Return

integer: Temperature in degrees Celsius.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Temperature: " + finch:GetTemperature()
finch:Disconnect()

IsShaking()

This action tells you whether the micro:bit is being shaken.

Return

boolean: A boolean value telling you the shake state.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
output "Is Shaking?: " + finch:IsShaking()
finch:Disconnect()

Output(text message)

This action lets the LED Array display a given message.

Parameters

  • text message: The message that will be displayed on the LED Array.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
finch:Output("Hello world")
finch:Disconnect()

Pause(number seconds)

This action pauses the program for a time in seconds.

Parameters

  • number seconds: Amount of time the program should pause

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//Display a smiley face for 1 second
finch:SetDisplay("0000001010000001000101110")
finch:Pause(1)
finch:SetDisplay("0000000000000000000000000")
finch:Disconnect()

PlayNote(integer note, number beats)

This action sets the micro:bit buzzer to play the given note for the given duration.

Parameters

  • integer note: Midi note number to play (Range: 32 to 135).
  • number beats: Duration in beats (Range: 0 to 16); each beat is one second.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//Play middle C for 1 beat.
finch:PlayNote(60, 1)
finch:Disconnect()

Print(text message)

This action lets the LED Array display a given message.

Parameters

  • text message: The message that will be displayed on the LED Array.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
finch:Print("Hello world")
finch:Disconnect()

ResetEncoders()

This action resets the finch encoder values to 0.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
finch:ResetEncoders()
finch:Disconnect()

SetBeak(integer red, integer green, integer blue)

This action sets the finch beak to the given rgb color.

Parameters

  • integer red: Red intensity (Range: 0 to 100).
  • integer green: Green intensity (Range: 0 to 100).
  • integer blue: Blue intensity (Range: 0 to 100).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//Set the finch beak to bright white
finch:SetBeak(100, 100, 100)
finch:Disconnect()

SetDisplay(text ledValues)

This action lets the LED Array display a pattern based on an array of 1s and 0s.

Parameters

  • text ledValues: The list of integers that the function takes in to set the LED Array. 1 means on and 0 means off.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//Display a smiley face on the micro:bit LED array
finch:SetDisplay("0000001010000001000101110")
finch:Disconnect()

SetMotors(number leftSpeed, number rightSpeed)

This action sets the right and left motors of the finch to the speeds given.

Parameters

  • number leftSpeed: The speed of the left motor as a percent (Range: -100 to 100).
  • number rightSpeed: The speed of the right motor as a percent (Range: -100 to 100).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//cause the finch to spin in place
finch:SetMotors(-20, 20)
finch:Pause(1)
//draw a small circle with the finch
finch:SetMotors(0, 30)
finch:Pause(5)
finch:Stop()
finch:Disconnect()

SetMove(text direction, number distance, number speed)

This action sends a request for the finch to move forward or backward a given distance at a given speed.

Parameters

  • text direction: The direction of movement ("forward" or "backward").
  • number distance: The distance to travel in centimeters (Range: 0 to 500).
  • number speed: The speed as a percent (Range: 0 to 100).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//move the finch forward 10 centimeters at 50% speed
finch:SetMove("forward", 10, 50)
finch:Disconnect()

SetPoint(integer row, integer column, integer value)

This action turns on or off a single LED on the micro:bit LED array.

Parameters

  • integer row
  • integer column
  • integer value: The value of the LED (0 for off, 1 for on).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
// Turn on the middle LED of the LED array.
finch:SetPoint(3, 3, 1)
finch:Disconnect()

SetTail(integer ledNum, integer red, integer green, integer blue)

This action sets the specified tail LED to the specified rgb color.

Parameters

  • integer ledNum: LED to set (Range: 1 to 4).
  • integer red: Red intensity (Range: 0 to 100).
  • integer green: Green intensity (Range: 0 to 100).
  • integer blue: Blue intensity (Range: 0 to 100)

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//Set tail LED 1 to cyan
finch:SetTail(1, 0, 100, 100)
finch:Disconnect()

SetTail(text ledNum, integer red, integer green, integer blue)

This action sets all tail LEDs to the specified rgb color.

Parameters

  • text ledNum: Text which must be specified as 'all'.
  • integer red: Red intensity (Range: 0 to 100).
  • integer green: Green intensity (Range: 0 to 100).
  • integer blue: Blue intensity (Range: 0 to 100).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//Set all tail LEDs to red
finch:SetTail("all", 100, 0, 0)
finch:Disconnect()

SetTurn(text direction, number angle, number speed)

This action sends a request for the finch to turn right or left to the given angle at the given speed.

Parameters

  • text direction: The direction of the turn ("right" or "left").
  • number angle: The angle of the turn in degrees (Range: 0 to 360).
  • number speed: The speed of the turn as a percent (Range: 0 to 100).

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//turn the finch to the right 90 degrees at 50% speed
finch:SetTurn("right", 90, 50)
finch:Disconnect()

Stop()

This action stops the finch motors.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
//cause the finch to spin in place
finch:SetMotors(-20, 20)
finch:Pause(1)
finch:Stop()
finch:Disconnect()

StopAll()

This action turns off all the outputs.

Example

use Libraries.Robots.BirdBrain.Finch
Finch finch
finch:StopAll()
finch:Disconnect()