1. Swift APIs

MetaSensors are supported on iOS, macOS, tvOS and watchOS. Ddevelopers can create Apps for iPads, iPhones, Watches and Mac desktops/latops. Any App you develop with our APIs can be released on the Apple App store.

For this tutorial, you will need Xcode on MAC OS.

You should be familiar with the Swift language and know how to deploy Apps and use Xcode before starting the tutorial.

Note

Other languages (such as Python) on MAC are not supported.

1.1. Installation

Ensure that you are running the latest OS:

  1. Visit the macOS page on the App Store or online:
  2. Click the download button and follow the onscreen instructions to begin your upgrade.
_images/apple-version-1.png
  1. Then check and perform your system for Updates in the System Preferences menu.

1.1.1. Bluetooth

Make sure your device support Bluetooth 4.0+

If the Bluetooth preferences lists options for enabling Bluetooth and making your device discoverable, Bluetooth is installed.

To check your Mac Bluetooth version:

  1. Click on the Apple menu.
  2. Select About This Mac.
  3. Click on the More Info button.
  4. Click on the System Report button.
  5. Select Bluetooth from the sidebar on the left, underneath “Hardware.”
  6. Scan down the list of information until you find “LMP Version.”

If your Mac is equipped with Bluetooth 4.0, LMP Version will say 0x6 (or higher). Anything lower than that is an older version of Bluetooth.

_images/apple-version-2.png

Warning

The Bluetooth version on your MAC will only be useful if you are developing a MAC App. If you are developing a Watch, iPad, and iPhone App, you must make sure that the device you are using for debugging supports Bluetooth 4.0 or later.

The following devices are compatible with wireless Bluetooth LE (4.0) connectivity:

  • iOS 8.12+ (With the exception of iOS 9 beta)
  • iPad Mini
  • iPad 3 (or later)
  • iPhone (4S or later)
  • iPod touch (5th Gen or later)
  • Mac OSX 10.10 (Yosemite)

The following Mac Models and later support BLE 4.0:

  • Mac mini - Mid 2011
  • MacBook Air - 2011
  • MacBook Pro - Late 2012
  • iMac - Late 2012
  • Mac Pro - Late 2013 / early 2014

Minimum Watch model recommendation:

  • WatchOS 5 and Apple Watch Series 4

1.1.2. Xcode

Xcode is an integrated development environment for macOS containing a suite of software development tools developed by Apple for developing software for macOS, iOS, watchOS and tvOS.

Download and install it from the App Store or from Apple’s website.

It will prompt you to create a developer account. Follow the steps from Apple.

_images/xcode.png

1.2. Dependencies

1.2.1. Terminal

The Terminal app allows you to control your Mac using a command prompt. You should get comfortable with the command line and basic commands.

The Terminal app is in the Utilities folder in Applications.

To open it, either open your Applications folder, then open Utilities and double-click on Terminal, or press Command - spacebar to launch Spotlight and type “Terminal,” then double-click the search result.

_images/apple-version-4.png

1.2.2. Homebrew

Homebrew is a free and open-source software package management system that simplifies the installation of software on Apple’s macOS operating system and Linux. Homebrew is an essential tool for any developer.

Before you can run Homebrew you need to have the Command Line Tools (CLT) for Xcode installed. CLT includes compilers that will allow you to build things from source, and if you are missing this it’s available through the App Store > Updates.

You can also run the following command to see if CLT is installed:

>>> xcode-select -p

This will return the path to the tool if the CLT is already installed: /Applications/Xcode.app/Contents/Developer.

_images/apple-version-6.png

To install Homebrew run the following:

>>> ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
_images/apple-version-5.png

1.2.3. Git

Git is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files.

Type the following command into your Terminal:

>>> git --version
_images/apple-version-3.png

If it is already installed, you don’t need to do anything, otherwise read and agree to the Command Line Tools License Agreement and you are ready to use Git!

If the terminal install did not succeeed, you can install Git from this site.

Another option is to use homebrew:

>>> brew install git

When done, test that it installed properly installed by running:

>>> git --version

Git should output /usr/local/bin/git.

Don’t forget to define your Git user (should be the same name and email you use for Github, Bitbucket or whichever repository you are using):

>>> git config --global user.name "Your Name Here"
>>> git config --global user.email "your_email@youremail.com"

They will get added to your .gitconfig file.

You can learn more about how to use Git on the respective sites.

1.2.4. RubyGems

RubyGems, the Ruby package manager, should be installed on your machine. If you previously have installed Ruby; verify this by running:

>>> which gem

To update to its latest version with:

>>> gem update --system
_images/apple-version-7.png

To install a gem (Ruby package), run:

>>> gem install <gemname>

To install without generating the documentation for each gem (faster):

>>> gem install <gemname> --no-document

List installed gems:

>>> gem list
_images/apple-version-8.png

To check if any installed gems are outdated:

>>> gem outdated

To update all gems or a particular gem:

>>> gem update [<gemname>]

RubyGems keeps old versions of gems, so feel free to do some cleaning after updating:

>>> gem cleanup

1.2.5. CocoaPods

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It has over 55 thousand libraries and is used in over 3 million apps.

You can learn more about CocoaPods here.

CocoaPods is built with Ruby and is installable with the default Ruby available on OS X. We recommend you use the default ruby.

Using the default Ruby install can require you to use sudo when installing gems:

>>> sudo gem install cocoapods
_images/apple-version-9.png

1.2.6. Simulator

Xcode Simulator allows you to rapidly prototype and test builds of your app during the development process. Installed as part of the Xcode tools, Simulator runs on your Mac and behaves like a standard Mac app while simulating an iPhone, iPad, Apple Watch, or Apple TV environment.

Warning

BLUETOOTH IS NOT SUPPORTED IN THE SIMULATOR.

You will need to compile your App and test it on the native machine you are developing for as Bluetooth is not supported in the Xcode simulator.

_images/apple-version-0.png

1.2.7. Developer Program

_images/app-developer.png

Developing for Apple and releasing Apps on the App store requires a Developer account. Please follow the directions on the Apple website:

_images/xcode-7.png

1.3. MetaWear

MetaWear is available as a CocoaPod to be added to your Xcode project. This is the recommended way to add MetaWear to your own iOS App if you already know how to use CocoaPods.

If you are a first time CocoaPods user, please see this tutorial.

If you are not comfortable with CoacoaPods, we recommend using our StarterApp project where everything has already been setup for you including a Podfile. Simply jump to to the next section.

To install it, simply add the following line to your Podfile:

>>> pod "MetaWear", :subspecs => ['UI', 'AsyncUtils', 'Mocks', 'DFU']

Save your Podfile.

Run:

>>> pod install
_images/swift-1.png

Open the MyApp.xcworkspace that was created.

1.4. Usage

Import the framework header files like this:

>>> import MetaWear
>>> import MetaWearCpp
_images/swift-2.png

1.4.1. Download API Repository

Head over to our Swift Github page: https://github.com/mbientlab/MetaWear-SDK-iOS-macOS-tvOS

You can clone the repository or simply download as a ZIP file:

>>>  git clone https://github.com/mbientlab/MetaWear-SDK-iOS-macOS-tvOS.git
_images/swift-3.png

Make sure the MetaWear-SDK-Cpp submodule is also downloaded. If it is not present, use the command:

>>>  git clone --recurse-submodules https://github.com/mbientlab/MetaWear-SDK-iOS-macOS-tvOS.git

1.4.2. About Swift APIs

The Swift APIs are a thin wrapper around the MetaWear C++ API so you will find the C++ documentation and API reference useful.

When you download our Repository, you will find:

  1. MetaWear -> Containing the Swift wrappers and the C++ MetaWear library Repository (this is what we submit to Cocoapods and includes all the source code)
  2. Starter Project -> An skeleton App for you to get started with (with the MetaWear Cocoapods pre-loaded)
  3. MetaWear API Test -> An example App for you to experiment with (with the MetaWear Cocoapods pre-loaded)
  4. Docs -> Documentation
  5. Images

We also have Swift API documentation here. Please keep this documentation handy.

1.5. Template App

For those who want to build a simple MetaWear App or are new to iOS development, we have provided a template for creating MetaWear Apps.

Go to the MetaWear-SDK-iOS-macOS-tvOS/StarterProject directory.

Run:

>>> pod update

Open StarterProject.xcworkspace with Xcode.

_images/xcode-1.png

Let’s build our first App!

Make sure you are confident with Xcode and Swift, there is a great tutorial here.

1.5.1. UI Elements

To add a start and stop button using interface builder, so open up iOS/Main.storyboard.

Then drag two buttons onto the Device View Controller and connect the buttons to DeviceViewController.swift.

_images/xcode-2.png

1.5.2. Data Stream

Switching back to the DeviceViewController class, lets fill in the startPressed and stopPressed functions.

The start button will enable the accelerometer data stream. The stop button will disable the stream.

@IBAction func startPressed(sender: AnyObject) {
    let board = device.board
    guard mbl_mw_metawearboard_lookup_module(board, MBL_MW_MODULE_ACCELEROMETER) != MODULE_TYPE_NA else {
        print("No accelerometer")
        return
    }
    let signal = mbl_mw_acc_get_acceleration_data_signal(board)
    mbl_mw_datasignal_subscribe(signal, bridge(obj: self)) { (context, data) in
        let _self: DeviceViewController = bridge(ptr: context!)
        let obj: MblMwCartesianFloat = data!.pointee.valueAs()
        print(obj)
    }
    mbl_mw_acc_enable_acceleration_sampling(board)
    mbl_mw_acc_start(board)
}

@IBAction func stopPressed(sender: AnyObject) {
    let board = device.board
    let signal = mbl_mw_acc_get_acceleration_data_signal(board)
    mbl_mw_acc_stop(board)
    mbl_mw_acc_disable_acceleration_sampling(board)
    mbl_mw_datasignal_unsubscribe(signal)
}
_images/xcode-3.png

1.5.3. Test the App

Connect your iOS device to your Mac.

_images/xcode-4.png

Load the StartApp onto your iOS device and connect to your board.

_images/xcode-6.png

Press the START button to see acceleration data being outputted to the log.

_images/xcode-5.png

1.6. Sample App

For those who want to see coded examples of the functionalities of the Metawear, we have provided a MetaWear API test App.

Go to the MetaWear-SDK-iOS-macOS-tvOS/MetaWearApiTest directory.

Run:

>>> pod update

Open MetaWearApiTest.xcworkspace with Xcode.

_images/xcode-10.png

This sample MetaWearAPI Test App shows you how to update firmware, graph accelerometer data, blink the leds red and much more. It is best for you to open up the project, run it on your phone and read through the code.

_images/xcode-11.png

Please note this is only an example App. It doesn’t support automatic reconnects, long term logging, or any functionalities you should have in a public published App.

When are you want learn more about the inner workings of the APIs and advanced functionalities of the MetaWear, go to the Next Steps.

1.7. Next Steps

Go over to our Swift Developers Section to learn more about the Swift development.