@mentra/bluetooth-sdk 3.2.0-dev.181 → 3.2.0-dev.187

package/README.md

@@ -295,6 +295,28 @@ await BluetoothSdk.clearDefaultDevice()
 await saveDeviceToYourAppStorage(null)
 ```
 
+## Native notification controls
+
+G2 exposes firmware-owned notification history and popups. `getNativeNotificationStatus()` reports support, source (`phone` on Android or `ancs` on iOS), authorization, the desired controls, and submission/failure state. `submitted` means the controls were queued for the glasses, not that firmware acknowledged them. Unsupported drivers reject configuration instead of silently succeeding.
+
+```ts
+await BluetoothSdk.configureNativeNotifications({
+  enabled: true,
+  autoDisplay: true,       // false keeps history without automatic popups
+  durationSeconds: 5,     // 1–30
+  doNotDisturb: false,
+  blockedApps: [],        // Android package names; iOS requires an empty list
+})
+const status = await BluetoothSdk.getNativeNotificationStatus()
+const subscription = BluetoothSdk.addListener('native_notification_status', handleStatus)
+```
+
+The native SDKs expose the same configuration/status methods and `NativeNotificationConfig` type. Engine hosts should use the shared `engine.phoneNotifications` presentation policy and settings rather than competing with it through direct SDK configuration.
+
+Android content uploads use the existing phone listener and a bounded G2 file-transfer queue. `native_notification_delivery` reports delivered, failed, cancelled, or dropped notifications by id without their content. Delivered means all three file phases acknowledged success. Disable, settings changes, and disconnect invalidate pending work. An interrupted or timed-out upload requires reconnect before another upload because the verified ACK format has no transaction id.
+
+iOS G2 receives notifications directly through ANCS. Authorization is reported from the connected accessory and controls are reapplied after reconnect or authorization changes. No iOS content upload or full title/body relay is exposed. iOS keeps the firmware's existing app filter and rejects a nonempty `blockedApps` list. Phone dismissals are not yet synchronized to G2 history; the verified protocol does not establish a removal command.
+
 ## Common Commands
 
 ```ts

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

@@ -367,6 +367,8 @@ class BluetoothSdkModule : Module() {
             "audio_disconnected",
             "save_setting",
             "phone_notification",
+            "native_notification_status",
+            "native_notification_delivery",
             "phone_notification_dismissed",
             "ws_text",
             "ws_bin",
@@ -573,6 +575,19 @@ class BluetoothSdkModule : Module() {
             sdk?.sendIncidentId(incidentId, apiBaseUrl)
         }
 
+        // MARK: - Native Notification Centre
+
+        // Public controls use the SDK facade; phone payload delivery uses DeviceManager.
+        SdkAsyncFunction("configureNativeNotifications") { config: Map<String, Any> ->
+            requireSdk().configureNativeNotifications(NativeNotificationConfig.fromMap(config))
+        }
+        SdkAsyncFunction("getNativeNotificationStatus") { ->
+            requireSdk().getNativeNotificationStatus().toMap()
+        }
+        AsyncFunction("sendPhoneNotification") { notification: Map<String, Any> ->
+            deviceManager?.sendPhoneNotification(notification)
+        }
+
         // MARK: - WiFi Commands
 
         SdkCoroutineFunction("requestWifiScan") { -> requireSdk().requestWifiScan().map { it.toMap() } }

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

@@ -1789,6 +1789,14 @@ class DeviceManager {
         sgc?.sendIncidentId(incidentId, apiBaseUrl)
     }
 
+    /** Push a notification into the glasses' own notification centre; rejects unsupported or disconnected devices. */
+    fun sendPhoneNotification(notification: Map<String, Any>) {
+        // Package only - never the notification text.
+        Bridge.log("MAN: sendPhoneNotification from ${notification["packageName"]}")
+        val driver = sgc ?: throw IllegalStateException("Glasses are not connected")
+        driver.sendPhoneNotification(notification)
+    }
+
     fun sendWifiCredentials(ssid: String, password: String) {
         Bridge.log("MAN: Sending wifi credentials: $ssid")
         sgc?.sendWifiCredentials(ssid, password)

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

@@ -3,9 +3,9 @@ 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.0"
-    const val RELEASE_IDENTITY: String = "3.2.0-dev.181"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.181"
-    const val SOURCE_COMMIT: String = "89a4792321ce95bd16aadd721bc3dbc20e338861"
-    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.181.json"
-    const val OTA_MANIFEST_SHA256: String = "d9a100cc81733d02848a86c7617eff154f4cd9d714d1d36407789aeebbf71251"
+    const val RELEASE_IDENTITY: String = "3.2.0-dev.187"
+    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.187"
+    const val SOURCE_COMMIT: String = "d8b34892f11593baa3c075b94380253b06eb874d"
+    const val OTA_MANIFEST_URL: String = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.187.json"
+    const val OTA_MANIFEST_SHA256: String = "cf21f4ab6347acb12eefa38d2f0a3b433bc0e05428c527bcda57a8693d7a72f9"
 }

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

@@ -506,6 +506,15 @@ class MentraBluetoothSdk private constructor(
         deviceManager.displayEvent(request.toMap())
     }
 
+    /** Configure native notification presentation on a supported connected driver. */
+    fun configureNativeNotifications(config: NativeNotificationConfig) {
+        val driver = deviceManager.sgc ?: throw IllegalStateException("Glasses are not connected")
+        driver.configureNativeNotifications(config)
+    }
+
+    fun getNativeNotificationStatus(): NativeNotificationStatus =
+        deviceManager.sgc?.getNativeNotificationStatus() ?: NativeNotificationStatus()
+
     fun clearDisplay() {
         deviceManager.clearDisplay()
     }

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

@@ -0,0 +1,42 @@
+package com.mentra.bluetoothsdk
+
+/** Desired notification-centre controls. Completion means submitted, not firmware-confirmed. */
+data class NativeNotificationConfig(
+    val enabled: Boolean = false,
+    val autoDisplay: Boolean = true,
+    val durationSeconds: Int = 5,
+    val doNotDisturb: Boolean = false,
+    val blockedApps: List<String> = emptyList(),
+) {
+    init { require(durationSeconds in 1..30) { "durationSeconds must be between 1 and 30" } }
+
+    fun toMap(): Map<String, Any> = mapOf(
+        "enabled" to enabled, "autoDisplay" to autoDisplay,
+        "durationSeconds" to durationSeconds, "doNotDisturb" to doNotDisturb, "blockedApps" to blockedApps,
+    )
+
+    companion object {
+        fun fromMap(value: Map<String, Any>) = NativeNotificationConfig(
+            enabled = value["enabled"] as? Boolean ?: false,
+            autoDisplay = value["autoDisplay"] as? Boolean ?: true,
+            durationSeconds = (value["durationSeconds"] as? Number)?.toInt() ?: 5,
+            doNotDisturb = value["doNotDisturb"] as? Boolean ?: false,
+            blockedApps = (value["blockedApps"] as? List<*>)?.filterIsInstance<String>() ?: emptyList(),
+        )
+    }
+}
+
+/** Availability is independent from notification content access and firmware acknowledgement. */
+data class NativeNotificationStatus(
+    val supported: Boolean = false,
+    val source: String = "unsupported",
+    val authorization: String = "unknown",
+    val state: String = "unavailable",
+    val config: NativeNotificationConfig = NativeNotificationConfig(),
+    val error: String = "",
+) {
+    fun toMap(): Map<String, Any> = mapOf(
+        "supported" to supported, "source" to source, "authorization" to authorization,
+        "state" to state, "config" to config.toMap(), "error" to error,
+    )
+}

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/EvenFileService.kt

@@ -0,0 +1,101 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import java.io.IOException
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withTimeoutOrNull
+
+/** A single in-flight Even file upload. The wire ACK has no transaction id. */
+internal class EvenFileService(
+    private val timeoutMs: Long = 15_000,
+    private val send: suspend (Byte, ByteArray) -> Unit,
+) {
+    private val mutex = Mutex()
+    private data class Pending(val generation: Long, val cid: Int, val result: CompletableDeferred<Int>)
+    @Volatile private var generation = 0L
+    @Volatile private var pending: Pending? = null
+    @Volatile var needsReconnect = false
+        private set
+
+    /** Only a new physical connection can clear an ambiguous in-flight transfer. */
+    @Synchronized fun resetConnection() {
+        generation++
+        pending?.result?.cancel()
+        pending = null
+        needsReconnect = false
+    }
+
+    fun acceptFrame(frame: ByteArray) {
+        decodeAckFrame(frame)?.let(::acceptAck)
+    }
+
+    /** Reject old-connection callbacks before calling this method. */
+    @Synchronized fun acceptAck(payload: ByteArray) {
+        if (payload.size != 2) return
+        val current = pending ?: return
+        if (current.generation == generation && current.cid == (payload[0].toInt() and 0xff)) {
+            current.result.complete(payload[1].toInt() and 0xff)
+        }
+    }
+
+    private suspend fun phase(epoch: Long, cid: Int, write: suspend () -> Unit): Int {
+        val ack = synchronized(this) {
+            check(epoch == generation) { "connection_changed" }
+            CompletableDeferred<Int>().also { pending = Pending(epoch, cid, it) }
+        }
+        try {
+            write()
+            return withTimeoutOrNull(timeoutMs) { ack.await() } ?: throw IOException("ack_timeout")
+        } finally {
+            synchronized(this) { if (pending?.result === ack) pending = null }
+        }
+    }
+
+    suspend fun transfer(fileType: Int, filename: String, bytes: ByteArray): Int = mutex.withLock {
+        check(!needsReconnect) { "needs_reconnect" }
+        val epoch = generation
+        try {
+            val start = phase(epoch, FileService.CID_SEND_START) {
+                send(0xC4.toByte(), FileService.sendStart(fileType, bytes.size, crc32(bytes), filename))
+            }
+            if (start != 0) return@withLock start
+            val data = phase(epoch, FileService.CID_SEND_DATA) {
+                send(0xC4.toByte(), FileService.sendData())
+                send(0xC5.toByte(), bytes)
+            }
+            if (data != 0) return@withLock data
+            phase(epoch, FileService.CID_SEND_RESULT_CHECK) {
+                send(0xC4.toByte(), FileService.resultCheck())
+            }
+        } catch (error: Exception) {
+            // No abort ACK or transaction id exists in the verified protocol. Reusing
+            // this channel after a timeout/cancel could accept the old transfer's ACK.
+            synchronized(this) { if (epoch == generation) needsReconnect = true }
+            throw error
+        }
+    }
+
+    companion object {
+        /** Verified ACK shape: one frame carrying cid/status plus payload CRC16. */
+        fun decodeAckFrame(frame: ByteArray): ByteArray? {
+            if (frame.size != 12 || frame[0] != 0xAA.toByte() || frame[3] != 4.toByte() ||
+                frame[4] != 1.toByte() || frame[5] != 1.toByte() ||
+                (frame[6] != 0xC4.toByte() && frame[6] != 0xC5.toByte()) ||
+                ((frame[7].toInt() shr 1) and 0x0F) != 0) return null
+            val payload = frame.copyOfRange(8, 10)
+            val crc = (frame[10].toInt() and 0xff) or ((frame[11].toInt() and 0xff) shl 8)
+            return payload.takeIf { g2Crc16(it) == crc }
+        }
+
+        /** CRC-32/Castagnoli, MSB-first, zero seed and no final xor (Even wire format). */
+        fun crc32(bytes: ByteArray): Int {
+            var crc = 0
+            for (byte in bytes) {
+                crc = crc xor ((byte.toInt() and 0xff) shl 24)
+                repeat(8) { crc = if (crc < 0) (crc shl 1) xor 0x1EDC6F41 else crc shl 1 }
+            }
+            return crc
+        }
+    }
+}

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/EvenNotificationProtocol.kt

@@ -0,0 +1,113 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import java.io.ByteArrayOutputStream
+
+// ---------- Even File Service (service 0xC4 cmd / 0xC5 data) ----------
+
+/**
+ * The glasses' generic file-push channel, and how notification content gets across: the body is a
+ * JSON document pushed as a file. Unlike every other G2 service this is **not** protobuf —
+ * SEND_START is a fixed 93-byte struct and the data phase writes raw bytes.
+ *
+ * Each phase is acked with a 2-byte `[cid][status]`:
+ *   START(fileType, length, crc32, filename) → ack → DATA → raw bytes on 0xC5 → ack
+ *     → RESULT_CHECK → ack
+ */
+internal object FileService {
+    // eEvenFileSendServiceCID — first byte of every 0xC4 payload
+    const val CID_SEND_START = 0
+    const val CID_SEND_DATA = 1
+    const val CID_SEND_RESULT_CHECK = 2
+
+    const val TYPE_ANDROID_MSG_JSON_NOTIFICATION = 1
+
+    // Notification bodies and the whitelist share this path: the firmware has one filename
+    // constant (`BleG2GlassesFilePath.notifyWhitelist`) and discriminates on `fileType`.
+    const val PATH_NOTIFY = "user/notify_whitelist.json"
+
+    const val FILENAME_FIELD_LEN = 80
+    const val SEND_START_LEN = 93 // 1 + 4 + 4 + 4 + 80
+
+    // eEvenFileServiceRsp
+    fun statusName(status: Int): String =
+        when (status) {
+            0 -> "SUCCESS"
+            1 -> "START_ERR"
+            2 -> "DATA_CRC_ERR"
+            3 -> "FLASH_WRITE_ERR"
+            4 -> "TIMEOUT"
+            5 -> "NO_RESOURCES"
+            6 -> "RESULT_CHECK_FAIL"
+            7 -> "FAIL"
+            8 -> "CANCEL"
+            else -> "status_$status"
+        }
+
+    private fun ByteArrayOutputStream.writeU32LE(value: Int) {
+        write(value and 0xFF)
+        write((value ushr 8) and 0xFF)
+        write((value ushr 16) and 0xFF)
+        write((value ushr 24) and 0xFF)
+    }
+
+    /** 93-byte fixed struct: cid | fileType u32 | fileLength u32 | fileCrc32 u32 | filename[80]. */
+    fun sendStart(fileType: Int, fileLength: Int, fileCrc32: Int, filename: String): ByteArray {
+        val out = ByteArrayOutputStream()
+        out.write(CID_SEND_START)
+        out.writeU32LE(fileType)
+        out.writeU32LE(fileLength)
+        out.writeU32LE(fileCrc32)
+
+        val nameBytes = filename.toByteArray(Charsets.US_ASCII)
+        require(nameBytes.size < FILENAME_FIELD_LEN) { "filename too long: $filename" }
+        out.write(nameBytes)
+        repeat(FILENAME_FIELD_LEN - nameBytes.size) { out.write(0) } // NUL-padded to 80
+
+        return out.toByteArray().also { check(it.size == SEND_START_LEN) }
+    }
+
+    fun sendData(): ByteArray = byteArrayOf(CID_SEND_DATA.toByte())
+
+    fun resultCheck(): ByteArray = byteArrayOf(CID_SEND_RESULT_CHECK.toByte())
+}
+
+// ---------- Notification payload JSON ----------
+
+/**
+ * The JSON document the glasses expect on the file service — these nine fields, exactly. Schema
+ * confirmed against a BLE capture of the Even app; see `notes/g2-notification-service.md`.
+ *
+ * `time_s` is UTC epoch seconds while `date` is **device-local** wall time; formatting `date` in
+ * UTC would skew every displayed timestamp by the device's offset.
+ */
+internal object NotificationJson {
+    fun androidNotification(
+        msgId: Int,
+        action: Int,
+        appIdentifier: String,
+        title: String,
+        subtitle: String,
+        message: String,
+        postTimeMs: Long,
+        displayName: String
+    ): ByteArray {
+        val dateFmt = java.text.SimpleDateFormat("yyyyMMdd'T'HHmmss", java.util.Locale.US)
+        val body =
+            org.json.JSONObject()
+                .put("msg_id", msgId)
+                .put("action", action)
+                .put("app_identifier", appIdentifier)
+                .put("title", title)
+                .put("subtitle", subtitle)
+                .put("message", message)
+                .put("time_s", postTimeMs / 1000)
+                .put("date", dateFmt.format(java.util.Date(postTimeMs)))
+                .put("display_name", displayName)
+
+        return org.json.JSONObject()
+            .put("android_notification", body)
+            .toString()
+            .toByteArray(Charsets.UTF_8)
+    }
+}
+