@mentra/bluetooth-sdk 0.1.20 → 0.1.21-beta.0

package/ios/Source/MentraBluetoothSDK.swift

@@ -42,10 +42,15 @@ private final class ActiveScanSession {
 @MainActor
 private final class PendingWifiScan {
     let pending: PendingResponse<[WifiScanResult]>
+    let scanId: String
     var latestResults: [WifiScanResult] = []
+    // Chunks accumulated from scanId-echoing glasses, deduplicated by SSID;
+    // resolved only when the glasses flag the scan complete.
+    var accumulated: [WifiScanResult] = []
 
-    init(pending: PendingResponse<[WifiScanResult]>) {
+    init(pending: PendingResponse<[WifiScanResult]>, scanId: String) {
         self.pending = pending
+        self.scanId = scanId
     }
 }
 
@@ -93,6 +98,25 @@ private final class PendingVideoRecordingRequest {
     }
 }
 
+// seq records send order (assigned and handed to the BLE queue in a single
+// MainActor turn) so that an id-carrying status for a newer start can
+// identify which older in-flight starts it preempted.
+@MainActor
+private final class PendingStreamStart {
+    let seq: Int
+    let pending: PendingResponse<StreamStatusEvent>
+    // Set when an id-carrying error arrives: a fatal publisher error never
+    // reaches the reconnect machinery and winds down with a streamId-less
+    // stopped, so the stash both attributes that stopped to this start and
+    // preserves the real error details for the rejection.
+    var lastError: StreamStatusEvent?
+
+    init(seq: Int, pending: PendingResponse<StreamStatusEvent>) {
+        self.seq = seq
+        self.pending = pending
+    }
+}
+
 @MainActor
 private final class PendingResponse<T> {
     private let operation: String
@@ -149,6 +173,9 @@ private final class PendingResponse<T> {
 @MainActor
 public final class MentraBluetoothSDK {
     private static let wifiScanTimeoutMs = 20_000
+    // A photo response is terminal only after capture, encoding, transport, and upload.
+    // Max-quality BLE fallback can legitimately exceed the generic command deadline.
+    private static let photoRequestTimeoutMs = 30_000
     private static let otaBesVersionWaitMs = 5_000
     private static let otaMtkVersionWaitMs = 2_000
     private static let otaVersionPollMs = 100
@@ -175,8 +202,12 @@ public final class MentraBluetoothSDK {
     private var pendingVideoRecordingRequests: [String: PendingVideoRecordingRequest] = [:]
     private var pendingRgbLedRequests: [String: PendingResponse<RgbLedControlResponseEvent>] = [:]
     private var pendingSettingsRequests: [String: PendingResponse<SettingsAckEvent>] = [:]
-    private var pendingStreamStarts: [String: PendingResponse<StreamStatusEvent>] = [:]
-    private var pendingStreamStop: (streamId: String?, pending: PendingResponse<StreamStatusEvent>)?
+    private var pendingStreamStarts: [String: PendingStreamStart] = [:]
+    private var streamStartSeq = 0
+    // seq is the stop's slot in the shared streamStartSeq order (drawn in the
+    // same await-free MainActor turn that sends the command): every pending
+    // start with a lower seq reached the glasses' FIFO before this stop.
+    private var pendingStreamStop: (streamId: String?, seq: Int, pending: PendingResponse<StreamStatusEvent>)?
     private var pendingGalleryStatus: PendingResponse<GalleryStatusEvent>?
     private var pendingOtaQuery: PendingResponse<OtaQueryResult>?
     private var pendingOtaStart: PendingResponse<OtaStartAckEvent>?
@@ -196,8 +227,24 @@ public final class MentraBluetoothSDK {
             }
         }
         bridgeEventSinkId = Bridge.addEventSink { [weak self] eventName, data in
-            Task { @MainActor [weak self] in
-                self?.dispatchBridgeEvent(eventName, data)
+            // Bridge.dispatchEvent always invokes sinks on the main thread, in the
+            // FIFO order events were dispatched (correlated WiFi-scan chunks rely
+            // on that order). A fresh Task per event can reach the MainActor out
+            // of creation order and reorder chunks, so consume synchronously
+            // while still on main.
+            if Thread.isMainThread {
+                MainActor.assumeIsolated {
+                    self?.dispatchBridgeEvent(eventName, data)
+                }
+            } else {
+                // Defensive fallback only — Bridge.dispatchEvent should never take
+                // this path. A serial main-queue hop still preserves FIFO order,
+                // unlike an unstructured Task.
+                DispatchQueue.main.async {
+                    MainActor.assumeIsolated {
+                        self?.dispatchBridgeEvent(eventName, data)
+                    }
+                }
             }
         }
         storeListenerId = DeviceStore.shared.store.addListener { [weak self] category, changes in
@@ -605,6 +652,59 @@ public final class MentraBluetoothSDK {
         return result
     }
 
+    /// Compatibility path for ASG clients that support only the older one-way FOV command.
+    public func setLegacyCameraFov(_ fov: CameraFov) throws -> CameraFovResult {
+        try DeviceManager.shared.sendLegacyCameraFovSetting(
+            fov: fov.fov,
+            roiPosition: fov.roiPosition.rawValue
+        )
+        return CameraFovResult(
+            requestId: "legacy",
+            fov: fov.fov,
+            roiPosition: fov.roiPosition,
+            timestamp: Int(Date().timeIntervalSince1970 * 1000)
+        )
+    }
+
+    /// Restores the persistent base FOV without requiring a settings acknowledgement.
+    public func restoreLegacyCameraFov() throws {
+        try DeviceManager.shared.restoreLegacyCameraFovSetting()
+    }
+
+    public func setCameraFovOverride(
+        leaseId: String,
+        fov: CameraFov,
+        ttlMs: Int
+    ) async throws -> CameraFovResult {
+        let ack = try await performSettingsCommand(
+            setting: "camera_fov_override",
+            updateStore: { _ in },
+            send: { requestId in
+                try DeviceManager.shared.sendCameraFovOverride(
+                    requestId: requestId,
+                    leaseId: leaseId,
+                    fov: fov.fov,
+                    roiPosition: fov.roiPosition.rawValue,
+                    ttlMs: ttlMs
+                )
+            }
+        )
+        return try CameraFovResult.from(ack: ack, fallback: fov)
+    }
+
+    public func releaseCameraFovOverride(leaseId: String) async throws -> SettingsAckEvent {
+        try await performSettingsCommand(
+            setting: "camera_fov_override",
+            updateStore: { _ in },
+            send: { requestId in
+                try DeviceManager.shared.releaseCameraFovOverride(
+                    requestId: requestId,
+                    leaseId: leaseId
+                )
+            }
+        )
+    }
+
     public func setCameraTuningConfig(anrOn: Bool, gainOn: Bool) async throws -> SettingsAckEvent {
         return try await performSettingsCommand(
             setting: "camera_tuning",
@@ -679,9 +779,12 @@ public final class MentraBluetoothSDK {
             return try await existing.value
         }
         let pending = PendingResponse<[WifiScanResult]>(operation: "WiFi scan request")
-        let request = PendingWifiScan(pending: pending)
+        let request = PendingWifiScan(pending: pending, scanId: "scan-\(UUID().uuidString)")
         pendingWifiScan = request
-        DeviceManager.shared.requestWifiScan()
+        // Claim the scan-results store for this scan before the command goes out,
+        // so a delayed chunk from an older, abandoned scan can no longer mutate it.
+        Bridge.claimWifiScanResults(scanId: request.scanId)
+        DeviceManager.shared.requestWifiScan(scanId: request.scanId)
         let task = Task { @MainActor [weak self] () async throws -> [WifiScanResult] in
             defer {
                 if let self {
@@ -795,7 +898,7 @@ public final class MentraBluetoothSDK {
         pendingPhotoRequests[routedRequest.requestId] = pending
         DeviceManager.shared.requestPhoto(routedRequest)
         do {
-            let event = try await pending.wait()
+            let event = try await pending.wait(timeoutMs: MentraBluetoothSDK.photoRequestTimeoutMs)
             pendingPhotoRequests.removeValue(forKey: routedRequest.requestId)
             return event
         } catch {
@@ -807,6 +910,7 @@ public final class MentraBluetoothSDK {
     public func warmUpCamera(
         requestId: String? = nil,
         size: PhotoSize,
+        mode: PhotoMode = .photo,
         exposureTimeNs: Double?,
         durationMs: Int
     ) async throws -> CameraStatusEvent {
@@ -818,6 +922,7 @@ public final class MentraBluetoothSDK {
             try DeviceManager.shared.warmUpCamera(
                 requestId: effectiveRequestId,
                 size: size,
+                mode: mode,
                 exposureTimeNs: exposureTimeNs,
                 durationMs: durationMs
             )
@@ -830,6 +935,15 @@ public final class MentraBluetoothSDK {
         }
     }
 
+    public func stopCameraWarmUp(requestId: String) throws {
+        guard let effectiveRequestId = nonBlankRequestId(requestId) else {
+            throw BluetoothSdkError(
+                code: "invalid_request", message: "A warm-up request ID is required."
+            )
+        }
+        try DeviceManager.shared.stopCameraWarmUp(requestId: effectiveRequestId)
+    }
+
     public func queryGalleryStatus() async throws -> GalleryStatusEvent {
         if pendingGalleryStatus != nil {
             throw BluetoothSdkError(
@@ -867,7 +981,12 @@ public final class MentraBluetoothSDK {
         let streamId = stringValue(values, "streamId").flatMap { $0.isEmpty ? nil : $0 } ?? "sdk-\(UUID().uuidString)"
         values["streamId"] = streamId
         let pending = PendingResponse<StreamStatusEvent>(operation: "start stream \(streamId)")
-        pendingStreamStarts[streamId] = pending
+        // seq assignment through the BLE hand-off must stay await-free so this
+        // MainActor turn is one critical section: rejectPreemptedStreamStarts
+        // only works if seq order equals the order the commands reach the
+        // glasses' FIFO.
+        streamStartSeq += 1
+        pendingStreamStarts[streamId] = PendingStreamStart(seq: streamStartSeq, pending: pending)
         stopStreamKeepAliveMonitor()
         DeviceManager.shared.startStream(values)
         do {
@@ -920,7 +1039,13 @@ public final class MentraBluetoothSDK {
             )
         }
         let pending = PendingResponse<StreamStatusEvent>(operation: "stop stream")
-        pendingStreamStop = (streamId: activeStreamKeepAlive?.streamId, pending: pending)
+        // The seq draw and the BLE hand-off stay in this single await-free
+        // MainActor turn, sharing startStream's ordering critical section:
+        // the stop takes its own slot in the send order, so its ack can
+        // separate the pending starts the glasses consumed before it (lower
+        // seq) from starts sent after it (higher seq).
+        streamStartSeq += 1
+        pendingStreamStop = (streamId: activeStreamKeepAlive?.streamId, seq: streamStartSeq, pending: pending)
         stopStreamKeepAliveMonitor()
         DeviceManager.shared.stopStream()
         do {
@@ -1411,20 +1536,51 @@ public final class MentraBluetoothSDK {
     }
 
     private func handleStreamStatusForRequests(_ event: StreamStatusEvent) {
-        if let (streamId, pending) = matchingStreamStart(for: event) {
+        if let (streamId, start) = matchingStreamStart(for: event) {
+            // Preemption is only proven by statuses the start path emits after
+            // the glasses' stopAllServices has run: initializing, reconnecting,
+            // reconnected, streaming. An id-stamped `error` can be a
+            // command-level preflight rejection (#3488 firmware) emitted
+            // synchronously before stopAllServices, and `stopped` is a
+            // stop-ack for a previous stream — treating either as a winner
+            // could reject an older start that is still healthy.
+            if let eventStreamId = event.streamId, !eventStreamId.isEmpty {
+                switch event.state {
+                case .initializing, .reconnecting, .reconnected, .streaming:
+                    rejectPreemptedStreamStarts(winnerSeq: start.seq)
+                default:
+                    break
+                }
+            }
             switch event.state {
-            case .streaming:
+            // `reconnected` also proves the stream is live: when an async start
+            // failure triggers the glasses' publisher retry, a successful retry
+            // reports `reconnected` instead of `streaming`.
+            case .streaming, .reconnected:
                 pendingStreamStarts.removeValue(forKey: streamId)
-                pending.resolve(event)
+                start.pending.resolve(event)
             case .reconnectFailed, .stopped:
                 pendingStreamStarts.removeValue(forKey: streamId)
-                pending.reject(streamStatusError(event, code: "stream_start_failed"))
+                start.pending.reject(streamStatusError(start.lastError ?? event, code: "stream_start_failed"))
             case .error:
-                // The glasses publisher automatically retries transient transport
-                // errors. Keep the start pending so a subsequent `streaming`
-                // status can resolve it; `reconnectFailed` or the request timeout
-                // still terminates a publisher that cannot recover.
-                break
+                if let eventStreamId = event.streamId, !eventStreamId.isEmpty, event.willRetry == true {
+                    // The glasses flag errors their publisher will retry with
+                    // `willRetry` (emitting side lands in PR #3488), so keep the
+                    // start pending for the retry's verdict — `reconnected` or
+                    // `streaming` on success, `reconnect_failed` or the
+                    // streamId-less `stopped` wind-down (which reports these
+                    // stashed details) on failure.
+                    start.lastError = event
+                } else {
+                    // An id-less error is the glasses' command-level rejection
+                    // (missing URL, low battery, no WiFi) emitted before any
+                    // publisher starts; an id-carrying error without `willRetry`
+                    // is terminal (`camera_busy` emits an error and nothing else).
+                    // Old firmware never sends `willRetry`, so its errors always
+                    // fail fast here — the shipped pre-#3487 Android behavior.
+                    pendingStreamStarts.removeValue(forKey: streamId)
+                    start.pending.reject(streamStatusError(event, code: "stream_start_failed"))
+                }
             default:
                 break
             }
@@ -1435,6 +1591,7 @@ public final class MentraBluetoothSDK {
                 if pendingStreamStop?.pending === stop.pending {
                     pendingStreamStop = nil
                 }
+                rejectStreamStartsSuperseded(byStopSeq: stop.seq)
                 stop.pending.resolve(stoppedStreamEvent(from: event, fallbackStreamId: stop.streamId))
             } else if event.state == .error || event.state == .reconnectFailed {
                 if pendingStreamStop?.pending === stop.pending {
@@ -1445,12 +1602,73 @@ public final class MentraBluetoothSDK {
         }
     }
 
-    private func matchingStreamStart(for event: StreamStatusEvent) -> (String, PendingResponse<StreamStatusEvent>)? {
+    // The glasses process BLE commands FIFO and every start_stream begins by
+    // stopping whatever runs, so an id-carrying status proving start X's
+    // start path ran on the glasses also proves every lower-seq start has
+    // already been preempted. Their only verdict on current firmware is a
+    // streamId-less stopped, which the id-less heuristic deliberately
+    // ignores — without this they would run out the 30s timeout instead of
+    // failing fast.
+    private func rejectPreemptedStreamStarts(winnerSeq: Int) {
+        for (streamId, start) in pendingStreamStarts where start.seq < winnerSeq {
+            pendingStreamStarts.removeValue(forKey: streamId)
+            start.pending.reject(
+                BluetoothSdkError(
+                    code: "stream_preempted",
+                    message: "start stream \(streamId) was preempted by a newer start_stream; "
+                        + "the glasses run a single stream and the last request wins."
+                )
+            )
+        }
+    }
+
+    // The glasses process BLE commands FIFO, so this stop's ack also settles
+    // every start sent before it: whatever those starts brought up (or would
+    // have brought up) has been stopped, and no further status will arrive
+    // for them. Without this they would run out the 30s start timeout.
+    // Starts sent after the stop keep waiting for their own statuses.
+    private func rejectStreamStartsSuperseded(byStopSeq stopSeq: Int) {
+        for (streamId, start) in pendingStreamStarts where start.seq < stopSeq {
+            pendingStreamStarts.removeValue(forKey: streamId)
+            start.pending.reject(
+                BluetoothSdkError(
+                    code: "stream_stopped",
+                    message: "start stream \(streamId) was superseded by a stop_stream issued after it."
+                )
+            )
+        }
+    }
+
+    private func matchingStreamStart(for event: StreamStatusEvent) -> (String, PendingStreamStart)? {
         if let streamId = event.streamId, !streamId.isEmpty {
-            guard let pending = pendingStreamStarts[streamId] else { return nil }
-            return (streamId, pending)
+            guard let start = pendingStreamStarts[streamId] else { return nil }
+            return (streamId, start)
+        }
+        if event.state == .error {
+            // An id-less error is a command-level preflight rejection (missing
+            // URL, low battery, no WiFi) emitted synchronously, while lifecycle
+            // statuses arrive async — so with overlapping starts the wire is
+            // genuinely ambiguous about which start it answers. Attribute it to
+            // the newest pending start: the common case is a later start
+            // failing preflight while an earlier one is already emitting
+            // lifecycle statuses, and at worst this swaps which start carries
+            // the error instead of letting both time out.
+            guard let entry = pendingStreamStarts.max(by: { $0.value.seq < $1.value.seq }) else { return nil }
+            return (entry.key, entry.value)
         }
         if pendingStreamStarts.count == 1, let entry = pendingStreamStarts.first {
+            // A streamId-less STOPPED is the glasses' stop-ack for a PREVIOUS
+            // stream (their stop ack carries no streamId), not a verdict on the
+            // pending start — a start_stream that replaces a running publisher
+            // emits exactly this sequence (stopped -> initializing -> streaming).
+            // Attributing it here would reject a start that is about to succeed.
+            // After a stashed `willRetry` error for the pending start, though,
+            // the stopped is the retrying publisher's wind-down (the stop-ack
+            // always precedes any status for the new start), so it is that
+            // start's verdict.
+            if event.state == .stopped, entry.value.lastError == nil {
+                return nil
+            }
             return (entry.key, entry.value)
         }
         return nil
@@ -1610,6 +1828,28 @@ public final class MentraBluetoothSDK {
         request.pending.resolve(results)
     }
 
+    // scanId-echoing glasses: results for another scan are ignored instead of
+    // resolving the pending request, and matching chunks accumulate until the
+    // glasses flag the scan complete.
+    private func handleCorrelatedWifiScanChunk(
+        scanId: String,
+        results: [WifiScanResult],
+        scanComplete: Bool
+    ) {
+        guard let request = pendingWifiScan, request.scanId == scanId else { return }
+        for network in results where !request.accumulated.contains(where: { $0.ssid == network.ssid }) {
+            request.accumulated.append(network)
+        }
+        if !request.accumulated.isEmpty {
+            request.latestResults = request.accumulated
+        }
+        guard scanComplete else { return }
+        if pendingWifiScan === request {
+            pendingWifiScan = nil
+        }
+        request.pending.resolve(request.accumulated)
+    }
+
     private func updateWifiScanLatestResults(_ results: [WifiScanResult]) {
         guard !results.isEmpty else { return }
         pendingWifiScan?.latestResults = results
@@ -1617,6 +1857,24 @@ public final class MentraBluetoothSDK {
 
     private func handleWifiStatusForRequests(_ event: WifiStatusEvent) {
         guard let request = pendingWifiStatus else { return }
+        // A wifi_status carrying the explicit error field is the glasses' failure
+        // verdict for the in-flight connect: reject now instead of running out the
+        // request timeout. Only the error field counts as failure — the glasses'
+        // connect sequence emits a debounced bare connected=false ~1-2s after
+        // credentials while association is still in progress, and rejecting on that
+        // would kill every connect attempt early.
+        if request.operation == .connect, let error = event.error {
+            if pendingWifiStatus === request {
+                pendingWifiStatus = nil
+            }
+            request.pending.reject(
+                BluetoothSdkError(
+                    code: error,
+                    message: "Glasses failed to join \"\(request.ssid)\": \(error)"
+                )
+            )
+            return
+        }
         guard wifiStatusMatches(event.status, request: request) else { return }
         if pendingWifiStatus === request {
             pendingWifiStatus = nil
@@ -1803,9 +2061,15 @@ public final class MentraBluetoothSDK {
             let networks = (data["networks"] as? [[String: Any]])?.map(WifiScanResult.init(values:)) ?? []
             let hasCompletionFlag = data.keys.contains("scanComplete") || data.keys.contains("scan_complete")
             let scanComplete = data["scanComplete"] as? Bool ?? data["scan_complete"] as? Bool ?? false
-            updateWifiScanLatestResults(networks)
-            if scanComplete || !hasCompletionFlag {
-                handleWifiScanResultsForRequests(networks)
+            let scanId = (data["scanId"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+            if let scanId {
+                handleCorrelatedWifiScanChunk(scanId: scanId, results: networks, scanComplete: scanComplete)
+            } else {
+                // Old firmware: no correlation id, keep the pre-scanId heuristics.
+                updateWifiScanLatestResults(networks)
+                if scanComplete || !hasCompletionFlag {
+                    handleWifiScanResultsForRequests(networks)
+                }
             }
             delegate?.mentraBluetoothSDK(self, didReceive: .raw(name: "wifi_scan_result", values: data))
         case "hotspot_error":