Skip to content

mbientlab/MetaWear-SDK-iOS-macOS-tvOS

Repository files navigation

MetaWear SDK for iOS/macOS/tvOS/watchOS by MBIENTLAB

Platforms License Version

alt tag

SDK for creating MetaWear apps that run in the Apple ecosystem. This is a thin wrapper around the MetaWear C++ API so you will find the C++ documentation and API reference useful. Check out the starter App and the very through example App App for sample code.

Like Combine more than Bolts? 😎

We're developing a Swift Combine SDK, now in beta with interactive documentation and two sample apps.

Overview

MetaWear is a complete development and production platform for wearable and connected device applications.

MetaWear features a number of sensors and peripherals all easily controllable over Bluetooth 4.0/5.0 Low Energy using this SDK, no firmware or hardware experience needed!

The MetaWear hardware comes pre-loaded with a wirelessly upgradeable firmware, so it keeps getting more powerful over time.

Requirements

  • MetaWear board
  • Apple ID, you can now get started for free! Once you are ready to submit an App to the App Store, you need a paid Apple Developer Account.
  • Device running iOS 14.0 or later with Bluetooth 4.0/5.0 (iOS 13+, XCODE12+, BLE5.0 recommended)

REQUIREMENT NOTES
The iOS simulator doesn’t support Bluetooth 4.0/5.0, so test apps must be run on a real iOS device which requires a developer account. Bluetooth 4.0 available on iPhone 4S+, iPad 3rd generation+, or iPod Touch 5th generation.

BLUETOOTH IS NOT SUPPORTED IN THE SIMULATOR

License

See the License

Support

Reach out to the community if you encounter any problems, or just want to chat :)

Getting Started

Pre-Installation

Xcode

You need to be profficient with Xcode development to use these APIs.

Swift

Our APIs are written and supported in Swift.

CocoaPods

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It has over 79 thousand libraries and is used in over 3 million apps. CocoaPods can help you scale your projects elegantly.

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

Using the default Ruby install can require you to use sudo when installing gems. Further installation instructions are in the guides.

sudo gem install cocoapods

Installation

MetaWear is available through CocoaPods. To install it, simply add the following line to your Podfile:

Then list the dependencies in a text file named Podfile in your Xcode project directory:

platform :ios, '14.0'
use_frameworks!
target 'MyApp' do
    // LOCAL
    pod "MetaWear", :subspecs => ['UI', 'AsyncUtils', 'DFU']
    // COCOA POD
    pod "MetaWear"
    // COCOA POD RELEASE SPECIFIC
    pod "MetaWear", '~> '4.0.2'
end

Tip: CocoaPods provides a pod init command to create a Podfile with smart defaults. You should use it.

Now you can install the dependencies in your project:

pod install

It might be good to update:

pod update

Make sure to always open the Xcode workspace instead of the project file when building your project:

open App.xcworkspace

Now you can import your dependencies e.g.:

#import MetaWear

Usage

Require the metawear package

import MetaWear
import MetaWearCpp

Call Swift APIs:

device.flashLED(color: .green, intensity: 1.0)

Or direct CPP SDK calls:

var pattern = MblMwLedPattern(high_intensity: 31,
                              low_intensity: 31,
                              rise_time_ms: 0,
                              high_time_ms: 2000,
                              fall_time_ms: 0,
                              pulse_duration_ms: 2000,
                              delay_time_ms: 0,
                              repeat_count: 0xFF)
mbl_mw_led_stop_and_clear(device.board)
mbl_mw_led_write_pattern(device.board, &pattern, color)
mbl_mw_led_play(device.board)

Or a mix of both as you can see in the example below.

Example

Here is a walkthrough to showcase a very basic connect and toggle LED operation.

MetaWearScanner.shared.startScan(allowDuplicates: true) { (device) in
    // We found a MetaWear board, see if it is close
    if device.rssi.intValue > -50 {
        // Hooray! We found a MetaWear board, so stop scanning for more
        MetaWearScanner.shared.stopScan()
        // Connect to the board we found
        device.connectAndSetup().continueWith { t in
            if let error = t.error {
                // Sorry we couldn't connect
                print(error)
            } else {
                // Hooray! We connected to a MetaWear board, so flash its LED!
                var pattern = MblMwLedPattern()
                mbl_mw_led_load_preset_pattern(&pattern, MBL_MW_LED_PRESET_PULSE)
                mbl_mw_led_stop_and_clear(device.board)
                mbl_mw_led_write_pattern(device.board, &pattern, MBL_MW_LED_COLOR_GREEN)
                mbl_mw_led_play(device.board)
            }
        }
    }
}

Tutorials

Tutorials can be found here.