iOS

Native iOS apps use the MentraBluetoothSDK Swift package. The same package also supports native macOS with AppKit or SwiftUI. The permissions and background modes below apply to iOS, including iOS apps running on Apple silicon Macs. Native Mac apps use the separate macOS setup.

Requirements

iOS deployment target 15.1 or newer.
Xcode 15 or newer.
Swift Package Manager.
A physical iPhone for Bluetooth, camera, microphone, direct phone photo, and direct phone WebRTC testing.

Install

The public SwiftPM repository is:

https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git

In Xcode, choose File > Add Package Dependencies, enter that URL, select version 3.2.1, and add the MentraBluetoothSDK product to your app target. For Package.swift consumers:

.package(
  url: "https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git",
  from: "3.2.1"
)

Then add the product to your target:

.product(name: "MentraBluetoothSDK", package: "mentra-bluetooth-sdk-ios")

For local SDK development, add the package folder directly in Xcode:

/path/to/MentraOS/mobile/modules/bluetooth-sdk

The SwiftPM package currently builds the core Bluetooth SDK only. It does not build optional local STT or tar.bz2 extraction code paths.

Permissions

Add usage descriptions to Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app connects to your smart glasses over Bluetooth.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone when you enable audio features.</string>
<key>NSLocalNetworkUsageDescription</key>
<string>This app can connect to optional local demo servers on your network.</string>

Background Operation

Declare Core Bluetooth background mode in your app’s Info.plist. It is required, not optional: iOS reads background modes only from the app’s own Info.plist, so the Swift package cannot add it for you.

<key>UIBackgroundModes</key>
<array>
  <string>bluetooth-central</string>
</array>

Mentra Live drops its Bluetooth link for short periods in normal use. During a software update, the glasses restart their Bluetooth chip and are unreachable for about 45 seconds; walking out of range or powering the glasses off has the same effect. When the link drops, the SDK keeps a pending connection to the same glasses open, and iOS completes it as soon as they advertise again. With bluetooth-central, iOS completes that reconnection and wakes your app even while the phone is locked in a pocket. Without it, iOS suspends your app and nothing reconnects until the user opens it again, so a software update started on a locked phone stalls after the Bluetooth chip restarts. App Review asks apps that declare bluetooth-central to need it; a companion app for connected glasses does. At startup the SDK checks your Info.plist and logs a warning when bluetooth-central is missing. Read MentraBluetoothSDK.supportsBackgroundReconnect to check it from code, for example in a debug assertion or a setup screen. If your app also keeps microphone capture or an audio session active in the background, add audio as well:

<key>UIBackgroundModes</key>
<array>
  <string>bluetooth-central</string>
  <string>audio</string>
</array>

Configure your AVAudioSession before starting continuous microphone or playback work. Start continuous microphone capture while the app is foregrounded; iOS background mode lets an active session continue, but the SDK does not start the phone microphone from the background. For example:

let session = AVAudioSession.sharedInstance()
try session.setCategory(.playAndRecord, mode: .default, options: [.allowBluetooth, .defaultToSpeaker])
try session.setActive(true)

bluetooth-central lets iOS deliver BLE events to your app and complete its pending reconnection in the background, subject to iOS scheduling and power-management limits. audio is required only for apps that intentionally keep recording or audio playback active after backgrounding.

This SDK version does not enable terminated-app Core Bluetooth state restoration with CBCentralManagerOptionRestoreIdentifierKey. If iOS terminates the app, relaunch the app and reconnect from your normal startup flow.

Basic Flow

import MentraBluetoothSDK

@MainActor
final class GlassesController: NSObject, MentraBluetoothSDKDelegate {
    private let sdk = MentraBluetoothSDK()
    private var selectedDevice: Device?

    override init() {
        super.init()
        sdk.delegate = self
    }

    func scan() throws {
        try sdk.scan(model: .mentraLive, timeout: 10) { [weak self] devices in
            self?.renderDevicePicker(devices) { device in
                self?.selectedDevice = device
            }
        }
    }

    func connect() throws {
        guard let selectedDevice else { return }
        try sdk.connect(to: selectedDevice)
    }

    func refreshStatus() {
        sdk.requestVersionInfo()
        let glasses = sdk.glasses
        if let device = glasses.device {
            let battery = glasses.battery?.level.map(String.init) ?? "unknown"
            print("Connected to \(device.deviceModel?.deviceType ?? "glasses"), battery=\(battery)%")
        }
    }

    func mentraBluetoothSDK(_ sdk: MentraBluetoothSDK, didUpdateGlasses glasses: GlassesRuntimeState) {
        // Keep app UI derived from SDK status.
        print("Glasses changed: \(glasses)")
    }

    private func renderDevicePicker(_ devices: [Device], onSelect: @escaping (Device) -> Void) {
        // Render devices in SDK-provided order and call onSelect with the user's choice.
    }

    deinit {
        sdk.invalidate()
    }
}

Local SDK Override

Use this when testing native Swift SDK source changes locally:

/path/to/MentraOS/mobile/modules/bluetooth-sdk

Add that folder as a local Swift package in Xcode. Keep local paths in your workspace settings or CI environment, not in committed project settings.

Getting Started

Platform Setup

Core APIs

Release

Requirements

Install

Permissions

Background Operation

Basic Flow

Local SDK Override

​Requirements

​Install

​Permissions

​Background Operation

​Basic Flow

​Local SDK Override

Requirements

Install

Permissions

Background Operation

Basic Flow

Local SDK Override