Framework

MetaWear

Develop Bluetooth Low Energy apps using our sensors and Combine

Overview

This SDK abstracts CoreBluetooth and our MetaWear C/C++ API using concise Combine publishers and presets. It offers three optional imports:

MetaWearSync — track groups of MetaWears across Apple devices using iCloud key-value storage
MetaWearCpp — mix our C/C++ API with Combine publishers for additional flexibility
MetaWearFirmware — update firmware over Bluetooth

MetaMotion S.

Getting Started

Beyond this guide, you can ramp up with an interactive From Zero to Machine Learning tutorial to build a simple app, similar to our barebones integration test host app. Existing MetaWear developers can orient with Migrating from the Bolts SDK. You can also examine the source code of our cross-platform MetaBase app.

1. Entitlements

For each target in your project, go to the Signing & Capabilities tab. For macOS, go to App Sandbox and check Bluetooth. For iOS, add Background Modes and check Uses Bluetooth LE accessories.

Optionally, for MetaWearSync, add iCloud and check Key value storage. If your plan to update MetaWear firmware in your app using MetaWearFirmware, for macOS in App Sandbox check Outgoing Connections.

For all platforms, go to the Info tab and add and provide a message for:

Privacy - Bluetooth Always Usage Description
Privacy - Bluetooth Peripheral Usage Description

2. Find nearby MetaWears

Create a MetaWearScanner instance or use the sharedRestore singleton.

Goal	API
Search	`startScan(higherPerformanceMode:)`
Stop searching	`stopScan()`
Individual discovery events	`didDiscover`
Refreshing dictionary of devices	`discoveredDevicesPublisher`
Bluetooth power and authorization	`bluetoothState`

A restored device may not be nearby right now, but was connected in a previous session. As with all MetaWear interactions, you’ll receive updates on that scanner’s bleQueue.

If you wish to sync MetaWear identities via iCloud, only use the scanner to start/stop scanning and observe Bluetooth state. Use the MetaWearSyncStore to retrieve, remember, and forget MetaWears. It will monitor the scanner’s output for you.

3. Interact

First, to connect to a MetaWear, call connect() or use the connectPublisher(). You can observe connection state via the connectionStatePublisher.

Since nearly every MetaWear interaction is an asynchronous call and response over a potentially low strength Bluetooth connection, this SDK reasons about these events and streams of data through Apple’s Combine framework. If unfamiliar with Combine, the From Zero to Machine Learning tutorial has some basics. A good reference is Joseph Heck’s Using Combine.

Most of this SDK’s functions extend Combine publishers that emit a MetaWear.

Fires	API
On every connection	`publishWhenConnected()`
First connection only	`publishWhenConnected()` `.first()`
On every disconnection	`publishWhenDisconnected()`
Now, failing if not connected	`publishIfConnected()`
Now	`publish()`

From those publishers, autocompletion will reveal MetaWear operators.

Operator	Example
`.command()`	`rename(advertisingName:)`
`.read()`	`batteryLevel`
`.stream()`	`sensorFusionQuaternion(mode:)`
`.log()`	`gyroscope(rate:range:)`
`.downloadLogs(:)`	Returns `MWDataTable` array and percent progress

Example: Wait until first connection, stream accelerometer vectors, update UI on main

Performing multiple interactions at once

To chain logging or other commands, you can use .optionallyLog() and/or .macro(executeOnBoot:actions:).

To stream an arbitrary number of sensors, you can setup individual pipelines, perhaps coordinated by prefix(untilOutputFrom:). You could also convert the myriad MWStreamable outputs to the same type, such as MWDataTable, and form an array of publishers consumable by Combine’s MergeMany.

Beware that Bluetooth Low Energy usually can’t deliver above 100 Hz without dropping some data. Also, the prefix(untilOutputFrom:) operator must output on the bleQueue to avoid undefined behavior.

Using onboard timers

For logging, you can program a MetaWear to fire an onboard timer to poll a signal (direct from sensor or after some data processing) or fire an event after some trigger.

Operator	Output Reference Pointer	Input
`.createPollingTimer()`	Data signal embedded in the timer	Publisher<(MetaWear, MWDataSignal)>
`.createTimer()`	Timer	Publisher<(MetaWear, MWDataSignal)>
`.createTimedEvent()`	Event timer	Publisher and a closure of commands to execute upon firing

An MWDataSignal is a type alias for OpaquePointer, which is simply a reference to a C type not exposed to Swift.

4. Debugging

Bytes transmitted over Bluetooth and other MetaWear actions can be viewed using the MWConsoleLogger. Just assign a reference to that logger to a MetaWear’s logDelegate property.

Sometimes an incomplete or incorrect command can put a MetaWear in a bad state, which will crash when you reconnect. If reseting the device via unit test our apps fails, manually reset by connecting the MetaWear to power at the same time as pressing the mechanical button for 10 seconds.

5. Testing

Unit test targets can call on a host app that exposes a MetaWearScanner, but XCTest cannot instantiate its own MetaWearScanner with Bluetooth permission on its own.

UI test targets may also improperly parse Swift Package Manager dependencies. (If encountered, please file feedback with Apple.)

Topics

Getting Started

From Zero to Machine Learning

Control MetaWear wearable sensors to classify movement. Let’s build Streamy, a barebones app using Swift, Combine, CoreML, and SwiftUI.

Migrating from the Bolts SDK

Overview of changes

Essentials

Using any MWPublisher ensures calls into the C++ library and reads of any properties occur on the bleQueue.

class MetaWearScanner

Start scanning for MetaWear devices without having to understand all of CoreBluetooth. Pipelines return on the scanner’s unique bleQueue.

class MetaWear

Each MetaWear object corresponds a physical MetaWear board. This SDK wraps type-safe Swift methods and Combine publishers around C/C++ functions and CoreBluetooth APIs so you can get started quickly.

enum MWError

MetaWear Error

typealias MWPublisher

This publisher subscribes and returns on its parent scanner’s Bluetooth queue to ensure safe usage of the MetaWear C++ library.

Interact

The .command(), .log(), .read(), and .stream() operators accept value types conforming to these protocols, which describe communication methods with the MetaWear.

protocol MWCommand

Issues a command, such as recording a macro or resetting to factory defaults.

protocol MWCommandWithResponse

Issues a command that returns a value.

protocol MWLoggable

Sensors that can log data to onboard storage adhere to this protocol to configure, start, stop, and download the logger.

protocol MWPollable

Sensors natively incapable of continuous output, such as thermistors, can output “streamable” and loggable outputs with the help of onboard timers that fire at reasonable intervals. This protocol organizes the methods and properties for polling such sensors.

protocol MWReadable

For signals that can only be read once Sensors natively incapable of continuous output, such as thermistors, adopt this protocol to organize configuring, reading, and closing a sensor’s data signal.

protocol MWReadableMerged

A read command that coalesces multiple operations into one output.

protocol MWStreamable

Sensors that can stream data at about 100 to 120 Hz adhere to this protocol to configure, start, and stop a data signal.

struct MWFrequency

Specify event frequencies in Hz or millisecond periods between events

Data Output

Streaming data arrives in Swift types, such as SIMD3<Float>. Logs download in a string-based MWDataTable that can output a .csv file.

struct MWDataTable

Stringly-expressed data from any sensor, ready to export in CSV format.

struct MWData

Useful when interacting with the C++ library.

protocol MWDataConvertible

Has a defined conversion from a MblMwData C++ struct into a defined Swift value type whose lifetime is not confined to the C++ closure.

typealias Download

Tuple of the approximate percentage of data already downloaded (by page size, not actual entries) and, once 100% complete, the downloaded data itself.

typealias Timestamped

Modules

struct MWAccelerometer

struct MWAmbientLight

Lux (Illuminance)

struct MWBarometer

struct MWBuzzer

The haptic module controls a high current driver to power a motor or buzzer (or similar devices).

struct MWGyroscope

struct MWHapticMotor

In the MMR+ model, the coin vibration motor provides haptic feedback. It does not provide pulse-width modulation capability.

struct MWHumidity

struct MWiBeacon

struct MWThermometer

Celcius

struct MWLED

struct MWMagnetometer

struct MWMechanicalButton

struct MWMotion

struct MWOrientationSensor

struct MWSensorFusion

struct MWStepCounter

Emits steps detected in 20 step intervals.

struct MWStepDetector

Emits each time a step is detected, leaving summation to you.

enum MWModules

Misc Signals & Commands

struct MWBatteryLevel

Battery life percentage 0 to 100

struct MWChargingStatus

Battery’s current charging state

struct MWChangeAdvertisingName

Changes only the device’s Bluetooth advertising name (not any SDK metadata).

struct MWLastResetTime

Board Restart Time

struct MWLogLength

Bytes

struct MWMACAddress

After connection or if remembered, a MetaWear’s info property exposes the stable MAC address.

struct MWMacro

Commands for recording, stopping, and removing sequences of commands.

enum MWNamedSignal

String key returned with a logger signal for a module by the C++ library. Subscripts can indicate a particular aspect (e.g., which thermistor), a custom slice into a Cartesian float, or other more advanced operations.

Reset or Restart Commands

struct MWFactoryReset

Wipes all data and settings from the MetaWear.

struct MWActivitiesReset

Removes all data processors, loggers, timers, and recorded events from both the board and the struct’s internal state. The board itself is not reset, so any configuration changes will be preserved.

struct MWRestart

Restarts, preserving macros, loggers, and settings, but any in-memory activities are lost.

Utilities

class MWConsoleLogger

Prints MetaWear Bluetooth packets to the console. Singleton. Set activateConsoleLoggingOnAllMetaWears to enroll all devices or manually set the logger in the target MetaWear.

protocol MWConsoleLoggerDelegate

Handles log messages (e.g., Bluetooth packets) from MetaWear devices

Identifiers

Each machine assigns a MetaWear a unique local UUID, but once connected info contains a stable MAC address.

typealias CBPeripheralIdentifier

While stable locally, Apple identifies CoreBluetooth peripherals via a UUID that differs between a user’s phones and computers. Once connected, a MetaWear’s `MetaWear/MetaWear/info`` property exposes the stable MAC address, as does our advertising packet when seen via Android.

typealias MACAddress

A 6-byte unique identifier for a MetaWear and any Bluetooth device (e.g., F1:4A:45:90:AC:9D)

C++ Bridging

When interacting with the C++ library, use these functions to reference Swift objects.

func bridge<T>(obj: T) -> UnsafeMutableRawPointer

Convert to void* without ownership, only use when lifetime of object is guaranteed elsewhere

func bridge<T>(ptr: UnsafeRawPointer) -> T

Convert from void* without ownership, only use when lifetime of object is guaranteed elsewhere

func bridgeRetained<T>(obj: T) -> UnsafeMutableRawPointer

Convert to void* with ownership, make sure these are always called in matching pairs with bridgeTransfer

func bridgeTransfer<T>(ptr: UnsafeRawPointer) -> T

Convert from void* with ownership, make sure these are always called in matching pairs with bridgeRetained

Opaque Pointer & C++ Aliases

When interacting with the C++ library or forming your own publishers, these type aliases hint at the identity of an OpaquePointer or an integer identifier.

typealias MWBoard

References the MetaWear’s board

typealias MWDataSignal

References a signal from a board module (e.g., accelerometer) for streaming, logging, or reading MblMwDataSignal