# API Reference

> Lifecycle, status, commands, events, and shared types for the Glassly Bluetooth SDK.

Source: https://docs.glassly.ai/bluetooth-sdk/api-reference/

The Glassly Bluetooth SDK exposes the same core glasses lifecycle across Android, iOS, and React Native:

- Scan for a supported glasses model.
- Connect to a discovered `Device` or an app-restored default device.
- Read typed lifecycle state through the public surface for your platform.
- Subscribe to typed hardware events.
- Send camera, stream, audio, Wi-Fi, hotspot, LED, and settings commands for Mentra Live.

## Packages And Imports

| Platform | Install package | Import |
| --- | --- | --- |
| Android | `ai.glassly:bluetooth-sdk` | `import com.glassly.bluetoothsdk.*` |
| iOS | `BluetoothSDK` Swift package | `import BluetoothSDK` |
| React Native / Expo | `@glassly/bluetooth-sdk` | `import BluetoothSdk, {DeviceModels} from '@glassly/bluetooth-sdk'` |
| React Native hooks | `@glassly/bluetooth-sdk` | `import {useBluetooth} from '@glassly/bluetooth-sdk/react'` |
| React Native photo receiver | `@glassly/bluetooth-sdk` | `import PhotoReceiver from '@glassly/bluetooth-sdk/photo-receiver'` |

Only documented imports are part of the supported app developer API. Undocumented package subpaths or symbols with a leading underscore can change without notice.

## Lifecycle

**React Native**

```tsx
import {useBluetoothEvent, useBluetooth} from '@glassly/bluetooth-sdk/react';

function DeviceScreen() {
  const glassly = useBluetooth();
  useBluetoothEvent('button_press', (event) => {
    console.log(event.buttonId, event.pressType);
  });

  console.log(glassly.glasses.connection.state);
}
```

**Android**

```kotlin
val sdk = BluetoothSdk.create(
    context = applicationContext,
    config = BluetoothSdkConfig(),
    listener = listener,
)

sdk.close()
```

**iOS**

```swift
let sdk = BluetoothSDK(configuration: .default)
sdk.delegate = delegate

sdk.invalidate()
```

Keep one SDK instance per active app session. The SDK owns Bluetooth connection state, native event delivery, and cleanup. Your app owns user identity, UI state, and whether a default device record is persisted across app restarts.

## Glassly SDK Usage Analytics

Usage analytics are currently turned off. This SDK version ships without a
PostHog key and sends none of the events below. The configuration options
still work, so apps that already opt out need no changes when analytics return.

When enabled, the SDK reports anonymous usage events to Glassly's PostHog
project so Glassly can understand SDK adoption and successful glasses
connections:

| Event | Fires When |
| --- | --- |
| `bluetooth_sdk_started` | Once per app runtime after the native SDK starts. |
| `bluetooth_sdk_glasses_connected` | When SDK status transitions from not connected to connected. Failed scans and failed connection attempts are not counted. |
| `bluetooth_sdk_glasses_identified` | Once per connection, as soon as the connected glasses report a valid manufacturing serial. It carries that serial as `glasses_device_id`. |

Analytics delivery is fire-and-forget: events are submitted asynchronously, do
not block Bluetooth SDK behavior, and are not retried if delivery fails.

**React Native**

Disable analytics before native SDK startup through the Expo config plugin:

```json
{
  "expo": {
    "plugins": [
      [
        "@glassly/bluetooth-sdk",
        {
          "analytics": false
        }
      ]
    ]
  }
}
```

The `analytics` prop also accepts the object form `{"analytics": {"enabled": false}}`,
which is equivalent.

**Android**

```kotlin
val sdk = BluetoothSdk.create(
    context = applicationContext,
    config = BluetoothSdkConfig(
        analytics = BluetoothSdkAnalyticsConfig.disabled()
    ),
    listener = listener,
)
```

Android apps can also set application metadata before SDK startup:

```xml
<meta-data
    android:name="com.glassly.bluetoothsdk.analytics.disabled"
    android:value="true" />
```

**iOS**

```swift
let sdk = BluetoothSDK(
    configuration: BluetoothSDKConfiguration(
        analytics: .disabled
    )
)
```

iOS apps can also set `BluetoothSdkAnalyticsDisabled` to `true` in
`Info.plist` before SDK startup.

Apps do not configure the analytics destination. Once analytics return, these
SDK usage events are sent to Glassly's PostHog project unless the app disables
them.

Captured properties are intentionally narrow:

| Property | Meaning |
| --- | --- |
| `event_source` | Always `glassly_bluetooth_sdk`. |
| `sdk_platform` | Native platform that sends the event: `android` or `ios`. |
| `sdk_surface` | Public SDK surface: `react_native`, `android`, or `ios`. |
| `sdk_version` | Bluetooth SDK version. |
| `app_package` / `app_bundle_identifier` | Consuming app identifier. |
| `os_platform`, `os_version` | Phone OS metadata. |
| `event_kind` | `sdk_started`, `glasses_connected`, or `glasses_identified`. |
| `fully_booted` | Connection and identification events only; whether the connected status already reports fully booted. |
| `glasses_model` | Connection and identification events only; included only when the SDK has a non-empty model value. |
| `glasses_device_id` | Identification event only; the glasses manufacturing serial. |
| `glasses_device_id_type` | Identification event only; always `manufacturing_serial`. |

`bluetooth_sdk_glasses_identified` intentionally includes the glasses
manufacturing serial so Glassly can correlate fleet deployments across
supported models. The serial identifies the glasses hardware, not the user or
the host phone. Its source depends on the model: Mentra Live reports the serial
provisioned in BES NV storage, while G1 and Ar99 decode it from the glasses'
BLE advertisement / manufacturer data.

Apart from that glasses serial, the SDK does not upload BLE MAC addresses,
CoreBluetooth identifiers, the host phone's device serial, Bluetooth device
names, user ids, tokens, Wi-Fi credentials, microphone data, photos, or
transcripts. It stores a locally generated anonymous SDK install id and sends
it as PostHog `distinct_id`; events include `$process_person_profile: false` so
PostHog does not create person profiles for these SDK usage pings.

## Connection

**React Native**

```ts
const devices = await BluetoothSdk.scan(DeviceModels.MentraLive, {
  timeoutMs: 10_000,
  onResults: (nextDevices) => renderDevicePicker(nextDevices),
});

const device = await chooseDevice(devices);
await BluetoothSdk.connect(device, {saveAsDefault: false});

await BluetoothSdk.setDefaultDevice(device);

async function reconnectSavedDevice() {
  const defaultDevice = await BluetoothSdk.getDefaultDevice();
  if (defaultDevice) {
    await BluetoothSdk.connectDefault();
  }
}

async function clearSavedDevice() {
  await BluetoothSdk.clearDefaultDevice();
}

async function stopConnection() {
  await BluetoothSdk.cancelConnectionAttempt();
  await BluetoothSdk.disconnect();
  await BluetoothSdk.forget();
}
```

**Android**

```kotlin
val devices = mutableListOf<Device>()
val scanSession = sdk.scan(DeviceModel.MENTRA_LIVE, timeoutMs = 10_000) { nextDevices ->
    devices.clear()
    devices.addAll(nextDevices)
    renderDevicePicker(nextDevices, onSelect = { device ->
        sdk.connect(device)
        sdk.setDefaultDevice(device)
    })
}

fun reconnectSavedDevice() {
    val defaultDevice = sdk.getDefaultDevice()
    if (defaultDevice != null) {
        sdk.connectDefault()
    }
}

fun clearSavedDevice() {
    sdk.clearDefaultDevice()
}

fun stopConnection() {
    sdk.cancelConnectionAttempt()
    sdk.disconnect()
    sdk.forget()
}
```

**iOS**

```swift
var devices: [Device] = []
let scanSession = try sdk.scan(model: .mentraLive, timeout: 10) { nextDevices in
    devices = nextDevices
    renderDevicePicker(nextDevices) { device in
        do {
            try sdk.connect(to: device)
            sdk.setDefaultDevice(device)
        } catch {
            handleConnectionError(error)
        }
    }
}

func reconnectSavedDevice() throws {
    if sdk.getDefaultDevice() != nil {
        try sdk.connectDefault()
    }
}

func clearSavedDevice() {
    sdk.clearDefaultDevice()
}

func stopConnection() {
    sdk.cancelConnectionAttempt()
    sdk.disconnect()
    sdk.forget()
}
```

Prefer connecting to a `Device` returned by SDK scan callbacks. If your app wants `connectDefault()` to work after restart, persist a small default-device record in app storage and restore it with `setDefaultDevice()` before calling `connectDefault()`.

Use `scan()` for user-facing device pickers. The progressive result callback is for UI: render the nearby-device list every time it changes during scanning. The returned final result is for control flow: after the timeout/completion, choose a device from the last list and connect. In multi-device environments, do not auto-connect to the first nearby glasses; present an explicit picker.

## Device Identity

`Device.id` is the stable app-facing key for a scan result, within the limits of the platform identifier available to the SDK. Use it as a list key, selected-device key, and persisted default-device key.

Do not parse `id` for model, name, or address information. Use the typed fields instead:

| Field | Meaning |
| --- | --- |
| `model` | Glasses family reported by the SDK, expected to be Mentra Live in these flows. |
| `name` | Bluetooth name reported during scan. |
| `address` / `identifier` | Platform device handle when available. Android commonly provides a Bluetooth address. iOS commonly provides a CoreBluetooth identifier. React Native exposes this value as `address`. |
| `rssi` | Optional signal strength from scan results. It may be undefined at first discovery and appear in a later scan update when the platform reports RSSI metadata. |

When the platform does not provide an address or identifier, the SDK falls back to a `model:name` key.

Do not require `rssi` for picker rows. Use SDK-provided stable discovery order by default, and treat RSSI as supplemental signal-strength metadata when it is present.

## Status

**React Native**

```tsx
import {useBluetooth} from '@glassly/bluetooth-sdk/react';

const glassly = useBluetooth();
```

React Native exposes `glassly.glasses.connection` as a discriminated union:

```ts
type GlassesConnectionStatus =
  | {state: 'disconnected'}
  | {state: 'scanning'}
  | {state: 'connecting'}
  | {state: 'bonding'}
  | {state: 'connected'; fullyBooted: boolean};
```

Use `glassly.glasses.connection.state` for link-layer progress. `fullyBooted` only exists when `state === 'connected'`. The hook exposes the React app state as `glasses`, `sdk`, and `scan`.

**Android**

```kotlin
val state = sdk.getState()
val glasses = sdk.getGlasses()
val sdkState = sdk.getSdkState()
val scan = sdk.getScanState()
```

Android exposes `GlassesRuntimeState` as `Connected` or `Disconnected`. The full state is grouped as `BluetoothState(glasses, sdk, scan)`.

**iOS**

```swift
let state = sdk.state
let glasses = sdk.glasses
let sdkState = sdk.sdkState
let scan = sdk.scanState
```

iOS exposes `GlassesRuntimeState` as `.connected(...)` or `.disconnected(...)`. The full state is grouped as `BluetoothState(glasses, sdk, scan)`.

Status snapshots are safe to read at any time. For continuous subsystems, keep UI state derived from status callbacks or hook state. Request/response commands document their exact promise resolution and error criteria below.

Public status is grouped the same way across platforms:

| Field | Meaning |
| --- | --- |
| `glasses` | Connected-glasses runtime state. Includes connection/readiness, connected device identity, battery, firmware, Wi-Fi, hotspot, and signal metadata when connected, plus the `controllers` map (see [Controllers](#controllers)). |
| `sdk` | Phone-side SDK runtime state. Includes default device, gallery mode, microphone route, mic ranking, Wi-Fi scan results, scan activity, system mic availability, other Bluetooth audio status, and recent SDK log lines. |
| `scan` | User-facing scan state. Includes whether a scan is active (for glasses or a controller model) and the stable-order discovered `Device[]` list. |

Use `glasses.connected` / `glassly.glasses.connected` before reading connected-only fields. Native Android uses `GlassesRuntimeState.Connected`; native iOS uses `GlassesRuntimeState.connected(...)`; React Native exposes `glassly.glasses` with the same grouped concepts in React-friendly objects.

### Controllers

Controllers (the Even Realities R1 ring, the Meta Neural Band, the IINE Gamebrick and Ananke Gen 2 gamepads running their Glassly firmware patches, an Apple Watch running the Glassly watch app on iOS, and a Wear OS watch running the Glassly Wear OS app on Android) link to the phone on their own, and several can be connected at once, including two of the same model. Each physical device has a **controller id** that stays the same while it is paired: the R1's ring id from its Bluetooth name (for example `CEC5BA`), the band's and both gamepads' peripheral identifier on iOS or Bluetooth address on Android, and a watch's UUID that its watch app mints on first launch. The Gamebrick needs its firmware flashed once over USB from a computer (`tetramo-labs/glassly-gamebrick-mini-cfw`); a unit on stock firmware is listed by the scan but cannot finish pairing. A factory-reset band gets a new id and is paired again. A watch links over WatchConnectivity (iOS) or the Wearable Data Layer (Android) rather than Bluetooth scanning: it counts as connected while it is the phone's paired watch with the app installed, and sends input only while the app is open on the wrist.

The Ananke Gen 2 needs [Glassly Ananke CFW](https://github.com/tetramo-labs/glassly-ananke-cfw), then **Pair + D-pad Right** for HID BLE pairing inside Glassly. It uses the observed eight-byte AE42 v2 stream; the SDK reports ready only after a valid packet. Previous system-gamepad records must be forgotten and paired again. Actual iPhone background/locked delivery remains under hardware validation.

`PublicGlassesStatus.controllers` is a `Record<string, ControllerStatus>` keyed by controller id. An entry exists only while the SDK has a driver for that controller (connecting, connected, or disconnecting); a paired controller that is idle has no entry. It replaces the single-controller `controllerConnected`, `controllerFullyBooted`, `controllerMacAddress`, `controllerBatteryLevel`, and `controllerSignalStrength` fields.

| `ControllerStatus` field | Meaning |
| --- | --- |
| `id`, `model`, `name` | Controller id, model (`"Even Realities R1"`, `"Meta Neural Band"`, `"Apple Watch"`, `"Wear OS Watch"`, `"IINE Gamebrick"`, `"IINE Ananke Gen 2"`), and display name (the R1's ring id, the band's Bluetooth name, the watch's name, `Gamebrick` plus the last four digits of the gamepad's id). |
| `connected` | The Bluetooth link is up. |
| `fullyBooted` | Delivering input: the R1's route is applied, or the band's claim is done. |
| `searching` | Scanning or connecting for this controller. |
| `batteryLevel`, `charging` | Battery percent (`-1` unknown) and charging flag. |
| `macAddress` | R1 only: the ring MAC the G2 needs to link it; `""` otherwise. |
| `signalStrength` | RSSI, `-1` unknown. |

The G2's own report of the ring it hosts stays in `ringConnected`, `ringBatteryLevel`, `ringCharging`, and `ringSignalStrength`.

## React Native Public Surface

These are the supported React Native app developer entrypoints:

| Area | Methods |
| --- | --- |
| Status and subscriptions | `useBluetooth`, `useBluetoothScan`, and `useBluetoothEvent` for React components; `addListener` is available as the lower-level non-React subscription API |
| Default device | `getDefaultDevice`, `setDefaultDevice`, `clearDefaultDevice` |
| Connection | `scan`, `startScan`, `stopScan`, `connect`, `connectDefault`, `cancelConnectionAttempt`, `disconnect`, `forget` |
| Wi-Fi and hotspot | `requestWifiScan`, `sendWifiCredentials`, `forgetWifiNetwork`, `setHotspotState` |
| Camera and gallery | `requestPhoto`, `warmUpCamera`, `stopCameraWarmUp`, `queryGalleryStatus`, `setGalleryModeEnabled`, `setPhotoCaptureDefaults` (deprecated), `setVideoRecordingDefaults`, `setMaxVideoRecordingDuration`, `setCameraFov`, `setCameraFovOverride`, `releaseCameraFovOverride`, `startVideoRecording`, `stopVideoRecording`, `queryVideoRecordingStatus` |
| Streaming | `startStream`, `stopStream` |
| Audio | `setMicState`, `setVoiceActivityDetectionEnabled`, `setLoudnessGateEnabled`, `setPreferredMic`, `setOwnAppAudioPlaying`, `getGlassesMediaVolume`, `setGlassesMediaVolume` |
| LED, version, and OTA | `rgbLedControl`, `requestVersionInfo`, `checkForOtaUpdate`, `startOtaUpdate` |

React Native helper exports include `DeviceModels`, `isConnectedGlassesConnectionStatus`, `isReadyGlassesConnectionStatus`, `isBusyGlassesConnectionStatus`, `isConnectedWifiStatus`, and `isEnabledHotspotStatus`. The React subpath exports `useBluetooth`, `useBluetoothScan`, and `useBluetoothEvent`, plus the `DefaultDeviceStorage` type for the `defaultDeviceStorage` option those hooks accept.

For React Native status UI, use `useBluetooth()` from `@glassly/bluetooth-sdk/react`. It returns `glassly.glasses`, `glassly.sdk`, and `glassly.scan` for connection, battery, Wi-Fi, hotspot, scan, and SDK runtime state.

Important defaults:

- `scan(model, options)` reports progressive results through `options.onResults`, resolves with the final matching `Device[]`, and times out after 15 seconds unless `options.timeoutMs` is set.
- `connect` and `connectDefault` default `saveAsDefault` and `cancelExistingConnectionAttempt` to `true`.
- `setMicState(enabled)` defaults to glasses microphone on, transcript events off, and LC3 events off. Microphone audio events are continuous while capture is enabled. Use `setVoiceActivityDetectionEnabled(...)` for glasses-side Voice Activity Detection and `setLoudnessGateEnabled(...)` for Mentra Live's center-microphone loudness gate ("Barrier"). With VAD disabled and Barrier enabled, quiet input is represented as silence while audio frames continue. The standalone public Bluetooth SDK defaults are VAD disabled and Barrier enabled, and both settings are reapplied after reconnect. The Glassly App manages separate persisted OS-level microphone preferences. `voice_activity_detection_status` reports whether VAD is enabled, and `speaking_status` reports speaking/not-speaking when supported. Microphone audio events include the latest `voiceActivityDetectionEnabled` value.
- `requestPhoto({authToken, ...})` omits the `Authorization` header when `authToken` is `null` or empty.
- `requestPhoto(...)` and `warmUpCamera(...)` generate unique request IDs when `requestId` is omitted or blank. Pass an explicit `requestId` only when your app needs to know it before the response, for example to poll a predictable upload-status URL.
- `requestPhoto({exposureTimeNs, ...})` uses auto exposure when `exposureTimeNs` is omitted or `null`; pass a positive nanosecond value for one-shot manual exposure.
- `requestPhoto({exposureTimeNs, iso, ...})` uses `iso` only when `exposureTimeNs` enables one-shot manual exposure. Omit `iso` / pass `null` for auto ISO selection.
- `requestPhoto(...)` capture fields apply to that one request. `setPhotoCaptureDefaults(...)` is deprecated; it still persists gallery-mode action-button photo defaults, but prefer per-request `requestPhoto(...)` options (e.g. `mode: "text"`) instead.
- `warmUpCamera({requestId, size, exposureTimeNs, durationMs})` opens/configures Mentra Live's camera and holds it warm without capturing or uploading media. Holds default to 15 seconds and are capped at 60 seconds. Use an explicit request ID when the owner may need to call `stopCameraWarmUp(requestId)` during teardown. The promise resolves on `camera_status.state === "ready"`; the later `stopped` event marks lease expiry/teardown for listeners and does not settle the already-resolved promise.
- Request/response commands now resolve from the glasses response rather than only updating local SDK state. React Native returns success-only values for commands whose raw events can also carry errors: `requestPhoto(...)` returns terminal `PhotoSuccessResponseEvent` after capture and delivery finish, `startVideoRecording(...)` returns `VideoRecordingStartedStatusEvent`, `stopVideoRecording(...)` returns `VideoRecordingStoppedStatusEvent`, and `rgbLedControl(...)` returns `RgbLedControlSuccessResponseEvent`. When `stopVideoRecording(...)` includes a webhook URL, the promise resolves after the video upload succeeds. The corresponding raw events still include error variants for listeners.
- `setCameraFov({fov, roiPosition})` clamps `fov` to 62-118 degrees and accepts `roiPosition` as `"center"`, `"bottom"`, or `"top"`. You can also call `setCameraFov({preset: "narrow" | "standard" | "wide"})`; presets map to 82, 102, and 118 degrees with center ROI. On Mentra Live this persists the setting, restarts the camera, and resolves with `CameraFovResult` only after the ASG client reports the setting was applied to camera hardware after the restart cooldown. The promise rejects if the glasses report an error, persist the setting without hardware application, or time out. Treat FOV as a framing/ROI control; output resolution and effective detail can vary by capture path, firmware, and camera mode.
- `startStream` optional `video` and `audio` configs are omitted unless supplied, so the connected glasses use their model defaults. Stream video input fields are `width`, `height`, `bitrate`, and `fps`; stream status reports the resolved effective frame rate as `resolvedConfig.video.fps`. The SDK sends stream keep-alives automatically and reports timeout/error state through `stream_status`.
- Photo capture, video recording, and streaming always enable the camera light as a privacy indicator.
- The SDK sends `set_system_time` once shortly after each glasses connection becomes ready, after the initial command burst has drained. The guard resets on disconnect, so reconnecting synchronizes again. There is no periodic clock correction during a long-lived connection; compare `requestVersionInfo().systemTimeMs` with the phone clock if your app needs to monitor later skew.

## Promise Results And Errors

One-shot commands resolve only after the matching ASG client response arrives. They reject/throw when the ASG response is an error, when the SDK cannot send the command, when an incompatible command is already in flight, or when the matching response times out. Keep listeners for streaming progress and status; use the returned value for the one-shot decision.

React Native exposes the narrowest return types for clear branching after `await`. Android and iOS async APIs throw `BluetoothSdkException` / `BluetoothSdkError` for the same error cases, so successful calls return the success payload even when the native event struct can also represent raw listener errors.

| API | Resolves With | Rejection / Throw Criteria |
| --- | --- | --- |
| `requestWifiScan()` | Final `WifiSearchResult[]` from `wifi_scan_result` where `scanComplete: true`, including `[]` when no networks are found. | Scan response timeout, send failure, or another Wi-Fi scan already in flight. |
| `sendWifiCredentials(ssid, password)` | `WifiStatusChangeEvent` whose state is `connected` for the requested SSID. Success typically resolves within a few seconds. | Glasses-reported provisioning failure, with the reason as the error code: `wrong_password` (typically ~7s), `connect_timeout` (~12s, network unreachable or join never completed), or `connected_to_other_network` (the glasses ended up on a different SSID than requested). Also request timeout, send failure, or another Wi-Fi status command in flight. Routine `disconnected` events during association do **not** reject — the glasses briefly report disconnected while switching networks. Glasses running older software never send failure reasons; failed attempts there surface as request timeouts. |
| `forgetWifiNetwork(ssid)` | `WifiStatusChangeEvent` once the requested SSID is no longer connected. | Timeout, send failure, or another Wi-Fi status command in flight. |
| `setHotspotState(enabled)` | `HotspotStatusChangeEvent` matching the requested enabled/disabled state. | `hotspot_error`, timeout, send failure, or another hotspot command in flight. |
| `requestVersionInfo()` | `VersionInfoResult` from the ASG `version_info` response. | Timeout, send failure, or another version query in flight. |
| Gallery capture settings | `SettingsAckSuccessEvent` with a non-failure status such as `applied` or `ready`; the SDK local settings store updates only after this ASG ack resolves. | `settings_ack.status` of `error`, `failed`, `failure`, or `rejected`; timeout; or send failure. |
| `setCameraFov(...)` | `CameraFovResult` with `fov`, `roiPosition`, `requestId`, and `timestamp` after the ASG client reports the setting was applied to camera hardware after the restart cooldown; the SDK local FOV setting updates only after this result resolves. | Glasses-side FOV/settings error, persist-only/no hardware-application ack, timeout, or send failure. |
| `queryGalleryStatus()` | `GalleryStatusEvent`, including `cameraBusy` and optional `cameraBusyReason`. | Timeout, send failure, or another gallery status query in flight. |
| `requestPhoto(...)` | Terminal response after capture and delivery finish: React Native `PhotoSuccessResponseEvent`; Android/iOS successful `PhotoResponseEvent`. The success includes `uploadUrl`, and may include webhook-returned `photoUrl`, `statusUrl`, `contentType`, or `fileSizeBytes`. Progress follows through `photo_status`. | Raw `photo_response.state === "error"` from glasses/phone, fallback upload failure, terminal response timeout, or send failure. |
| `warmUpCamera(...)` | `CameraStatusEvent` whose `state` is `ready`, meaning the camera is open/configured and held warm for the requested TTL. Progress follows through `camera_status`; `stopped` is a listener-only lifecycle event after `ready`. | `camera_status.state === "error"` such as `camera_busy`, `camera_restart_cooldown`, `photo_capture_in_progress`, `ble_transfer_in_progress`, `media_capture_service_unavailable`, or `camera_warm_up_failed`; timeout; or send failure. |
| `startVideoRecording(...)` | React Native `VideoRecordingStartedStatusEvent` with `status: "recording_started"`; Android/iOS successful `VideoRecordingStatusEvent` with `status: "recording_started"`. | `success: false` statuses such as `already_recording`, timeout, send failure, or duplicate request ID. |
| `stopVideoRecording(requestId, webhookUrl?, authToken?)` | React Native `VideoRecordingStoppedStatusEvent` with `status: "recording_stopped"`; Android/iOS successful `VideoRecordingStatusEvent` with `status: "recording_stopped"`. When `webhookUrl` is supplied, the promise waits for the video upload to finish successfully. | `success: false` statuses such as `not_recording`, video upload failure, timeout, send failure, or duplicate request ID. |
| `queryVideoRecordingStatus(requestId)` | `VideoRecordingStatusEvent` with `status: "recording_status"`, the current `data.recording` value, and elapsed `data.duration_ms` when available. | Disconnected glasses, timeout, send failure, or a duplicate video request ID. |
| `startStream(...)` | `StreamStatusEvent` for the requested stream once `status` is `streaming`. | `stream_status` error/reconnect failure, timeout, or send failure. |
| `stopStream()` | `StreamStatusEvent` once `status` is `stopped`; an already-stopped / not-streaming glasses reply resolves as a normalized stopped event. | Real stop error, timeout, send failure, or another stream stop in flight. |
| `rgbLedControl(...)` | React Native `RgbLedControlSuccessResponseEvent`; Android/iOS successful `RgbLedControlResponseEvent`. | Raw `rgb_led_control_response.state === "error"`, timeout, or send failure. |
| `checkForOtaUpdate()` | `boolean`, true when the configured OTA manifest has an ASG APK, MTK, or BES update for the connected glasses; false only when the manifest was checked successfully and no update is available. | Rejects when the glasses are disconnected, version info is unavailable, the manifest cannot be fetched, or the manifest response is invalid/missing required ASG app version fields. |
| `startOtaUpdate()` | `OtaStartAckEvent` from `ota_start_ack`. | Known glasses battery below 5% (`battery_low` before ack), start-ack timeout, send failure, or another OTA start in flight. |

## Gallery Mode

Mentra Live has a gallery mode for the right action button. When gallery mode is enabled, a short press takes a photo, a long press starts video recording, and a short press stops the active video recording. Button and touch events are still reported to the SDK.

Use `setGalleryModeEnabled(true)` to enable local button capture, and `setGalleryModeEnabled(false)` to report button events without triggering local gallery capture while the glasses are connected. These setting calls return `SettingsAckSuccessEvent` from the ASG client and reject on failure statuses. Raw `settings_ack` listeners still receive `SettingsAckEvent` because listener events can include both success and failure statuses. The SDK can also configure the capture settings used by gallery mode:

| Setting | API |
| --- | --- |
| Photo capture defaults (deprecated) | `setPhotoCaptureDefaults(...)` — prefer per-request `requestPhoto(...)` |
| Video resolution and frame rate | `setVideoRecordingDefaults({width, height, fps})` |
| Maximum local video length | `setMaxVideoRecordingDuration(minutes)` |
| Camera field of view | `setCameraFov(...)` |

`requestPhoto(...)` accepts optional `requestId` plus `size`, `mode`, `transferMethod`, `webhookUrl`, `authToken`, `compress`, `save`, `sound`, `exposureTimeNs`, `iso`, `aeExposureDivisor`, `isoCap`, `zsl`, `mfnr`, `noiseReduction`, `edgeEnhancement`, `ispDigitalGain`, and `ispAnalogGain`. ZSL buffering and MFNR still capture are independent flags, both enabled by default; pass `zsl: false` and/or `mfnr: false` to opt out. Photo, video, and stream capture always enable the camera light as a privacy indicator. Manual `iso` is used only when `exposureTimeNs` enables manual exposure.

| `requestPhoto` field | Values | Meaning |
| --- | --- | --- |
| `mode` | `photo` (default), `text` | `text` selects the text sensor size and crop for documents and barcodes. |
| `transferMethod` | `auto` (default), `direct`, `ble` | `direct` disables BLE fallback; `ble` skips the direct upload and forces phone-relayed transfer. |

`warmUpCamera(...)` accepts optional `requestId` plus `size`, `mode`, `exposureTimeNs`, `durationMs`, `zsl`, and `mfnr`. In React Native, omitting `durationMs` or passing a non-positive value takes the default 15 second warm hold; the Android and iOS native APIs take `durationMs` as a required argument. Values above 60 seconds are capped. `mode` matches the `requestPhoto` values, and `zsl` / `mfnr` configure the warm-up session the same way they configure a capture — keep them the same as the photo you intend to take, since a different configuration forces the camera to reconfigure. `camera_status` reports `warming`, `ready`, `stopped`, or `error`; the method resolves on `ready` and rejects on `error`. Call `stopCameraWarmUp(requestId)` to release a known lease. Cancelling before `ready` rejects the pending warm-up with `camera_warm_up_cancelled`; cancelling after `ready` emits `stopped`. Compatible ready leases share the camera and expire independently.

### Camera FOV Leases

`setCameraFov(...)` persists the field of view. `setCameraFovOverride(...)` takes the same `{fov, roiPosition}` or `{preset}` request plus two lease fields, and applies the FOV only for as long as the lease is held:

| Field | Meaning |
| --- | --- |
| `leaseId` | Phone-owned identifier for this override. Pass the same id to `releaseCameraFovOverride(leaseId)` so a delayed release cannot revert an override some later owner installed. |
| `ttlMs` | Optional safety expiry. Re-sending the same `leaseId` with the same configuration refreshes the TTL without restarting the camera. |

Use an override for a temporary framing change, such as a scan mode, and release it when that mode exits. `releaseCameraFovOverride(leaseId)` resolves with `SettingsAckSuccessEvent`.

`setPhotoCaptureDefaults(...)` is **deprecated**. It still accepts `size`, `zsl`, `mfnr`, `noiseReduction`, `edgeEnhancement`, `ispDigitalGain`, `ispAnalogGain`, `aeExposureDivisor`, `isoCap`, `compress`, `sound`, and `resetCaptureTuning`, but prefer per-request `requestPhoto(...)` options (for example `mode: "text"` for text sensor size/crop, or explicit `aeExposureDivisor`) instead of sticky button-photo presets. Its independent `zsl` and `mfnr` values are persisted for physical camera-button photos; when either is omitted, that field inherits the corresponding global device default. Omitted fields leave existing action-button photo defaults unchanged. `resetCaptureTuning: true` clears the optional action-button tuning overrides without changing global ZSL/MFNR settings or photo size unless `size` is also provided.

## Common Commands

| Area | Commands |
| --- | --- |
| Connection | `scan`, `startScan`, `stopScan`, `connect`, `connectDefault`, `disconnect`, `forget` |
| Wi-Fi and hotspot | `requestWifiScan`, `sendWifiCredentials`, `forgetWifiNetwork`, `setHotspotState` |
| Camera | `requestPhoto`, gallery mode, photo capture defaults, video recording defaults, camera field of view |
| Streaming | `startStream`, `stopStream` |
| Audio | `setMicState`, Voice Activity Detection setting and events, audio callbacks, local transcription, media volume |
| Settings | Gallery mode, camera options, microphone route, Wi-Fi, hotspot, and OTA |
| LEDs | `rgbLedControl` on supported glasses |
| System | `requestVersionInfo`, `checkForOtaUpdate`, `startOtaUpdate` |

Mentra Live has camera, microphone, speaker, Wi-Fi, LED, and OTA capabilities. Gate UI by connection readiness, permissions, and the latest SDK status.

## Additional Methods

These are also on the public surface. Most are model-specific; a call that the connected driver has no surface for rejects rather than silently succeeding.

### Status Subscriptions

| Method | Purpose |
| --- | --- |
| `getGlassesStatus(): Promise<PublicGlassesStatus>` | Read an immutable snapshot of the current glasses state. |
| `getBluetoothStatus(): Promise<PublicBluetoothStatus>` | Read an immutable snapshot of the phone Bluetooth adapter state. |
| `subscribeGlassesStatus(listener): () => void` | Observe immutable glasses-state patches. Returns an unsubscribe function. |
| `subscribeBluetoothStatus(listener): () => void` | Observe immutable Bluetooth-state patches. Returns an unsubscribe function. |

### Display And Dashboard

| Method | Purpose |
| --- | --- |
| `displayText(text, x?, y?, size?): Promise<void>` | Draw text on the glasses display. |
| `clearDisplay(): Promise<void>` | Clear the glasses display. |
| `showDashboard(): Promise<void>` | Show the glasses' built-in dashboard. |
| `setDashboardPosition(height, depth): Promise<void>` | Set the dashboard's on-screen height and depth. |
| `setHeadUpAngle(angleDegrees): Promise<void>` | Set the head-up activation angle (default 45°). The G2 driver also turns on the firmware's head-up switch, which the Glassly CFW needs before it reports head position, and sends both again on every connect. |
| `setImuEnabled(enabled): Promise<void>` | Enable or disable the glasses IMU. |
| `setScreenDisabled(disabled): Promise<void>` | Turn the glasses display off without disconnecting. |

### Notifications

| Method | Purpose |
| --- | --- |
| `setGlassesNotificationConfig(config): Promise<void>` | Apply on-glass notification behaviour. Rejects when no glasses are connected or the connected driver has no firmware notification surface. |
| `getGlassesNotificationStatus(): Promise<GlassesNotificationStatus>` | Read whether the surface is supported, which feed it uses, wearer consent, the applied config, and the current phase. |
| `showNativeNotificationPanel(): Promise<void>` | Open the glasses' built-in notification panel (the same effect as the wearer saying "Hey Even, show notifications"). G2 only; a no-op elsewhere. |

`GlassesNotificationConfig` carries `enabled` (master switch), `popups` and `popupSeconds` (0 lets the firmware choose), `holdDuringApps` (hold popups while another glasses feature is on screen), `blockedApps`, and `allowedApps` for firmware whose filter is an allowlist. Filtering is off whenever `blockedApps` is empty.

The G2 and the RayNeo iO have this surface. Their status `feed` is `ancs` when the glasses read the iPhone's notifications themselves: the G2 on iOS, and the RayNeo iO on iOS once it runs the Glassly CFW. The wearer allows this with **Share System Notifications** for the glasses in iOS Bluetooth settings; the G2 reports the answer in `access` (`granted` or `denied`), the RayNeo iO as `unknown`. Otherwise `feed` is `phone_upload`: the phone sends each notification to the glasses.

### System And Connection

| Method | Purpose |
| --- | --- |
| `ping(): Promise<void>` | Keep legacy Mentra Live OTA sessions awake. Modern sessions normally do not require this. |
| `setSystemTime(timestampMs): Promise<void>` | Set the glasses clock from the phone after an OTA clock-skew failure. |
| `setWifiAdbState(enabled): Promise<void>` | Enable or disable Wi-Fi ADB on Mentra Live. A no-op on other devices. |
| `setPreferredMic(preferredMic): Promise<void>` | Choose the microphone route: `auto`, `phone`, `glasses`, or `bluetooth`. |
| `setOwnAppAudioPlaying(playing): Promise<void>` | Tell the SDK your app is playing audio so it can arbitrate the audio route. |
| `setCameraTuningConfig(anrOn, gainOn): Promise<SettingsAckSuccessEvent>` | Configure Mentra Live camera HAL tuning (ANR / gain) without a reboot. By convention, `(false, false)` when activating scan mode for sharper text and barcode captures, `(true, true)` to restore defaults. |
| `setLegacyCameraFov(request): Promise<CameraFovResult>` | One-way FOV command for legacy ASG clients that do not send settings acknowledgements. |

### Firmware Flash

Glasses that ship a bundled Glassly custom firmware (Even Realities G1 and G2, RayNeo iO)
can be flashed over BLE from the app. The SDK routes these calls to the connected
glasses' driver.

| Method | Purpose |
| --- | --- |
| `availableFirmwareArtifacts(): Promise<FirmwareArtifact[]>` | List the firmware images bundled for the connected model, each with `id` (`stock` or `glassly-cfw`), `displayName`, `version`, `fileName`, `sha256`, and `size`. |
| `startFirmwareFlash(target): Promise<FirmwareFlashResult>` | Flash one of those images. `target` is `stock` or `glassly-cfw`. Progress arrives through `firmware_flash_progress`. Resolves with `ok`, `target`, and the flashed artifact's `version` and `sha256`; on the RayNeo iO that happens only after the glasses reboot and reconnect. |

Keep the app in the foreground and the phone next to the glasses until the promise settles. The RayNeo iO refuses to flash below 50% glasses battery. The G1 is flashed one temple at a time over MCUmgr SMP (about four minutes each); both temples then restart and take about two minutes to reconnect. Its `stock` target is the vendor's 1.6.3 application (the network core is never touched), while the Glassly CFW is built on the 1.5.60 application and identifies as `1.5.60 (Glassly CFW v37)`.

The glasses status carries `firmwareUpdateAvailable: true` while the connected glasses run stock firmware or a Glassly CFW revision older than the one the SDK bundles. It clears when the connection resets.

### G2 Firmware Flash (legacy aliases)

| Method | Purpose |
| --- | --- |
| `availableG2FirmwareArtifacts(): Promise<G2FirmwareArtifact[]>` | Alias of `availableFirmwareArtifacts()`, kept for apps written against the G2-only API. |
| `startG2FirmwareFlash(target): Promise<G2FirmwareFlashResult>` | Alias of `startFirmwareFlash(target)`. Progress also arrives through `g2_firmware_flash_progress`. |

### AR99 OTA

| Method | Purpose |
| --- | --- |
| `startAr99OtaFromFile(path): Promise<boolean>` | Start an Ar99 OTA from a local firmware file. Progress arrives through `ar99_ota_status`. |
| `cancelAr99Ota(): Promise<void>` | Cancel the running Ar99 OTA. |
| `sendAr99FactoryReset(): Promise<void>` | Send the Ar99 factory-reset command. |
| `buildAr99OtaSignature(secret, appName, currentVersion, serialNumber, nonce): string` | Build the signature the Ar99 update server expects. Synchronous. |

### OTA Manifest

| Method | Purpose |
| --- | --- |
| `setOtaVersionUrl(otaVersionUrl): void` | Select the OTA manifest used by subsequent update checks and installs. The URL may point at Glassly's hosted manifest or any customer-controlled HTTP(S) server. |
| `getOtaVersionUrl(): string` | Return the configured or release-embedded manifest URL. Rejects when a source build is unconfigured. |
| `getReleaseChangelogs(fromVersion?, toVersion?): ReleaseChangelog[]` | Return bundled release changelogs crossed between two coordinated product versions, newest first. Synchronous. |

### STT And TTS Models

Speech model management is on the SDK surface today and is expected to move out of the Bluetooth SDK in a later release.

| Method | Purpose |
| --- | --- |
| `setSttModelDetails(path, languageCode): Promise<void>` | Point the local transcriber at a model directory and language. |
| `getSttModelPath(): Promise<string>` | Return the configured STT model path. |
| `checkSttModelAvailable(): Promise<boolean>` | Whether an STT model is present on the phone. |
| `validateSttModel(path): Promise<boolean>` | Whether the files at `path` form a usable STT model. |
| `restartTranscriber(): Promise<void>` | Restart local transcription after a model change. |
| `extractTarBz2(sourcePath, destinationPath): Promise<boolean>` | Extract a downloaded model archive. Progress arrives through `extraction_progress`. |
| `getOfflineTranslationLanguages(source): Promise<OfflineTranslationLanguage[]>` | iOS 26+. Languages `source` can be translated into on-device, each with its install status. |
| `getOfflineTranslationStatus(source, target): Promise<OfflineTranslationStatus>` | iOS 26+. `installed`, `supported` (downloadable), `unsupported`, or `unavailable`. |
| `downloadOfflineTranslation(source, target): Promise<OfflineTranslationStatus>` | iOS 26+. Show the system prompt that downloads a language pair, then return its status. |
| `translateOffline(text, source, target): Promise<string>` | iOS 26+. Translate text on-device. Rejects with `not_installed` when the pair is not downloaded. |
| `setTtsModelDetails(path, languageCode): Promise<void>` | Point TTS at a model directory and language. |
| `getTtsModelPath(): Promise<string>` | Return the configured TTS model path. |
| `getTtsModelLanguage(): Promise<string>` | Return the configured TTS language code. |
| `checkTtsModelAvailable(): Promise<boolean>` | Whether a TTS model is present on the phone. |
| `validateTtsModel(path): Promise<boolean>` | Whether the files at `path` form a usable TTS model. |
| `generateTtsAudio(text, modelPath, outputPath, speakerId, speed): Promise<boolean>` | Synthesize `text` to an audio file at `outputPath`. |

## OTA Updates

Each Bluetooth SDK release has a matching Mentra Live glasses software release with the same version number. When your app checks for an update, the SDK uses the OTA manifest for its own release. For the current `0.4.2` software and complete installation instructions, see [Update Mentra Live](https://docs.glassly.ai/bluetooth-sdk/software-update.md).

For React Native apps, use Glassly Engine instead of assembling these primitives
yourself. `MentraLiveOtaFlow` supplies the exact Glassly App pages, and
`useMentraLiveOta` supports custom presentation over the same tested
coordinator. See [Update Mentra Live](https://docs.glassly.ai/bluetooth-sdk/software-update.md#add-the-ota-requirement-to-your-app).

The APIs below are low-level building blocks used by native Android/iOS apps
and by Glassly Engine. They are not a second React Native OTA coordinator.

Mentra Live OTA installation is glasses-owned. The SDK checks its release-specific manifest on the phone, then sends `ota_start` with that same manifest URL when the user accepts the update:

| API | Purpose |
| --- | --- |
| `checkForOtaUpdate()` | Fetch the configured manifest and resolve `true` when an ASG APK, MTK, or BES update is available. |
| `startOtaUpdate()` | Send `ota_start` with the configured manifest URL after your app presents the update and the user accepts it. Resolves with `OtaStartAckEvent` from the ASG client. |
| `queryOtaStatus()` | Query and return the active OTA session status after a reconnect or interrupted response. React Native only. |

Use the boolean check result for update prompts and keep `ota_status` listeners/delegates for install progress and terminal `complete` / `failed` state. Availability is exposed through `checkForOtaUpdate()` rather than a public event; React Native receives `ota_start_ack` and `ota_status` events during the install flow. Android listeners receive `onOtaStartAck` and `onOtaStatus`; iOS delegates receive `.otaStartAck` and `.otaStatus` through `BluetoothEvent`.

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`.

Treat `complete` as terminal even though the connection may drop immediately after it: when the final step of an update is the BES firmware, the glasses power-cycle right after emitting `complete`, so no further `ota_status` follows. If the BES firmware transfer step stalls on the glasses side, it aborts itself after about 30 seconds and surfaces as `failed`; the APK and MTK steps use their own timeout paths. On such an abort the BES stays on its current firmware — earlier APK or MTK steps of the same update may already have completed — and retrying the whole update from the app is the intended recovery.

## Events

React Native components should use `useBluetoothEvent()` for hardware events. The hook keeps the callback typed and removes the native subscription when the component unmounts. Native apps receive the same event categories through listener/delegate methods:

**React Native**

```tsx
import {useBluetoothEvent} from '@glassly/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('stream_status', (event) => console.log(event.resolvedConfig?.video?.fps));
  useBluetoothEvent('ota_status', (event) => console.log(event.overall_percent));
  useBluetoothEvent('speaking_status', (event) => console.log(event.speaking));
  useBluetoothEvent('mic_pcm', (event) => {
    console.log(event.sampleRate, event.bitsPerSample, event.channels, event.encoding);
    console.log(event.pcm);
  });

  return null;
}
```

**Android**

```kotlin
class GlassesEvents : BluetoothSdkCallback() {
    override fun onButtonPress(event: ButtonPressEvent) {
        Log.d("Glassly", "${event.buttonId} ${event.pressType}")
    }

    override fun onPhotoResponse(event: PhotoResponseEvent) {
        Log.d("Glassly", "Photo request ${event.requestId}: ${event.response.state}")
    }

    override fun onMicPcm(event: MicPcmEvent) {
        Log.d("Glassly", "${event.sampleRate} Hz ${event.bitsPerSample}-bit PCM")
    }

    override fun onOtaStatus(event: OtaStatusEvent) {
        Log.d("Glassly", "OTA ${event.status}: ${event.overallPercent}%")
    }
}
```

**iOS**

```swift
final class GlassesEvents: BluetoothSDKDelegate {
    func bluetoothSDK(_ sdk: BluetoothSDK, didReceive event: BluetoothEvent) {
        switch event {
        case let .buttonPress(button):
            print("\(button.buttonId) \(button.pressType)")
        case let .photoResponse(photo):
            print("Photo request \(photo.requestId): \(photo.response.state.rawValue)")
        case let .otaStatus(status):
            print("OTA \(status.status): \(status.overallPercent)%")
        default:
            break
        }
    }

    func bluetoothSDK(_ sdk: BluetoothSDK, didReceiveMicPcm event: MicPcmEvent) {
        print("\(event.sampleRate) Hz \(event.bitsPerSample)-bit PCM")
    }
}
```

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.

The React Native event surface is typed through `BluetoothSdkEventMap`. These are the public event names accepted by `useBluetoothEvent()` and `BluetoothSdk.addListener()`:

| Event name | Payload type | When it fires |
| --- | --- | --- |
| `log` | `LogEvent` | SDK diagnostic log line. |
| `device_discovered` | `Device` | A supported glasses device is discovered during scan. |
| `default_device_changed` | `{device?: Device}` | The SDK default device changes. |
| `glasses_not_ready` | `GlassesNotReadyEvent` | A command needs ready glasses but the connected device is not ready. |
| `button_press` | `ButtonPressEvent` | Glasses button press. |
| `touch_event` | `TouchEvent` | Glasses or controller touch gesture, named by `gestureName`, with optional `source`, `index`, `controllerId`, and (on R1 slide steps) `distance` and `speed`. See [Touch Gestures](#touch-gestures). |
| `keyboard_key` | `KeyboardKeyEvent` | Raw HID key transition (`page`, `usage`, `down`, `timestamp`) from a keyboard paired to G2 Glassly CFW glasses (revision 39+). |
| `keyboard_advert` | `KeyboardAdvertEvent` | An advertiser seen during `g2KeyboardScan()`. |
| `keyboard_pairing` | `KeyboardPairingEvent` | Keyboard pairing prompt: `passkey` (enter the keyboard's PIN), `display` (type `value` on the keyboard) or `compare` (confirm `value`). |
| `neural_band_claim` | `NeuralBandClaimEvent` | Progress of the one-time claim a Meta Neural Band goes through the first time it connects to this phone: `controllerId`, `stage` (`progress`, `completed`, `failed`), optional `message` and `bandName`, and `sessionExpired` when the saved Meta session was refused. |
| `neural_band_handwriting` | `NeuralBandHandwritingEvent` | A Neural Band's handwriting model, tagged with its `controllerId`: `kind: "state"` with the capture `phase`, or `kind: "text"` with the `text` written so far. |
| `neural_band_pointer` | `NeuralBandPointerEvent` | A Neural Band's air mouse, tagged with its `controllerId`: `kind: "move"` with `dx` / `dy` in degrees (right and down positive), or `kind: "buttons"` with the pinch bit mask in `buttons` (`1` index, `2` middle). |
| `accel_event` | `AccelEvent` | Glasses accelerometer sample with `x`, `y`, `z`, and `timestamp`. |
| `voice_activity_detection_status` | `VoiceActivityDetectionStatusEvent` | Glasses-side Voice Activity Detection is enabled or disabled. |
| `speaking_status` | `SpeakingStatusEvent` | Glasses-side Voice Activity Detection reports speaking or not speaking. |
| `battery_status` | `BatteryStatusEvent` | Battery update from glasses. |
| `local_transcription` | `LocalTranscriptionEvent` | SDK local transcription text update. |
| `wifi_status_change` | `WifiStatusChangeEvent` | Glasses Wi-Fi connection state changes. When the event is the verdict of a failed `sendWifiCredentials` attempt it carries an `error` reason (`wrong_password`, `connect_timeout`, `connected_to_other_network`); the reason describes the attempt, not the link, so `connected_to_other_network` arrives on a `connected` state. Routine link updates carry no `error`. |
| `wifi_scan_result` | `WifiScanResultEvent` | Wi-Fi scan results. Intermediate events can have `scanComplete: false`; the final event has `scanComplete: true` and is what `requestWifiScan()` awaits. |
| `version_info` | `VersionInfoEvent` | Glasses version metadata response. Also returned by `requestVersionInfo()`. |
| `hotspot_status_change` | `HotspotStatusChangeEvent` | Glasses hotspot state changes. |
| `hotspot_error` | `HotspotErrorEvent` | Hotspot operation fails. |
| `photo_response` | `PhotoResponseEvent` | Terminal photo result. Success means capture and webhook delivery completed; error means the glasses or phone rejected/failed the request. `requestPhoto(...)` resolves with the success case and rejects on the error case; progress follows through `photo_status`. |
| `photo_status` | `PhotoStatusEvent` | Photo capture progress changes. May include `resolvedConfig`, `requestedCaptureConfig`, `meteredPreview`, or `captureMetadata` depending on status. |
| `camera_status` | `CameraStatusEvent` | Camera warm-up lifecycle. `warmUpCamera(...)` resolves on `ready`, rejects on `error`, and listeners can observe `warming` and `stopped` progress. `stopped` is emitted after `ready` when the lease expires or the camera closes; pending warm-ups receive `error` instead if teardown happens before `ready`. |
| `video_recording_status` | `VideoRecordingStatusEvent` | Video recording start/stop succeeds or fails, or a status query reports `status: "recording_status"` with `data.recording`. `startVideoRecording(...)` resolves from `recording_started`; `stopVideoRecording(...)` resolves from `recording_stopped` unless a webhook upload was requested, in which case it waits for upload success. |
| `media_success` / `media_error` | `MediaUploadEvent` | Raw glasses media upload completion events. Video webhook stops use these events to resolve or reject the `stopVideoRecording(...)` promise after recording has stopped. |
| `gallery_status` | `GalleryStatusEvent` | Gallery content/camera-busy status changes. `cameraBusyReason` is included when the glasses report a busy camera reason such as `video` or `stream`. |
| `settings_ack` | `SettingsAckEvent` | Raw gallery/button/FOV setting acknowledgements from the glasses. Gallery and button setting methods return `SettingsAckSuccessEvent` and reject failure statuses; `setCameraFov(...)` resolves a friendlier `CameraFovResult` after the raw ack reports camera hardware application. |
| `compatible_glasses_search_stop` | `CompatibleGlassesSearchStopEvent` | Compatible-glasses search stops for a model. |
| `swipe_volume_status` | `SwipeVolumeStatusEvent` | Swipe-volume setting changes. |
| `switch_status` | `SwitchStatusEvent` | Glasses switch status changes. |
| `rgb_led_control_response` | `RgbLedControlResponseEvent` | RGB LED command succeeds or fails. `rgbLedControl(...)` resolves with the success case and rejects on the error case. |
| `glasses_notification_status` | `GlassesNotificationStatus` | The on-glass notification surface changes: whether the connected driver supports one, the feed it uses, wearer consent, the applied config, and the current phase. |
| `notification_upload_result` | `NotificationUploadResult` | Android: the outcome of one notification the phone uploaded to G2 glasses, as `notificationId`, `outcome` (`sent`, `failed`, `cancelled`, `dropped`), and `detail`. No notification content is attached. |
| `pair_failure` | `PairFailureEvent` | Bluetooth pairing fails. |
| `pairing_info` | `PairingInfoEvent` | Pairing metadata observed during a connection attempt: whether a bond already existed, the spoken pairing code, classic-bond readiness, and secure-pairing capability. |
| `entering_pairing_mode` | `EnteringPairingModeEvent` | The glasses enter pairing mode; `window_ms` is how long the window stays open. |
| `owner_replaced` | `OwnerReplacedEvent` | Another phone took ownership of the glasses, with the firmware-supplied `reason`. |
| `glasses_session_changed` | `GlassesSessionChangedEvent` | The glasses process restarted while the BES kept the BLE link alive (its `sid` changed). There is no physical disconnect, so treat this as the logical reconnect edge. |
| `audio_pairing_needed` | `AudioPairingNeededEvent` | The phone needs Bluetooth audio pairing for the device. |
| `audio_connected` | `AudioConnectedEvent` | Bluetooth audio connects. |
| `audio_disconnected` | `AudioDisconnectedEvent` | Bluetooth audio disconnects. |
| `mic_pcm` | `MicPcmEvent` | PCM microphone frame arrives. |
| `mic_lc3` | `MicLc3Event` | LC3 microphone frame arrives. |
| `mic_health` | `MicHealthEvent` | Native LC3 processing detects a `sequence_gap` or `decode_failure`. Includes cumulative current-connection counters and last LC3/PCM receipt timestamps. |
| `stream_status` | `StreamStatusEvent` | Camera stream lifecycle, reconnect, or error state changes. May include `resolvedConfig` with effective stream settings: encoded output size in `video.width` / `video.height`, native camera capture size in `video.captureWidth` / `video.captureHeight`, video bitrate and `fps`, plus audio bitrate, sample rate, echo cancellation, and noise suppression. |
| `ota_start_ack` | `OtaStartAckEvent` | Mentra Live acknowledges `startOtaUpdate()`. Also returned by `startOtaUpdate()`. |
| `ota_status` | `OtaStatusEvent` | OTA step, phase, status, progress, or error changes. |
| `mtk_update_complete` | `MtkUpdateCompleteEvent` | The Mentra Live MTK updater finished and the glasses are about to restart. |
| `ar99_ota_status` | `Ar99OtaStatusEvent` | Ar99 OTA progress: `phase`, `progress`, byte `offset` / `total`, and an error message on failure. |
| `firmware_flash_progress` | `FirmwareFlashProgressEvent` | Progress of `startFirmwareFlash(...)` on any model with a bundled Glassly CFW, with `message`, `progress` (0..1), and terminal `done` / `ok` flags. |
| `g2_firmware_flash_progress` | `G2FirmwareFlashProgressEvent` | Legacy alias of `firmware_flash_progress`, still emitted by the G2 driver. |
| `extraction_progress` | `ExtractionProgressEvent` | `extractTarBz2(...)` progress, as `percentage` plus `bytesRead` / `totalBytes`. |

Five type names used above — `CameraStatusEvent`, `MediaUploadEvent`,
`WarmUpCameraParams`, `VideoRecordingSettings`, and
`CameraFovOverrideRequest` — are not yet re-exported from
`@glassly/bluetooth-sdk`. They describe the payloads and parameters the SDK
really uses, but you cannot import them by name today; annotate with the
inferred types from the method signatures instead.

For request/response commands, prefer the returned value from the method, such as the `PhotoSuccessResponseEvent` returned by React Native `requestPhoto(...)` or the operation-specific video result returned by React Native `startVideoRecording(...)` / `stopVideoRecording(...)` / `queryVideoRecordingStatus(...)`. `requestPhoto(...)` waits for the terminal `photo_response`: it resolves after the photo is captured and delivered to the webhook, and rejects if the glasses reject the request, the phone-side fallback upload fails, or the terminal response times out. `stopVideoRecording(...)` keeps the same end-to-end shape for video webhook stops: it waits for recording stop plus upload success, and rejects on upload failure. Photo capture/upload/Bluetooth fallback progress follows through `photo_status`; raw video upload completion arrives through `media_success` and `media_error` for listeners that need the glasses event stream directly. Use event listeners for ongoing hardware streams and status updates: for example, `useBluetoothEvent('mic_pcm', ...)` receives a `MicPcmEvent`. `MicPcmEvent` includes `sampleRate`, `bitsPerSample`, `channels`, `encoding`, and `voiceActivityDetectionEnabled`; `MicLc3Event` includes `sampleRate`, `channels`, `encoding`, `frameDurationMs`, `frameSizeBytes`, `bitrate`, `packetizedFromGlasses`, and `voiceActivityDetectionEnabled`. `mic_health` reports native sequence/decode failures that cannot be reconstructed from PCM and includes `sequenceGapEvents`, `decodeFailures`, `lastLc3ReceivedAt`, and `lastPcmProducedAt`. `speaking_status` is separate from microphone audio frames so apps can use continuous audio while still reacting to speech activity.

Public 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 events expose `deviceModel` and `gestureName`, successful photo responses expose `uploadUrl` and may include webhook-returned `photoUrl`, `statusUrl`, `contentType`, and `fileSizeBytes`, successful media upload events expose `requestId`, `mediaUrl`, and `mediaType`, hotspot errors expose `errorMessage`, Wi-Fi scan events expose `scanComplete`, and gallery status exposes `hasContent`, `cameraBusy`, and optional `cameraBusyReason`.

### Touch Gestures

`touch_event.gestureName` is a string such as `single_tap`, `double_tap`, `long_press`, `swipe_up`, or `swipe_down`. Models add their own names, so handle the ones you know and ignore the rest. The G1 on Glassly CFW reports `single_tap`, `double_tap`, `triple_tap` and `long_press` from either temple's touch pad. Hardware that reports press edges brackets a held press with `tap_start` and `tap_end`, the pair to use for hold-to-talk.

Head position arrives on the same stream: `head_up` when the wearer looks up, `head_down` when the head comes back down. The G1, the Nimo, and the G2 on Glassly CFW report both; the G2 needs revision 45 or newer for `head_up` and 46 or newer for `head_down`, and reports them only while a Glassly page is on screen. Mentra Display reports only `head_up`. Glasses without head tracking stand in for it: on the Mach1 two or more taps toggle between the two, falling back to `head_down` after 15 seconds, and the RayNeo iO sends one `head_up` when its link comes up.

`source` marks controller input: `2` for the Even Realities R1 ring, `3` for the Meta Neural Band, `4` for a watch (Apple Watch or Wear OS), `5` for the IINE Gamebrick, `6` for the IINE Ananke Gen 2. `controllerId` names the device when several controllers are connected; it is absent for glasses input and for ring input the G2 relays when the SDK cannot tell which R1 it came from.

The R1 reports a slide once per step of travel, directly or relayed by a G2: each step is a `swipe_up` or `swipe_down` with `distance` (travel since the previous step, out of the ring's 200-unit touch span) and `speed` (smoothed, 0-255), between the press's `touch_down` and `tap_end`. Treat the first step of a press as the swipe. The Engine does this for miniapps: one swipe per press, plus `scroll_up` / `scroll_down` for every step.

The Gamebrick's D-pad sends one `swipe_up` / `swipe_down` / `swipe_left` / `swipe_right` per press, bracketed by `touch_down` and `tap_end` (no `tap_start`), all with `index` 12-15 for up, down, left, right. B sends `double_tap` on press, and A follows the band's hold-aware lifecycle: `touch_down` on press, `tap_start` once held 400 ms, `tap_end` on release, `single_tap` only after a quick press.

The Ananke preserves indexed controls: 0–3 A/B/X/Y, 4–7 L/R/ZL/ZR, 8–11 Minus/Plus/Capture/Home, 12–15 Up/Down/Left/Right. Every button emits `touch_down`, `tap_start` after 400 ms held and `tap_end` on release. Quick nondirectional releases also emit `single_tap` (B emits `double_tap` for back); directions additionally emit one indexed swipe on press. Packet loss or reconnect releases outstanding holds and establishes a baseline without replaying presses.

The band:

- sends `touch_down` and `tap_end` around every index- or middle-finger pinch, plus one `tap_start` once the pinch has been held for 400 ms;
- holds each `single_tap` for a 350 ms window and drops it when a second pinch of the same finger makes a `double_tap`;
- tags pinch gestures and their edges with `index` (`0` index finger, `1` middle), and also sends `swipe_left`, `swipe_right`, `dial_up`, and `dial_down`;
- ends a pinch still held when the band disconnects with its `tap_end`.

A watch (`source` `4`: an Apple Watch on iOS, a Wear OS watch on Android) sends `single_tap`, `double_tap`, and `long_press` from its screen, four-way `swipe_*` from screen swipes, `dial_up` / `dial_down` per Digital Crown detent or rotary bezel step, and on the Apple Watch `single_tap` for the Double Tap hand gesture. Every press is bracketed by `tap_start` on finger-down and `tap_end` on lift, like the temples, so hold-to-talk works from the watch. It sends no `index`. The watch's wrist-remote commands arrive on the `watch_command` event (`WatchCommandEvent`), and `watchAvailability()` reports whether a watch with the app is paired.

The Bluetooth SDK delivers the band's events but has no public methods for its one-time claim (which needs the wearer's Meta session), handwriting, or air mouse. Those live on the Engine's [`engine.glasses.neuralBand`](https://docs.glassly.ai/glasses-oems/engine.md#engine-glasses-neuralband); without them, `neural_band_claim` ends in `failed` on a band this phone has not claimed before.

### Photo Status Metadata

`PhotoStatusEvent` reports progress through capture and transfer. Capture metadata is attached to the stage where the glasses know that data:

| Status | Optional field | Description |
| --- | --- | --- |
| `configuring` | `resolvedConfig` | Effective JPEG dimensions, quality, requested size, source (`sdk` or `button`), transfer method, compression, and manual exposure fields when present. |
| `capturing` | `requestedCaptureConfig` | Camera2 still request values submitted to the HAL, such as exposure time, ISO, frame duration, AE mode, AE lock, exposure compensation, target FPS range, AF mode, and ZSL. |
| `capturing` | `meteredPreview` | Latest preview auto-exposure estimate before the still capture, including exposure time, ISO, and a light proxy when available. |
| `captured` | `captureMetadata` | Actual still capture result returned by the HAL, including applied exposure time, ISO, frame duration, AE state/name, noise reduction mode, edge mode, sensor timestamp, and MFNR hint when available. |

Transport statuses such as `uploading`, `compressing`, `ble_fallback_compression`, `ready_for_transfer`, and `transferring` describe upload or BLE 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. Apps should read actual capture values from `event.captureMetadata` on the `captured` status, not from upload statuses.

Local action-button photos emitted by the glasses use the same `photo_status` shape when the phone SDK is connected. Those local captures set `resolvedConfig.source` to `button` and `resolvedConfig.transferMethod` to `local`.

Android and iOS expose typed callbacks/delegate methods instead of the React Native string event API. Android uses `BluetoothSdkListener` methods such as `onStateChanged`, `onGlassesChanged`, `onSdkStateChanged`, `onScanChanged`, `onDeviceDiscovered`, `onButtonPress`, `onSpeakingStatus`, `onPhotoResponse`, `onPhotoStatus`, `onMicPcm`, `onMicHealth`, `onStreamStatus`, and `onOtaStatus`. iOS uses `BluetoothSDKDelegate` methods such as `bluetoothSDK(_:didUpdate:)`, `bluetoothSDK(_:didUpdateGlasses:)`, `bluetoothSDK(_:didUpdateSdkState:)`, `bluetoothSDK(_:didUpdateScan:)`, `bluetoothSDK(_:didDiscover:)`, `bluetoothSDK(_:didReceive:)`, `bluetoothSDK(_:didReceiveMicPcm:)`, and `bluetoothSDK(_:didReceiveMicLc3:)`; microphone health arrives through `didReceive` as `.micHealth`, while OTA install progress arrives as `.otaStartAck` or `.otaStatus`. Microphone audio callbacks use `MicPcmEvent` and `MicLc3Event` objects with the same metadata as React Native.

| Event area | Examples |
| --- | --- |
| Input | Button press, touch, swipe, head position |
| Device state | Battery, case, Wi-Fi, hotspot, connection, RSSI |
| Camera | Photo request result, camera warm-up state, gallery state, camera settings |
| Streaming | Stream initializing, active, stopped, error |
| OTA | Update available, start acknowledged, step/progress status |
| Audio | Microphone PCM, LC3, local transcription, audio route state |
| Diagnostics | SDK log events |

## Version Fields

Call `requestVersionInfo()` after connection when your app wants the glasses to refresh version metadata. Updated values arrive through the normal glasses-status callback and are also available in the next status snapshot.

| Field | Meaning |
| --- | --- |
| `firmwareVersion` | Generic glasses firmware version when the connected model reports one. |
| `deviceFirmwareVersion` | Device firmware version for models that report device info as a structured payload. |
| `leftFirmwareVersion` / `rightFirmwareVersion` | Per-side firmware versions for glasses that report left/right firmware separately. |
| `besFirmwareVersion` | Mentra Live BES firmware version. |
| `mtkFirmwareVersion` | Mentra Live MTK/system OTA firmware version. |
| `appVersion` | Glasses-side companion app version. On Mentra Live this is the ASG client APK version, not firmware. |
| `androidVersion` | Android OS version on Android-based glasses. This is not firmware. |

Different glasses models expose different version fields, so apps should prefer the generic firmware field when present, then fall back to model-specific firmware fields. Keep app and OS versions visibly labeled as app/OS versions.
