# iOS

> Use the Glassly Bluetooth SDK from a native iOS app.

Source: https://docs.dev.glassly.ai/bluetooth-sdk/ios/

Native iOS apps use the `BluetoothSDK` Swift package.

## 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:

```text
https://github.com/tetramo-labs/glassly-bluetooth-sdk-ios.git
```

In Xcode, choose **File > Add Package Dependencies**, enter that URL, select version `0.4.2-dev.1184`, and add the `BluetoothSDK` product to your app target.

For `Package.swift` consumers:

```swift
.package(
  url: "https://github.com/tetramo-labs/glassly-bluetooth-sdk-ios.git",
  from: "0.4.2-dev.1184"
)
```

Then add the product to your target:

```swift
.product(name: "BluetoothSDK", package: "glassly-bluetooth-sdk-ios")
```

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

```text
/path/to/Glassly/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`:

```xml
<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

If your iOS app needs to keep the glasses BLE link alive while the phone is locked or the app is backgrounded, enable Core Bluetooth background mode:

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

If your app also keeps microphone capture or an audio session active in the background, add `audio` as well:

```xml
<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:

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

`bluetooth-central` allows iOS to continue BLE central activity 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

```swift
import BluetoothSDK

@MainActor
final class GlassesController: NSObject, BluetoothSDKDelegate {
    private let sdk = BluetoothSDK()
    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() async throws {
        _ = try await 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 bluetoothSDK(_ sdk: BluetoothSDK, 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:

```text
/path/to/Glassly/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.
