Expo setup

Why Expo Go cannot run this SDK

react-native-ble-plx ships custom native code. Expo Go is a prebuilt binary with a fixed set of native modules — anything outside that set cannot be loaded at runtime, no matter what JavaScript you ship. Every app using @rogue/console-sdk therefore runs in a development build: your own binary, with the SDK’s native dependency compiled in.

The path is expo-dev-client plus Continuous Native Generation (CNG) — you never hand-maintain ios/ or android/ directories.

One plugin line does all permission work

Add the dev client and the SDK’s first-party config plugin to app.json:

{
  "expo": {
    "plugins": [
      "expo-dev-client",
      "@rogue/console-sdk"
    ]
  }
}

That single "@rogue/console-sdk" entry writes every piece of BLE permission config the SDK needs:

• iOS Info.plist: NSBluetoothAlwaysUsageDescription with a Rogue-branded default string. The deprecated NSBluetoothPeripheralUsageDescription is never written.
• Android AndroidManifest.xml: the Android 12+ pair — BLUETOOTH_SCAN with android:usesPermissionFlags="neverForLocation" and BLUETOOTH_CONNECT — plus the legacy trio (BLUETOOTH, BLUETOOTH_ADMIN, ACCESS_FINE_LOCATION) capped at maxSdkVersion="30" for Android 11 and below.

Runtime permission prompts are separate from manifest config and are driven in-app through the useBlePermissions() hook — your code never touches PermissionsAndroid.

Plugin props

Background BLE is off by default and opt-in:

{
  "expo": {
    "plugins": [
      "expo-dev-client",
      ["@rogue/console-sdk", { "background": true }]
    ]
  }
}

Leave it off unless you specifically need connections to survive backgrounding — with the default { background: false }, no UIBackgroundModes entry is written.

Regenerate native projects after plugin changes

CNG means ios/ and android/ are build products. After adding the plugin, changing plugin props, or bumping a native dependency:

npx expo prebuild --clean

The dev loop

# once per native change (plugin edit, native dep bump, Expo SDK bump)
npx expo run:ios --device       # or: npx expo run:android --device

# then, for pure-JS iteration — no native rebuild needed
npx expo start --dev-client

Physical device required for BLE

Bluetooth Low Energy works in neither the iOS Simulator nor stock Android emulators. Real consoles need a physically connected phone or tablet.

For the simulator, demos, and CI there is a first-class alternative: the simulated transport in @rogue/console-sdk/testing drives the full SDK — scanning, connecting, live metrics, workouts — with zero hardware and zero radios. See Testing & mocking.

Distributing dev builds to your team

Teammates without Xcode or Android Studio can install a dev client built with EAS Build: a development profile ("developmentClient": true, "distribution": "internal") produces an installable internal build, and a release-mode preview profile is the right shape for BLE smoke testing. EAS detects npm workspaces and installs from the workspace root — no copy steps.