@mentra/bluetooth-sdk 0.1.17 → 0.1.18

package/README.md

@@ -475,7 +475,7 @@ For bare native iOS apps, use the public SwiftPM repository:
 https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git
 ```
 
-Select version `0.1.16`, then add the `MentraBluetoothSDK` product to your app target.
+Select version `0.1.18`, then add the `MentraBluetoothSDK` product to your app target.
 
 For local SDK development, add this package folder directly in Xcode:
 

package/android/src/main/java/com/mentra/bluetoothsdk/Bridge.kt

@@ -30,6 +30,18 @@ public class Bridge private constructor() {
         private const val MIC_CHANNELS = 1
         private const val LC3_FRAME_DURATION_MS = 10
         private const val DEFAULT_LC3_FRAME_SIZE_BYTES = 60
+        private val AUDIO_TRACE_METADATA_KEYS =
+                listOf(
+                        "sampleRate",
+                        "bitsPerSample",
+                        "channels",
+                        "encoding",
+                        "frameDurationMs",
+                        "frameSizeBytes",
+                        "bitrate",
+                        "packetizedFromGlasses",
+                        "voiceActivityDetectionEnabled",
+                )
 
         @Volatile private var instance: Bridge? = null
 
@@ -731,13 +743,14 @@ public class Bridge private constructor() {
                     return
                 }
 
-                if (shouldTraceTypedMessage(type)) {
+                val tracePayload = tracePayloadForTypedMessage(type, mutableBody as Map<String, Any>)
+                if (tracePayload != null) {
                     try {
                         BleTraceLogger.logMap(
                             "phone_to_app",
                             "sdk_event_dispatch",
                             type,
-                            mutableBody as Map<String, Any>,
+                            tracePayload,
                         )
                     } catch (e: Exception) {
                         Log.d(TAG, "BLE trace logging failed for typed message '$type'", e)
@@ -762,8 +775,43 @@ public class Bridge private constructor() {
             }
         }
 
-        private fun shouldTraceTypedMessage(type: String): Boolean =
-                type != "log" && type != "mic_pcm" && type != "mic_lc3"
+        private fun tracePayloadForTypedMessage(
+                type: String,
+                body: Map<String, Any>
+        ): Map<String, Any>? =
+                when {
+                    type == "log" -> null
+                    isAudioPayloadEvent(type) -> audioTracePayload(type, body)
+                    else -> body
+                }
+
+        private fun isAudioPayloadEvent(type: String): Boolean =
+                type == "mic_pcm" || type == "mic_lc3"
+
+        private fun audioTracePayload(type: String, body: Map<String, Any>): Map<String, Any> {
+            val payload = HashMap<String, Any>()
+            payload["type"] = type
+            payload["timestamp"] = System.currentTimeMillis()
+            payload["payloadOmitted"] = true
+            payload["payloadOmittedReason"] = "audio"
+
+            val audioBytes =
+                    when (type) {
+                        "mic_pcm" -> (body["pcm"] as? ByteArray)?.size
+                        "mic_lc3" -> (body["lc3"] as? ByteArray)?.size
+                        else -> null
+                    }
+            audioBytes?.let { payload["audioBytes"] = it }
+
+            AUDIO_TRACE_METADATA_KEYS.forEach { key ->
+                val value = body[key]
+                if (value != null) {
+                    payload[key] = value
+                }
+            }
+
+            return payload
+        }
     }
 
     init {

package/ios/LocalPhotoUploadServer.swift

@@ -104,6 +104,7 @@ final class LocalPhotoUploadServer {
   }
 
   private func handle(_ connection: NWConnection) {
+    traceWifiInput("photo_receiver_connection", connection: connection, state: nil)
     connection.start(queue: queue)
     receive(connection, state: RequestReadState())
   }
@@ -171,6 +172,14 @@ final class LocalPhotoUploadServer {
       let request = HttpRequest.parse(headerText)
       state.request = request
       onLog("\(request.method) \(request.path)")
+      var requestTraceValues: [String: Any] = [
+        "method": request.method,
+        "path": request.path,
+      ]
+      if let contentLength = request.headers["content-length"].flatMap(Int.init) {
+        requestTraceValues["contentLength"] = contentLength
+      }
+      traceWifiInput("photo_receiver_request", connection: connection, state: state, values: requestTraceValues)
 
       if request.method == "GET", request.path == "/" || request.path == "/health" {
         writeJson(connection, status: 200, body: #"{"ok":true,"service":"mentra-photo-upload-receiver"}"#)
@@ -263,6 +272,29 @@ final class LocalPhotoUploadServer {
     )
 
     onLog("upload fields=\(parsed.fields.keys.joined(separator: ",")) requestId=\(requestId ?? "") bytes=\(photoPart.byteCount) saved=\(photoFile.path)")
+    var uploadReceivedTraceValues: [String: Any] = [
+      "durationMs": Int(Date().timeIntervalSince1970 * 1000 - state.startMs),
+      "photoBytes": photoPart.byteCount,
+      "contentLength": state.contentLength,
+      "method": request.method,
+      "path": request.path,
+    ]
+    if let requestId {
+      uploadReceivedTraceValues["requestId"] = requestId
+    }
+    traceWifiInput("photo_receiver_upload_received", connection: connection, state: state, values: uploadReceivedTraceValues)
+    var uploadResponseTraceValues: [String: Any] = [
+      "statusCode": 200,
+      "success": true,
+      "durationMs": Int(Date().timeIntervalSince1970 * 1000 - state.startMs),
+      "contentLength": state.contentLength,
+      "method": request.method,
+      "path": request.path,
+    ]
+    if let requestId {
+      uploadResponseTraceValues["requestId"] = requestId
+    }
+    traceWifiOutput("photo_receiver_response", connection: connection, state: state, values: uploadResponseTraceValues)
     writeJson(
       connection,
       status: 200,
@@ -370,6 +402,51 @@ final class LocalPhotoUploadServer {
     }
   }
 
+  private func traceWifiInput(
+    _ type: String,
+    connection: NWConnection,
+    state: RequestReadState?,
+    values: [String: Any] = [:]
+  ) {
+    traceWifi(direction: "wifi_to_phone", layer: "wifi_http_input", type: type, connection: connection, state: state, values: values)
+  }
+
+  private func traceWifiOutput(
+    _ type: String,
+    connection: NWConnection,
+    state: RequestReadState?,
+    values: [String: Any] = [:]
+  ) {
+    traceWifi(direction: "phone_to_wifi", layer: "wifi_http_output", type: type, connection: connection, state: state, values: values)
+  }
+
+  private func traceWifi(
+    direction: String,
+    layer: String,
+    type: String,
+    connection: NWConnection,
+    state: RequestReadState?,
+    values: [String: Any]
+  ) {
+    var payload = endpointPayload(type: type, connection: connection)
+    if let state {
+      payload["startMs"] = state.startMs
+    }
+    for (key, value) in values {
+      payload[key] = value
+    }
+    BleTraceLogger.logMap(direction: direction, layer: layer, type: type, payload: payload)
+  }
+
+  private func endpointPayload(type: String, connection: NWConnection) -> [String: Any] {
+    var payload: [String: Any] = ["type": type]
+    if case let .hostPort(host, port) = connection.endpoint {
+      payload["remoteHost"] = String(describing: host)
+      payload["remotePort"] = Int(port.rawValue)
+    }
+    return payload
+  }
+
   private struct HttpRequest {
     let method: String
     let path: String
@@ -613,6 +690,7 @@ final class LocalPhotoUploadServer {
   }
 
   private final class RequestReadState {
+    let startMs = Date().timeIntervalSince1970 * 1000
     var buffer = Data()
     var request: HttpRequest?
     var contentLength = 0

package/ios/MentraPhotoReceiverModule.swift

@@ -79,6 +79,16 @@ public class MentraPhotoReceiverModule: Module {
   }
 
   private func handlePhotoUpload(_ upload: PhotoUpload) {
+    BleTraceLogger.logMap(
+      direction: "phone_to_app",
+      layer: "photo_receiver_event",
+      type: "photo_upload",
+      payload: [
+        "requestId": upload.requestId ?? "",
+        "fileName": upload.photoFile.lastPathComponent,
+        "byteCount": upload.byteCount,
+      ]
+    )
     sendEvent("photoUpload", [
       "requestId": upload.requestId as Any,
       "fileUri": upload.photoFile.absoluteString,

package/ios/Source/BluetoothSdkDefaults.swift

@@ -7,7 +7,7 @@ enum BluetoothSdkDefaults {
     }
 
     static let voiceActivityDetectionEnabled = false
-    private static let swiftPackageSdkVersion = "0.1.17"
+    private static let swiftPackageSdkVersion = "0.1.18"
     private static let swiftPackageSdkVersionPlaceholder = "__MENTRA" + "_BLUETOOTH_SDK_VERSION__"
 
     private static func normalizedSdkVersion(_ value: String?) -> String? {

package/ios/Source/Bridge.swift

@@ -15,6 +15,17 @@ class Bridge {
     private static let micChannels = 1
     private static let lc3FrameDurationMs = 10
     private static let defaultLc3FrameSizeBytes = 60
+    private static let audioTraceMetadataKeys = [
+        "sampleRate",
+        "bitsPerSample",
+        "channels",
+        "encoding",
+        "frameDurationMs",
+        "frameSizeBytes",
+        "bitrate",
+        "packetizedFromGlasses",
+        "voiceActivityDetectionEnabled",
+    ]
     private static let eventSinkLock = NSLock()
     private static let defaultEventSinkId = "default"
     private static var eventSinks: [String: (String, [String: Any]) -> Void] = [:]
@@ -486,7 +497,59 @@ class Bridge {
     static func sendTypedMessage(_ type: String, body: [String: Any]) {
         var body = body
         body["type"] = type
+        if let tracePayload = tracePayloadForTypedMessage(type, body: body) {
+            BleTraceLogger.logMap(
+                direction: "phone_to_app",
+                layer: "sdk_event_dispatch",
+                type: type,
+                payload: tracePayload
+            )
+        }
         // Send directly using type as event name - no JSON serialization
         dispatchEvent(type, body)
     }
+
+    private static func tracePayloadForTypedMessage(_ type: String, body: [String: Any]) -> [String: Any]? {
+        if type == "log" {
+            return nil
+        }
+        if isAudioPayloadEvent(type) {
+            return audioTracePayload(type, body: body)
+        }
+        return body
+    }
+
+    private static func isAudioPayloadEvent(_ type: String) -> Bool {
+        type == "mic_pcm" || type == "mic_lc3"
+    }
+
+    private static func audioTracePayload(_ type: String, body: [String: Any]) -> [String: Any] {
+        var payload: [String: Any] = [
+            "type": type,
+            "timestamp": Int(Date().timeIntervalSince1970 * 1000),
+            "payloadOmitted": true,
+            "payloadOmittedReason": "audio",
+        ]
+
+        switch type {
+        case "mic_pcm":
+            if let data = body["pcm"] as? Data {
+                payload["audioBytes"] = data.count
+            }
+        case "mic_lc3":
+            if let data = body["lc3"] as? Data {
+                payload["audioBytes"] = data.count
+            }
+        default:
+            break
+        }
+
+        for key in audioTraceMetadataKeys {
+            if let value = body[key] {
+                payload[key] = value
+            }
+        }
+
+        return payload
+    }
 }

package/ios/Source/internal/BleTraceLogger.swift

@@ -0,0 +1,192 @@
+import Foundation
+import os.log
+import UIKit
+
+enum BleTraceLogger {
+    private static let log = OSLog(subsystem: "com.mentra.bluetoothsdk", category: "MentraBleTrace")
+    private static let maxPayloadChars = 3000
+    private static let k900Type = "k900"
+    private static let sensitiveKeyParts = ["password", "pass", "token", "secret", "authorization", "auth", "email"]
+
+    static func logJson(
+        direction: String,
+        layer: String,
+        payload: [String: Any]?,
+        bytes: Int? = nil,
+        sourceFile: String = #fileID,
+        sourceFunction: String = #function,
+        sourceLine: Int = #line
+    ) {
+        guard let payload else {
+            emit(format(
+                direction: direction,
+                layer: layer,
+                source: source(file: sourceFile, function: sourceFunction, line: sourceLine),
+                type: "null",
+                bytes: bytes,
+                payload: "null"
+            ))
+            return
+        }
+
+        let sanitized = sanitizeDictionary(payload)
+        emit(format(
+            direction: direction,
+            layer: layer,
+            source: source(file: sourceFile, function: sourceFunction, line: sourceLine),
+            type: extractType(from: payload),
+            bytes: bytes,
+            payload: jsonString(sanitized)
+        ))
+    }
+
+    static func logMap(
+        direction: String,
+        layer: String,
+        type: String?,
+        payload: [String: Any],
+        bytes: Int? = nil,
+        sourceFile: String = #fileID,
+        sourceFunction: String = #function,
+        sourceLine: Int = #line
+    ) {
+        let sanitized = sanitizeDictionary(payload)
+        emit(format(
+            direction: direction,
+            layer: layer,
+            source: source(file: sourceFile, function: sourceFunction, line: sourceLine),
+            type: type ?? extractType(from: sanitized),
+            bytes: bytes,
+            payload: jsonString(sanitized)
+        ))
+    }
+
+    static func logLifecycle(component: String, event: String, extra: [String: Any] = [:]) {
+        var payload: [String: Any] = [
+            "event": event,
+            "component": component,
+            "pid": ProcessInfo.processInfo.processIdentifier,
+            "model": UIDevice.current.model,
+            "systemVersion": UIDevice.current.systemVersion,
+        ]
+        for (key, value) in extra {
+            payload[key] = value
+        }
+        logMap(direction: "phone_app", layer: "app_lifecycle", type: event, payload: payload)
+    }
+
+    private static func emit(_ line: String) {
+        os_log("%{public}@", log: log, type: .info, line)
+    }
+
+    private static func format(
+        direction: String,
+        layer: String,
+        source: String,
+        type: String,
+        bytes: Int?,
+        payload: String
+    ) -> String {
+        let bytesText = bytes.map { " bytes=\($0)" } ?? ""
+        return "BLE_TRACE direction=\(direction) layer=\(layer) source=\(source) type=\(type)\(bytesText) payload=\(truncate(payload))"
+    }
+
+    private static func extractType(from payload: [String: Any]) -> String {
+        if let type = payload["type"] as? String, !type.isEmpty {
+            return type
+        }
+        if let cValue = payload["C"] as? String, !cValue.isEmpty {
+            if let data = cValue.data(using: .utf8),
+               let inner = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+               let type = inner["type"] as? String,
+               !type.isEmpty
+            {
+                return type
+            }
+            return extractK900Type(cValue)
+        }
+        return "unknown"
+    }
+
+    private static func extractK900Type(_ value: String) -> String {
+        value == "sr_log" ? "\(k900Type):sr_log" : k900Type
+    }
+
+    private static func sanitizeDictionary(_ value: [String: Any]) -> [String: Any] {
+        var output: [String: Any] = [:]
+        for (key, child) in value {
+            output[key] = sanitizeValue(key: key, value: child)
+        }
+        return output
+    }
+
+    private static func sanitizeArray(_ value: [Any]) -> [Any] {
+        value.map { sanitizeValue(key: nil, value: $0) }
+    }
+
+    private static func sanitizeValue(key: String?, value: Any) -> Any {
+        if let key, sensitiveKeyParts.contains(where: { key.localizedCaseInsensitiveContains($0) }) {
+            return "<redacted>"
+        }
+
+        if key == "C", let stringValue = value as? String {
+            if let data = stringValue.data(using: .utf8),
+               let parsed = try? JSONSerialization.jsonObject(with: data)
+            {
+                return jsonString(sanitizeJsonValue(parsed))
+            }
+            return sanitizeK900Command(stringValue)
+        }
+
+        return sanitizeJsonValue(value)
+    }
+
+    private static func sanitizeJsonValue(_ value: Any) -> Any {
+        switch value {
+        case let dictionary as [String: Any]:
+            return sanitizeDictionary(dictionary)
+        case let array as [Any]:
+            return sanitizeArray(array)
+        case let data as Data:
+            return "<data \(data.count) bytes>"
+        case let url as URL:
+            return url.absoluteString
+        case let bool as Bool:
+            return bool
+        case let number as NSNumber:
+            return number
+        case let string as String:
+            return string
+        case _ as NSNull:
+            return NSNull()
+        default:
+            return String(describing: value)
+        }
+    }
+
+    private static func sanitizeK900Command(_ value: String) -> String {
+        value == "sr_log" ? value : "<non-json C payload>"
+    }
+
+    private static func jsonString(_ value: Any) -> String {
+        guard JSONSerialization.isValidJSONObject(value),
+              let data = try? JSONSerialization.data(withJSONObject: value),
+              let string = String(data: data, encoding: .utf8)
+        else {
+            return String(describing: value)
+        }
+        return string
+    }
+
+    private static func source(file: String, function: String, line: Int) -> String {
+        "\(function)(\(file):\(line))"
+    }
+
+    private static func truncate(_ value: String) -> String {
+        guard value.count > maxPayloadChars else {
+            return value
+        }
+        let endIndex = value.index(value.startIndex, offsetBy: maxPayloadChars)
+        return "\(value[..<endIndex])...(truncated \(value.count - maxPayloadChars) chars)"
+    }
+}

package/ios/Source/sgcs/MentraLive.swift

@@ -1134,9 +1134,13 @@ extension MentraLive: CBPeripheralDelegate {
 
     nonisolated func peripheral(_: CBPeripheral, didWriteValueFor _: CBCharacteristic, error: Error?) {
         let errorDescription = error?.localizedDescription
-        DispatchQueue.main.async {
+        DispatchQueue.main.async { [weak self] in
             if let errorDescription {
                 Bridge.log("LIVE: Error writing characteristic: \(errorDescription)")
+                self?.logBleWriteTrace("write_callback", self?.pending?.trace, extra: [
+                    "success": false,
+                    "errorMessage": errorDescription,
+                ])
             } else {
                 Bridge.log("LIVE: Characteristic write successful")
             }
@@ -1358,6 +1362,8 @@ class MentraLive: NSObject, SGCManager {
     private let SIGNAL_STRENGTH_READ_INTERVAL_MS: TimeInterval = 10.0
     private let MIN_SEND_DELAY_MS: UInt64 = 160_000_000 // 160ms in nanoseconds
     private let READINESS_CHECK_INTERVAL_MS: TimeInterval = 2.5 // 2.5 seconds
+    private let SIGNIFICANT_BLE_TRACE_DELAY_MS: TimeInterval = 250
+    private let SIGNIFICANT_BLE_TRACE_QUEUE_SIZE = 5
 
     /// Device Settings Keys
     private let PREFS_DEVICE_NAME = "MentraLiveLastConnectedDeviceName"
@@ -1385,6 +1391,7 @@ class MentraLive: NSObject, SGCManager {
     private var isNewVersion = false
     private var globalMessageId = 0
     private var lastReceivedMessageId = 0
+    private var bleWriteTraceSequence = 0
 
     private var fullyBooted: Bool {
         get { DeviceStore.shared.get("glasses", "fullyBooted") as? Bool ?? false }
@@ -1741,15 +1748,40 @@ class MentraLive: NSObject, SGCManager {
     // MARK: - Command Queue
 
     class PendingMessage {
-        init(data: Data, id: String, retries: Int) {
+        init(data: Data, id: String, retries: Int, trace: BleWriteTrace? = nil) {
             self.data = data
             self.id = id
             self.retries = retries
+            self.trace = trace
         }
 
         let data: Data
         let retries: Int
         let id: String
+        let trace: BleWriteTrace?
+    }
+
+    struct OutgoingBleCommandTraceInfo {
+        let commandType: String
+        let requestId: String?
+        let appId: String?
+        let messageId: Int64?
+    }
+
+    struct BleWriteTrace {
+        let sequence: Int
+        let commandType: String
+        let requestId: String?
+        let appId: String?
+        let messageId: Int64?
+        let chunkId: String?
+        let chunkIndex: Int?
+        let totalChunks: Int?
+        let payloadBytes: Int?
+        let packedBytes: Int
+        let wakeup: Bool
+        let chunked: Bool
+        let queuedAtMs: TimeInterval
     }
 
     private var pending: PendingMessage?
@@ -1758,12 +1790,14 @@ class MentraLive: NSObject, SGCManager {
     actor CommandQueue {
         private var commands: [PendingMessage] = []
 
-        func enqueue(_ command: PendingMessage) {
+        func enqueue(_ command: PendingMessage) -> Int {
             commands.append(command)
+            return commands.count
         }
 
-        func pushToFront(_ command: PendingMessage) {
+        func pushToFront(_ command: PendingMessage) -> Int {
             commands.insert(command, at: 0)
+            return commands.count
         }
 
         func dequeue() -> PendingMessage? {
@@ -1791,18 +1825,28 @@ class MentraLive: NSObject, SGCManager {
         guard let peripheral = connectedPeripheral,
               let txChar = txCharacteristic
         else {
+            logBleWriteTrace("write_dropped", message.trace, extra: [
+                "errorMessage": "missing peripheral or TX characteristic",
+            ])
             return
         }
 
         // Enforce rate limiting
         let currentTime = Date().timeIntervalSince1970 * 1000
         let timeSinceLastSend = currentTime - lastSendTimeMs
+        let queueDelayMs = message.trace.map { currentTime - $0.queuedAtMs }
 
         try? await Task.sleep(nanoseconds: UInt64(1_000_000))
         lastSendTimeMs = Date().timeIntervalSince1970 * 1000
 
         // Send the data
         peripheral.writeValue(message.data, for: txChar, type: .withResponse)
+        logBleWriteTrace("write_requested", message.trace, extra: [
+            "queueDelayMs": queueDelayMs,
+            "timeSinceLastSendMs": timeSinceLastSend,
+            "currentMtu": currentMtu,
+            "writeType": "withResponse",
+        ])
 
         // don't do the retry system on the old glasses versions
         if !isNewVersion {
@@ -1844,12 +1888,19 @@ class MentraLive: NSObject, SGCManager {
             let retryMessage = PendingMessage(
                 data: pendingMessage.data,
                 id: pendingMessage.id,
-                retries: pendingMessage.retries + 1
+                retries: pendingMessage.retries + 1,
+                trace: pendingMessage.trace
             )
 
             // Push to front of queue for immediate retry
             Task {
-                await self.commandQueue.pushToFront(retryMessage)
+                let queueSize = await self.commandQueue.pushToFront(retryMessage)
+                await MainActor.run {
+                    self.logBleWriteTrace("retry_queued", retryMessage.trace, extra: [
+                        "retryDelayMs": 0,
+                        "queueSizeAfterAdd": queueSize,
+                    ])
+                }
             }
 
             Bridge.log(
@@ -2102,6 +2153,7 @@ class MentraLive: NSObject, SGCManager {
     private func processJsonObject(_ json: [String: Any]) {
         // Log ALL incoming JSON objects for debugging
         // Bridge.log("LIVE: DEBUG: processJsonObject: \(json)")
+        BleTraceLogger.logJson(direction: "glasses_to_phone", layer: "sdk_ble_event", payload: json)
 
         if MessageChunker.isChunkedMessage(json) {
             processChunkedJsonObject(json)
@@ -3651,8 +3703,211 @@ class MentraLive: NSObject, SGCManager {
     // MARK: - Sending Data
 
     func queueSend(_ data: Data, id: String) {
+        queueSend(data, id: id, trace: nil)
+    }
+
+    func queueSend(_ data: Data, id: String, trace: BleWriteTrace?) {
+        let significantQueueSize = SIGNIFICANT_BLE_TRACE_QUEUE_SIZE
         Task {
-            await commandQueue.enqueue(PendingMessage(data: data, id: id, retries: 0))
+            let queueSize = await commandQueue.enqueue(PendingMessage(data: data, id: id, retries: 0, trace: trace))
+            guard trace != nil, queueSize >= significantQueueSize else {
+                return
+            }
+            await MainActor.run {
+                self.logBleChunkTrace("queued", trace, extra: [
+                    "queueSizeAfterAdd": queueSize,
+                ])
+            }
+        }
+    }
+
+    private func outgoingBleCommandTraceInfo(_ json: [String: Any]) -> OutgoingBleCommandTraceInfo {
+        OutgoingBleCommandTraceInfo(
+            commandType: nonBlankString(json["type"]) ?? "unknown",
+            requestId: nonBlankString(json["requestId"]),
+            appId: nonBlankString(json["appId"]),
+            messageId: traceInt64(json["mId"])
+        )
+    }
+
+    private func createBleWriteTrace(
+        commandInfo: OutgoingBleCommandTraceInfo,
+        chunkId: String?,
+        chunkIndex: Int?,
+        totalChunks: Int?,
+        payloadBytes: Int?,
+        packedBytes: Int,
+        wakeup: Bool,
+        chunked: Bool
+    ) -> BleWriteTrace {
+        let sequence = bleWriteTraceSequence
+        bleWriteTraceSequence += 1
+        return BleWriteTrace(
+            sequence: sequence,
+            commandType: commandInfo.commandType,
+            requestId: commandInfo.requestId,
+            appId: commandInfo.appId,
+            messageId: commandInfo.messageId,
+            chunkId: chunkId,
+            chunkIndex: chunkIndex,
+            totalChunks: totalChunks,
+            payloadBytes: payloadBytes,
+            packedBytes: packedBytes,
+            wakeup: wakeup,
+            chunked: chunked,
+            queuedAtMs: Date().timeIntervalSince1970 * 1000
+        )
+    }
+
+    private func logBleChunkTrace(
+        _ stage: String,
+        _ trace: BleWriteTrace?,
+        extra: [String: Any?] = [:]
+    ) {
+        logBleTrace(layer: "sdk_ble_chunk", stage: stage, trace: trace, extra: extra)
+    }
+
+    private func logBleWriteTrace(
+        _ stage: String,
+        _ trace: BleWriteTrace?,
+        extra: [String: Any?] = [:]
+    ) {
+        logBleTrace(layer: "sdk_ble_write", stage: stage, trace: trace, extra: extra)
+    }
+
+    private func logBleTrace(
+        layer: String,
+        stage: String,
+        trace: BleWriteTrace?,
+        extra: [String: Any?] = [:]
+    ) {
+        guard let trace,
+              let warningReason = bleTraceWarningReason(stage: stage, extra: extra)
+        else {
+            return
+        }
+
+        var payload: [String: Any] = [
+            "level": "warning",
+            "warningReason": warningReason,
+            "stage": stage,
+            "sequence": trace.sequence,
+            "commandType": trace.commandType,
+            "packedBytes": trace.packedBytes,
+            "wakeup": trace.wakeup,
+            "chunked": trace.chunked,
+            "queuedAtMs": trace.queuedAtMs,
+        ]
+        if let requestId = trace.requestId { payload["requestId"] = requestId }
+        if let appId = trace.appId { payload["appId"] = appId }
+        if let messageId = trace.messageId { payload["messageId"] = messageId }
+        if let chunkId = trace.chunkId { payload["chunkId"] = chunkId }
+        if let chunkIndex = trace.chunkIndex {
+            payload["chunkIndex"] = chunkIndex
+            payload["chunkNumber"] = chunkIndex + 1
+        }
+        if let totalChunks = trace.totalChunks { payload["totalChunks"] = totalChunks }
+        if let payloadBytes = trace.payloadBytes { payload["payloadBytes"] = payloadBytes }
+        for (key, value) in extra {
+            if let value {
+                payload[key] = value
+            }
+        }
+
+        BleTraceLogger.logMap(direction: "phone_to_glasses", layer: layer, type: trace.commandType, payload: payload)
+    }
+
+    private func bleTraceWarningReason(stage: String, extra: [String: Any?]) -> String? {
+        if extraValue(extra, "errorClass") != nil || extraValue(extra, "errorMessage") != nil {
+            return "ble_write_error"
+        }
+        if let success = extraValue(extra, "success") as? Bool, !success {
+            return "ble_write_failed"
+        }
+        if let writeAccepted = extraValue(extra, "writeAccepted") as? Bool, !writeAccepted {
+            return "ble_write_rejected"
+        }
+        if traceDouble(extraValue(extra, "queueDelayMs")).map({ $0 >= SIGNIFICANT_BLE_TRACE_DELAY_MS }) == true {
+            return "queue_delay"
+        }
+        if traceDouble(extraValue(extra, "callbackDelayMs")).map({ $0 >= SIGNIFICANT_BLE_TRACE_DELAY_MS }) == true {
+            return "write_callback_delay"
+        }
+        if traceDouble(extraValue(extra, "remainingDelayMs")).map({ $0 >= SIGNIFICANT_BLE_TRACE_DELAY_MS }) == true {
+            return "rate_limit_delay"
+        }
+        if traceDouble(extraValue(extra, "nextProcessDelayMs")).map({ $0 >= SIGNIFICANT_BLE_TRACE_DELAY_MS }) == true {
+            return "next_process_delay"
+        }
+        if extraValue(extra, "retryDelayMs") != nil {
+            return "write_retry"
+        }
+        if stage == "queued",
+           traceInt(extraValue(extra, "queueSizeAfterAdd")).map({ $0 >= SIGNIFICANT_BLE_TRACE_QUEUE_SIZE }) == true
+        {
+            return "queue_depth"
+        }
+        return nil
+    }
+
+    private func extraValue(_ extra: [String: Any?], _ key: String) -> Any? {
+        extra[key] ?? nil
+    }
+
+    private func nonBlankString(_ value: Any?) -> String? {
+        guard let value else { return nil }
+        let string: String
+        if let value = value as? String {
+            string = value
+        } else {
+            string = String(describing: value)
+        }
+        return string.isEmpty ? nil : string
+    }
+
+    private func traceInt64(_ value: Any?) -> Int64? {
+        guard let value else { return nil }
+        switch value {
+        case let value as Int64:
+            return value
+        case let value as Int:
+            return Int64(value)
+        case let value as NSNumber:
+            return value.int64Value
+        case let value as String:
+            return Int64(value)
+        default:
+            return nil
+        }
+    }
+
+    private func traceInt(_ value: Any?) -> Int? {
+        guard let value else { return nil }
+        switch value {
+        case let value as Int:
+            return value
+        case let value as NSNumber:
+            return value.intValue
+        case let value as String:
+            return Int(value)
+        default:
+            return nil
+        }
+    }
+
+    private func traceDouble(_ value: Any?) -> Double? {
+        guard let value else { return nil }
+        switch value {
+        case let value as Double:
+            return value
+        case let value as Int:
+            return Double(value)
+        case let value as NSNumber:
+            return value.doubleValue
+        case let value as String:
+            return Double(value)
+        default:
+            return nil
         }
     }
 
@@ -3671,6 +3926,14 @@ class MentraLive: NSObject, SGCManager {
 
             let jsonData = try JSONSerialization.data(withJSONObject: json)
             if let jsonString = String(data: jsonData, encoding: .utf8) {
+                let commandInfo = outgoingBleCommandTraceInfo(json)
+                BleTraceLogger.logJson(
+                    direction: "phone_to_glasses",
+                    layer: "sdk_ble_command",
+                    payload: json,
+                    bytes: jsonData.count
+                )
+
                 // First check if the message needs chunking
                 // Create a test C-wrapped version to check size
                 var testWrapper: [String: Any] = [K900ProtocolUtils.FIELD_C: jsonString]
@@ -3707,7 +3970,21 @@ class MentraLive: NSObject, SGCManager {
                             // All other chunks get "-1" (no ACK tracking)
                             let isFinalChunk = (index == chunks.count - 1)
                             let chunkTrackingId = (requireAck && isFinalChunk) ? trackingId : "-1"
-                            queueSend(packedData, id: chunkTrackingId)
+                            let trace = createBleWriteTrace(
+                                commandInfo: commandInfo,
+                                chunkId: chunk["id"] as? String,
+                                chunkIndex: index,
+                                totalChunks: chunks.count,
+                                payloadBytes: chunkStr.data(using: .utf8)?.count,
+                                packedBytes: packedData.count,
+                                wakeup: wakeUp && index == 0,
+                                chunked: true
+                            )
+                            logBleChunkTrace("created", trace, extra: [
+                                "chunkJsonBytes": chunkStr.data(using: .utf8)?.count,
+                                "messageBytes": jsonData.count,
+                            ])
+                            queueSend(packedData, id: chunkTrackingId, trace: trace)
 
                             // Add small delay between chunks to avoid overwhelming the connection
                             if index < chunks.count - 1 {
@@ -3724,7 +4001,20 @@ class MentraLive: NSObject, SGCManager {
                     }
                     Bridge.log("LIVE: Sending data to glasses: \(jsonString)")
                     let packedData = packJson(jsonString, wakeUp: wakeUp) ?? Data()
-                    queueSend(packedData, id: trackingId)
+                    let trace = createBleWriteTrace(
+                        commandInfo: commandInfo,
+                        chunkId: nil,
+                        chunkIndex: nil,
+                        totalChunks: nil,
+                        payloadBytes: jsonData.count,
+                        packedBytes: packedData.count,
+                        wakeup: wakeUp,
+                        chunked: false
+                    )
+                    logBleChunkTrace("created", trace, extra: [
+                        "messageBytes": jsonData.count,
+                    ])
+                    queueSend(packedData, id: trackingId, trace: trace)
                 }
             }
         } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",