@mentra/bluetooth-sdk 0.1.8 → 0.1.10

package/README.md

@@ -7,8 +7,8 @@ The package includes:
 - A React Native / Expo module API exposed as `BluetoothSdk`.
 - React hooks under `@mentra/bluetooth-sdk/react` for common scan,
   connection, status, and event lifecycles.
-- Native Android code published as `com.mentra:bluetooth-sdk`.
-- Native iOS code published as the `MentraBluetoothSDK` CocoaPod.
+- Native Android code published as `com.mentraglass:bluetooth-sdk`.
+- Native iOS code available as the `MentraBluetoothSDK` Swift package.
 - An Expo config plugin that wires the native dependencies into generated Android and iOS projects.
 
 Use a development build or production native build. Expo Go cannot load this package because the SDK contains native code.
@@ -129,7 +129,8 @@ if (!device) {
 }
 
 await BluetoothSdk.connect(device)
-await BluetoothSdk.requestVersionInfo()
+const versionInfo = await BluetoothSdk.requestVersionInfo()
+console.log(versionInfo.buildNumber)
 ```
 
 In multi-device environments, present an explicit picker instead of
@@ -230,19 +231,27 @@ await BluetoothSdk.clearDisplay()
 await BluetoothSdk.showDashboard()
 await BluetoothSdk.setDashboardPosition(4, 2)
 
-await BluetoothSdk.requestWifiScan()
-await BluetoothSdk.sendWifiCredentials('Office WiFi', 'secret')
-await BluetoothSdk.forgetWifiNetwork('Office WiFi')
-await BluetoothSdk.setHotspotState(true)
+const networks = await BluetoothSdk.requestWifiScan()
+console.log(networks.map((network) => network.ssid))
 
-await BluetoothSdk.setGalleryModeEnabled(true)
+const wifiStatus = await BluetoothSdk.sendWifiCredentials('Office WiFi', 'secret')
+console.log(wifiStatus.state)
+
+const forgetStatus = await BluetoothSdk.forgetWifiNetwork('Office WiFi')
+console.log(forgetStatus.state)
+
+const hotspotStatus = await BluetoothSdk.setHotspotState(true)
+console.log(hotspotStatus.state)
+
+const galleryAck = await BluetoothSdk.setGalleryModeEnabled(true)
+console.log(galleryAck.status)
 await BluetoothSdk.setGalleryModeEnabled(false)
 
 await BluetoothSdk.setPreferredMic('auto')
 await BluetoothSdk.setMicState(true)
 await BluetoothSdk.setOwnAppAudioPlaying(false)
 
-await BluetoothSdk.rgbLedControl(
+const ledAck = await BluetoothSdk.rgbLedControl(
   `led-${Date.now()}`,
   'com.example.app',
   'on',
@@ -251,14 +260,59 @@ await BluetoothSdk.rgbLedControl(
   500,
   3,
 )
+console.log(ledAck.state)
 ```
 
-`setMicState(true)` defaults to continuous microphone PCM from the glasses. The SDK does not apply phone-side Voice Activity Detection gating to microphone audio events. Use `setVoiceActivityDetectionEnabled(false)` when you want glasses-side Voice Activity Detection disabled for continuous external STT, recording, or playback. `voice_activity_detection_status` reports whether glasses-side Voice Activity Detection is enabled, and `speaking_status` reports speaking/not-speaking when supported. Microphone events include the latest `voiceActivityDetectionEnabled` value.
+Settings commands that return `SettingsAckSuccessEvent` reject when the ASG reports an error ack. The SDK updates its local settings store only after that ASG ack resolves successfully, so observed SDK state reflects the acknowledged glasses state rather than a queued request. Raw `settings_ack` listener events still use `SettingsAckEvent` because they can include both success and failure statuses. `rgbLedControl(...)` resolves from a successful ASG `rgb_led_control_response` and rejects when the ASG reports `state: "error"`; raw `settings_ack` and `rgb_led_control_response` events remain available through listeners.
+
+WiFi, hotspot, and version-info commands resolve from the ASG response path, not local dispatch:
+`requestWifiScan()` resolves from the ASG `wifi_scan_result` completion response with the updated scan list, including `[]` when no networks are found. Intermediate `wifi_scan_result` events can arrive with `scanComplete: false` while the glasses stream discovered networks; the final event uses `scanComplete: true`. `sendWifiCredentials()` resolves when the requested SSID is connected, `forgetWifiNetwork()` resolves when that SSID is no longer connected, `setHotspotState()` resolves when the requested hotspot state is reported, and `requestVersionInfo()` resolves from the ASG `version_info` response instead of local store changes.
+
+React Native narrows returned values to success shapes where the raw listener event can also report errors:
+
+| API | Returned Value After `await` | Error Path |
+| --- | --- | --- |
+| `requestPhoto(...)` | Terminal `PhotoSuccessResponseEvent` with `state: "success"` after capture and delivery finish. `uploadUrl` is always present; webhook JSON metadata such as `photoUrl`, `statusUrl`, `contentType`, or `fileSizeBytes` is included when the receiver returns it. | Rejects when raw `photo_response.state === "error"`, the SDK cannot send the command, or the terminal photo response times out. |
+| `startVideoRecording(...)` | `VideoRecordingStartedStatusEvent` with `success: true` and `status: "recording_started"`. | Rejects on `success: false` statuses such as `already_recording`, send failure, or timeout. |
+| `stopVideoRecording(...)` | `VideoRecordingStoppedStatusEvent` with `success: true` and `status: "recording_stopped"`. | Rejects on `success: false` statuses such as `not_recording`, send failure, or timeout. |
+| `rgbLedControl(...)` | `RgbLedControlSuccessResponseEvent` with `state: "success"`. | Rejects when raw `rgb_led_control_response.state === "error"` or the response times out. |
+| `checkForOtaUpdate()` / `retryOtaVersionCheck()` | `OtaQueryResult`, either `ota_update_available` or current `ota_status`. | Rejects on command transport timeout/failure. A returned `ota_status.status === "failed"` is glasses OTA state, not a command rejection. |
+
+Android and iOS async APIs use `BluetoothException` / `BluetoothError` for the same error paths. Their returned event structs are the successful response in normal `try`/`await` code, while raw listener/delegate events still include both success and error payloads.
+
+`setMicState(true)` defaults to continuous microphone PCM from the glasses. The SDK does not apply phone-side Voice Activity Detection gating to microphone audio events. Glasses-side Voice Activity Detection is disabled by default for public SDK consumers; use `setVoiceActivityDetectionEnabled(true)` when you want supported glasses to gate microphone audio and emit live speaking status. `voice_activity_detection_status` reports whether glasses-side Voice Activity Detection is enabled, and `speaking_status` reports speaking/not-speaking when supported. Microphone events include the latest `voiceActivityDetectionEnabled` value.
+
+## OTA Updates
+
+Mentra Live firmware owns the OTA flow. The SDK mirrors the MentraOS app commands and events:
+
+- `checkForOtaUpdate()` sends `ota_query_status` and resolves with the ASG response (`ota_update_available` or the current `ota_status`).
+- `startOtaUpdate()` sends `ota_start` and resolves with the ASG start ack after your app presents the update and the user accepts it.
+- `retryOtaVersionCheck()` sends `ota_retry_version_check` and resolves with the same ASG response shape as `checkForOtaUpdate()`; use it only after fixing a known clock-skew/TLS failure.
+
+```ts
+import BluetoothSdk from '@mentra/bluetooth-sdk'
+
+BluetoothSdk.addListener('ota_status', (event) => {
+  console.log(`OTA ${event.status}: ${event.overall_percent}%`)
+})
+
+const ota = await BluetoothSdk.checkForOtaUpdate()
+if (ota.type === 'ota_update_available') {
+  const userAccepted = await promptUserToInstallUpdate(ota) // your app's UI
+  if (userAccepted) {
+    const startAck = await BluetoothSdk.startOtaUpdate()
+    console.log('OTA start acknowledged', startAck.timestamp)
+  }
+}
+```
+
+OTA requires Mentra Live glasses firmware that supports the ASG OTA protocol and network access from the glasses. During install, normal BLE traffic can be interrupted and the glasses may restart; keep the app connected and avoid sending unrelated commands until `ota_status.status` is `complete` or `failed`.
 
 ## Photo Upload
 
 ```ts
-await BluetoothSdk.requestPhoto({
+const photo = await BluetoothSdk.requestPhoto({
   requestId: `photo-${Date.now()}`,
   appId: 'com.example.app',
   size: 'medium',
@@ -269,13 +323,16 @@ await BluetoothSdk.requestPhoto({
   exposureTimeNs: null, // auto exposure; pass a positive nanosecond value for manual exposure
   iso: null, // auto ISO; pass a positive ISO only with manual exposureTimeNs
 })
+console.log('photo delivered', photo.photoUrl ?? photo.uploadUrl, photo.fileSizeBytes)
 ```
 
-The webhook should accept multipart form data with a `photo` file and `requestId`. If `authToken` is provided, the uploader adds `Authorization: Bearer <token>`. The camera light is always enabled for photo capture.
+`requestPhoto(...)` resolves only after the full photo action reaches terminal success: capture completed and the photo was delivered to the webhook, either directly from the glasses over Wi-Fi or through the phone's Bluetooth fallback relay. It rejects if the ASG reports `state: "error"`, if phone-side fallback upload fails, if the SDK cannot send the command, or if no terminal `photo_response` arrives before the command timeout. Use `photo_status` for intermediate stages such as `accepted`, `configuring`, `capturing`, `captured`, `uploading`, `ble_fallback_compression`, `ready_for_transfer`, and `transferring`; `photo_status` is progress, while `photo_response` is terminal success/error. The raw `photo_response` event stream still includes both success and error events for subscribers. The webhook should accept multipart form data with a `photo` file and `requestId`. If `authToken` is provided, the uploader adds `Authorization: Bearer <token>`. The camera light is always enabled for photo capture.
 
 For one-shot manual capture tuning, pass `exposureTimeNs` and `iso` together. `exposureTimeNs` is sensor exposure time in nanoseconds; `iso` is sensor ISO. If `exposureTimeNs` is omitted, `null`, invalid, or unsupported by the connected glasses, the camera uses auto exposure and ignores `iso`.
 
-Use `setCameraFov({fov, roiPosition})` to configure Mentra Live camera field of view and crop position. FOV is clamped to 82-118 degrees; ROI position is `0` center, `1` bottom, or `2` top. Applying FOV/ROI restarts the camera for about 5 seconds, so wait before requesting the next photo.
+Use `setCameraFov({fov, roiPosition})` to configure Mentra Live camera field of view and crop position. FOV is clamped to 62-118 degrees; ROI position is `"center"`, `"bottom"`, or `"top"`. You can also call `setCameraFov({preset: "narrow" | "standard" | "wide"})`; presets map to 82, 102, and 118 degrees with center ROI. The returned `CameraFovResult` resolves only after the ASG client reports that the setting was applied to camera hardware after the restart cooldown, and the promise rejects if the glasses report an error, persist the setting without hardware application, or time out. Raw `settings_ack` events remain available through `addListener("settings_ack", ...)` for diagnostic fields such as `hardwareApplied`. Treat FOV as a framing/ROI control; output resolution and effective detail can vary by capture path, firmware, and camera mode.
+
+`startVideoRecording(...)` and `stopVideoRecording(...)` resolve from successful ASG `video_recording_status` events only when the status matches the requested operation (`recording_started` or `recording_stopped`) and reject when the ASG reports `success: false`. Raw `video_recording_status` events remain available through listeners, including `recording_status` query events with `data.recording`.
 
 ## Streaming
 
@@ -292,7 +349,7 @@ await BluetoothSdk.startStream({
 await BluetoothSdk.stopStream()
 ```
 
-Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https://` for WHIP/WebRTC ingest. The SDK sends stream keep-alives automatically while streaming and reports keep-alive failures through `stream_status`. The camera light is always enabled while streaming.
+Use `rtmp://` or `rtmps://` for RTMP, `srt://` for SRT, and `http://` or `https://` for WHIP/WebRTC ingest. `startStream()` resolves with the correlated `stream_status` event once the glasses report `status: "streaming"`; `stopStream()` resolves when the glasses report `status: "stopped"` or confirms the stream was already stopped / not streaming. `stopStream()` returns a normalized stopped event for that already-stopped case. Stream starts reject if the glasses report an error before streaming; stream stops reject for real stop errors, send failure, another stop in flight, or timeout. The SDK sends stream keep-alives automatically while streaming and reports keep-alive failures through `stream_status`. The camera light is always enabled while streaming.
 `stream_status` events may include `resolvedConfig`, which reports the effective transport, video, and audio settings after glasses defaults, clamps, and camera preflight.
 
 ## Events
@@ -305,8 +362,7 @@ import {useBluetoothEvent} from '@mentra/bluetooth-sdk/react'
 export function HardwareEventLogger() {
   useBluetoothEvent('button_press', (event) => console.log(event))
   useBluetoothEvent('touch_event', (event) => console.log(event))
-  useBluetoothEvent('photo_status', (event) => console.log(event.status, event.resolvedConfig))
-  useBluetoothEvent('photo_response', (event) => console.log(event))
+  useBluetoothEvent('photo_status', (event) => console.log(event.status, event.resolvedConfig, event.captureMetadata))
   useBluetoothEvent('stream_status', (event) => console.log(event))
   useBluetoothEvent('speaking_status', (event) => console.log(event.speaking))
   useBluetoothEvent('mic_pcm', (event) => {
@@ -320,9 +376,19 @@ export function HardwareEventLogger() {
 
 For non-React modules, `BluetoothSdk.addListener(...)` is the low-level subscription API. Keep the returned subscription and call `remove()` when the listener is no longer needed.
 
-Common event names include `button_press`, `touch_event`, `head_up`, `battery_status`, `wifi_status_change`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `stream_status`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
+Common event names include `button_press`, `touch_event`, `head_up`, `battery_status`, `wifi_status_change`, `wifi_scan_result`, `hotspot_status_change`, `photo_status`, `photo_response`, `gallery_status`, `settings_ack`, `version_info`, `stream_status`, `ota_update_available`, `ota_start_ack`, `ota_status`, `mic_pcm`, `mic_lc3`, `local_transcription`, `rgb_led_control_response`, `audio_connected`, `audio_disconnected`, and `log`.
+
+React Native event payload fields usually use camelCase. OTA events intentionally mirror the glasses firmware field names, such as `overall_percent` and `version_name`. For example, `touch_event` includes `gestureName`, `wifi_scan_result` includes `networks` and `scanComplete`, `version_info` matches the `requestVersionInfo()` result shape, `photo_response` success includes `uploadUrl` and may include webhook-returned `photoUrl`, `statusUrl`, `contentType`, and `fileSizeBytes`, and `gallery_status` includes `hasContent`, `cameraBusy`, and optional `cameraBusyReason`. `photo_status` reports intermediate photo states such as `accepted`, `queued`, `configuring`, `capturing`, `captured`, `compressing`, `ble_fallback_compression`, `uploading`, `ready_for_transfer`, `transferring`, and `failed`; the `configuring` event includes `resolvedConfig` with the effective JPEG dimensions, quality, requested size, transfer method, compression, and manual exposure fields when present. The `capturing` event may include `requestedCaptureConfig` and `meteredPreview`; the `captured` event may include `captureMetadata` with the HAL-applied exposure, ISO, frame duration, and AE state. `mic_pcm` includes `sampleRate`, `bitsPerSample`, `channels`, and `encoding`; `mic_lc3` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, and `packetizedFromGlasses`.
+
+Photo status metadata is tied to the capture stage where the glasses know it:
+
+| Status | Optional metadata | Meaning |
+| --- | --- | --- |
+| `configuring` | `resolvedConfig` | Effective JPEG size, quality, requested size, source, transfer method, compression, and manual capture settings when present. |
+| `capturing` | `requestedCaptureConfig`, `meteredPreview` | Camera2 still request about to be submitted, plus the latest auto-exposure preview estimate before capture. |
+| `captured` | `captureMetadata` | HAL-applied still capture result, including actual exposure, ISO, frame duration, AE state, and related camera modes when available. |
 
-React Native event payload fields use camelCase. For example, `touch_event` includes `gestureName`, `photo_response` success includes `uploadUrl`, and `gallery_status` includes `hasContent` and `cameraBusy`. `photo_status` reports intermediate photo states such as `accepted`, `queued`, `configuring`, `capturing`, `captured`, `compressing`, `uploading`, `ready_for_transfer`, `transferring`, and `failed`; the `configuring` event includes `resolvedConfig` with the effective JPEG dimensions, quality, requested size, transfer method, compression, and manual exposure fields when present. `mic_pcm` includes `sampleRate`, `bitsPerSample`, `channels`, and `encoding`; `mic_lc3` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, and `packetizedFromGlasses`.
+Upload and transfer statuses such as `uploading`, `compressing`, `ble_fallback_compression`, `ready_for_transfer`, and `transferring` describe transport progress only and do not carry capture metadata. `ble_fallback_compression` means the direct Wi-Fi/webhook upload failed and the glasses are compressing the already-captured photo for Bluetooth fallback delivery. Local action-button photos emitted by the glasses use the same `photo_status` event shape when the phone SDK is connected; those events use `resolvedConfig.source: "button"` and `resolvedConfig.transferMethod: "local"`.
 
 Only documented imports are supported for app developers. Undocumented package subpaths or symbols with a leading underscore can change without notice.
 
@@ -337,6 +403,38 @@ MENTRA_BLUETOOTH_SDK_PACKAGE_PATH=/path/to/MentraOS/mobile/modules/bluetooth-sdk
 
 Use `bunx expo run:android` for Android. Keep local paths in your shell or CI environment, not in committed app config.
 
+For bare native iOS apps, use the public SwiftPM repository:
+
+```text
+https://github.com/Mentra-Community/mentra-bluetooth-sdk-ios.git
+```
+
+Add the `MentraBluetoothSDK` product to your app target at version `0.1.7` or newer.
+
+For local SDK development, add this package folder directly in Xcode:
+
+```text
+/path/to/MentraOS/mobile/modules/bluetooth-sdk
+```
+
+The core Swift package intentionally excludes optional local STT, Nex/SwiftProtobuf, Vuzix/Ultralite, and tar.bz2 extraction code paths.
+
+Maintainers publishing the public SwiftPM mirror should follow
+[RELEASING_IOS_SPM.md](./RELEASING_IOS_SPM.md).
+
+## Android Maven Publishing
+
+Maintainers publishing the native Android artifacts to Maven Central should
+follow [RELEASING_ANDROID_MAVEN.md](./RELEASING_ANDROID_MAVEN.md).
+
+Public Maven publishing uses a public SDK mode that omits MentraOS-only Android
+integrations from the artifact metadata while normal MentraOS app builds keep
+those integrations enabled.
+
+Use `android/gradle.properties.example` as the template for Sonatype Central and
+GPG signing properties. Put real values in `~/.gradle/gradle.properties` or CI
+secrets, not in the repository.
+
 ## Starter Example App
 
 The [Mentra Bluetooth SDK Starter Kit](https://github.com/Mentra-Community/Mentra-Bluetooth-SDK-Starter-Kit) includes starter example apps for Android, iOS, and React Native / Expo. The React Native starter demonstrates scan/connect, display, camera photo upload, RTMP/SRT/WebRTC streaming, Wi-Fi/hotspot, microphone PCM, RGB LED, gallery mode, and console event inspection.

package/android/build.gradle

@@ -1,13 +1,185 @@
 import groovy.json.JsonSlurper
+import java.security.MessageDigest
 
 apply plugin: 'com.android.library'
 apply plugin: 'maven-publish'
 apply plugin: 'signing'
 
 def packageJson = new JsonSlurper().parse(file("../package.json"))
+def mavenGroupId = 'com.mentraglass'
+def mavenPublishVersion = (findProperty('mentraMavenVersion') ?: System.getenv('MENTRA_MAVEN_VERSION') ?: packageJson.version).toString()
+def publicMavenSdk = (findProperty('mentraPublicSdk') ?: System.getenv('MENTRA_PUBLIC_SDK') ?: 'false').toString().toBoolean()
 
-group = 'com.mentra'
-version = packageJson.version
+// Download Sherpa-ONNX Android AAR from the upstream GitHub release and stage
+// it as a Maven artifact in a tiny on-disk repository under libs/maven/.
+// Why this shape:
+//   - Jitpack stopped publishing for v1.13.2+ (their build step fails because
+//     the AAR asset isn't present when its install-file step runs).
+//   - We can't just `implementation files("…aar")` because AGP refuses local
+//     .aar deps from library modules ("Direct local .aar file dependencies
+//     are not supported when building an AAR"). Maven-coord deps are fine.
+// The SHA-256 is pinned (matches the upstream checksum.txt for v1.13.2) so a
+// tampered or partially-written artifact is rejected before being used.
+def sherpaOnnxGroup = "com.k2fsa.sherpa.onnx"
+def sherpaOnnxArtifact = "sherpa-onnx"
+def sherpaOnnxVersion = "1.13.2"
+def sherpaOnnxSha256 = "aa5505c0ec4f8bdaee5f214a64ba3012be64f2aecc022e82a64f33392b8dd245"
+
+def sherpaOnnxMavenRoot = file("libs/maven")
+def sherpaOnnxRepoDir = new File(
+  sherpaOnnxMavenRoot,
+  "${sherpaOnnxGroup.replace('.', '/')}/${sherpaOnnxArtifact}/${sherpaOnnxVersion}"
+)
+def sherpaOnnxAar = new File(sherpaOnnxRepoDir, "${sherpaOnnxArtifact}-${sherpaOnnxVersion}.aar")
+def sherpaOnnxPom = new File(sherpaOnnxRepoDir, "${sherpaOnnxArtifact}-${sherpaOnnxVersion}.pom")
+
+def sha256OfFile = { File f ->
+  def digest = MessageDigest.getInstance("SHA-256")
+  f.withInputStream { input ->
+    def buf = new byte[64 * 1024]
+    int n
+    while ((n = input.read(buf)) != -1) {
+      digest.update(buf, 0, n)
+    }
+  }
+  digest.digest().collect { String.format("%02x", it & 0xff) }.join("")
+}
+
+// If a stale AAR exists with the wrong hash (e.g. from a previous failed
+// download or a version bump), drop it so we re-fetch.
+if (sherpaOnnxAar.exists() && sha256OfFile(sherpaOnnxAar) != sherpaOnnxSha256) {
+  logger.lifecycle("Sherpa-ONNX AAR checksum mismatch on disk; redownloading.")
+  if (!sherpaOnnxAar.delete()) {
+    throw new GradleException(
+      "Sherpa-ONNX AAR at ${sherpaOnnxAar.absolutePath} has a mismatched SHA-256 " +
+      "but could not be deleted. Refusing to continue with a potentially tampered artifact."
+    )
+  }
+}
+
+if (!sherpaOnnxAar.exists()) {
+  sherpaOnnxRepoDir.mkdirs()
+  def sherpaOnnxUrl = "https://github.com/k2-fsa/sherpa-onnx/releases/download/v${sherpaOnnxVersion}/${sherpaOnnxArtifact}-${sherpaOnnxVersion}.aar"
+  logger.lifecycle("Downloading Sherpa-ONNX AAR v${sherpaOnnxVersion} from GitHub release…")
+  // Download to a .part sibling and rename only after the SHA-256 matches, so
+  // an interrupted or tampered download can't be silently accepted as valid.
+  def partial = file("${sherpaOnnxAar.absolutePath}.part")
+  try {
+    new URL(sherpaOnnxUrl).withInputStream { input ->
+      partial.withOutputStream { output -> output << input }
+    }
+    def actual = sha256OfFile(partial)
+    if (actual != sherpaOnnxSha256) {
+      throw new GradleException(
+        "Sherpa-ONNX AAR v${sherpaOnnxVersion} SHA-256 mismatch.\n" +
+        "  expected: ${sherpaOnnxSha256}\n" +
+        "  actual:   ${actual}\n" +
+        "Refusing to use the downloaded artifact."
+      )
+    }
+    if (!partial.renameTo(sherpaOnnxAar)) {
+      throw new GradleException("Failed to move ${partial.name} to ${sherpaOnnxAar.name}")
+    }
+  } finally {
+    if (partial.exists()) {
+      partial.delete()
+    }
+  }
+}
+
+// Minimal POM so the Maven resolver is happy. No transitive deps — the AAR
+// ships its own native libs and we already pin onnxruntime separately below.
+if (!sherpaOnnxPom.exists()) {
+  sherpaOnnxPom.text = """<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>${sherpaOnnxGroup}</groupId>
+  <artifactId>${sherpaOnnxArtifact}</artifactId>
+  <version>${sherpaOnnxVersion}</version>
+  <packaging>aar</packaging>
+</project>
+"""
+}
+
+repositories {
+  maven { url = uri(sherpaOnnxMavenRoot) }
+  maven { url 'https://jitpack.io' }
+}
+
+
+group = mavenGroupId
+version = mavenPublishVersion
+
+def credentialValue = { List<String> propertyNames, List<String> envNames ->
+  for (propertyName in propertyNames) {
+    def value = findProperty(propertyName)
+    if (value != null && value.toString().trim()) {
+      return value.toString()
+    }
+  }
+  for (envName in envNames) {
+    def value = System.getenv(envName)
+    if (value != null && value.trim()) {
+      return value
+    }
+  }
+  return null
+}
+
+def centralTokenParts = { boolean failOnInvalid = false ->
+  def token = credentialValue(['sonatypeTokenBase64', 'mavenCentralTokenBase64'], ['SONATYPE_TOKEN_BASE64', 'MAVEN_CENTRAL_TOKEN_BASE64'])
+  if (!token) {
+    return null
+  }
+  def decoded
+  try {
+    decoded = new String(token.decodeBase64(), 'UTF-8')
+  } catch (Exception e) {
+    if (failOnInvalid) {
+      throw new GradleException('Sonatype token must be valid base64 for username:password', e)
+    }
+    return null
+  }
+  def separator = decoded.indexOf(':')
+  if (separator <= 0) {
+    if (failOnInvalid) {
+      throw new GradleException('Sonatype token must decode to username:password')
+    }
+    return null
+  }
+  return [decoded.substring(0, separator), decoded.substring(separator + 1)]
+}
+
+def centralUsername = { boolean failOnInvalidToken = false ->
+  credentialValue(['sonatypeUsername', 'mavenCentralUsername'], ['SONATYPE_USERNAME', 'MAVEN_CENTRAL_USERNAME']) ?: centralTokenParts(failOnInvalidToken)?.get(0)
+}
+
+def centralPassword = { boolean failOnInvalidToken = false ->
+  credentialValue(['sonatypePassword', 'mavenCentralPassword'], ['SONATYPE_PASSWORD', 'MAVEN_CENTRAL_PASSWORD']) ?: centralTokenParts(failOnInvalidToken)?.get(1)
+}
+
+def signingKey = {
+  credentialValue(['signingKey'], ['SIGNING_KEY'])
+}
+
+def signingPassword = {
+  credentialValue(['signingPassword'], ['SIGNING_PASSWORD'])
+}
+
+def shouldUseGpgCmd = {
+  (credentialValue(['signing.useGpgCmd'], ['SIGNING_USE_GPG_CMD']) ?: 'false').toBoolean()
+}
+
+def isCentralPublishTask = {
+  gradle.taskGraph.allTasks.any { it.name.toLowerCase().contains('sonatypecentral') }
+}
+
+gradle.taskGraph.whenReady {
+  if (isCentralPublishTask()) {
+    centralUsername(true)
+    centralPassword(true)
+  }
+}
 
 def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
 apply from: expoModulesCorePlugin
@@ -40,7 +212,7 @@ android {
   namespace "com.mentra.bluetoothsdk"
   defaultConfig {
     versionCode 1
-    versionName packageJson.version
+    versionName project.version
   }
   publishing {
     singleVariant("release") {
@@ -51,6 +223,11 @@ android {
   lintOptions {
     abortOnError false
   }
+  testOptions {
+    unitTests {
+      includeAndroidResources = true
+    }
+  }
   packagingOptions {
     pickFirst '**/libjsc.so'
     pickFirst '**/libc++_shared.so'
@@ -82,6 +259,21 @@ dependencies {
 
   // OkHttp for HTTP requests
   implementation 'com.squareup.okhttp3:okhttp:4.12.0'
+  implementation 'androidx.exifinterface:exifinterface:1.3.7'
+
+  // AVIF decode for BLE photo fallback. Public Maven artifacts omit this
+  // JitPack-only decoder from runtime metadata; Android 12+ can still use the
+  // platform decoder, while MentraOS app builds keep HeifCoder for broader
+  // fallback support.
+  // Pinned to the JitPack 1.7.3 build (same as asg_client): the Maven Central
+  // 2.2.x releases transitively pull kotlin-stdlib 2.3.0, which breaks this
+  // project's Kotlin 2.1 compile of :expo.
+  dependencies.add(publicMavenSdk ? 'compileOnly' : 'implementation', 'com.github.awxkee:avif-coder:1.7.3')
+
+  testImplementation 'junit:junit:4.13.2'
+  testImplementation 'org.robolectric:robolectric:4.11.1'
+  testImplementation 'org.assertj:assertj-core:3.24.2'
+  testImplementation 'androidx.test:core:1.5.0'
 
   // Local photo upload receiver
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"
@@ -89,28 +281,57 @@ dependencies {
   // LC3 audio codec library
   implementation project(':lc3Lib')
 
-  // Sherpa-ONNX for local transcription
-  implementation 'com.github.k2-fsa:sherpa-onnx:v1.12.8'
+  // These integrations are used by the full MentraOS app, but are not exposed
+  // through the public SDK API. Public Maven artifacts compile against them
+  // without publishing them as runtime transitives, so consumers only need
+  // Maven Central/Google repositories for normal SDK use.
+  def optionalMentraOsIntegrationDependency = publicMavenSdk ? 'compileOnly' : 'implementation'
+
+  // Sherpa-ONNX for local transcription. Jitpack's v1.13.2 build failed
+  // upstream, so we stage the prebuilt AAR into libs/maven/ (see top of file)
+  // and consume it as a Maven coord — AGP rejects raw files() .aar deps in
+  // library modules.
+  dependencies.add(optionalMentraOsIntegrationDependency, "${sherpaOnnxGroup}:${sherpaOnnxArtifact}:${sherpaOnnxVersion}@aar")
 
-  // Vuzix Z100
-  implementation 'com.vuzix:ultralite-sdk-android:1.8'
-  implementation 'com.squareup.picasso:picasso:2.8'
+  if (!publicMavenSdk) {
+    // Silero VAD — vendored source under silero/, wired as :silero
+    // sub-project (see settings.gradle). This replaces the previous Jitpack AAR
+    // (com.github.gkonovalov:android-vad:2.0.9) whose prebuilt JNI was bound to
+    // an ORT version incompatible with the one bundled by sherpa-onnx, causing a
+    // dlopen UnsatisfiedLinkError for OrtGetApiBase at VAD startup. By owning the
+    // source we control both the Java API surface and the ORT version it links
+    // against; today both consumers (Silero VAD and sherpa-onnx) load their own
+    // libonnxruntime.so — see packagingOptions pickFirst above.
+    implementation project(':silero')
+
+    // Vuzix Z100
+    implementation 'com.vuzix:ultralite-sdk-android:1.8'
+    implementation 'com.squareup.picasso:picasso:2.8'
+  } else {
+    compileOnly project(':silero')
+    compileOnly 'com.vuzix:ultralite-sdk-android:1.8'
+    compileOnly 'com.squareup.picasso:picasso:2.8'
+  }
 
   implementation 'com.google.protobuf:protobuf-java:4.32.0'
   implementation 'com.google.protobuf:protobuf-java-util:4.32.0'
 }
 
-// Force override onnxruntime version to 1.17.1
+// Pin onnxruntime-android to 1.24.3 — the version sherpa-onnx 1.13.2 was built
+// against (its libonnxruntime.so exports OrtGetApiBase@@VERS_1.24.3). Matching
+// this lets the :silero VAD module share a single libonnxruntime.so with
+// sherpa-onnx, resolving the ELF symbol-versioning conflict that crashed VAD
+// startup on previous mismatched versions.
 configurations.all {
   resolutionStrategy {
     eachDependency { DependencyResolveDetails details ->
       if (details.requested.group == 'com.microsoft.onnxruntime') {
-        details.useVersion '1.17.1'
-        details.because('Force override transitive onnxruntime version')
+        details.useVersion '1.24.3'
+        details.because('Match sherpa-onnx 1.13.2 ORT 1.24.3')
       }
       if (details.requested.name == 'onnxruntime-android') {
-        details.useVersion '1.17.1'
-        details.because('Force override transitive onnxruntime version')
+        details.useVersion '1.24.3'
+        details.because('Match sherpa-onnx 1.13.2 ORT 1.24.3')
       }
     }
   }
@@ -120,7 +341,7 @@ afterEvaluate {
   publishing {
     publications {
       release(MavenPublication) {
-        groupId = 'com.mentra'
+        groupId = mavenGroupId
         artifactId = 'bluetooth-sdk'
         version = project.version
 
@@ -151,13 +372,65 @@ afterEvaluate {
         }
       }
     }
+    repositories {
+      maven {
+        name = 'sonatypeCentral'
+        url = uri('https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/')
+        credentials {
+          username = centralUsername()
+          password = centralPassword()
+        }
+      }
+    }
   }
 
   signing {
+    def inMemorySigningKey = signingKey()
+    if (inMemorySigningKey) {
+      useInMemoryPgpKeys(inMemorySigningKey, signingPassword())
+    } else if (shouldUseGpgCmd()) {
+      useGpgCmd()
+    }
     required {
-      gradle.taskGraph.allTasks.any { it.name.toLowerCase().contains("publish") } &&
-        (findProperty("signing.keyId") || findProperty("signingKey"))
+      isCentralPublishTask()
     }
     sign publishing.publications.release
   }
 }
+
+tasks.withType(Sign).configureEach {
+  onlyIf { isCentralPublishTask() }
+}
+
+tasks.register('uploadSonatypeCentralDeployment') {
+  group = 'publishing'
+  description = "Uploads the ${mavenGroupId} OSSRH compatibility repository to the Central Portal."
+  def releasePublishTaskPath = project.path == ':'
+    ? ':publishReleasePublicationToSonatypeCentralRepository'
+    : "${project.path}:publishReleasePublicationToSonatypeCentralRepository"
+  dependsOn ':lc3Lib:publishReleasePublicationToSonatypeCentralRepository',
+    releasePublishTaskPath
+
+  doLast {
+    def username = centralUsername(true)
+    def password = centralPassword(true)
+    if (!username || !password) {
+      throw new GradleException('Set sonatypeTokenBase64 or sonatypeUsername/sonatypePassword before uploading to Central.')
+    }
+
+    def publishingType = (findProperty('sonatypePublishingType') ?: System.getenv('SONATYPE_PUBLISHING_TYPE') ?: 'user_managed').toString()
+    def endpoint = new URL("https://ossrh-staging-api.central.sonatype.com/manual/upload/defaultRepository/${mavenGroupId}?publishing_type=${publishingType}")
+    def connection = endpoint.openConnection()
+    connection.requestMethod = 'POST'
+    connection.setRequestProperty('Authorization', "Bearer ${"${username}:${password}".bytes.encodeBase64()}")
+    connection.setRequestProperty('Content-Length', '0')
+
+    def statusCode = connection.responseCode
+    def responseBody = statusCode >= 400 ? connection.errorStream?.text : connection.inputStream?.text
+    if (statusCode < 200 || statusCode >= 300) {
+      throw new GradleException("Central deployment upload failed with HTTP ${statusCode}: ${responseBody ?: ''}")
+    }
+
+    println "Sonatype Central deployment upload requested for ${mavenGroupId} (${publishingType})."
+  }
+}

package/android/gradle.properties.example

@@ -0,0 +1,9 @@
+# Copy these values into ~/.gradle/gradle.properties or inject them as CI
+# secrets before running Android Maven publishing tasks. Do not commit real
+# Sonatype tokens, GPG key names, or GPG passphrases.
+sonatypeTokenBase64=...
+sonatypePublishingType=user_managed
+signing.useGpgCmd=true
+signing.gnupg.executable=/opt/homebrew/bin/gpg
+signing.gnupg.keyName=...
+signing.gnupg.passphrase=...