@mentra/bluetooth-sdk 3.2.1-dev.314 → 3.3.0-beta.942

package/android/src/debug/java/com/mentra/bluetoothsdk/sgcs/NimoFramebufferProtocol.kt

@@ -0,0 +1,156 @@
+package com.mentra.bluetoothsdk.sgcs
+
+/** Private FBP1 protocol for one pinned diagnostic build, never a general memory reader. */
+internal object NimoFramebufferProtocol {
+  const val EXPECTED_VERSION = "FW-VERSION-v0.1.1.1-20260827164351-537cf1-dirty-Debug"
+  const val ARTIFACT_SHA256 = "4de441f887e85b1f8194881695b96c16e8018fbdc19d4edc9f5b5d4210e5aa83"
+  const val WIDTH = 540
+  const val HEIGHT = 280
+  const val PAGE_BYTES = 240
+  const val PAGE_COUNT = 315
+  const val BANK_BYTES = PAGE_BYTES * PAGE_COUNT
+  private val MAGIC = "FBP1".toByteArray(Charsets.US_ASCII)
+  private val BUILD_TAG = "537cf1p1".toByteArray(Charsets.US_ASCII)
+
+  data class Request(val nonce: Long, val op: Int, val bank: Int, val page: Int)
+  data class State(val draw: Int, val prepared: Int, val dirty: Int, val pending: Int)
+  data class Reply(val nonce: Long, val op: Int, val bank: Int, val page: Int,
+    val before: State, val after: State, val data: ByteArray)
+
+  fun hex(bytes: ByteArray): String {
+    val digits = "0123456789abcdef"
+    val chars = CharArray(bytes.size * 2)
+    bytes.forEachIndexed { index, byte ->
+      val value = byte.toInt() and 255
+      chars[index * 2] = digits[value ushr 4]
+      chars[index * 2 + 1] = digits[value and 15]
+    }
+    return chars.concatToString()
+  }
+
+  fun queryFrame(key: Int): ByteArray {
+    require(key == 0x0B || key == 0x19) { "Only version and readiness queries are permitted" }
+    return frame(key, byteArrayOf())
+  }
+
+  fun requestFrame(request: Request): ByteArray {
+    validate(request)
+    val nonce = ByteArray(4) { (request.nonce shr (8 * it)).toByte() }
+    return frame(0x15, MAGIC + nonce + byteArrayOf(request.op.toByte(), request.bank.toByte(),
+      request.page.toByte(), (request.page shr 8).toByte()))
+  }
+
+  fun version(packet: ByteArray): String {
+    val payload = basicPayload(packet, 0x0B)
+    require(payload.isNotEmpty() && payload[0] == 0.toByte()) { "Version query rejected" }
+    val expected = EXPECTED_VERSION.toByteArray(Charsets.US_ASCII)
+    require(payload.copyOfRange(1, payload.size).contentEquals(expected)) { "Unexpected firmware identity" }
+    return EXPECTED_VERSION
+  }
+
+  /** Preserve status and all three readiness fields, including a not-ready result. */
+  fun readiness(packet: ByteArray): List<Int> {
+    val payload = basicPayload(packet, 0x19)
+    require(payload.size == 4) { "Readiness response must contain status, ready, TWS, and peer GATT" }
+    return payload.map { it.toInt() and 255 }
+  }
+
+  fun basicPayload(packet: ByteArray, key: Int): ByteArray {
+    require(key == 0x0B || key == 0x19) { "Unexpected basic query" }
+    return payload(packet, key, 128)
+  }
+
+  fun reply(packet: ByteArray, expected: Request): Reply {
+    validate(expected)
+    val body = payload(packet, 0x15, 23 + PAGE_BYTES)
+    require(body.size >= 23) { "Short FBP1 response" }
+    require(body.copyOfRange(1, 5).contentEquals(MAGIC)) { "FBP1 response magic mismatch" }
+    require(word(body, 21) == body.size - 23) { "FBP1 data length mismatch" }
+    val status = unsigned(body, 0)
+    require(status in listOf(0, 6, 7)) { "Unknown FBP1 response status $status" }
+    if (status != 0) {
+      require(body.size == 23) { "Rejected FBP1 response contains data" }
+      throw IllegalArgumentException("FBP1 request rejected with status $status")
+    }
+    val nonce = (0..3).fold(0L) { value, i -> value or (unsigned(body, 5 + i).toLong() shl (8 * i)) }
+    val actual = Request(nonce, unsigned(body, 9), unsigned(body, 10), word(body, 11))
+    require(actual == expected) { "FBP1 response correlation mismatch" }
+    val before = state(body, 13)
+    val after = state(body, 17)
+    require(before == after) { "Framebuffer metadata changed during page copy" }
+    val data = body.copyOfRange(23, body.size)
+    if (actual.op == 0) require(data.contentEquals(BUILD_TAG)) { "Unexpected FBP1 build tag" }
+    else require(data.size == PAGE_BYTES) { "Framebuffer page must contain $PAGE_BYTES bytes" }
+    return Reply(nonce, actual.op, actual.bank, actual.page, before, after, data)
+  }
+
+  /** Sequential, single-pass assembler. Any rejected input permanently invalidates the read. */
+  class BankRead(val nonce: Long, val bank: Int) {
+    var pageCount = 0
+      private set
+    var metadata: State? = null
+      private set
+    private var failed = false
+    private val data = ByteArray(BANK_BYTES)
+
+    init { validate(Request(nonce, 1, bank, 0)) }
+
+    fun add(reply: Reply) {
+      require(!failed) { "Bank read was invalidated" }
+      try {
+        require(pageCount < PAGE_COUNT && reply.page == pageCount) { "Duplicate or out-of-order framebuffer page" }
+        require(reply.nonce == nonce && reply.bank == bank && reply.op == 1) { "Bank read correlation mismatch" }
+        require(reply.data.size == PAGE_BYTES) { "Invalid framebuffer page length" }
+        require(reply.before == reply.after) { "Metadata changed during page copy" }
+        require(metadata == null || metadata == reply.before) { "Metadata changed between pages" }
+        metadata = reply.before
+        reply.data.copyInto(data, pageCount * PAGE_BYTES)
+        pageCount += 1
+      } catch (error: IllegalArgumentException) {
+        failed = true
+        throw error
+      }
+    }
+
+    fun bytes(): ByteArray {
+      require(!failed && pageCount == PAGE_COUNT) { "Framebuffer bank is incomplete or invalidated" }
+      return data.copyOf()
+    }
+  }
+
+  fun verifyPair(first: BankRead, second: BankRead) {
+    require(first.nonce != second.nonce) { "Static verification requires independent nonces" }
+    require(first.bank == second.bank && first.metadata == second.metadata) { "Static pair metadata mismatch" }
+    require(first.bytes().contentEquals(second.bytes())) { "Framebuffer pixels changed between passes" }
+  }
+
+  private fun validate(request: Request) {
+    require(request.nonce in 0..0xFFFFFFFFL && request.op in 0..1 && request.bank in 0..1 &&
+      request.page in 0 until PAGE_COUNT && (request.op != 0 || request.page == 0)) { "Invalid FBP1 request" }
+  }
+
+  private fun state(body: ByteArray, offset: Int): State {
+    val state = State(unsigned(body, offset), unsigned(body, offset + 1), unsigned(body, offset + 2), unsigned(body, offset + 3))
+    require(state.draw in 0..1 && state.prepared in 0..1) { "Invalid framebuffer selectors" }
+    return state
+  }
+
+  private fun payload(packet: ByteArray, key: Int, maximum: Int): ByteArray {
+    require(packet.size in 12..(12 + maximum)) { "Invalid frame size" }
+    require(unsigned(packet, 0) == 0xBF && packet[1] == 0.toByte()) { "Expected BF00 frame" }
+    require(word(packet, 6) == 0) { "Fragmented framebuffer responses are not supported" }
+    require(word(packet, 2) == packet.size - 8 && word(packet, 10) == packet.size - 12) { "Frame length mismatch" }
+    require(unsigned(packet, 8) == 2 && unsigned(packet, 9) == key) { "Frame command mismatch" }
+    require(word(packet, 4) == NimoCanvasCodec.crc16(packet.copyOfRange(8, packet.size))) { "Frame CRC mismatch" }
+    return packet.copyOfRange(12, packet.size)
+  }
+
+  private fun frame(key: Int, payload: ByteArray): ByteArray {
+    val body = byteArrayOf(2, key.toByte(), payload.size.toByte(), (payload.size shr 8).toByte()) + payload
+    val crc = NimoCanvasCodec.crc16(body)
+    return byteArrayOf(0xBF.toByte(), 0, body.size.toByte(), (body.size shr 8).toByte(),
+      crc.toByte(), (crc shr 8).toByte(), 0, 0) + body
+  }
+  private fun unsigned(bytes: ByteArray, index: Int) = bytes[index].toInt() and 255
+  private fun word(bytes: ByteArray, index: Int) = unsigned(bytes, index) or (unsigned(bytes, index + 1) shl 8)
+}

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

@@ -46,7 +46,12 @@ internal class BluetoothSdkAnalytics(
     // The tracker is touched from store listeners and SDK entry points, hence
     // @Synchronized on the methods that read or write it.
     private val tracker = BluetoothSdkAnalyticsTracker(DeviceTypes.SIMULATED)
+    private val usage = BluetoothSdkUsageTracker()
     private var startedCaptured = false
+    private var lastGlasses: AnalyticsGlassesSnapshot? = null
+    // Set by an SDK disconnect/forget/cancel call and consumed by the next
+    // connected -> disconnected transition, so that transition can say why.
+    private var pendingDisconnectReason: String? = null
     // Resolved once, lazily, on the transport executor: PackageManager lookups
     // must not run on the caller (often main or the Bluetooth status) thread.
     private val hostProperties: Map<String, Any> by lazy { BluetoothSdkAnalyticsHost.resolve(appContext).toMap() }
@@ -56,9 +61,15 @@ internal class BluetoothSdkAnalytics(
         timeZone = TimeZone.getTimeZone("UTC")
     }
 
+    /** False when the host disabled analytics; callers skip building usage facts entirely. */
+    val isEnabled: Boolean
+        get() = config.isReady
+
     @Synchronized
     fun initializeGlassesStatus(status: GlassesStatus) {
-        tracker.initialize(status.toAnalyticsSnapshot(), BluetoothSdkAnalyticsTracker.reportingDay(System.currentTimeMillis()))
+        val snapshot = status.toAnalyticsSnapshot()
+        lastGlasses = snapshot
+        tracker.initialize(snapshot, BluetoothSdkAnalyticsTracker.reportingDay(System.currentTimeMillis()))
     }
 
     @Synchronized
@@ -71,12 +82,54 @@ internal class BluetoothSdkAnalytics(
     }
 
     @Synchronized
-    fun observeGlassesStatus(status: GlassesStatus) {
-        val events = tracker.observe(status.toAnalyticsSnapshot(), BluetoothSdkAnalyticsTracker.reportingDay(System.currentTimeMillis()))
+    fun observeGlassesStatus(status: GlassesStatus, phoneBluetoothOff: () -> Boolean) {
+        val snapshot = status.toAnalyticsSnapshot()
+        lastGlasses = snapshot
+        val now = System.currentTimeMillis()
+        val events =
+            tracker.observe(snapshot, BluetoothSdkAnalyticsTracker.reportingDay(now), now) {
+                pendingDisconnectReason
+                    ?: if (phoneBluetoothOff()) {
+                        BluetoothSdkAnalyticsTracker.DISCONNECT_BLUETOOTH_OFF
+                    } else {
+                        BluetoothSdkAnalyticsTracker.DISCONNECT_LINK_LOST
+                    }
+            }
+        if (!snapshot.connected || events.any { it.name == "bluetooth_sdk_glasses_connected" }) {
+            pendingDisconnectReason = null
+        }
         if (!config.isReady) return
         for (event in events) capture(event.name, event.properties)
     }
 
+    @Synchronized
+    fun noteDisconnectRequested(reason: String) {
+        if (lastGlasses?.connected == true) pendingDisconnectReason = reason
+    }
+
+    @Synchronized
+    fun recordUsage(build: BluetoothSdkUsageTracker.() -> AnalyticsEvent?) {
+        if (!config.isReady) return
+        val event = usage.build() ?: return
+        capture(event.name, glassesContext() + event.properties)
+    }
+
+    /** Usage-tracker state changes that emit nothing themselves (e.g. a stop request). */
+    @Synchronized
+    fun updateUsage(update: BluetoothSdkUsageTracker.() -> Unit) {
+        if (!config.isReady) return
+        usage.update()
+    }
+
+    private fun glassesContext(): Map<String, Any> {
+        val glasses = lastGlasses?.takeIf { it.connected } ?: return emptyMap()
+        return buildMap {
+            glasses.model.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
+            glasses.serialNumber.validManufacturingSerial()?.let { put("glasses_device_id", it) }
+            glasses.buildNumber.takeIf { it.isNotBlank() }?.let { put("glasses_build_number", it) }
+        }
+    }
+
     /**
      * Delivery is owned by the process-wide transport, so nothing is torn down
      * here: a retry in flight when this instance closes still completes, and a
@@ -101,7 +154,7 @@ internal class BluetoothSdkAnalytics(
                         "api_key" to DEFAULT_POSTHOG_API_KEY,
                         "uuid" to uuid,
                         "event" to eventName,
-                        "distinct_id" to distinctId(),
+                        "distinct_id" to BluetoothSdkInstallId.get(appContext),
                         "timestamp" to isoFormat.format(Date(capturedAt)),
                         "properties" to baseProperties(activeConfig) + hostProperties + eventProperties,
                     )
@@ -156,16 +209,12 @@ internal class BluetoothSdkAnalytics(
             put("app_package", appContext.packageName)
             put("os_platform", "android")
             put("os_version", Build.VERSION.SDK_INT)
+            Build.MANUFACTURER?.takeIf { it.isNotBlank() }?.let { put("phone_manufacturer", it) }
+            Build.MODEL?.takeIf { it.isNotBlank() }?.let { put("phone_model", it) }
+            put("locale", Locale.getDefault().toLanguageTag())
+            put("timezone", TimeZone.getDefault().id)
         }
 
-    private fun distinctId(): String {
-        val prefs = appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
-        prefs.getString(PREFS_DISTINCT_ID, null)?.let { return it }
-        val generated = "mentra-bt-sdk-${UUID.randomUUID()}"
-        prefs.edit().putString(PREFS_DISTINCT_ID, generated).apply()
-        return generated
-    }
-
     private fun captureUrl(): String {
         val normalized = DEFAULT_POSTHOG_HOST.trim().trimEnd('/')
         return "$normalized/i/v0/e/"
@@ -173,8 +222,6 @@ internal class BluetoothSdkAnalytics(
 
     companion object {
         internal const val META_ANALYTICS_DISABLED = "com.mentra.bluetoothsdk.analytics.disabled"
-        private const val PREFS_NAME = "mentra_bluetooth_sdk_analytics"
-        private const val PREFS_DISTINCT_ID = "distinct_id"
         private const val DEFAULT_POSTHOG_API_KEY = "phc_FCweXVAxVgU7wZK4Fk3okOx4RmyNqVHJf62YpZSfJt5"
         private const val DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com"
     }
@@ -212,4 +259,6 @@ private fun GlassesStatus.toAnalyticsSnapshot(): AnalyticsGlassesSnapshot =
         androidVersion = androidVersion,
         appVersion = appVersion,
         buildNumber = buildNumber,
+        batteryLevel = batteryLevel,
+        charging = charging,
     )

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

@@ -14,6 +14,9 @@ internal data class AnalyticsGlassesSnapshot(
     val androidVersion: String = "",
     val appVersion: String = "",
     val buildNumber: String = "",
+    /** -1 while the glasses have not reported a level. */
+    val batteryLevel: Int = -1,
+    val charging: Boolean = false,
 )
 
 internal data class AnalyticsEvent(
@@ -36,12 +39,21 @@ internal data class AnalyticsEvent(
  *   is visible in both weeks. Reporting days follow `America/Los_Angeles`, the
  *   calendar the WAU weeks are cut on; a UTC day would miss the Sunday-evening to
  *   Monday-morning Pacific boundary, which is one UTC day.
+ * - `bluetooth_sdk_glasses_disconnected` when a counted connection ends, with its
+ *   length, why it ended, and the battery levels seen during it. The reason is
+ *   supplied by the caller: an SDK disconnect/forget/cancel call, the phone's
+ *   Bluetooth turning off, or otherwise a lost link.
  */
 internal class BluetoothSdkAnalyticsTracker(private val simulatedModel: String) {
     private var lastConnected = false
     private var connectedPendingModel = false
     private var identifiedSerial: String? = null
     private var identifiedReportingDay: Long? = null
+    private var connectedAtMs: Long? = null
+    private var batteryAtConnect = -1
+    private var lastBattery = -1
+    private var lastCharging: Boolean? = null
+    private var lastModel = ""
 
     fun initialize(snapshot: AnalyticsGlassesSnapshot, reportingDay: Long) {
         lastConnected = snapshot.connected
@@ -54,7 +66,12 @@ internal class BluetoothSdkAnalyticsTracker(private val simulatedModel: String)
         identifiedReportingDay = identifiedSerial?.let { reportingDay }
     }
 
-    fun observe(snapshot: AnalyticsGlassesSnapshot, reportingDay: Long): List<AnalyticsEvent> {
+    fun observe(
+        snapshot: AnalyticsGlassesSnapshot,
+        reportingDay: Long,
+        nowMs: Long = 0L,
+        disconnectReason: () -> String = { DISCONNECT_UNKNOWN },
+    ): List<AnalyticsEvent> {
         val events = mutableListOf<AnalyticsEvent>()
         val wasConnected = lastConnected
         lastConnected = snapshot.connected
@@ -64,14 +81,30 @@ internal class BluetoothSdkAnalyticsTracker(private val simulatedModel: String)
                 connectedPendingModel = false
                 events += connectedEvent(snapshot, modelUnresolved = true)
             }
+            connectedAtMs?.let { startedAt ->
+                events += disconnectedEvent(nowMs - startedAt, disconnectReason())
+            }
+            connectedAtMs = null
             identifiedSerial = null
             identifiedReportingDay = null
             return events
         }
 
+        if (snapshot.model.isNotBlank()) lastModel = snapshot.model
+        if (snapshot.batteryLevel >= 0) {
+            if (batteryAtConnect < 0) batteryAtConnect = snapshot.batteryLevel
+            lastBattery = snapshot.batteryLevel
+            lastCharging = snapshot.charging
+        }
+
         if (!wasConnected) {
             identifiedSerial = null
             identifiedReportingDay = null
+            connectedAtMs = nowMs
+            lastModel = snapshot.model
+            batteryAtConnect = snapshot.batteryLevel
+            lastBattery = snapshot.batteryLevel
+            lastCharging = snapshot.charging.takeIf { snapshot.batteryLevel >= 0 }
             if (snapshot.model.isBlank()) {
                 connectedPendingModel = true
             } else {
@@ -106,6 +139,21 @@ internal class BluetoothSdkAnalyticsTracker(private val simulatedModel: String)
             },
         )
 
+    private fun disconnectedEvent(durationMs: Long, reason: String) =
+        AnalyticsEvent(
+            "bluetooth_sdk_glasses_disconnected",
+            buildMap {
+                put("event_kind", "glasses_disconnected")
+                put("session_duration_ms", durationMs.coerceAtLeast(0))
+                put("disconnect_reason", reason)
+                lastModel.takeIf { it.isNotBlank() }?.let { put("glasses_model", it) }
+                put("glasses_is_simulated", lastModel == simulatedModel)
+                batteryAtConnect.takeIf { it >= 0 }?.let { put("battery_level_at_connect", it) }
+                lastBattery.takeIf { it >= 0 }?.let { put("battery_level_at_disconnect", it) }
+                lastCharging?.let { put("charging", it) }
+            },
+        )
+
     private fun identifiedEvent(snapshot: AnalyticsGlassesSnapshot, serial: String, kind: String) =
         AnalyticsEvent(
             "bluetooth_sdk_glasses_identified",
@@ -126,6 +174,12 @@ internal class BluetoothSdkAnalyticsTracker(private val simulatedModel: String)
         )
 
     companion object {
+        const val DISCONNECT_USER = "user_disconnect"
+        const val DISCONNECT_FORGET = "forget"
+        const val DISCONNECT_CANCEL = "cancel"
+        const val DISCONNECT_BLUETOOTH_OFF = "bluetooth_off"
+        const val DISCONNECT_LINK_LOST = "link_lost"
+        const val DISCONNECT_UNKNOWN = "unknown"
         const val MILLIS_PER_DAY = 86_400_000L
         val REPORTING_ZONE: TimeZone = TimeZone.getTimeZone("America/Los_Angeles")
 

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

@@ -3,5 +3,8 @@ package com.mentra.bluetoothsdk
 /** Defaults for the public Bluetooth SDK surface. */
 object BluetoothSdkDefaults {
     const val VOICE_ACTIVITY_DETECTION_ENABLED = false
-    const val LOUDNESS_GATE_ENABLED = false
+    const val LOUDNESS_GATE_ENABLED = true
+
+    /** Off until someone turns it on in Super Mode. Re-pushed on connect. */
+    const val AUTO_POWER_OFF_ENABLED = false
 }

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

@@ -0,0 +1,23 @@
+package com.mentra.bluetoothsdk
+
+import android.content.Context
+import java.util.UUID
+
+/**
+ * One random id per app install, shared by usage analytics (as the PostHog
+ * `distinct_id`) and the startup update check, so both describe the same install.
+ * It is created on first use whether or not analytics is enabled.
+ */
+internal object BluetoothSdkInstallId {
+    private const val PREFS_NAME = "mentra_bluetooth_sdk_analytics"
+    private const val PREFS_DISTINCT_ID = "distinct_id"
+
+    @Synchronized
+    fun get(context: Context): String {
+        val prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        prefs.getString(PREFS_DISTINCT_ID, null)?.let { return it }
+        val generated = "mentra-bt-sdk-${UUID.randomUUID()}"
+        prefs.edit().putString(PREFS_DISTINCT_ID, generated).apply()
+        return generated
+    }
+}

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

@@ -334,6 +334,7 @@ class BluetoothSdkModule : Module() {
             "glasses_status",
             "bluetooth_status",
             "log",
+            "sdk_update_notice",
             "device_discovered",
             "default_device_changed",
             // Individual event handlers
@@ -404,7 +405,6 @@ class BluetoothSdkModule : Module() {
             "send_command_to_ble",
             "receive_command_from_ble",
             "miniapp_selected",
-            "captions_tester_incident",
             "extraction_progress",
         )
 
@@ -550,6 +550,8 @@ class BluetoothSdkModule : Module() {
 
         SdkAsyncFunction("forget") { -> sdk?.forget() }
 
+        SdkCoroutineFunction("unpair") { -> deviceManager?.unpair() }
+
         AsyncFunction("connectDefaultController") { deviceManager?.connectDefaultController() }
 
         AsyncFunction("disconnectController") { deviceManager?.disconnectController() }
@@ -616,7 +618,7 @@ class BluetoothSdkModule : Module() {
         // MARK: - Incident Reporting
 
         SdkAsyncFunction("sendIncidentId") { incidentId: String, apiBaseUrl: String? ->
-            sdk?.sendIncidentId(incidentId, apiBaseUrl)
+            requireSdk().sendIncidentId(incidentId, apiBaseUrl)
         }
 
         // MARK: - Native Notification Centre
@@ -676,6 +678,10 @@ class BluetoothSdkModule : Module() {
             sdk?.setLoudnessGateEnabled(enabled)
         }
 
+        SdkAsyncFunction("setAutoPowerOffEnabled") { enabled: Boolean ->
+            sdk?.setAutoPowerOffEnabled(enabled)
+        }
+
         @Suppress("DEPRECATION")
         SdkCoroutineFunction("setPhotoCaptureDefaults") { params: Map<String, Any?> ->
             requireSdk().setPhotoCaptureDefaults(PhotoCaptureDefaults.fromMap(params)).values

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

@@ -0,0 +1,184 @@
+package com.mentra.bluetoothsdk
+
+import android.content.Context
+import android.os.Build
+import org.json.JSONObject
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.concurrent.Executors
+import java.util.concurrent.RejectedExecutionException
+import java.util.concurrent.ScheduledExecutorService
+import java.util.concurrent.ScheduledFuture
+import java.util.concurrent.TimeUnit
+
+internal data class BluetoothSdkUpdateCheckResult(
+    val status: String,
+    val channel: String,
+    val latestVersion: String?,
+    val minimumSupportedVersion: String?,
+) {
+    companion object {
+        fun parse(body: String): BluetoothSdkUpdateCheckResult? =
+            try {
+                val json = JSONObject(body)
+                BluetoothSdkUpdateCheckResult(
+                    status = json.optString("status"),
+                    channel = json.optString("channel"),
+                    latestVersion = json.optNonBlankString("latestVersion"),
+                    minimumSupportedVersion = json.optNonBlankString("minimumSupportedVersion"),
+                )
+            } catch (_: Exception) {
+                null
+            }
+
+        private fun JSONObject.optNonBlankString(key: String): String? =
+            if (isNull(key)) null else optString(key).trim().takeIf { it.isNotEmpty() }
+    }
+}
+
+/** The developer-facing console banner for an out-of-date SDK. Never shown in app UI. */
+internal object BluetoothSdkUpdateNotice {
+    const val STATUS_UPDATE_AVAILABLE = "update_available"
+    const val STATUS_UNSUPPORTED = "unsupported"
+    private const val RULE = "=================================================================="
+
+    /** Null when the installed SDK is current or the server could not tell. */
+    fun banner(installedVersion: String, result: BluetoothSdkUpdateCheckResult, surface: String): String? {
+        val latest = result.latestVersion
+        val heading =
+            when (result.status) {
+                STATUS_UNSUPPORTED -> "MENTRA BLUETOOTH SDK $installedVersion IS NO LONGER SUPPORTED"
+                STATUS_UPDATE_AVAILABLE -> if (latest != null) "MENTRA BLUETOOTH SDK UPDATE AVAILABLE" else return null
+                else -> return null
+            }
+        return buildString {
+            appendLine(RULE)
+            appendLine("  $heading")
+            appendLine("  Installed: $installedVersion    Latest: ${latest ?: "unknown"}")
+            appendLine("  Update:    ${updateLine(surface, latest)}")
+            if (result.status == STATUS_UNSUPPORTED) {
+                appendLine("  This version has known issues that are fixed in newer releases.")
+            }
+            appendLine("  Running an old SDK is the most common cause of glasses issues.")
+            append(RULE)
+        }
+    }
+
+    private fun updateLine(surface: String, version: String?): String =
+        when (surface) {
+            "react_native" -> "bun add @mentra/bluetooth-sdk@${version ?: "latest"}"
+            "ios" -> "the MentraBluetoothSDK Swift package at ${version ?: "its latest release"}"
+            else -> "com.mentraglass:bluetooth-sdk:${version ?: "<latest release>"}"
+        }
+}
+
+/**
+ * Checks Mentra Core for a newer SDK on every SDK start and, when this SDK is
+ * behind, prints a console banner now and every [REPRINT_INTERVAL_MINUTES] while
+ * the SDK instance lives. The check is one request with a short timeout and no
+ * retry; any failure is silent and changes no SDK behavior. It runs regardless
+ * of the analytics setting.
+ */
+internal class BluetoothSdkUpdateCheck(
+    context: Context,
+    private val surface: String,
+    private val sdkVersion: String = BuildConfig.SDK_VERSION,
+    private val transport: (String) -> String? = ::post,
+    private val onNotice: (banner: String, result: BluetoothSdkUpdateCheckResult) -> Unit,
+) {
+    private val appContext = context.applicationContext
+    private val lock = Any()
+    private var stopped = false
+    private var reprint: ScheduledFuture<*>? = null
+
+    fun start() {
+        if (!isCheckable(sdkVersion)) return
+        try {
+            executor.execute { runCatching { check() } }
+        } catch (_: RejectedExecutionException) {
+        }
+    }
+
+    fun stop() {
+        synchronized(lock) {
+            stopped = true
+            reprint?.cancel(false)
+            reprint = null
+        }
+    }
+
+    private fun check() {
+        val response = transport(requestBody().toString()) ?: return
+        val result = BluetoothSdkUpdateCheckResult.parse(response) ?: return
+        val banner = BluetoothSdkUpdateNotice.banner(sdkVersion, result, surface) ?: return
+        synchronized(lock) {
+            if (stopped) return
+            onNotice(banner, result)
+            reprint =
+                executor.scheduleAtFixedRate(
+                    { synchronized(lock) { if (!stopped) onNotice(banner, result) } },
+                    REPRINT_INTERVAL_MINUTES,
+                    REPRINT_INTERVAL_MINUTES,
+                    TimeUnit.MINUTES,
+                )
+        }
+    }
+
+    internal fun requestBody(): JSONObject {
+        val host = BluetoothSdkAnalyticsHost.resolve(appContext)
+        return JSONObject().apply {
+            put("install_id", BluetoothSdkInstallId.get(appContext))
+            put("app_identifier", appContext.packageName)
+            host.appVersion?.let { put("app_version", it) }
+            host.appBuild?.let { put("app_build", it) }
+            put("app_build_type", host.buildType)
+            put("app_install_source", host.installSource)
+            host.environment?.let { put("app_environment", it) }
+            put("sdk_version", sdkVersion)
+            put("sdk_platform", "android")
+            put("sdk_surface", surface)
+            put("os_platform", "android")
+            put("os_version", Build.VERSION.SDK_INT.toString())
+        }
+    }
+
+    companion object {
+        const val UPDATE_CHECK_URL = "https://core.mentraglass.com/api/client/bluetooth-sdk/update-check"
+        const val REPRINT_INTERVAL_MINUTES = 15L
+        private const val TIMEOUT_MS = 4_000
+
+        private val executor: ScheduledExecutorService =
+            Executors.newSingleThreadScheduledExecutor { runnable ->
+                Thread(runnable, "MentraBluetoothSdkUpdateCheck").apply { isDaemon = true }
+            }
+
+        fun isCheckable(version: String): Boolean = version.isNotBlank() && version != "unknown"
+
+        private fun post(body: String): String? {
+            val connection = URL(UPDATE_CHECK_URL).openConnection() as HttpURLConnection
+            return try {
+                connection.requestMethod = "POST"
+                connection.connectTimeout = TIMEOUT_MS
+                connection.readTimeout = TIMEOUT_MS
+                connection.doOutput = true
+                connection.setRequestProperty("Content-Type", "application/json")
+                connection.outputStream.use { it.write(body.toByteArray(Charsets.UTF_8)) }
+                if (connection.responseCode != 200) {
+                    connection.errorStream?.close()
+                    null
+                } else {
+                    connection.inputStream.bufferedReader(Charsets.UTF_8).use { it.readText() }
+                }
+            } catch (_: Exception) {
+                null
+            } finally {
+                connection.disconnect()
+            }
+        }
+
+        /** Test hook: waits until every task submitted so far has run. */
+        internal fun awaitIdle() {
+            executor.submit {}.get()
+        }
+    }
+}