Kotlin is a language used to write apps for Android phones and tablets, as well as Amazon Fire tablets. It includes Bluetooth functionality that can be used to connect to the Finch Robot 2.0 and the Hummingbird Bit. We use it when writing our own apps, and we have created a library that you can use to create your own apps. This tutorial assumes that you are already familiar with Kotlin and Android Studio.

Requirements

To write Android apps for tablets and phone, you will need a few things:

  • A Mac, Windows , or Linux computer with Android Studio installed. 
  • A phone or tablet to run your app. Apps that use Bluetooth cannot run in the simulator. You will need to connect your phone or tablet to the computer with a USB cord. If you are using a Mac with only Thunderbolt ports, you may need an adapter.

Setup

Open Android Studio. Then click Check out project from Version Control on the right side of the screen. Then click Git.

Enter the Github address shown below and click Clone. Click Yes when Android Studio asks if you want to open the project.

https://github.com/BirdBrainTechnologies/Basic-Android-Apps-Finch2-Bit

Next, you will need to choose which branch of the project to work on. Each branch is a sample app for the Finch Robot 2.0 or Hummingbird Bit. Your choices are listed below. We recommend starting with either finch-basic-app or hummingbird-basic, depending on which robot you are using.

Branch Description
Finch-Basic-App A basic sample app using the Finch. The app includes buttons to move the Finch, sliders to control the lights, and a display of Finch sensor information.
Finch-Beebot Allows the user to “program” the Finch by pressing arrows. The app creates a list of the movements the user has selected and executes those movements when the play button is pressed.
Finch-Blank-App A blank app that can be used as a template for creating your own Finch apps.
Hummingbird-Basic-App A basic sample app using the Hummingbird. The app includes buttons and sliders to control the Hummingbird lights and motors, as well as a display of Hummingbird sensor information.
Hummingbird-Blank-App A blank app that can be used as a template for creating your own Hummingbird apps.
master Same as finch-basic-app.

To choose a branch, click on Git: master in the lower right-hand corner of the screen.

Click the branch you want and then choose Checkout As…. Android will ask you to choose a name for the branch. The default is fine. This tutorial will use the Finch-Basic-App branch, but the app structure and functionality are analogous for the Hummingbird branches.

Structure of Apps

Each app is created with the same structure. All of the classes specific to the Finch are in the Finch folder. For most basic apps, you will not need to change anything in this folder. 

The app opens with a screen that enables you to choose your Finch and connect to it. That is the activity_scan.xml file in the res/layout folder, and it is controlled by ScanActivity.kt. You will need to connect to the robot, so you should leave the functionality of these alone (though you may want to beautify the layout). 

Once you choose a device to connect to, the app will move to the MainActivity, which is controlled by MainActivity.kt with a layout in activity_main.xml. The MainActivity class is defined as a FinchListener and it declares a variable named finch that is set equal to the Finch object for the entire app. If you add additional activities to your app, each one will need to be a FinchListener and to declare the Finch object.

MainActivity.kt and activity_main.xml are where you can make modifications to create your own app. MainActivity.swift uses the finch variable to access the Finch Robot. The finch variable has public methods that you can use to control the lights, motors, and buzzers of the Finch. Those functions are described in the Kotlin Finch 2.0 library, or the Kotlin Hummingbird Bit library if you are using a Hummingbird.

In addition, the finch variable has an internal variable named sensorState, which you can use to access all of the values of the Finch sensors. For example, finch?.sensorState?.distance will give you the value of the Finch distance sensor. An analogous hummingbird variable with an internal sensorState is used in the Hummingbird apps. The variables inside that structure that contain the Finch or Hummingbird data are described in the sensor section of the Kotlin Finch 2.0 library or the Kotlin Hummingbird Bit library.

Running a Sample App

Next, get your Finch or Hummingbird ready by loading the Bluetooth firmware. You will not need to do this if you have previously used your Finch or Hummingbird with BirdBlox or the BlueBird Connector. Connect the micro:bit in the robot to the computer with a USB cord. The micro:bit will appear as an external drive. Drag this file onto the micro:bit.

To run an app from Android studio on your phone or tablet, you will need to enable the developer options. Instructions are here for Android devices and here for Fire tablets.

Connect your phone or tablet to the computer with a USB cord. If you are using a Mac with only Thunderbolt ports, you may need an adapter.

Select your device in the middle of the top bar in Android Studio. Now you are ready to run your program! Turn on your robot and press the play button in the upper right hand corner of Xcode to run your program.

Writing Your Own Apps

To create your own apps, use the Finch-Blank-App and Hummingbird-Blank-App branches in the Github repository. These contain the app components required to connect to the robot, but the acitivity_main.xml is left blank for you. Remember, if you add additional activities to your app, each one will need to be a FinchListener and to declare the Finch object.

For more information about what methods and variables are included in the Finch and Hummingbird objects, please see the Kotlin Finch 2.0 library and the Kotlin Hummingbird Bit library.