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

package/README.md

@@ -125,6 +125,7 @@ const devices = await BluetoothSdk.scan(DeviceModels.MentraLive, {
   onResults: (nextDevices) => {
     console.log('Nearby glasses:', nextDevices)
   },
+  onDiagnostic: (hint) => showScanHint(hint.message),
 })
 
 const device = await chooseDevice(devices)
@@ -137,6 +138,12 @@ const versionInfo = await BluetoothSdk.requestVersionInfo()
 console.log(versionInfo.buildNumber)
 ```
 
+`onDiagnostic` optionally reports a matching phone connection after an empty scan
+on Android and iOS. It is advisory, does not identify another app, and leaves
+normal empty completion unchanged. React hooks expose it as `scan.diagnostic`
+on `useMentraBluetooth()`, or `diagnostic` on `useBluetoothScan()`. Clear the hint
+when retrying or connecting.
+
 In multi-device environments, present an explicit picker instead of
 auto-connecting to the first nearby device.
 
@@ -288,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",
@@ -541,6 +543,12 @@ class BluetoothSdkModule : Module() {
             sdk?.startScan(DeviceModel.fromDeviceType(model))
         }
 
+        SdkAsyncFunction("getScanDiagnostic") { model: String ->
+            sdk?.connectedDeviceScanDiagnostic(DeviceModel.fromDeviceType(model))?.let {
+                mapOf("code" to it.code, "message" to it.message)
+            }
+        }
+
         SdkAsyncFunction("stopScan") { -> sdk?.stopScan() }
 
         SdkAsyncFunction("cancelConnectionAttempt") { -> sdk?.cancelConnectionAttempt() }
@@ -567,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/ConnectedDeviceMatcher.kt

@@ -0,0 +1,69 @@
+package com.mentra.bluetoothsdk
+
+/**
+ * Pure matcher deciding whether a GATT-connected peripheral (as enumerated by
+ * `BluetoothManager.getConnectedDevices`) is plausibly the glasses a scan for a
+ * given [DeviceModel] was looking for. This is a name/address heuristic, not
+ * proof of device identity or connection ownership.
+ *
+ * Kept free of Android framework types so the logic is unit-testable on the
+ * JVM (see `ConnectedDeviceMatcherTest`).
+ */
+internal object ConnectedDeviceMatcher {
+
+    /**
+     * True when the candidate peripheral either matches the saved default
+     * device for the scanned [model] (by address ignoring case when both
+     * addresses exist, otherwise by a nonblank exact name) or carries a
+     * known advertised-name prefix for that model.
+     *
+     * [defaultDevice] only counts when its model equals the scanned [model];
+     * a saved Mentra Live cannot explain an empty Nex scan. [DeviceModel.SIMULATED]
+     * never matches anything.
+     */
+    fun matches(
+        model: DeviceModel,
+        defaultDevice: Device?,
+        candidateName: String?,
+        candidateAddress: String?,
+    ): Boolean {
+        if (model == DeviceModel.SIMULATED) return false
+        val matchesDefault = if (defaultDevice?.model == model) {
+            val savedAddress = defaultDevice.address?.takeIf { it.isNotBlank() }
+            val address = candidateAddress?.takeIf { it.isNotBlank() }
+            if (savedAddress != null && address != null) {
+                address.equals(savedAddress, ignoreCase = true)
+            } else {
+                !candidateName.isNullOrBlank() && candidateName == defaultDevice.name
+            }
+        } else {
+            false
+        }
+        return matchesDefault || (candidateName != null && matchesModelNamePrefix(model, candidateName))
+    }
+
+    /**
+     * Per-model advertised/bonded-name filters, mirroring the scan filters the
+     * SGCs apply: MentraLive.kt (`Xy_A`, `XyBLE_`, `MENTRA_LIVE_BLE`,
+     * `MENTRA_LIVE_BT`, lowercase `mentra_live`) and MentraNex.kt (`Nex1-`,
+     * `MENTRA_DISPLAY_`). Models without a Mentra-branded advertised name
+     * (G1, G2, Nimo, Ar99, ...) have no prefix entry here and are detected
+     * only through the saved-default match above.
+     */
+    private fun matchesModelNamePrefix(
+        model: DeviceModel,
+        name: String,
+    ): Boolean =
+        when (model) {
+            DeviceModel.MENTRA_LIVE ->
+                name == "Xy_A" ||
+                    name.startsWith("XyBLE_") ||
+                    name.startsWith("MENTRA_LIVE_BLE") ||
+                    name.startsWith("MENTRA_LIVE_BT") ||
+                    name.lowercase().startsWith("mentra_live")
+            DeviceModel.MENTRA_NEX ->
+                name.startsWith("Nex1-") ||
+                    name.startsWith("MENTRA_DISPLAY_")
+            else -> false
+        }
+}

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.180"
-    const val RELEASE_SET_ID: String = "mentra-3.2.0-dev.180"
-    const val SOURCE_COMMIT: String = "1f24e462561fef37b7082204847a541db4a87c41"
-    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.180.json"
-    const val OTA_MANIFEST_SHA256: String = "cbf2a1b81430bd34942e2a1764138f6d79197767b4434a2d8c44311768f8b873"
+    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

@@ -3,6 +3,7 @@ package com.mentra.bluetoothsdk
 import android.app.Activity
 import android.app.Application
 import android.bluetooth.BluetoothManager
+import android.bluetooth.BluetoothProfile
 import android.content.Context
 import android.os.Bundle
 import android.os.Handler
@@ -347,6 +348,16 @@ class MentraBluetoothSdk private constructor(
             timeoutMs = timeoutMs,
         )
 
+    /**
+     * Scans for glasses of [model], reporting through [callback].
+     *
+     * A completed or cancelled scan ends with [ScanCallback.onComplete].
+     * [ScanCallback.onError] remains reserved for failure to start scanning.
+     * Callbacks implementing [ScanDiagnosticCallback] may receive a best-effort
+     * hint before an empty completed scan. Android reports phone-wide connection
+     * state, so this hint cannot identify an owning app or prove why scanning
+     * found no devices. React Native's separate scan implementation is unaffected.
+     */
     @JvmOverloads
     fun scan(
         model: DeviceModel,
@@ -378,7 +389,9 @@ class MentraBluetoothSdk private constructor(
             mainHandler.removeCallbacks(timeoutRunnable)
             session.markStopped()
             stopScan(reason)
-            callback.onComplete(latestResults.toList())
+            callback.completeScan(reason, latestResults.toList()) {
+                connectedDeviceScanDiagnostic(model)
+            }
         }
 
         timeoutRunnable = Runnable { finish(ScanStopReason.COMPLETED) }
@@ -493,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()
     }
@@ -1494,6 +1516,49 @@ class MentraBluetoothSdk private constructor(
         )
     }
 
+    /**
+     * A model-compatible device already connected to this phone can explain an
+     * empty scan, but Android does not expose app ownership or exclusive use.
+     * Skip known SDK connections/attempts and unavailable Bluetooth permissions.
+     */
+    internal fun connectedDeviceScanDiagnostic(model: DeviceModel): ScanDiagnostic? {
+        if (model == DeviceModel.SIMULATED) return null
+        val glassesStatus = getRawGlassesStatus()
+        if (glassesStatus.connected ||
+            glassesStatus.connectionState == GlassesConnectionState.CONNECTED ||
+            glassesStatus.connectionState == GlassesConnectionState.CONNECTING ||
+            glassesStatus.connectionState == GlassesConnectionState.BONDING
+        ) {
+            return null
+        }
+        return try {
+            val bluetoothManager =
+                appContext.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager ?: return null
+            val adapter = bluetoothManager.adapter ?: return null
+            if (!adapter.isEnabled) return null
+            val defaultDevice = currentDefaultDevice()
+            val device = bluetoothManager.getConnectedDevices(BluetoothProfile.GATT)
+                .firstOrNull { device ->
+                    ConnectedDeviceMatcher.matches(
+                        model = model,
+                        defaultDevice = defaultDevice,
+                        candidateName = device.name,
+                        candidateAddress = device.address,
+                    )
+                } ?: return null
+            val name = device.name?.takeIf { it.isNotBlank() } ?: device.address
+            ScanDiagnostic(
+                code = "device_connected_on_phone",
+                message =
+                    "Scan found no glasses, but a matching device \"$name\" is already connected to this phone. " +
+                        "If another app is using it, disconnect it there and scan again.",
+            )
+        } catch (error: SecurityException) {
+            // BLUETOOTH_CONNECT can be absent or revoked while scanning.
+            null
+        }
+    }
+
     private fun requireBluetoothReady(operation: String) {
         val bluetoothManager = appContext.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager
         val adapter =

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/connection/ConnectionModels.kt

@@ -53,13 +53,50 @@ enum class ScanStopReason {
     ERROR,
 }
 
+/**
+ * Callbacks for `MentraBluetoothSdk.scan`.
+ *
+ * Completed and cancelled scans report [onComplete]. A failure to start reports
+ * [onError] and is thrown to the caller. Optional empty-scan hints are delivered
+ * separately through [ScanDiagnosticCallback], never as errors.
+ */
 interface ScanCallback {
     fun onResults(devices: List<Device>) {}
     fun onComplete(devices: List<Device>) {}
     fun onError(error: BluetoothError) {}
 }
 
-abstract class MentraBluetoothScanCallback : ScanCallback
+/** A non-fatal scan hint; it does not establish the cause of an empty result. */
+data class ScanDiagnostic(val code: String, val message: String)
+
+/**
+ * Optional scan diagnostics, delivered before [onComplete] for an empty completed
+ * scan. Kept separate so existing compiled [ScanCallback] implementations do not
+ * need a new method. Android's `device_connected_on_phone` hint identifies a
+ * model-compatible GATT connection on this phone, not which app owns it.
+ */
+interface ScanDiagnosticCallback : ScanCallback {
+    fun onDiagnostic(diagnostic: ScanDiagnostic)
+}
+
+abstract class MentraBluetoothScanCallback : ScanDiagnosticCallback {
+    override fun onDiagnostic(diagnostic: ScanDiagnostic) {}
+}
+
+/** Complete once, with an optional advisory that never replaces completion. */
+internal fun ScanCallback.completeScan(
+    reason: ScanStopReason,
+    devices: List<Device>,
+    diagnostic: () -> ScanDiagnostic?,
+) {
+    try {
+        if (this is ScanDiagnosticCallback && reason == ScanStopReason.COMPLETED && devices.isEmpty()) {
+            diagnostic()?.let { onDiagnostic(it) }
+        }
+    } finally {
+        onComplete(devices)
+    }
+}
 
 class ScanSession internal constructor(
     private val stopAction: () -> Unit,

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)
+    }
+}
+