@mentra/bluetooth-sdk 3.2.1-dev.311 → 3.2.1

package/ios/Source/utils/DemandDrivenAudioWorker.swift

@@ -0,0 +1,150 @@
+import Foundation
+
+/// Owns a processor on one serial queue. Empty queues schedule no recurring work.
+/// Demand changes invalidate queued audio/results immediately; creation, processing,
+/// and destruction finish in order without blocking the caller (including the UI).
+final class DemandDrivenAudioWorker<Processor> {
+    struct Snapshot {
+        let active: Bool
+        let initialized: Bool
+        let processing: Bool
+        let queuedBuffers: Int
+        let processedBuffers: UInt64
+        let droppedBuffers: UInt64
+    }
+
+    private let lock = NSLock()
+    private let queue: DispatchQueue
+    private let capacity: Int
+    private let makeProcessor: () -> Processor?
+    private let process: (Processor, Data, UInt64) -> Void
+    private var active = false
+    private var generation: UInt64 = 0
+    private var buffers = [Data]()
+    private var scheduled = false
+    private var initialized = false
+    private var processing = false
+    private var processedBuffers: UInt64 = 0
+    private var droppedBuffers: UInt64 = 0
+
+    // Accessed only on queue, including release of the previous processor.
+    private var processor: Processor?
+    private var processorGeneration: UInt64?
+    private var attemptedInitialization = false
+
+    init(capacity: Int = 100,
+         queue: DispatchQueue = DispatchQueue(label: "com.mentra.speech.processor", qos: .userInitiated),
+         makeProcessor: @escaping () -> Processor?,
+         process: @escaping (Processor, Data, UInt64) -> Void)
+    {
+        precondition(capacity > 0)
+        self.capacity = capacity
+        self.queue = queue
+        self.makeProcessor = makeProcessor
+        self.process = process
+    }
+
+    func setActive(_ value: Bool) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard active != value else { return }
+        active = value
+        invalidateLocked()
+    }
+
+    /// Reload a changed model only if there is still local-transcription demand.
+    func restart() {
+        lock.lock()
+        defer { lock.unlock() }
+        invalidateLocked()
+    }
+
+    private func invalidateLocked() {
+        generation &+= 1
+        buffers.removeAll(keepingCapacity: true)
+        initialized = false
+        scheduleLocked()
+    }
+
+    func accept(_ data: Data) {
+        guard !data.isEmpty else { return }
+        lock.lock()
+        defer { lock.unlock() }
+        guard active else { return }
+        // Bound even audio arriving while model loading or decoding is blocked.
+        if buffers.count == capacity {
+            buffers.removeFirst()
+            droppedBuffers &+= 1
+        }
+        buffers.append(data)
+        scheduleLocked()
+    }
+
+    func isCurrent(_ token: UInt64) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return active && generation == token
+    }
+
+    func snapshot() -> Snapshot {
+        lock.lock()
+        defer { lock.unlock() }
+        return Snapshot(active: active, initialized: initialized, processing: processing,
+                        queuedBuffers: buffers.count, processedBuffers: processedBuffers,
+                        droppedBuffers: droppedBuffers)
+    }
+
+    private func scheduleLocked() {
+        guard !scheduled else { return }
+        scheduled = true
+        queue.async { self.drain() }
+    }
+
+    private func drain() {
+        while true {
+            lock.lock()
+            let token = generation
+            if processorGeneration != token {
+                lock.unlock()
+                // ARC destruction stays serialized with inference and model loading.
+                processor = nil
+                processorGeneration = token
+                attemptedInitialization = false
+                continue
+            }
+            guard active else {
+                scheduled = false
+                lock.unlock()
+                return
+            }
+            if !attemptedInitialization {
+                attemptedInitialization = true
+                lock.unlock()
+                processor = makeProcessor()
+                lock.lock()
+                if generation == token { initialized = processor != nil }
+                lock.unlock()
+                continue
+            }
+            guard let processor else {
+                buffers.removeAll(keepingCapacity: true)
+                scheduled = false
+                lock.unlock()
+                return // Missing model: retry on a demand transition or model restart.
+            }
+            guard !buffers.isEmpty else {
+                scheduled = false
+                lock.unlock()
+                return
+            }
+            let data = buffers.removeFirst()
+            processing = true
+            lock.unlock()
+            process(processor, data, token)
+            lock.lock()
+            processedBuffers &+= 1
+            processing = false
+            lock.unlock()
+        }
+    }
+}

package/ios/Source/utils/G2Text.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+/// Empty interior rows shut down some EvenHub firmware pages. Keep the row
+/// without exposing this protocol workaround to miniapps or other devices.
+enum G2Text {
+    static func containerContent(_ text: String) -> String {
+        if text.isEmpty { return " " }
+        return text.components(separatedBy: "\n")
+            .map { $0.isEmpty ? "\u{200B}" : $0 }.joined(separator: "\n")
+    }
+}

package/ios/Tests/BluetoothBackgroundModeTests.swift

@@ -0,0 +1,32 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class BluetoothBackgroundModeTests: XCTestCase {
+    func testDetectsDeclaredBluetoothCentral() {
+        XCTAssertTrue(
+            BluetoothBackgroundMode.declaresBluetoothCentral(
+                ["UIBackgroundModes": ["audio", "bluetooth-central"]]
+            )
+        )
+    }
+
+    func testReportsMissingOrMalformedBackgroundModes() {
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral(nil))
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral([:]))
+        XCTAssertFalse(BluetoothBackgroundMode.declaresBluetoothCentral(["UIBackgroundModes": ["audio"]]))
+        XCTAssertFalse(
+            BluetoothBackgroundMode.declaresBluetoothCentral(["UIBackgroundModes": "bluetooth-central"])
+        )
+    }
+
+    func testMacOSHasNoBackgroundModeRequirement() {
+        #if os(macOS)
+            XCTAssertTrue(BluetoothBackgroundMode.isDeclared(in: nil))
+        #endif
+    }
+
+    func testWarningPointsToTheDocs() {
+        XCTAssertTrue(BluetoothBackgroundMode.missingWarning.contains("bluetooth-central"))
+        XCTAssertTrue(BluetoothBackgroundMode.missingWarning.contains("#background-operation"))
+    }
+}

package/ios/Tests/DashboardContentFormatterTests.swift

@@ -5,14 +5,14 @@ final class DashboardContentFormatterTests: XCTestCase {
     func testEmptyContentReturnsStatusHeaderOnly() {
         XCTAssertEqual(
             DashboardContentFormatter.template(for: ""),
-            "$TIME12$ $DATE$ $GBATT$ $CONNECTION_STATUS$"
+            "$TIME12$ $DATE$ $GBATT$"
         )
     }
 
     func testNonEmptyContentIsAppendedExactlyAfterBlankLine() {
         XCTAssertEqual(
             DashboardContentFormatter.template(for: "  Next meeting\nRoom 2  "),
-            "$TIME12$ $DATE$ $GBATT$ $CONNECTION_STATUS$\n\n  Next meeting\nRoom 2  "
+            "$TIME12$ $DATE$ $GBATT$\n\n  Next meeting\nRoom 2  "
         )
     }
 }

package/ios/Tests/DashboardRenderingTests.swift

@@ -15,6 +15,36 @@ final class DashboardRenderingTests: XCTestCase {
         return (manager, display)
     }
 
+    func testFullFrameDashboardHandoffDoesNotClearActiveScene() async {
+        let (manager, display) = setupDashboard()
+        display.sceneHandoffRequiresClear = false
+        await manager.setDashboardContent("new dashboard")
+        XCTAssertEqual(display.cleanupCount, 0)
+        XCTAssertEqual(display.clearDisplayCount, 0)
+        XCTAssertEqual(display.texts.count, 1)
+        XCTAssertTrue(display.texts[0].hasSuffix("new dashboard"))
+    }
+
+    func testHiddenSceneHandoffCannotClearMainView() async {
+        let (manager, display) = setupDashboard()
+        DeviceStore.shared.apply("glasses", "headUp", false)
+        manager.displayEvent([
+            "view": "dashboard",
+            "scene": ["appId": "replacement", "sceneEpoch": 2, "elements": [[String: Any]]()],
+        ])
+        await Task.yield()
+        XCTAssertEqual(display.cleanupCount, 0)
+        XCTAssertEqual(display.clearDisplayCount, 0)
+        XCTAssertTrue(display.scenes.isEmpty)
+    }
+
+    func testNimoOptsOutOfDestructiveTransientOverlays() {
+        let device: SGCManager = Nimo()
+        XCTAssertFalse(device.sceneHandoffRequiresClear)
+        XCTAssertFalse(device.showBrightnessConfirmation)
+        XCTAssertFalse(device.showConnectionConfirmation)
+    }
+
     func testSetterWaitsForCleanupAndLatestContentWins() async {
         let (manager, display) = setupDashboard()
         var firstReturned = false
@@ -74,6 +104,7 @@ final class DashboardRenderingTests: XCTestCase {
 private final class PausedDisplay: SGCManager {
     var type = "Test display"
     let hasMic = false
+    var sceneHandoffRequiresClear = true
     let cleanupStarted = XCTestExpectation(description: "cleanup suspended")
     var cleanupCount = 0
     var clearDisplayCount = 0

package/ios/Tests/DemandDrivenAudioWorkerTests.swift

@@ -0,0 +1,157 @@
+import Foundation
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class DemandDrivenAudioWorkerTests: XCTestCase {
+    private final class Processor {
+        let onRelease: () -> Void
+        init(onRelease: @escaping () -> Void = {}) {
+            self.onRelease = onRelease
+        }
+
+        deinit { onRelease() }
+    }
+
+    func testNoDemandAndEmptyActiveQueueScheduleNoRecurringWork() {
+        let queue = DispatchQueue(label: "test.speech")
+        var creations = 0
+        var processed = [Data]()
+        let worker = DemandDrivenAudioWorker(queue: queue, makeProcessor: {
+            creations += 1
+            return Processor()
+        }, process: { _, data, _ in processed.append(data) })
+        worker.accept(Data([1]))
+        queue.sync {}
+        XCTAssertEqual(creations, 0)
+        worker.setActive(true)
+        worker.setActive(true)
+        queue.sync {}
+        XCTAssertEqual(creations, 1)
+        XCTAssertTrue(worker.snapshot().initialized)
+        XCTAssertFalse(worker.snapshot().processing)
+        // A serial barrier completes with an empty queue; no sleeping consumer holds it.
+        queue.sync {}
+        XCTAssertTrue(processed.isEmpty)
+        worker.setActive(false)
+        queue.sync {}
+        XCTAssertFalse(worker.snapshot().initialized)
+    }
+
+    func testFirstAudioIsRetainedDuringAsynchronousInitializationAndBounded() {
+        let queue = DispatchQueue(label: "test.speech")
+        let loading = DispatchSemaphore(value: 0)
+        let release = DispatchSemaphore(value: 0)
+        var processed = [Data]()
+        let worker = DemandDrivenAudioWorker(capacity: 3, queue: queue, makeProcessor: {
+            XCTAssertFalse(Thread.isMainThread)
+            loading.signal()
+            release.wait()
+            return Processor()
+        }, process: { _, data, _ in processed.append(data) })
+        worker.setActive(true)
+        XCTAssertEqual(loading.wait(timeout: .now() + 2), .success)
+        worker.accept(Data([1]))
+        worker.accept(Data([2]))
+        XCTAssertEqual(worker.snapshot().queuedBuffers, 2)
+        release.signal()
+        queue.sync {}
+        XCTAssertEqual(processed, [Data([1]), Data([2])])
+        worker.setActive(false)
+        queue.sync {}
+    }
+
+    func testStopDuringLoadingDropsOldAudioAndCannotResurrectProcessor() {
+        let queue = DispatchQueue(label: "test.speech")
+        let loading = DispatchSemaphore(value: 0)
+        let release = DispatchSemaphore(value: 0)
+        var released = 0
+        var processed = 0
+        let worker = DemandDrivenAudioWorker(capacity: 2, queue: queue, makeProcessor: {
+            loading.signal()
+            release.wait()
+            return Processor { released += 1 }
+        }, process: { _, _, _ in processed += 1 })
+        worker.setActive(true)
+        XCTAssertEqual(loading.wait(timeout: .now() + 2), .success)
+        for byte: UInt8 in 1 ... 10 {
+            worker.accept(Data([byte]))
+        }
+        XCTAssertEqual(worker.snapshot().queuedBuffers, 2)
+        XCTAssertEqual(worker.snapshot().droppedBuffers, 8)
+        worker.setActive(false)
+        XCTAssertEqual(worker.snapshot().queuedBuffers, 0)
+        release.signal()
+        queue.sync {}
+        XCTAssertEqual(processed, 0)
+        XCTAssertEqual(released, 1)
+        XCTAssertFalse(worker.snapshot().initialized)
+    }
+
+    func testRestartAndRapidDemandChangesSerializeOldAndNewProcessors() {
+        let queue = DispatchQueue(label: "test.speech")
+        let processing = DispatchSemaphore(value: 0)
+        let release = DispatchSemaphore(value: 0)
+        var creations = 0
+        var destructions = 0
+        var tokens = [UInt64]()
+        var dataSeen = [Data]()
+        let worker = DemandDrivenAudioWorker(queue: queue, makeProcessor: {
+            XCTAssertEqual(creations, destructions)
+            creations += 1
+            return Processor { destructions += 1 }
+        }, process: { _, data, token in
+            dataSeen.append(data)
+            tokens.append(token)
+            if data == Data([1]) {
+                processing.signal()
+                release.wait()
+            }
+        })
+        worker.setActive(true)
+        worker.accept(Data([1]))
+        XCTAssertEqual(processing.wait(timeout: .now() + 2), .success)
+        worker.accept(Data([2]))
+        worker.restart()
+        worker.setActive(false)
+        worker.setActive(true)
+        worker.accept(Data([3]))
+        release.signal()
+        queue.sync {}
+        XCTAssertEqual(dataSeen, [Data([1]), Data([3])])
+        XCTAssertFalse(worker.isCurrent(tokens[0]))
+        XCTAssertTrue(worker.isCurrent(tokens[1]))
+        XCTAssertEqual(creations, 2)
+        worker.setActive(false)
+        queue.sync {}
+        XCTAssertEqual(destructions, 2)
+        XCTAssertFalse(worker.isCurrent(tokens[1]))
+    }
+
+    func testMissingModelDoesNotRetryEveryFrameAndRestartWithoutDemandDoesNotLoad() {
+        let queue = DispatchQueue(label: "test.speech")
+        var attempts = 0
+        let worker = DemandDrivenAudioWorker<Processor>(queue: queue, makeProcessor: {
+            attempts += 1
+            return nil
+        }, process: { _, _, _ in XCTFail("Missing processor") })
+        worker.restart()
+        queue.sync {}
+        XCTAssertEqual(attempts, 0)
+        worker.setActive(true)
+        for _ in 0 ..< 5 {
+            worker.accept(Data([1]))
+            queue.sync {}
+        }
+        XCTAssertEqual(attempts, 1)
+        XCTAssertEqual(worker.snapshot().queuedBuffers, 0)
+        worker.restart()
+        queue.sync {}
+        XCTAssertEqual(attempts, 2)
+        worker.setActive(false)
+        worker.setActive(true)
+        queue.sync {}
+        XCTAssertEqual(attempts, 3)
+        worker.setActive(false)
+        queue.sync {}
+    }
+}

package/ios/Tests/DeviceIdentityPairingTests.swift

@@ -0,0 +1,49 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+@MainActor
+final class DeviceIdentityPairingTests: XCTestCase {
+    func testReadinessPromotesCoherentIdentityAndPreservesSameDeviceReconnects() {
+        let store = DeviceStore.shared.store
+        let saved = ["bluetooth", "glasses"].map { ($0, store.getCategory($0)) }
+        defer {
+            for (category, values) in saved {
+                for key in store.getCategory(category).keys where values[key] == nil {
+                    store.remove(category, key)
+                }
+                for (key, value) in values {
+                    store.set(category, key, value)
+                }
+            }
+        }
+        let cases = [
+            // pending name, pending address, saved model, expected address
+            ("new", "", "test", ""),
+            ("new", "new-address", "test", "new-address"),
+            ("old", "", "test", "old-address"),
+            ("", "", "test", "old-address"),
+            ("old", "", "other-model", ""),
+        ]
+        for (pendingName, pendingAddress, savedModel, expectedAddress) in cases {
+            let manager = DeviceManager()
+            let device = Simulated()
+            device.type = "test"
+            manager.sgc = device
+            defer {
+                manager.disconnect()
+                manager.cleanup()
+            }
+            store.set("bluetooth", "default_wearable", savedModel)
+            store.set("bluetooth", "device_name", "old")
+            store.set("bluetooth", "device_address", "old-address")
+            store.set("bluetooth", "pending_device_name", pendingName)
+            store.set("bluetooth", "pending_device_address", pendingAddress)
+            store.set("bluetooth", "shouldSendBootingMessage", false)
+            manager.handleDeviceReady()
+            XCTAssertEqual(DeviceStore.shared.get("bluetooth", "device_name") as? String, pendingName.isEmpty ? "old" : pendingName)
+            XCTAssertEqual(DeviceStore.shared.get("bluetooth", "device_address") as? String, expectedAddress)
+            XCTAssertEqual(DeviceStore.shared.get("bluetooth", "pending_device_name") as? String, "")
+            XCTAssertEqual(DeviceStore.shared.get("bluetooth", "pending_device_address") as? String, "")
+        }
+    }
+}