Android emulators

bun run emulators runs the whole stack and opens OpenBeacon on several Android emulators that move around Derby. You can run it in two ways:

• Route mode (the default) starts four copies of one Android Virtual Device (AVD), each following a different route. It's a quick way to see several group members moving on the map.
• Version mode starts one emulator per Android version. Use it to check a change on old and new Android at the same time, or to reproduce a bug on one specific version.

Before you startCopy Anchor Link

You need Bun, Python 3, Java 17, Docker Compose and the Android SDK with the emulator and platform tools. In Android Studio's SDK Manager, install the Android NDK and accept the SDK licences. adb and emulator must be on your PATH.

• Route mode needs at least one AVD. Create one in Android Studio's Device Manager.
• Version mode creates its own AVDs, so it also needs Android SDK Command-line Tools (latest) and ANDROID_HOME set to your SDK.

Stop anything already using Metro's port 8081 or the emulator ports the run needs. Each emulator takes two ports from 5554 upwards, so four emulators use 5554–5560 and all ten versions use 5554–5572.

What it doesCopy Anchor Link

1. Installs dependencies.
2. Starts PostgreSQL and Redis in Docker, applies database migrations and starts the backend with hot reload. It skips this step if you point it at another backend.
3. Builds the Android development APK, unless you pass --apk.
4. Starts Metro and the emulators, installs the app on each and opens it. If the app closes during startup, it tries again, up to three times per emulator.
5. Moves each emulator's GPS once a second until you press Ctrl+C.

On the first run it creates .env from .env.example with a generated auth secret. It then stops and lists the storage settings you still need to fill in: S3_ACCESS_KEY_ID, S3_ACCESS_KEY, S3_BUCKET_NAME, R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET and R2_PM_TILES_KEY. Pictures and maps need real storage credentials and a PMTiles object. It never overwrites an existing .env.

The four routes are:

Press Ctrl+C to stop the backend, Metro and the emulators. The database and cache keep running; stop them with docker compose stop db redis. Each emulator's log is saved to a temporary folder, which is printed at startup and again if something fails.

Run specific Android versionsCopy Anchor Link

bun run emulators:versions

This starts one emulator for every supported Android version. To run only some, list their API levels:

bun run emulators:versions 24 36
bun run emulators:versions 31

bun run emulators:versions is a shortcut for bun run emulators --android-versions, so the two lines above are the same as bun run emulators --android-versions 24 36 and bun run emulators --android-versions 31. Running a single version is the easiest way to reproduce a bug someone reported on their Android version.

The supported API levels are 24, 26, 28, 29, 30, 31, 33, 34, 35 and 36. The compatibility matrix maps them to Android versions. Any other number is rejected. Duplicates are ignored, and the emulators always start in order from oldest to newest.

For each version, the script:

• installs the Google APIs system image with sdkmanager if it's missing, using arm64-v8a on ARM machines and x86_64 on others, and reinstalls any image left half-installed;
• creates an AVD called OpenBeacon_API_<level> on a Pixel 6 profile with a 6 GB data partition and a hardware keyboard, and recreates it if its settings don't match;
• gives the emulators routes in turn: the first version is stationary, the second walking, the third jogging, the fourth driving, and then the routes repeat.

AVDs go in ANDROID_AVD_HOME, or ~/.android/avd if that isn't set.

OptionsCopy Anchor Link

You can combine version mode with the other options, for example:

bun run emulators:versions 24 30 36 --memory-mb 4096
bun run emulators:versions 34 --apk apps/mobile/android/app/build/outputs/apk/debug/app-debug.apk
bun run emulators --avd Medium_Phone --api-url https://api.example.com

10.0.2.2 is how an Android emulator reaches your computer. The API URL is built into the development bundle, so restart the command when you switch backends. That backend's auth and network settings must allow the URL.

MemoryCopy Anchor Link

Before building anything, the script adds up the RAM each emulator needs plus 2 GiB of headroom. It then compares the total with the free memory reported by /proc/meminfo on Linux or vm_stat on macOS. If there isn't enough, it stops and suggests fewer emulators, a lower --memory-mb or --skip-memory-check. If it can't read free memory, it skips the check.

Route mode needs about 26 GiB by default: four emulators at 6 GiB plus headroom. Version mode with all ten versions needs about 56 GiB. Most machines need a shorter list of versions or a lower --memory-mb.

Android SDK and JavaCopy Anchor Link

The script uses ANDROID_HOME, or ANDROID_SDK_ROOT if that isn't set. If that SDK has no NDK or no accepted licence and ~/Android/Sdk has both, it uses ~/Android/Sdk instead and says so. On Linux, if /usr/lib/jvm/java-17-openjdk exists and your current Java isn't 17, it switches to Java 17 for the run.

If the Android build fails, check that the NDK is installed, the SDK licences are accepted, and ANDROID_HOME points to that SDK.

Android compatibility matrixCopy Anchor Link

The app's Android build settings come from the Expo 55 and React Native 0.83 defaults. The app doesn't override them.

The minimum is a technical floor, not a promise that every phone at that version works. Raising targetSdk brings in newer Android rules even on older phones, so check the version changes below when you update Expo or React Native.

"Checked" means the app ran on that version's emulator with bun run emulators:versions. That's how the Android 7 location upload bug was found and fixed.

Versions not in the list:

• Android 7.1 (25), 8.1 (27) and 12L (32) are above the minimum, so the app installs on them, but they have no emulator in the script.
• Android 17 isn't in the script yet and hasn't been checked.
• Versions below 7.0 can't install the app.

Emulators don't replace real phones for battery, GPS, background behaviour or manufacturer power management.

Real-device test planCopy Anchor Link

No real phone has been signed off yet. This is the coverage being worked towards:

One phone can cover more than one row. For each run, record:

• the phone: manufacturer, model, launch year, Android version and API level, security patch and Google Play services version;
• the conditions: app build, network and battery mode;
• the run itself: tester, date, results and any bugs.

On every device, try these cases:

• allowing, denying and later granting location, background location and notifications;
• approximate instead of precise location;
• turning location services off;
• screen off, rebooting and force-stopping the app;
• manufacturer battery restrictions;
• long periods offline, then reconnecting.

Check that locations still arrive encrypted and up to date, and measure battery use and delay rather than assuming tracking never stops.