Skip to content

Troubleshooting

Common issues and solutions when developing with the Maverick AI SDK.

BLE Connection Issues

Bluetooth permissions denied

Android 12+ (API 31): BLUETOOTH_SCAN and BLUETOOTH_CONNECT are runtime permissions. Request them before calling Evs.showUI() or Evs.glassesService.connect().

iOS: Ensure NSBluetoothAlwaysUsageDescription is set in Info.plist.

See Required Permissions for the full list.

Glasses not found during scan

  • Ensure the glasses are powered on and not connected to another device.
  • Glasses are discoverable as EV[NUMBER] (e.g. EV0080).
  • On Android, confirm Bluetooth and Location services are enabled.
  • On iOS, confirm Bluetooth is enabled in Settings.

Connection drops or fails

  • BLE 5 is recommended for stable connections. BLE 4.2 works but with reduced throughput.
  • Ensure only one application is connected to the glasses at a time.
  • If using a simulator, verify you're on the same network and port 8765 is not blocked by a firewall.

BLE disconnects in background

If the glasses disconnect when the app goes to background:

Android:

  • Ensure your app runs a foreground service with foregroundServiceType="connectedDevice". Without it, Android kills the BLE connection shortly after backgrounding.
  • Ask users to disable battery optimization for your app (Settings > Apps > [Your App] > Battery > Unrestricted). Aggressive battery savers on some OEMs (Samsung, Xiaomi, Huawei) can kill foreground services.
  • Verify FOREGROUND_SERVICE and FOREGROUND_SERVICE_CONNECTED_DEVICE permissions are declared in your manifest.

iOS:

  • Add bluetooth-central to UIBackgroundModes in Info.plist. Without this, iOS suspends BLE within seconds of backgrounding.
  • Ensure NSBluetoothAlwaysUsageDescription is set (not just WhenInUse).

See BLE Background Connectivity for the full setup guide.

API Key / Certificate Errors

"Certificate missing or expired"

The SDK requests a glasses certificate from the Everysight server on first connection or when the certificate expires (every 30 days). This requires:

  • Internet access - the app must have the INTERNET permission (Android) and network connectivity.
  • Valid sdk.key - ensure the key file is placed in the app resources and has not been renamed incorrectly.

Key not found

The SDK searches for API key files in this order:

  1. app.key
  2. sdk.key

Verify the key file is in the correct location for your project type - see the Resources guide:

  • Native Android: app/src/main/assets/sdk.key
  • Native iOS: at the iOS app bundle root (Xcode → "Copy Bundle Resources")
  • KMP Compose: composeApp/src/commonMain/composeResources/files/sdk.key (with the resolver installed) or per-platform under androidMain/assets/ + iosMain/resources/

Resource Loading Failures

Fonts or images not appearing

  • Native Android / Native iOS - the SDK reads files directly from assets/ (Android) or the iOS bundle. Verify your file is actually in those locations. No resolver is required.
  • KMP Compose Multiplatform - you must install an IM2ResourcesResolver that bridges to Res.readBytes("files/$path") immediately after Evs.init(...). See the Resources guide → KMP for the exact one-liner used by LiveAI and Mav2Tester.

If your iOS app crashes with MissingResourceException ... compose-resources/... it is not a resolver issue - see the next section.

iOS: MissingResourceException ... compose-resources/...

This means the SDK's M2 phone-UI Kit Compose resources never reached <App>.app/compose-resources/.

  • Native iOS: add the rsync Run Script in iOS Setup → step 4.
  • KMP iOS: make sure your Xcode "Compile Kotlin Framework" Run Script invokes :composeApp:syncComposeResourcesForIos alongside :composeApp:embedAndSignAppleFrameworkForXcode (or use the CocoaPods integration which does it for you).

Simulator Issues

Cannot connect to simulator

  • Verify the simulator is running and shows "Waiting for phone connection..." in the web dashboard.
  • Ensure the phone/emulator and the computer running the simulator are on the same network.
  • Check that port 8765 is not blocked by a firewall.
  • Use the full WebSocket URL: ws://<IP_ADDRESS>:8765/ws

Simulator shows nothing after connection

  • Ensure a screen has been added via Evs.screenService.addScreen().
  • Verify the API key is valid - the simulator also requires a valid sdk.key.

Build Issues

Android: NDK version mismatch

The SDK requires NDK 28.2.13676358. Install it via Android Studio SDK Manager or set ndkVersion in your build.gradle.kts.

iOS: Framework not found

For KMP projects, ensure the Xcode build phase includes both Gradle tasks:

./gradlew :composeApp:embedAndSignAppleFrameworkForXcode :composeApp:syncComposeResourcesForIos

For additional support, see the Community page.