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

package/ios/Source/sgcs/MentraLiveL2capChannel.swift

@@ -0,0 +1,183 @@
+import CoreBluetooth
+import Foundation
+
+/// Read-only LE L2CAP CoC fast path for Mentra Live file transfers.
+///
+/// BES sends the same K900 file frames over this channel that it otherwise
+/// sends through the FILE_READ GATT characteristic. The stream is drained on
+/// a dedicated thread so CoreBluetooth credits are returned independently of
+/// React Native and main-thread work.
+final class MentraLiveL2capChannel: NSObject, StreamDelegate {
+    private static let readChunkSize = 4096
+    private static let maxBufferSize = 64 * 1024
+    private static let frameHeaderSize = 5
+    private static let frameOverhead = 32
+    private static let maxFilePayloadSize = K900ProtocolUtils.FILE_PACK_SIZE
+
+    private let channel: CBL2CAPChannel
+    private let onFileFrame: (Data) -> Void
+    private let onClose: () -> Void
+    private let stateLock = NSLock()
+
+    private var receiveBuffer = [UInt8]()
+    private var worker: Thread?
+    private var closed = false
+    private var closeNotified = false
+
+    init(
+        channel: CBL2CAPChannel,
+        onFileFrame: @escaping (Data) -> Void,
+        onClose: @escaping () -> Void
+    ) {
+        self.channel = channel
+        self.onFileFrame = onFileFrame
+        self.onClose = onClose
+        super.init()
+    }
+
+    func start() {
+        guard worker == nil else { return }
+        let thread = Thread { [weak self] in
+            self?.runReadLoop()
+        }
+        thread.name = "MentraLive-L2CAP"
+        thread.qualityOfService = .userInitiated
+        worker = thread
+        thread.start()
+    }
+
+    func close() {
+        stateLock.lock()
+        let wasClosed = closed
+        closed = true
+        stateLock.unlock()
+
+        guard !wasClosed else { return }
+        channel.inputStream?.close()
+        channel.outputStream?.close()
+    }
+
+    private var isClosed: Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return closed
+    }
+
+    private func runReadLoop() {
+        guard let input = channel.inputStream, let output = channel.outputStream else {
+            notifyClosed()
+            return
+        }
+
+        input.delegate = self
+        input.schedule(in: .current, forMode: .default)
+        output.schedule(in: .current, forMode: .default)
+        input.open()
+        output.open()
+
+        while !isClosed {
+            _ = RunLoop.current.run(mode: .default, before: Date(timeIntervalSinceNow: 0.1))
+        }
+
+        input.close()
+        output.close()
+        input.remove(from: .current, forMode: .default)
+        output.remove(from: .current, forMode: .default)
+        input.delegate = nil
+        notifyClosed()
+    }
+
+    func stream(_ aStream: Stream, handle eventCode: Stream.Event) {
+        guard aStream === channel.inputStream else { return }
+
+        switch eventCode {
+        case .hasBytesAvailable:
+            drainInput()
+        case .endEncountered, .errorOccurred:
+            close()
+        default:
+            break
+        }
+    }
+
+    private func drainInput() {
+        guard let input = channel.inputStream else { return }
+        var chunk = [UInt8](repeating: 0, count: Self.readChunkSize)
+
+        while input.hasBytesAvailable, !isClosed {
+            let count = input.read(&chunk, maxLength: chunk.count)
+            if count > 0 {
+                appendAndDispatch(Array(chunk.prefix(count)))
+            } else if count < 0 {
+                close()
+                return
+            } else {
+                break
+            }
+        }
+    }
+
+    private func appendAndDispatch(_ bytes: [UInt8]) {
+        if receiveBuffer.count + bytes.count > Self.maxBufferSize {
+            receiveBuffer.removeAll(keepingCapacity: true)
+        }
+        guard bytes.count <= Self.maxBufferSize else { return }
+        receiveBuffer.append(contentsOf: bytes)
+
+        while true {
+            guard let start = startMarkerIndex() else {
+                if receiveBuffer.last == 0x23 {
+                    receiveBuffer = [0x23]
+                } else {
+                    receiveBuffer.removeAll(keepingCapacity: true)
+                }
+                return
+            }
+
+            if start > 0 {
+                receiveBuffer.removeFirst(start)
+            }
+            guard receiveBuffer.count >= Self.frameHeaderSize else { return }
+
+            let payloadSize = (Int(receiveBuffer[3]) << 8) | Int(receiveBuffer[4])
+            guard payloadSize <= Self.maxFilePayloadSize else {
+                receiveBuffer.removeFirst()
+                continue
+            }
+
+            let frameSize = Self.frameOverhead + payloadSize
+            guard receiveBuffer.count >= frameSize else { return }
+
+            guard receiveBuffer[frameSize - 2] == 0x24,
+                  receiveBuffer[frameSize - 1] == 0x24
+            else {
+                receiveBuffer.removeFirst()
+                continue
+            }
+
+            onFileFrame(Data(receiveBuffer.prefix(frameSize)))
+            receiveBuffer.removeFirst(frameSize)
+        }
+    }
+
+    private func startMarkerIndex() -> Int? {
+        guard receiveBuffer.count >= 2 else { return nil }
+        for index in 0 ..< (receiveBuffer.count - 1)
+            where receiveBuffer[index] == 0x23 && receiveBuffer[index + 1] == 0x23
+        {
+            return index
+        }
+        return nil
+    }
+
+    private func notifyClosed() {
+        stateLock.lock()
+        guard !closeNotified else {
+            stateLock.unlock()
+            return
+        }
+        closeNotified = true
+        stateLock.unlock()
+        onClose()
+    }
+}

package/ios/Source/sgcs/MentraNex.swift

@@ -376,7 +376,7 @@ class MentraNexSGC: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate, SG
     func dbg1() {}
     func dbg2() {}
 
-    func requestWifiScan() {}
+    func requestWifiScan(scanId _: String?) {}
 
     func sendWifiCredentials(_: String, _: String) {}
 

package/ios/Source/sgcs/Nimo.swift

@@ -1066,7 +1066,7 @@ class Nimo: NSObject, SGCManager {
 
     // MARK: - SGCManager: Network (no WiFi)
 
-    func requestWifiScan() {}
+    func requestWifiScan(scanId _: String?) {}
     func sendWifiCredentials(_: String, _: String) {}
     func forgetWifiNetwork(_: String) {}
     func sendHotspotState(_: Bool) {}

package/ios/Source/sgcs/SGCManager.swift

@@ -54,6 +54,7 @@ protocol SGCManager {
     // MARK: - Audio Control
 
     func setMicEnabled(_ enabled: Bool)
+    var isMicSuspendedForAudio: Bool { get }
     func sortMicRanking(list: [String]) -> [String]
 
     // MARK: - Messaging
@@ -184,7 +185,7 @@ protocol SGCManager {
 
     // MARK: - Network Management
 
-    func requestWifiScan()
+    func requestWifiScan(scanId: String?)
     func sendWifiCredentials(_ ssid: String, _ password: String)
     func forgetWifiNetwork(_ ssid: String)
     func sendHotspotState(_ enabled: Bool)
@@ -217,6 +218,8 @@ protocol SGCManager {
 /// doesn't seem to work for concurrency reasons :(
 /// we can make read-only getters for convienence though:
 extension SGCManager {
+    var isMicSuspendedForAudio: Bool { false }
+
     /// Default: no-op. Only G2 renders positioned text containers; other glasses ignore it.
     func sendPositionedText(
         _: String, x _: Int32, y _: Int32, width _: Int32, height _: Int32,
@@ -362,7 +365,7 @@ extension SGCManager {
 
     func sendVoiceActivityDetectionSetting() {}
 
-    /// Default no-op; Mentra Live overrides when phone detects clock skew during gallery sync.
+    /// Default no-op; Mentra Live and G2 override to handle phone-detected clock skew.
     func sendSetSystemTime(_: Int64) {
         Bridge.log("SGC: sendSetSystemTime not supported")
     }

package/ios/Source/sgcs/Simulated.swift

@@ -226,7 +226,7 @@ class Simulated: SGCManager {
 
     // MARK: - Network Management
 
-    func requestWifiScan() {
+    func requestWifiScan(scanId _: String?) {
         Bridge.log("requestWifiScan")
     }
 

package/ios/Source/status/WifiHotspotStatus.swift

@@ -133,20 +133,39 @@ public enum WifiStatus: CustomStringConvertible, Equatable {
 public struct WifiStatusEvent: CustomStringConvertible {
     public let status: WifiStatus
 
-    public init(status: WifiStatus) {
+    /// Glasses-reported provisioning failure reason when THIS event is the verdict of a
+    /// failed connect attempt; nil for routine link-state updates. An attempt property,
+    /// not a link property — which is why it lives on the event and not on `WifiStatus`:
+    /// "connect_timeout" arrives with a disconnected status (never associated), while
+    /// "connected_to_other_network" arrives with a *connected* status — the attempt
+    /// failed and Android's auto-join left the glasses on (or returned them to) a
+    /// different SSID than requested, so the link is genuinely up while the request
+    /// genuinely failed. Sent by ASG client builds that include the WiFi error
+    /// surfacing (v40+); older glasses never set it.
+    public let error: String?
+
+    public init(status: WifiStatus, error: String? = nil) {
         self.status = status
+        self.error = error
     }
 
     init(connected: Bool, ssid: String?, localIp: String?) {
         status = WifiStatus.fromStoreFields(connected: connected, ssid: ssid, localIp: localIp) ?? .disconnected
+        error = nil
     }
 
     init(values: [String: Any]) {
         status = WifiStatus(values: values) ?? .disconnected
+        let rawError = stringValue(values, "error")
+        error = rawError?.isEmpty == false ? rawError : nil
     }
 
     public var values: [String: Any] {
-        status.values.merging(["type": "wifi_status_change"]) { _, new in new }
+        var body = status.values.merging(["type": "wifi_status_change"]) { _, new in new }
+        if let error {
+            body["error"] = error
+        }
+        return body
     }
 
     public var description: String {

package/ios/Source/streaming/StreamModels.swift

@@ -553,6 +553,11 @@ public enum StreamStatus: CustomStringConvertible, Equatable {
 
 public struct StreamStatusEvent: CustomStringConvertible {
     public let status: StreamStatus
+    // True when the glasses will retry the failed publisher themselves
+    // (emitting side lands in PR #3488); absent on older firmware and on
+    // events not parsed from a glasses status map. Carried here instead of
+    // as an `.error` associated value so the public case stays unchanged.
+    public private(set) var willRetry: Bool?
 
     public init(status: StreamStatus) {
         self.status = status
@@ -560,6 +565,7 @@ public struct StreamStatusEvent: CustomStringConvertible {
 
     public init(values: [String: Any]) {
         status = StreamStatus(values: values)
+        willRetry = boolValue(values, "willRetry")
     }
 
     public var state: StreamState {
@@ -577,6 +583,9 @@ public struct StreamStatusEvent: CustomStringConvertible {
     public var values: [String: Any] {
         var values = status.values
         values["type"] = "stream_status"
+        if let willRetry {
+            values["willRetry"] = willRetry
+        }
         return values
     }
 

package/ios/Source/tts/TTSTools.swift

@@ -111,7 +111,7 @@ class TTSTools {
                 voiceStyle: (modelPath as NSString).appendingPathComponent(kFileVoiceStyle)
             )
             var modelConfig = sherpaOnnxOfflineTtsModelConfig(
-                numThreads: 2,
+                numThreads: 8,
                 supertonic: supertonic
             )
             var config = sherpaOnnxOfflineTtsConfig(model: modelConfig, maxNumSentences: 1)

package/ios/Source/utils/G1Text.swift

@@ -24,6 +24,33 @@ class G1Text {
 
     init() {}
 
+    /// Converts text to the base Latin glyphs available in G1 firmware.
+    /// Newer glasses bypass this G1-only transport and keep the original text.
+    static func sanitizeForDisplay(_ text: String) -> String {
+        let expanded = text.reduce(into: "") { result, character in
+            switch character {
+            case "Đ", "Ð": result.append("D")
+            case "đ", "ð": result.append("d")
+            case "Ł": result.append("L")
+            case "ł": result.append("l")
+            case "Ø": result.append("O")
+            case "ø": result.append("o")
+            case "Æ": result.append("AE")
+            case "æ": result.append("ae")
+            case "Œ": result.append("OE")
+            case "œ": result.append("oe")
+            case "ẞ": result.append("SS")
+            case "ß": result.append("ss")
+            case "Þ": result.append("TH")
+            case "þ": result.append("th")
+            default: result.append(character)
+            }
+        }
+
+        return expanded
+            .folding(options: .diacriticInsensitive, locale: Locale(identifier: "en_US_POSIX"))
+    }
+
     // MARK: - Text Wall Methods
 
     //    func displayTextWall(_ text: String) {
@@ -72,7 +99,9 @@ class G1Text {
     func chunkTextForTransmission(_ text: String) -> [[UInt8]] {
         // Handle empty or whitespace-only text by sending at least a space
         // This ensures the display gets updated/cleared properly
-        let textToSend = text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? " " : text
+        let textToSend = text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            ? " "
+            : G1Text.sanitizeForDisplay(text)
         guard let textData = textToSend.data(using: .utf8) else { return [] }
         let textBytes = [UInt8](textData)
         let totalChunks = Int(ceil(Double(textBytes.count) / Double(G1Text.MAX_CHUNK_SIZE)))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "0.1.19",
+  "version": "0.1.21-beta.0",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -105,7 +105,6 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "dependencies": {},
   "devDependencies": {
     "@types/node": "^25.9.3",
     "expo-module-scripts": "^55.0.2",

package/src/BluetoothSdk.types.ts

@@ -116,6 +116,16 @@ export function isConnectedWifiStatus(status: WifiStatus): status is ConnectedWi
 
 export type WifiStatusChangeEvent = WifiStatus & {
   type: "wifi_status_change"
+  /**
+   * Glasses-reported provisioning failure reason when THIS event is the verdict of a
+   * failed connect attempt; absent on routine link-state updates. An attempt property,
+   * not a link property — which is why it lives on the event, not on WifiStatus:
+   * "connect_timeout" arrives on a disconnected status (never associated), while
+   * "connected_to_other_network" arrives on a *connected* status (the attempt failed
+   * and the glasses ended up on / fell back to a different SSID than requested).
+   * Requires ASG client v40+ — older glasses never send it.
+   */
+  error?: string
 }
 
 export type HotspotStatus = {state: "disabled"} | {state: "enabled"; ssid: string; password: string; localIp: string}
@@ -405,6 +415,7 @@ export type SettingsAckSetting =
   | "button_video_recording"
   | "button_max_recording_time"
   | "camera_fov"
+  | "camera_fov_override"
   | "camera_tuning"
 
 export type SettingsAckEvent = {
@@ -416,6 +427,7 @@ export type SettingsAckEvent = {
   fov?: number
   roiPosition?: CameraRoiPositionValue
   hardwareApplied?: boolean
+  leaseId?: string
   active?: boolean
   size?: ButtonPhotoSize | string
   width?: number
@@ -440,8 +452,14 @@ export type SettingsAckSuccessEvent = Omit<SettingsAckEvent, "status"> & {
 export type RgbLedAction = "on" | "off"
 export type RgbLedColor = "red" | "green" | "blue" | "orange" | "white"
 export type PhotoSize = "low" | "medium" | "high" | "max"
+export type PhotoMode = "photo" | "text"
 export type ButtonPhotoSize = "low" | "medium" | "high" | "max"
 
+/**
+ * @deprecated Sticky action-button photo presets via {@link BluetoothSdkPublicModule.setPhotoCaptureDefaults}
+ * are deprecated. Prefer per-request {@link BluetoothSdkPublicModule.requestPhoto} options
+ * (e.g. `mode: "text"` for AE ÷3) instead of persisting button-photo tuning on the glasses.
+ */
 export type PhotoCaptureDefaults = {
   size?: PhotoSize
   mfnr?: boolean
@@ -527,6 +545,13 @@ export type CameraFovResult = {
   timestamp: number
 }
 
+export type CameraFovOverrideRequest = CameraFovRequest & {
+  /** Phone-owned lease used to make delayed releases safe. */
+  leaseId: string
+  /** Safety TTL; refresh the same lease/configuration to extend without a HAL restart. */
+  ttlMs?: number
+}
+
 export type CameraFovSetting = {
   fov: number
   roiPosition: CameraRoiPositionValue
@@ -544,6 +569,9 @@ export type PhotoRequestParams = {
   requestId?: string
   appId?: string
   size: PhotoSize
+  mode?: PhotoMode
+  /** `ble` skips direct upload and forces phone-relayed BLE image transfer. */
+  transferMethod?: "auto" | "ble"
   webhookUrl: string | null
   authToken: string | null
   compress: PhotoCompression
@@ -566,9 +594,12 @@ export type PhotoRequestParams = {
 }
 
 export type WarmUpCameraParams = {
+  /** Supply this when the owner needs to call stopCameraWarmUp during teardown. */
   requestId?: string
   size: PhotoSize
+  mode?: PhotoMode
   exposureTimeNs?: number | null
+  /** Ready-state hold; defaults to 15 seconds and is capped at 60 seconds by ASG. */
   durationMs?: number
 }
 
@@ -690,11 +721,25 @@ export type StreamResolvedConfig = {
   }
 }
 
+/** Live encoder telemetry, when the glasses emit it (no firmware does yet). */
+export type StreamLiveStats = {
+  /** Current encoded video bitrate in bits per second. */
+  bitrate?: number
+  /** Current encode frame rate. */
+  fps?: number
+  droppedFrames?: number
+  /** Seconds since the stream started. */
+  duration?: number
+  /** Device temperature in °C, if the hardware reports it. */
+  temperatureC?: number
+}
+
 type StreamStatusCommon = {
   type: "stream_status"
   streamId?: string
   timestamp?: number
   resolvedConfig?: StreamResolvedConfig
+  stats?: StreamLiveStats
 }
 
 export type StreamStatusEvent =
@@ -817,6 +862,8 @@ export type BluetoothSdkModuleEvents = {
   speaking_status: (event: SpeakingStatusEvent) => void
   battery_status: (event: BatteryStatusEvent) => void
   local_transcription: (event: LocalTranscriptionEvent) => void
+  phone_notification: (event: PhoneNotificationEvent) => void
+  phone_notification_dismissed: (event: PhoneNotificationDismissedEvent) => void
   wifi_status_change: (event: WifiStatusChangeEvent) => void
   wifi_scan_result: (event: WifiScanResultEvent) => void
   hotspot_status_change: (event: HotspotStatusChangeEvent) => void
@@ -863,6 +910,23 @@ export interface ExtractionProgressEvent {
   totalBytes: number
 }
 
+export interface PhoneNotificationEvent {
+  notificationId: string
+  app: string
+  title: string
+  content: string
+  priority: string
+  timestamp: number
+  packageName: string
+}
+
+export interface PhoneNotificationDismissedEvent {
+  notificationId: string
+  notificationKey: string
+  packageName: string
+  timestamp: number
+}
+
 export type PublicGlassesStatus = Omit<
   GlassesStatus,
   "otaUpdateAvailable" | "otaProgress" | "otaInProgress" | "otaVersionUrl"
@@ -972,10 +1036,19 @@ export interface BluetoothSdkPublicModule {
 
   setGalleryModeEnabled(enabled: boolean): Promise<SettingsAckSuccessEvent>
   setVoiceActivityDetectionEnabled(enabled: boolean): Promise<void>
+  /**
+   * @deprecated Sticky action-button photo presets are deprecated. Prefer per-request
+   * `requestPhoto(...)` options (e.g. `mode: "text"` for AE ÷3, or explicit per-shot
+   * fields). Still functional until removed in a future release.
+   */
   setPhotoCaptureDefaults(settings: PhotoCaptureDefaults): Promise<SettingsAckSuccessEvent>
   setVideoRecordingDefaults(settings: VideoRecordingDefaults): Promise<SettingsAckSuccessEvent>
   setMaxVideoRecordingDuration(minutes: number): Promise<SettingsAckSuccessEvent>
   setCameraFov(request: CameraFovRequest): Promise<CameraFovResult>
+  /** One-way FOV command for legacy ASG clients that do not send settings acknowledgements. */
+  setLegacyCameraFov(request: CameraFovRequest): Promise<CameraFovResult>
+  setCameraFovOverride(request: CameraFovOverrideRequest): Promise<CameraFovResult>
+  releaseCameraFovOverride(leaseId: string): Promise<SettingsAckSuccessEvent>
   /**
    * Configure camera HAL tuning (ANR / gain) on Mentra Live glasses.
    *
@@ -993,6 +1066,8 @@ export interface BluetoothSdkPublicModule {
   queryGalleryStatus(): Promise<GalleryStatusEvent>
   requestPhoto(params: PhotoRequestParams): Promise<PhotoSuccessResponseEvent>
   warmUpCamera(params: WarmUpCameraParams): Promise<CameraStatusEvent>
+  /** Release one request-owned warm-up. Opening requests reject with camera_warm_up_cancelled. */
+  stopCameraWarmUp(requestId: string): Promise<void>
   startVideoRecording(
     requestId: string,
     save: boolean,

package/src/_internal.ts

@@ -9,3 +9,5 @@
 export {default} from "./_private/BluetoothSdkModule"
 export type {BluetoothSdkInternalModule} from "./_private/BluetoothSdkModule"
 export * from "./BluetoothSdk.types"
+export {default as MentraLocalNetwork} from "./_private/MentraLocalNetworkModule"
+export * from "./_private/MentraLocalNetworkModule"