DEV Community: Ran Engel

I built a cross-platform BLE discovery layer for iOS and Android — here's how it works

Ran Engel — Mon, 22 Jun 2026 21:07:35 +0000

NearbyDiscoveryKit is a thin, app-agnostic framework that handles proximity discovery and payload handoff over Bluetooth so you don't have to.

Most apps that need "find someone nearby" don't actually need Bluetooth for very long. They need it for about three seconds — long enough to discover a nearby device, exchange a small piece of data, and hand control back to the app.

That narrow job is surprisingly hard to do cleanly across iOS and Android. CoreBluetooth and the Android BLE APIs are both capable but verbose, stateful, and full of edge cases. Every app ends up reimplementing the same scan → connect → exchange → disconnect cycle from scratch.

We got tired of doing that. So we extracted it into a reusable layer called NearbyDiscoveryKit.

The mental model

Before writing any code, we defined exactly what the framework should do:

Find a nearby device, briefly connect, exchange a small payload, and get out of the way.

That's it. The framework doesn't know what your payload means. It doesn't run a persistent session. It doesn't replace your backend. It just does the BLE part and hands the result to your app.

Two roles, one flow:

Host                              Client
  |                                  |
  | ← BLE advertisement ──────────── |
  | ← connect request ─────────────  |
  | ─── handoff payload ──────────→  |
  | ─── disconnect ───────────────→  |

After the handoff the client has whatever the host put in the payload — a room code, a session ID, a backend URL, an invite token. From that point on, your app takes over.

The protocol

For iOS and Android to interoperate, they have to speak the same language at the BLE layer. We defined a shared protocol with three things:

Fixed UUIDs — both platforms advertise and scan for the same service UUID:

Service:        A1B2C3D4-E5F6-7890-ABCD-EF1234567890
Characteristic: B2C3D4E5-F6A7-8901-BCDE-F12345678901

A JSON message envelope — all messages are UTF-8 JSON, max 512 bytes:

{
  "type": "handoff",
  "protocolVersion": 1,
  "appId": "com.example.myapp",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "payload": {
    "roomCode": "SWIFT42",
    "backendUrl": "https://api.example.com/room/SWIFT42"
  }
}

Three message types:

join_request — sent by the client after subscribing to notifications
handoff — sent by the host in response, contains the payload
reject — reserved for future use

The key design decision here was to keep the envelope strictly typed but the payload completely open. The framework validates protocolVersion and appId — if they don't match, the connection is rejected before any payload is exchanged. What's inside payload is entirely up to the app.

The iOS implementation

The public API surface is intentionally small:

let client = NearbyDiscoveryClient()

client.onEvent = { event in
    switch event {
    case .payloadReceived(let message):
        let roomCode = message.payload?["roomCode"] ?? ""
        // hand off to your backend
    case .stateChanged(let state):
        print(state)  // "scanning", "connecting", "connected"
    case .error(let error):
        print(error)
    default:
        break
    }
}

// Join a nearby session
client.startScanning(appId: "com.example.myapp")

// Or host one
client.startHosting(
    appId:     "com.example.myapp",
    sessionId: UUID().uuidString,
    payload:   ["roomCode": "SWIFT42"]
)

Under the hood, NearbyDiscoveryClient delegates to NDKAdvertiser (host path, built on CBPeripheralManager) and NDKScanner (client path, built on CBCentralManager). The GATT sequence — service setup, advertising, characteristic write, notification, disconnect — is all handled internally. The app never touches CoreBluetooth directly.

One subtlety worth calling out: the scanner subscribes to characteristic notifications before writing the join request. This ensures it doesn't miss the handoff response if the host replies faster than expected.

The Android implementation

The Kotlin API mirrors the Swift one exactly:

val client = NearbyDiscoveryClient(context)

client.onEvent = { event ->
    when (event) {
        is NDKEvent.PayloadReceived -> {
            val roomCode = event.message.payload?.get("roomCode")
            // hand off to your backend
        }
        is NDKEvent.StateChanged -> println(event.state)
        is NDKEvent.Error        -> println(event.message)
        else -> Unit
    }
}

// Join
client.startScanning(appId = "com.example.myapp")

// Or host
client.startHosting(
    appId     = "com.example.myapp",
    sessionId = UUID.randomUUID().toString(),
    payload   = mapOf("roomCode" to "KOTLIN42")
)

We were deliberate about keeping the API symmetric. If someone reads the iOS docs and then picks up the Android library, the concepts map directly. Same event names, same lifecycle, same payload shape.

The emulator problem

Here's where it got interesting.

Android emulators don't have Bluetooth hardware. When you're developing an Android app that uses BLE, you're stuck — you either test only on physical devices, or you build some kind of mock layer.

We didn't want to ship a mock. Mocks test your mock, not your code. We wanted the Android implementation to run real BLE operations, just... bridged to hardware that the emulator can't access directly.

So we built BLEForEmulator — a small Mac menu bar app that acts as a BLE proxy. The Android emulator connects to it over TCP (10.0.2.2:7788, the standard emulator-to-host address). The Mac app translates those TCP commands into real CoreBluetooth calls on the Mac side.

Android Emulator ──TCP──→ BLEForEmulator Mac App ──CoreBluetooth──→ iOS device

The Android library detects whether it's running on an emulator and automatically routes through the bridge if so:

class NearbyDiscoveryClient(private val context: Context) {
    val usingBridge: Boolean = EmulatorDetector.isEmulator()

    fun startScanning(appId: String) {
        val scanner: NDKDiscovery = if (usingBridge)
            NDKBridgeScanner(context, appId)   // TCP → Mac → CoreBluetooth
        else
            NDKScanner(context, appId)          // real BLE
        // ...
    }
}

The same NearbyDiscoveryClient API works on both paths. On a physical Android device, it uses the Android BLE stack directly. On an emulator, it goes through the bridge — and your app code doesn't change.

We confirmed both paths work: iOS host → Android join, and Android host → iOS join.

What we learned

Keep BLE sessions short. Every second a BLE connection stays open is a second where something can go wrong. Our sessions last as long as it takes to exchange one message and disconnect — typically under two seconds. Reliability went up dramatically when we stopped trying to keep connections alive.

Shared protocol docs prevent subtle bugs. Before we wrote shared/protocol.json and docs/protocol.md, the iOS and Android implementations had drifted slightly in how they serialized certain fields. A shared canonical reference fixed that quickly and made it easy to add cross-platform JSON compatibility tests.

Symmetric APIs are worth the extra effort. It would have been faster to just write whatever felt natural in each language. But having the iOS and Android APIs mirror each other has real value — someone who knows one can pick up the other, and the mental model of "host/join/payload" transfers completely.

What's next

A few things are stubbed with TODOs in the current codebase:

MTU chunking — messages close to 512 bytes may get truncated before negotiation. Not an issue in practice for typical payloads, but needs fixing.
RSSI filtering — the scanner connects to the first host it finds regardless of signal strength. A threshold would enforce physical proximity.
Reject envelope — the host currently sends a raw GATT error on rejection. It should send a proper reject message so the client can handle it cleanly.

Try it

The framework is MIT-licensed and on GitHub:

👉 github.com/engelon/NearbyDiscoveryKit

The repo includes a TypeRaceDemo app for both iOS and Android that shows host and join screens wired up to the framework. If you have an iOS device and an Android emulator with BLEForEmulator running on your Mac, you can run a full cross-platform handoff in under five minutes.

If you find it useful or hit any issues, open an issue or a PR. The protocol is versioned so the plan is to keep the API stable from here.

How I Gave the Android Emulator Real Bluetooth

Ran Engel — Sun, 21 Jun 2026 19:04:47 +0000

I was building a proximity-based app — the kind where two phones discover each other over BLE, exchange a small payload, and start a session together. Think of it like AirDrop, but for your own app.

The iOS side was easy. The Android side was going well too, until I tried to test it.

The Android Emulator doesn't support Bluetooth.

The Wall

Not "limited support." Not "experimental." Just nothing. You run a BLE scan on an emulator and it sits there, silent, finding zero devices, forever.

The standard answer is: use a physical device. Which is fine until you're iterating fast, running on a Mac without a USB cable handy, or trying to test a cross-platform handshake between iOS and Android at the same time.

There are workarounds. One involves a USB Bluetooth dongle, a full Python Bluetooth stack called Bumble, sudo access, and a specific Android API level. I spent an afternoon with it. It works, but it's not something you'd wish on anyone.

I wanted something that just worked.

The Idea

The emulator can't do Bluetooth. But my Mac can. And the emulator can reach my Mac over TCP at 10.0.2.2 — the standard emulator host IP.

What if I wrote a small macOS app that:

Runs a TCP server
Listens for BLE commands from the emulator
Performs those commands using the Mac's real Bluetooth radio via CoreBluetooth
Sends the results back over the same connection

And on the Android side, a library that:

Detects when it's running in an emulator
Replaces the BLE transport with TCP calls to the Mac
Gets out of the way entirely on real devices

No configuration. No USB. No Python. Just a menu bar app and one Gradle dependency.

Building It

The protocol came first. I designed a simple JSON format — one object per line, newline-delimited — that mirrors the standard BLE vocabulary:

{ "command": "startScan", "serviceUuids": ["A1B2C3D4-..."] }
{ "event": "advertisementFound", "address": "2AD28C65-...", "rssi": -62 }
{ "command": "connect", "address": "2AD28C65-..." }
{ "event": "connected", "connectionId": "conn-abc123" }

Commands flow from Android to Mac. Events flow back. Binary values are base64. The whole thing fits in a single JSON spec file.

The Mac app is a SwiftUI menu bar app using MenuBarExtra (macOS 13+). It runs an NWListener TCP server and owns two CoreBluetooth proxies — one CBCentralManager for scanning and connecting, one CBPeripheralManager for advertising. Each connected emulator gets its own session that routes commands to the right proxy and forwards delegate callbacks back as events.

The Android library wraps the whole thing in a BLEBridge class with a callback-based API. Emulator detection uses Build.FINGERPRINT — if it contains "generic" or "emulator", you're on an AVD.

The Bugs That Taught Me Things

Port conflict. I originally used port 7788. Turns out the Android emulator's netsimd daemon already uses 7788 for its own internal gRPC BLE simulation protocol. Multiple phantom connections were hitting my bridge before the Android app even started. Moved to 7877, problem gone.

Bluetooth not ready. CoreBluetooth initializes asynchronously. If a startScan command arrives before CBCentralManager reports .poweredOn, it silently fails. The fix: queue the pending scan and replay it when the state update fires.

Premature service discovery. didDiscoverServices fires before characteristics are fetched. I was emitting servicesDiscovered too early — the Android side would call writeCharacteristic, the Mac would look up the characteristic, find nothing, and silently no-op. Fixed by always waiting for didDiscoverCharacteristicsFor before emitting the event.

App Sandbox. Xcode projects get App Sandbox enabled by default. With sandbox on, both TCP listening and Bluetooth are blocked at the OS level — silently, with no useful error message. Removing it from Signing & Capabilities fixed everything.

The Result

End-to-end, it works like this:

Mac bridge is running in the menu bar
Android emulator starts, BLEBridge connects over TCP
Bridge sends bridgeReady — Android starts scanning
Mac scans via CoreBluetooth, finds an iPhone running in host mode
advertisementFound sent to Android
Android connects, discovers services, writes a join request
iPhone receives the write, sends a handoff notification
Android receives the payload

Both directions work — the emulator can scan for real peripherals, or advertise and receive connections from them.

Try It

Mac: Download BLEForEmulator.zip from GitHub Releases, unzip, move to /Applications, open it.

Android: Add to your settings.gradle.kts:

maven { url = uri("https://jitpack.io") }

And to your app's build.gradle.kts:

debugImplementation("com.github.engelon:BLEForEmulator:v0.1.1")

Then:

val bridge = BLEBridge()
bridge.onEvent = { event ->
    when (event) {
        is BridgeEvent.BridgeReady -> bridge.startScan(listOf(MY_SERVICE_UUID))
        is BridgeEvent.AdvertisementFound -> bridge.connect(event.address)
        // ...
    }
}
bridge.connect()

The full source, protocol spec, and docs are at github.com/engelon/BLEForEmulator.

It's a development tool — not for production, use debugImplementation. But for fast iteration on BLE features without reaching for a physical device every time, it does exactly what I needed.