Swift is the language used to write apps for Apple products, including iPads and iPhones. 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 Swift and Xcode.

Requirements

To write iOS apps for iPads and iPhones, you will need a few things:

  • A MacOS computer with Xcode installed. You cannot write iOS apps without a Mac computer.
  • An iPhone or iPad to run your app. Apps that use Bluetooth cannot run in the simulator. You will need to connect your iPad or iPhone to the computer with a USB cord. If your Mac has only Thunderbolt ports, you may need an adapter.
  • An Apple ID. You do not need to be a member of the Apple Developer Program to write and test your own apps. However, you do need a paid membership to distribute apps in the app store.

Setup

Open Xcode. Then click Clone an existing project at the bottom of the left side of the screen.

Enter the Github address shown below and click Clone

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

You will need to choose which branch to clone. 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. This tutorial will use the finch-basic-app branch, but the app structure and functionality are analogous for the Hummingbird branches.

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-object-tracking Uses ARKit to enable the Finch to follow an object. The object is a book cover named “monster” that you will need to replace with your own two-dimensional object.
finch-blank-app A blank app that can be used as a template for creating your own Finch apps.
hummingbird-basic 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 A blank app that can be used as a template for creating your own Hummingbird apps.
master Same as finch-basic-app.

Xcode will ask you where you want to save a copy of the app and then open it in Xcode. When you see the project open in Xcode, you are ready to start working with your robot in Swift!

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 Device Chooser Scene in Main.storyboard, and it is controlled by DeviceChooserViewController.swift. You will need to connect to the robot, so you should leave the functionality of these alone (though you may want to beautify the scene).

Once the app connects to a robot, it uses a segue to move to the Main View Controller Scene in Main.storyboard, which is controlled by MainViewController.swift. Before it does that, it calls prepare() in the DeviceChooserViewController. This sets up the robot so that it can be used in the MainViewController. You need to override prepare() in the same way for any other segues that you create in your app. 

The Main View Controller Scene and MainViewController.swift are where you can make modifications to create your own app. MainViewController.swift uses three main variables for the robot.

Variable Description
finch: Finch? or hummingbird: Hummingbird? Has public functions that you can use to control the lights, motors, and buzzers of the robot. Those functions are described in the Swift Finch 2.0 library and the Swift Hummingbird Bit library.
finchManager: FinchManager? or hummingbirdManager: HummingbirdManager? Required by the Bluetooth package.
finchSensorState: Finch.SensorState? or hummingbirdSensorState: Hummingbird.SensorState? Structure that contains the sensor information for the robot. The variables inside that structure that contain the robot data are described in the sensor section of the Swift Finch 2.0 library and the Swift 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. This will require an adapter if you only have Thunderbolt ports. The micro:bit will appear as an external drive. Drag this file onto the micro:bit.

First, make sure your account is selected under Signing & Capabilities. You will also need to chose your own bundle identifier.

Connect your iPad or iPhone to the computer with a USB cord. If your Mac has only Thunderbolt ports, you may need an adapter.

Select your device in the upper right corner of Xcode. Your iPhone/iPad will ask you if you can trust the computer; select Trust. You may also need to enter your password on your computer.

You also need to explicitly trust your Apple development profile on the iPad or iPhone. To do this on your iPad or iPhone, go to Settings/General. Then click on Device Management and select the option to trust your developer profile.

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 branches in the Github repository. These contain the app components required to connect to the robot, but the Main View Controller Scene is left blank for you. Remember, if you add any segues to your app, you need to override prepare() in MainViewController.swift to pass control of the robot to a new scene.

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