Public Finch Methods

 

NOTE: If you issue Bluetooth commands very close together (< 100 ms), it is possible that some commands may be skipped. For example, if you set the color of the Finch beak and then immediately set the wheels, you may not see the effect of the beak command.

Method Signature: setMove(direction: String, distance: Double, speed: Int)
Description: Moves the Finch forward or backward for a specified distance at a specified speed. The method requires a direction (“F” for forward or “B” for backward), a distance in centimeters, and a speed from 0-100.
Example: finch.setMove(direction: "F", distance: 10, speed: 50)

Method Signature: setTurn(direction: String, angle: Double, speed: Int)
Description: Turns the Finch right or left for a specified angle at a specified speed. The method requires a direction (“R” for right or “L” for left), an angle in degrees, and a speed from 0-100.
Example: finch.setTurn(direction: "R", angle: 90, speed: 50)

Method Signature: setMotors(leftSpeed: Int, rightSpeed: Int)
Description: Sets the Finch wheels to spin at the given speeds. The method requires two speeds between -100 and 100 for the left and right wheels. Setting the speed to 0 turns the motor off.
Example: finch.setMotors(leftSpeed: -50, rightSpeed: 50)

Method Signature: stop()
Description: Stops the Finch wheels.
Example: finch.stop()

Method Signature: setBeak(red: Int, green: Int, blue: Int)
Description: Sets a tri-color LED in the Finch beak to a given color by setting the intensities of the red, green, and blue elements inside it. The method requires three intensity values from 0-100. Setting all three intensity values to 0 turns the beak off.
Example: finch.setBeak(red: 0, green: 100, blue: 0)

Method Signature: setTail(port: Int, red: Int, green: Int, blue: Int)
Description: Sets a tri-color LED in the Finch tail to a given color by setting the intensities of the red, green, and blue elements inside it. The method requires the port number of the LED (1-4) and three intensity values from 0-100. Setting all three intensity values to 0 turns the LED off.
Example: finch.setTail(port: 1, red: 0, green: 100, blue: 0)

Method Signature: setTail(port: String, red: Int, green: Int, blue: Int)
Description: Sets all the tri-color LEDs in the Finch tail to a given color by setting the intensities of the red, green, and blue elements inside it. The method requires a String equal to “all” and three intensity values from 0-100. Setting all three intensity values to 0 turns the LED off.
Example: finch.setTail(port: "all", red: 0, green: 100, blue: 0)

Method Signature: playNote(note: Int, beats: Double)
Description: Plays a note using the buzzer on the Finch. The method requires an integer representing the note (32-135) and a number giving the number of beats (0-16). The number of beats can be a decimal number.
Example: finch.playNote(note: 60, beats: 0.5)

Method Signature: setDisplay(pattern: Array<Int>)
Description: Sets the LED array of the micro:bit to display a pattern defined by an array. Each value in the array must be 0 (off) or 1 (on). The first five values in the array correspond to the five LEDs in the first row, the next five values to the second row, etc.
Example: finch.setDisplay(pattern: [1,1,1,1,1,0,0,0,0,0,1,1,1,1,1,0,0,0,0,0,1,1,1,1,1])

Method Signature: printString(_ stringToPrint: String)
Description: Print a string on the micro:bit LED array. The string must have 15 or fewer characters and should contain only digits and English letters (upper or lower case).
Example: finch.printString("hello")

Method Signature: stopAll()
Description: Stops all outputs. This includes the LED display for the micro:bit and all lights and motors for the Finch.
Example: finch.stopAll()

Method Signature: correctLightSensorValues() -> Array<Int?>
Description: The Finch light sensors are slightly affected by the value of the beak. It is a fairly small effect, but if you want, you can use this function to correct them.
Example: let correctedLightSensors = finch.correctLightSensorValues()

Method Signature: calibrateCompass()
Description: This function sends a Bluetooth command to calibrate the compass. When the Finch receives this command, it will place dots on the micro:bit screen as it waits for you to tilt the Finch in different directions. If the calibration is successful, you will then see a check on the micro:bit screen. Otherwise, you will see an X.
Example: finch.calibrateCompass()

Method Signature: resetEncoders()
Description: This function sets the right and left encoder values to 0.
Example: finch.resetEncoders()

Finch Sensor State

 

You can access the following variables within finchSensorState:

timestamp: Date Time of the sensor reading

batteryVoltage: Float Voltage of Finch battery

isStale: Bool True when data is out of date

distance: Int Value of the distance sensor in centimeters

leftLight: Int Value of left light sensor (0-100)

rightLight: Int Value of right light sensor (0-100)

leftLine: Int Value of left line sensor (0-100)

rightLine: Int Value of left line sensor (0-100)

leftEncoder: Double Number of rotations the left wheel has turned since the encoders were reset

rightEncoder: Double Number of rotations the right wheel has turned since the encoders were reset

acceleration: Array<Double> Acceleration in m/s2 in the x, y, and z directions

magnetometer: Array<Double> Magnetometer readings in µT in the x, y, and z directions

compass: Int? Degrees from North; undefined when acceleration in the z direction is 0

buttonA: Bool True when button A is pressed

buttonB: Bool True when button B is pressed

shake: Bool True when Finch is being shaken

movementFlag: Bool True when the Finch is moving. You need to watch this flag if you do not want to start another Finch movement until the first one is finished.