@mentra/bluetooth-sdk 3.2.1 → 3.3.0-beta.954

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

@@ -0,0 +1,388 @@
+package com.mentra.bluetoothsdk
+
+/**
+ * Pure decision logic for the Mentra Live usage events: one event per photo,
+ * recording, stream, mic session, setup attempt, OTA attempt and timed-out
+ * glasses command. It owns no threads and no I/O; [BluetoothSdkAnalytics] feeds
+ * it facts and captures what it returns, and only when analytics is enabled.
+ *
+ * Durations are measured on the phone's clock between the start and end
+ * statuses it observes. A recording or stream whose end never reaches this
+ * process (the app was killed mid-stream) produces only its start.
+ */
+internal class BluetoothSdkUsageTracker(private val maxRequestTimeouts: Int = MAX_REQUEST_TIMEOUTS) {
+    private data class OpenRecording(
+        var startedAtMs: Long? = null,
+        val width: Int? = null,
+        val height: Int? = null,
+        val fps: Int? = null,
+        val save: Boolean? = null,
+        val maxDurationMinutes: Int? = null,
+        var stoppedByApp: Boolean = false,
+    )
+
+    private data class OpenStream(
+        val streamId: String,
+        val protocol: String,
+        /** Set by the first live status; null while the start is still pending. */
+        var startedAtMs: Long? = null,
+        var reconnectAttempts: Int = 0,
+        var stoppedByApp: Boolean = false,
+        var bitrate: Long? = null,
+        var fps: Double? = null,
+        var droppedFrames: Long? = null,
+        var temperatureC: Double? = null,
+    )
+
+    private data class OpenOta(
+        val startedAtMs: Long,
+        val fromBuildNumber: String,
+        val fromBesFirmwareVersion: String,
+        val fromMtkFirmwareVersion: String,
+    )
+
+    private val recordings = boundedMap<String, OpenRecording>(MAX_OPEN_RECORDINGS)
+    private var stream: OpenStream? = null
+    private var micSource: String? = null
+    private var micStartedAtMs = 0L
+    private var micTranscribed = false
+    private val otaSessions = boundedMap<String, OpenOta>(MAX_OTA_SESSIONS)
+    private val finishedOtaSessions = boundedMap<String, Boolean>(MAX_OTA_SESSIONS)
+    private var requestTimeouts = 0
+
+    fun photoSettled(
+        size: String,
+        mode: String,
+        compress: String,
+        save: Boolean,
+        transferMethod: String,
+        latencyMs: Long,
+        fileSizeBytes: Long?,
+        errorCode: String?,
+    ): AnalyticsEvent =
+        AnalyticsEvent(
+            EVENT_PHOTO_TAKEN,
+            buildMap {
+                put("trigger", TRIGGER_API)
+                putOutcome(errorCode)
+                put("latency_ms", latencyMs)
+                put("photo_size", size)
+                put("photo_mode", mode)
+                put("compress", compress)
+                put("save_to_gallery", save)
+                put("transfer_method", transferMethod)
+                fileSizeBytes?.takeIf { it > 0 }?.let { put("file_size_bytes", it) }
+            },
+        )
+
+    /** A button photo the glasses could not take; successful button photos never reach the phone. */
+    fun buttonPhotoFailed(errorCode: String?): AnalyticsEvent =
+        AnalyticsEvent(
+            EVENT_PHOTO_TAKEN,
+            buildMap {
+                put("trigger", TRIGGER_BUTTON)
+                putOutcome(errorCode ?: "photo_request_failed")
+            },
+        )
+
+    /** Records the API parameters of a recording so its end event can report them. */
+    fun videoRequested(requestId: String, width: Int, height: Int, fps: Int, save: Boolean, maxDurationMinutes: Int) {
+        recordings[requestId] =
+            OpenRecording(
+                width = width.takeIf { it > 0 },
+                height = height.takeIf { it > 0 },
+                fps = fps.takeIf { it > 0 },
+                save = save,
+                maxDurationMinutes = maxDurationMinutes.takeIf { it > 0 },
+            )
+    }
+
+    fun videoStopRequested(requestId: String) {
+        recordings[requestId]?.stoppedByApp = true
+    }
+
+    /**
+     * Glasses report every recording, button-started ones included, through
+     * `video_recording_status`. A recording is reported once: when it stops, or
+     * when a command for it fails. `not_recording` answers a stop for a recording
+     * that already ended and is not a recording of its own.
+     */
+    fun videoStatus(requestId: String, status: String, success: Boolean, nowMs: Long): AnalyticsEvent? {
+        if (requestId.isBlank()) return null
+        if (success) {
+            when (status) {
+                "recording_started" -> {
+                    val recording = recordings[requestId] ?: OpenRecording().also { recordings[requestId] = it }
+                    if (recording.startedAtMs == null) recording.startedAtMs = nowMs
+                    return null
+                }
+                "recording_stopped" -> {
+                    val recording = recordings.remove(requestId) ?: return null
+                    return videoEvent(requestId, recording, nowMs, errorCode = null)
+                }
+                else -> return null
+            }
+        }
+        if (status == "not_recording") {
+            recordings.remove(requestId)
+            return null
+        }
+        val recording = recordings.remove(requestId) ?: OpenRecording()
+        return videoEvent(requestId, recording, nowMs, errorCode = status.ifBlank { "video_recording_failed" })
+    }
+
+    private fun videoEvent(requestId: String, recording: OpenRecording, nowMs: Long, errorCode: String?) =
+        AnalyticsEvent(
+            EVENT_VIDEO_RECORDED,
+            buildMap {
+                put("trigger", if (requestId.startsWith(LOCAL_VIDEO_REQUEST_PREFIX)) TRIGGER_BUTTON else TRIGGER_API)
+                putOutcome(errorCode)
+                recording.startedAtMs?.let { put("duration_ms", (nowMs - it).coerceAtLeast(0)) }
+                recording.width?.let { put("width", it) }
+                recording.height?.let { put("height", it) }
+                recording.fps?.let { put("fps", it) }
+                recording.save?.let { put("save_to_gallery", it) }
+                recording.maxDurationMinutes?.let { put("max_duration_minutes", it) }
+                put("stopped_by_app", recording.stoppedByApp)
+            },
+        )
+
+    /**
+     * Opens the stream as its start command is sent, so a status that arrives
+     * before `startStream` returns is still attributed to it. A new start
+     * supersedes a stream that was live (the glasses stop it), so that stream is
+     * reported as `replaced`.
+     */
+    fun streamRequested(streamId: String, streamUrl: String, nowMs: Long): AnalyticsEvent? {
+        val replaced =
+            stream
+                ?.takeIf { it.startedAtMs != null && it.streamId != streamId }
+                ?.let { streamEndedEvent(it, "replaced", errorDetails = null, nowMs = nowMs) }
+        stream = OpenStream(streamId = streamId, protocol = streamProtocol(streamUrl))
+        return replaced
+    }
+
+    fun streamStartSettled(
+        streamUrl: String,
+        width: Int?,
+        height: Int?,
+        fps: Int?,
+        bitrate: Int?,
+        captureAudio: Boolean,
+        glassesNetwork: String,
+        latencyMs: Long,
+        errorCode: String?,
+    ): AnalyticsEvent =
+        AnalyticsEvent(
+            EVENT_STREAM_STARTED,
+            buildMap {
+                putOutcome(errorCode)
+                put("protocol", streamProtocol(streamUrl))
+                width?.let { put("width", it) }
+                height?.let { put("height", it) }
+                fps?.let { put("fps", it) }
+                bitrate?.let { put("bitrate", it) }
+                put("capture_audio", captureAudio)
+                put("glasses_network", glassesNetwork)
+                put("latency_ms", latencyMs)
+            },
+        )
+
+    fun streamStopRequested() {
+        stream?.stoppedByApp = true
+    }
+
+    /**
+     * Folds one accepted `stream_status` into the open stream and reports the
+     * stream once, on its terminal status. Glasses with stream revisions flag the
+     * terminal status; older glasses only send a final `stopped` or
+     * `reconnect_failed`. A stream that never went live ends silently: its
+     * `bluetooth_sdk_stream_started` already reported the failure.
+     */
+    fun streamStatus(
+        streamId: String?,
+        state: String,
+        terminal: Boolean?,
+        reconnectAttempt: Int?,
+        bitrate: Long?,
+        fps: Double?,
+        droppedFrames: Long?,
+        temperatureC: Double?,
+        errorDetails: String?,
+        nowMs: Long,
+    ): AnalyticsEvent? {
+        val open = stream ?: return null
+        if (!streamId.isNullOrBlank() && streamId != open.streamId) return null
+        if (state in LIVE_STREAM_STATES && open.startedAtMs == null) open.startedAtMs = nowMs
+        reconnectAttempt?.let { open.reconnectAttempts = maxOf(open.reconnectAttempts, it) }
+        bitrate?.let { open.bitrate = it }
+        fps?.let { open.fps = it }
+        droppedFrames?.let { open.droppedFrames = it }
+        temperatureC?.let { open.temperatureC = it }
+        val ended = terminal == true || (terminal == null && state in LEGACY_TERMINAL_STREAM_STATES)
+        if (!ended) return null
+        stream = null
+        if (open.startedAtMs == null) return null
+        return streamEndedEvent(open, state, errorDetails, nowMs)
+    }
+
+    private fun streamEndedEvent(open: OpenStream, endState: String, errorDetails: String?, nowMs: Long) =
+        AnalyticsEvent(
+            EVENT_STREAM_ENDED,
+            buildMap {
+                put("protocol", open.protocol)
+                open.startedAtMs?.let { put("duration_ms", (nowMs - it).coerceAtLeast(0)) }
+                put("end_state", endState)
+                put("stopped_by_app", open.stoppedByApp)
+                put("reconnect_attempts", open.reconnectAttempts)
+                sanitizedDetail(errorDetails)?.let { put("error_code", it) }
+                open.bitrate?.let { put("bitrate", it) }
+                open.fps?.let { put("fps", it) }
+                open.droppedFrames?.let { put("dropped_frames", it) }
+                open.temperatureC?.let { put("temperature_c", it) }
+            },
+        )
+
+    /**
+     * Follows the active mic source. A session ends when the source turns off or
+     * changes; `local_transcription` is true if on-device transcription ran at
+     * any point during it.
+     */
+    fun observeMic(currentMic: String, transcribing: Boolean, nowMs: Long): AnalyticsEvent? {
+        val next = currentMic.takeIf { it.isNotBlank() }
+        val previous = micSource
+        if (next == previous) {
+            if (next != null && transcribing) micTranscribed = true
+            return null
+        }
+        val ended =
+            previous?.let {
+                AnalyticsEvent(
+                    EVENT_MIC_SESSION,
+                    mapOf(
+                        "duration_ms" to (nowMs - micStartedAtMs).coerceAtLeast(0),
+                        "mic_source" to it,
+                        "local_transcription" to micTranscribed,
+                    ),
+                )
+            }
+        micSource = next
+        micStartedAtMs = nowMs
+        micTranscribed = next != null && transcribing
+        return ended
+    }
+
+    fun wifiSetupSettled(latencyMs: Long, errorCode: String?): AnalyticsEvent =
+        AnalyticsEvent(EVENT_WIFI_SETUP, buildMap { putOutcome(errorCode); put("latency_ms", latencyMs) })
+
+    fun hotspotStartSettled(latencyMs: Long, errorCode: String?): AnalyticsEvent =
+        AnalyticsEvent(EVENT_HOTSPOT_STARTED, buildMap { putOutcome(errorCode); put("latency_ms", latencyMs) })
+
+    /**
+     * One event per OTA session, on `complete` or `failed`. The "from" versions are
+     * the glasses versions when this process first saw the session in progress.
+     */
+    fun otaStatus(
+        sessionId: String,
+        status: String,
+        stepType: String,
+        totalSteps: Int,
+        errorMessage: String?,
+        fromBuildNumber: String,
+        fromBesFirmwareVersion: String,
+        fromMtkFirmwareVersion: String,
+        nowMs: Long,
+    ): AnalyticsEvent? {
+        if (finishedOtaSessions.containsKey(sessionId)) return null
+        if (status != OTA_COMPLETE && status != OTA_FAILED) {
+            if (status != OTA_IDLE && !otaSessions.containsKey(sessionId)) {
+                otaSessions[sessionId] =
+                    OpenOta(nowMs, fromBuildNumber, fromBesFirmwareVersion, fromMtkFirmwareVersion)
+            }
+            return null
+        }
+        finishedOtaSessions[sessionId] = true
+        val open = otaSessions.remove(sessionId)
+        val success = status == OTA_COMPLETE
+        return AnalyticsEvent(
+            EVENT_OTA_FINISHED,
+            buildMap {
+                put("success", success)
+                if (!success) {
+                    stepType.takeIf { it.isNotBlank() }?.let { put("failed_step_type", it) }
+                    sanitizedDetail(errorMessage)?.let { put("error_message", it) }
+                }
+                if (totalSteps > 0) put("total_steps", totalSteps)
+                open?.let { session ->
+                    put("duration_ms", (nowMs - session.startedAtMs).coerceAtLeast(0))
+                    session.fromBuildNumber.takeIf { it.isNotBlank() }?.let { put("from_build_number", it) }
+                    session.fromBesFirmwareVersion.takeIf { it.isNotBlank() }?.let { put("from_bes_firmware_version", it) }
+                    session.fromMtkFirmwareVersion.takeIf { it.isNotBlank() }?.let { put("from_mtk_firmware_version", it) }
+                }
+            },
+        )
+    }
+
+    /** At most [maxRequestTimeouts] per SDK instance, so a failure loop cannot run up event volume. */
+    fun requestTimedOut(operation: String): AnalyticsEvent? {
+        if (requestTimeouts >= maxRequestTimeouts) return null
+        requestTimeouts++
+        return AnalyticsEvent(EVENT_REQUEST_FAILED, mapOf("operation" to operation, "error_code" to "request_timeout"))
+    }
+
+    private fun MutableMap<String, Any>.putOutcome(errorCode: String?) {
+        put("success", errorCode == null)
+        sanitizedDetail(errorCode)?.let { put("error_code", it) }
+    }
+
+    companion object {
+        const val EVENT_PHOTO_TAKEN = "bluetooth_sdk_photo_taken"
+        const val EVENT_VIDEO_RECORDED = "bluetooth_sdk_video_recorded"
+        const val EVENT_STREAM_STARTED = "bluetooth_sdk_stream_started"
+        const val EVENT_STREAM_ENDED = "bluetooth_sdk_stream_ended"
+        const val EVENT_MIC_SESSION = "bluetooth_sdk_mic_session"
+        const val EVENT_WIFI_SETUP = "bluetooth_sdk_wifi_setup"
+        const val EVENT_HOTSPOT_STARTED = "bluetooth_sdk_hotspot_started"
+        const val EVENT_OTA_FINISHED = "bluetooth_sdk_ota_finished"
+        const val EVENT_REQUEST_FAILED = "bluetooth_sdk_request_failed"
+
+        const val MAX_REQUEST_TIMEOUTS = 100
+        private const val MAX_OPEN_RECORDINGS = 16
+        private const val MAX_OTA_SESSIONS = 16
+        private const val MAX_DETAIL_LENGTH = 200
+        private const val TRIGGER_API = "api"
+        private const val TRIGGER_BUTTON = "button"
+        /** Glasses report button-capture photo failures under this request id (ASG MediaCaptureService). */
+        const val LOCAL_PHOTO_REQUEST_ID = "local"
+        /** Button-started recordings use `local_video_<ts>_<rand>` request ids on the glasses. */
+        const val LOCAL_VIDEO_REQUEST_PREFIX = "local_video_"
+        private const val OTA_COMPLETE = "complete"
+        private const val OTA_FAILED = "failed"
+        private const val OTA_IDLE = "idle"
+        private val LEGACY_TERMINAL_STREAM_STATES = setOf("stopped", "reconnect_failed")
+        private val LIVE_STREAM_STATES = setOf("streaming", "reconnected")
+        private val URL_PATTERN = Regex("""[A-Za-z][A-Za-z0-9+.\-]*://\S+""")
+
+        /** Mirrors the glasses' scheme mapping in ASG StreamCommandHandler. */
+        fun streamProtocol(streamUrl: String): String =
+            when (streamUrl.trim().substringBefore("://", "").lowercase()) {
+                "srt" -> "srt"
+                "rtmp", "rtmps" -> "rtmp"
+                "http", "https" -> "whip"
+                else -> "unknown"
+            }
+
+        /** Free-text details may carry stream or upload URLs; those never leave the phone. */
+        fun sanitizedDetail(value: String?): String? =
+            value
+                ?.replace(URL_PATTERN, "<url>")
+                ?.trim()
+                ?.takeIf { it.isNotEmpty() }
+                ?.take(MAX_DETAIL_LENGTH)
+
+        private fun <K, V> boundedMap(capacity: Int): MutableMap<K, V> =
+            object : LinkedHashMap<K, V>() {
+                override fun removeEldestEntry(eldest: MutableMap.MutableEntry<K, V>?): Boolean = size > capacity
+            }
+    }
+}

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

@@ -1989,8 +1989,11 @@ class DeviceManager internal constructor(initializeHardware: Boolean) {
         sgc?.requestSavedWifiNetworks(requestId, sid) ?: false
 
     fun sendIncidentId(incidentId: String, apiBaseUrl: String? = null) {
+        val driver = sgc ?: throw BluetoothSdkException(
+            "glasses_not_connected", "Cannot request incident logs because glasses are not connected.",
+        )
         Bridge.log("MAN: Sending incidentId to glasses for log upload: $incidentId")
-        sgc?.sendIncidentId(incidentId, apiBaseUrl)
+        driver.sendIncidentId(incidentId, apiBaseUrl)
     }
 
     /** Push a notification into the glasses' own notification centre; rejects unsupported or disconnected devices. */

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

@@ -3,8 +3,9 @@ package com.mentra.bluetoothsdk
 /** Generated from /changelogs. Do not edit directly. */
 internal val GENERATED_RELEASE_CHANGELOGS: List<ReleaseChangelog> =
     listOf(
+        ReleaseChangelog(version = "3.3.0", markdown = "This release is under active development. User-facing changes will be documented as they land."),
         ReleaseChangelog(version = "3.2.1", markdown = "- **Livestreamer:** \"Stream Here\" now works without a Wi-Fi network. Improved stream startup and connection reliability.\n- **Photos and gallery:** More reliable photo capture and gallery syncing.\n- **Mentra AI:** Reliability improvements and bug fixes.\n- **Miniapps:** Smoother transitions, with back buttons and gestures that take you to the previous screen inside a miniapp.\n- **Pairing and connections:** Improved G1 pairing and G2 background reconnection.\n- **Glasses updates:** Fixed repeated update checks and improved recovery after interrupted updates.\n- **Mentra Maps:** Bug fixes.\n- **NIMO:** Improved text and map layouts.\n- **Self-hosting:** Connect the Mentra App to your own self-hosted Mentra backend."),
-        ReleaseChangelog(version = "3.2.0", markdown = "- Improved glasses connectivity and Wi-Fi setup."),
+        ReleaseChangelog(version = "3.2.0", markdown = "- Improved glasses connectivity and Wi-Fi setup.\n\n- Breaking Bluetooth SDK change: `forgetWifiNetwork(ssid)` now returns `WifiForgetResult` instead of `WifiStatusChangeEvent`. Migrate status-only consumers to the semantic `outcome`; the requested network remains `ssid`, while optional post-command connectivity is reported by `connected`, `currentSsid`, and `localIp`."),
         ReleaseChangelog(version = "3.1.1", markdown = "- Improved Google login on iOS.\n- Pairing no longer requires phone microphone access."),
         ReleaseChangelog(version = "3.1.0", markdown = "**Mentra App and glasses**\n\n- Improved glasses pairing and reconnection, including on iPad.\n- Improved Android background reliability for captions and miniapps.\n- Added Xingyi AR99 support.\n- More reliable photo and video capture, with improved shutter sounds and privacy-light timing. Taking photos no longer interrupts your running miniapp.\n- Added video thumbnails and smoother gallery browsing.\n- Easier Mentra Live updates through your phone, with clearer progress and better recovery from interruptions.\n\n**Miniapp updates**\n\n- **Mentra AI:** Control whether photos are included with questions. Improved visual answers and connected-app follow-ups.\n- **Captions:** Added offline transcription settings and top/bottom positioning on supported displays.\n- **Translation:** Restored all 60 languages.\n- **Mentra Maps:** Clearer directions on G1/G2, less display flickering, and improved Android offline routing.\n- **Livestreamer:** More video-quality controls and custom streaming options, plus improved startup and sharing.\n- **Merge:** Tap to expand an insight; swipe down or back to dismiss it.\n- **Mentra Notes:** Smoother back navigation.\n- **Recorder:** Fixed audio sharing."),
     )

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

@@ -2,10 +2,10 @@ package com.mentra.bluetoothsdk
 
 /** Generated by release CI. Do not edit in a release checkout. */
 internal object GeneratedReleaseMetadata {
-    const val FAMILY_BASE_VERSION: String = "3.2.1"
-    const val RELEASE_IDENTITY: String = "3.2.1"
-    const val RELEASE_SET_ID: String = "mentra-3.2.1"
-    const val SOURCE_COMMIT: String = "be56e1456c69f681985642f376ed3d397ec022cc"
-    const val OTA_MANIFEST_URL: String = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.2.1/mentra-live-ota-3.2.1-beta.578.json"
-    const val OTA_MANIFEST_SHA256: String = "21af62269e29fd2ee6b9737745a895694bc221672b191d80795057b5a832f400"
+    const val FAMILY_BASE_VERSION: String = "3.3.0"
+    const val RELEASE_IDENTITY: String = "3.3.0-beta.954"
+    const val RELEASE_SET_ID: String = "mentra-3.3.0-beta.954"
+    const val SOURCE_COMMIT: String = "25f6b1d70ce39dfe5d454021542f1627e256775a"
+    const val OTA_MANIFEST_URL: String = "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.3.0/mentra-live-ota-3.3.0-beta.954.json"
+    const val OTA_MANIFEST_SHA256: String = "03d976cb897215b97b5c40a53dabbc8356a045d1fbb57d5ad2c95bbc21203e21"
 }