# Air-Gapped Bluetooth SDK Deployment

> Run the Glassly Bluetooth SDK and Mentra Live OTA updates without access to Glassly-hosted runtime services.

Source: https://docs.dev.glassly.ai/bluetooth-sdk/air-gapped-deployment/

The Glassly Bluetooth SDK can run inside a disconnected or restricted network. Your
mobile app communicates with Mentra Live over Bluetooth, and you can disable Glassly
SDK analytics and host the complete Mentra Live update set on your own network.

This guide covers a standalone Bluetooth SDK deployment. It does not require Glassly
Core, the Glassly App, or Glassly-hosted runtime services. Any network destinations
added by your own mobile app, such as photo webhooks or streaming endpoints, remain
your responsibility.

## Understand The Release Set

Glassly publishes coordinated releases. One release identity, such as `X.Y.Z` or
`X.Y.Z-beta.N`, identifies all of the components tested together:

| Component                | Coordinate or asset                                |
| ------------------------ | -------------------------------------------------- |
| React Native / Expo SDK  | `@glassly/bluetooth-sdk@<release-identity>`         |
| Android SDK              | `ai.glassly:bluetooth-sdk:<release-identity>` |
| iOS SDK                  | SwiftPM tag `<release-identity>`                   |
| Hosted OTA manifest      | Recorded in the completed release record           |
| Self-hosted OTA bundle   | Recorded in the completed release record           |
| Completed release record | `glassly-release-<release-identity>.json`           |

Each release has its own GitHub page:

```text
https://github.com/tetramo-labs/glassly/releases/tag/glassly-v<release-identity>
```

For example, release `3.1.0-beta.12` is at
`https://github.com/tetramo-labs/glassly/releases/tag/glassly-v3.1.0-beta.12`.

Use a release only after its page contains
`glassly-release-<release-identity>.json`. That completed release record is written
only after the required SDK publications, OTA assets, and release verification
succeed. A page that says the release is still in progress is not ready for a
customer deployment.

## 1. Pin The Exact SDK Release

Use the same complete release identity on every platform. Do not use moving tags
such as `dev`, `beta`, or `latest` in a controlled deployment.

**React Native / Expo**

```bash
bun add @glassly/bluetooth-sdk@X.Y.Z
```

**Android**

```kotlin
dependencies {
    implementation("ai.glassly:bluetooth-sdk:X.Y.Z")
}
```

The companion `ai.glassly:lc3Lib` artifact resolves transitively from Maven
Central.

**iOS**

Add the following Swift package and select the exact `X.Y.Z` tag:

```text
https://github.com/tetramo-labs/glassly-bluetooth-sdk-ios.git
```

If the customer build environment is also disconnected, mirror the exact npm,
Maven, or SwiftPM package into the customer's internal dependency registry before
building the app. The registries are build-time dependencies; the compiled mobile
app does not contact them at runtime.

## 2. Disable Glassly SDK Analytics

Analytics must be disabled before the native SDK starts.

**React Native / Expo**

Add the setting to the SDK config plugin, then rebuild the native app:

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

**Android**

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

Android apps can instead 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 instead set `BluetoothSdkAnalyticsDisabled` to `true` in
`Info.plist` before SDK startup.

## 3. Resolve, Download, And Verify The OTA Bundle

First download the completed release record from the selected release page:

```text
glassly-release-<release-identity>.json
```

You can download it in a browser or with the GitHub CLI after replacing the
example identity:

```bash
RELEASE_IDENTITY=X.Y.Z
gh release download "glassly-v${RELEASE_IDENTITY}" \
  --repo tetramo-labs/glassly \
  --pattern "glassly-release-${RELEASE_IDENTITY}.json"
```

Treat that record as the authority for the selected bundle's filename and URL.
A prerelease normally points at a same-version bundle on its own release page. A
stable release intentionally promotes the exact tested beta OTA bytes, so its
record can point at a beta-named bundle on the beta release page instead.

Resolve and download exactly the bundle selected by the record:

```bash
RELEASE_RECORD="glassly-release-${RELEASE_IDENTITY}.json"
BUNDLE=$(jq -er '
  .artifacts
  | map(select(.coordinate | startswith("mentra-live-ota-bundle-") and endswith(".zip")))
  | if length == 1 then .[0].coordinate else error("expected exactly one OTA bundle") end
' "$RELEASE_RECORD")
BUNDLE_URL=$(jq -er --arg bundle "$BUNDLE" \
  '.artifacts[] | select(.coordinate == $bundle) | .url' \
  "$RELEASE_RECORD")
curl --fail --location --output "$BUNDLE" "$BUNDLE_URL"
```

The ZIP contains:

- The matching Mentra Live ASG APK.
- Every referenced MTK patch.
- The referenced BES firmware.
- `version.template.json`.
- `configure.mjs` and deployment instructions.
- `SHA256SUMS` for the included OTA payloads.

The completed release record contains the SHA-256 checksum and size of the ZIP,
the hosted OTA manifest, and the published SDK coordinates. Find the expected
bundle checksum in the release record:

```bash
EXPECTED_SHA256=$(jq -r --arg bundle "$BUNDLE" \
  '.artifacts[] | select(.coordinate == $bundle) | .sha256' \
  "$RELEASE_RECORD")
printf '%s\n' "$EXPECTED_SHA256"
```

Calculate the downloaded ZIP's checksum and compare it with that value before
moving the bundle across the air-gap boundary:

```bash
ACTUAL_SHA256=$(shasum -a 256 "$BUNDLE" | awk '{print $1}')
test "$ACTUAL_SHA256" = "$EXPECTED_SHA256"
```

On Linux, `sha256sum` provides the equivalent calculation. Keep the release record
with the imported bundle as the deployment audit record.

## 4. Generate The Internal Manifest

Extract the bundle, then run its dependency-free configurator with the exact URL
where the final manifest will be served:

```bash
unzip "$BUNDLE" -d "mentra-live-ota-${RELEASE_IDENTITY}"
cd "mentra-live-ota-${RELEASE_IDENTITY}"
node configure.mjs \
  "https://updates.example.internal/glassly/${RELEASE_IDENTITY}/version.json"
```

The command writes `version.json`. It converts every bundled artifact reference to
an absolute URL under the supplied location. Run the command again if the hosted
directory moves.

Host the entire extracted directory without renaming or removing its `artifacts/`
files. Both the phone and Mentra Live must be able to resolve and reach the manifest
and artifact URLs. The endpoints must support ordinary unauthenticated HTTP GET
requests; the OTA protocol does not attach a customer login session or custom
authorization headers. Restrict access at the internal network boundary instead.

For HTTPS, use a certificate chain trusted by both the phone and Mentra Live. Test
internal DNS and certificate trust from both devices before beginning an update.

## 5. Configure The Customer App

Set the internal manifest URL before the app checks for or starts an update:

**React Native / Expo**

```ts
import BluetoothSdk from "@glassly/bluetooth-sdk"

const otaManifestUrl = "https://updates.example.internal/glassly/X.Y.Z/version.json"

BluetoothSdk.setOtaVersionUrl(otaManifestUrl)

BluetoothSdk.addListener("ota_status", (event) => {
  console.log(event.status, event.overall_percent)
})

const updateAvailable = await BluetoothSdk.checkForOtaUpdate()
if (updateAvailable && (await askUserToInstallUpdate())) {
  await BluetoothSdk.startOtaUpdate()
}
```

**Android**

```kotlin
sdk.setOtaVersionUrl(
    "https://updates.example.internal/glassly/X.Y.Z/version.json"
)

if (sdk.checkForOtaUpdate() && askUserToInstallUpdate()) {
    sdk.startOtaUpdate()
}
```

**iOS**

```swift
try sdk.setOtaVersionUrl(
    "https://updates.example.internal/glassly/X.Y.Z/version.json"
)

if try await sdk.checkForOtaUpdate(), await askUserToInstallUpdate() {
    try await sdk.startOtaUpdate()
}
```

OTA remains app-controlled. The SDK does not check for or install updates
automatically. Present the update to the user, display `ota_status` progress, and
avoid unrelated glasses commands until the update reaches `complete` or `failed`.

## 6. Connect Mentra Live To The Internal Network

The standalone Bluetooth SDK OTA flow expects Mentra Live to reach the internal
update server over Wi-Fi. Your app can provision that network with
`sendWifiCredentials(...)`.

The phone-hosted hotspot OTA orchestration used by the Glassly App is not currently
part of the standalone public Bluetooth SDK flow. If the glasses are not allowed on
an internal Wi-Fi network, update them during factory provisioning instead.

Mentra Live ASG builds before build 39 ignore a custom OTA manifest URL. Bootstrap older inventory through its factory
or legacy update path once. Factory-provision new deployments with build 39 or newer.

## 7. Validate Without Internet Access

Before deployment, test the complete customer app and update flow with public
internet access blocked:

1. Confirm SDK analytics are disabled in the compiled app.
2. Pair and connect Mentra Live over Bluetooth.
3. Connect Mentra Live to the internal Wi-Fi network.
4. Confirm `getOtaVersionUrl()` returns the internal, versioned manifest URL.
5. Run the OTA check and install every available ASG, MTK, and BES step.
6. Reconnect after restarts and repeat the check until no update remains.
7. Confirm firewall and DNS logs contain only customer-approved destinations.
8. Exercise the Bluetooth SDK features used by the customer app.

## Updating To A New Release

Treat each release identity as immutable:

1. Select another completed coordinated release.
2. Update the app to that exact Bluetooth SDK version.
3. Import and verify the OTA bundle selected by that release's completed record.
4. Host it under a new versioned directory.
5. Point the new app build at the new internal `version.json`.
6. Keep older directories available while older app versions remain deployed.

Never select a bundle from its filename alone. Use the bundle referenced by the
completed release record; that record is the correlation mechanism, including
when a stable SDK release promotes an exact beta-tested OTA bundle.

## What This Does Not Self-Host

The Bluetooth SDK itself does not require Glassly Core or Glassly-hosted runtime
services for pairing, Bluetooth commands, camera control, microphone audio, or OTA.
Cloud speech-to-text, cloud text-to-speech, photo webhooks, and streaming services
are separate application choices. Use on-device capabilities or customer-hosted
services when those features must also remain inside the restricted network.
