# Building a BLE companion app that survives real phones

> What it takes to build a BLE companion app that works on real phones: GATT design, permissions, reconnection, background limits and device testing.

- Author: Milo Perović, Founder & lead engineer
- Published: 2026-10-16
- Topic: Software

A BLE companion app looks like the easy part of a connected product. The firmware already exposes a few characteristics, the phone has Bluetooth, and a demo works on the engineer's own handset within a day. Then the beta goes out and the support inbox fills with "it won't connect", "it forgets my device" and "it only works when the app is open".

This post is for founders and product teams who are about to commission or build the phone side of a BLE device. It covers the decisions that make the difference between a demo and an app that holds up on hundreds of different phones.

## Design the GATT profile for the app, not just the firmware

Most connection pain starts in the GATT table. Designed by firmware engineers alone, it tends to mirror the device's internal data structures: one characteristic per sensor, some debug values, and a write characteristic that accepts whatever bytes the current firmware expects. Fine on the bench, painful in production.

We design the profile with the app developer in the room and treat it as a versioned API. In practice that means:

- **A version characteristic** that the app reads first, so it knows which protocol it is speaking before it touches anything else.

- **Custom 128-bit UUIDs** for your own services, and standard services (Battery, Device Information) where they already fit.

- **Notifications for live data** rather than the app polling with reads, which wastes radio time on both sides.

- **A small command/response channel** for configuration, with explicit status codes, instead of a growing list of single-purpose write characteristics.

- **Room to grow**: unknown fields ignored, new commands added rather than old ones changed.

Remember that the default ATT MTU is 23 bytes, which leaves 20 bytes of payload per notification. Larger MTUs are negotiated per connection: iOS does this on its own, while on Android the app has to request it. Design the protocol so it still works, more slowly, at 20 bytes, and treat a bigger MTU as a speed-up rather than an assumption.

## Permissions and platform rules that break a BLE companion app

The two mobile platforms disagree on almost everything about Bluetooth, and the rules have changed several times across OS versions. A BLE companion app has to handle every combination your users will realistically have.

### Android

From Android 12, scanning and connecting need the `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` runtime permissions. On older versions, scanning required location permission, and on some versions location services also had to be switched on before scan results appeared. Users distrust an app that asks for location to talk to a thermostat, so onboarding must explain why, and the app needs a clear "permission refused" state rather than an empty device list.

### iOS

Core Bluetooth never exposes the hardware address. It gives each peripheral an identifier that is stable for that phone but different on every other phone. If your backend needs to know which physical unit a user owns, the device has to tell the app, typically through a serial number in the Device Information service or in the advertising data.

Background behaviour is the other trap. With the Bluetooth background mode enabled, an iOS app can keep connections and receive notifications while suspended, but background scanning only works when you filter by service UUID, and it is slower and less frequent than foreground scanning. If the product promise depends on the phone noticing the device while the app is closed, prove that on real hardware during the prototype, not after launch.

## Connection handling is a state machine, not a callback

The single biggest source of flaky BLE apps is treating connection as an event rather than a state. Phones drop connections constantly: the user walks away, the OS reclaims resources or the device reboots.

We model the link explicitly, with states such as scanning, connecting, discovering services, ready, and reconnecting, and every screen in the app reads from that state. A few rules we hold to:

- **Queue every GATT operation.** Android's Bluetooth stack expects one outstanding read, write or descriptor operation at a time. Firing several at once leads to silently dropped requests and the infamous generic error 133.

- **Time out everything.** A connection attempt or write that never returns must fail cleanly after a sensible limit, typically a few seconds, and hand control back to the state machine.

- **Reconnect with backoff.** Retry quickly at first, then less often, and stop draining the phone's battery if the device is clearly out of range.

- **Re-subscribe after every reconnect.** Notification subscriptions do not survive a dropped link unless the devices are bonded, and even then it is safer to set them again.

- **Log the link, not just the errors.** A ring buffer of state changes that a user can attach to a support ticket is worth more than any crash reporter for BLE issues.

## Pairing, bonding and security

Whether to bond is a product decision as much as a security one. Bonding gives you an encrypted, authenticated link and lets the phone reconnect without user input, but it adds OS-level pairing dialogs and a failure mode where the phone and the device disagree about whether they are bonded. When a user resets the device but not the phone, the phone holds stale keys and connections fail until the user forgets the device in system settings, which most users will never find.

If you bond, use LE Secure Connections and plan the recovery path in the app: detect the failure, explain it in one sentence, and link to the right settings screen. If the device has no display or buttons, "Just Works" pairing gives you encryption but no protection against an active man-in-the-middle, so sensitive commands may need an application-layer check as well, for example a token issued by your backend during onboarding.

Firmware updates over BLE deserve their own care. The app is often the only path to the device, so an interrupted transfer must never leave it unbootable. We covered the device side of that in [our post on secure OTA updates for small fleets](https://miloperovic.com/journal/secure-ota-updates-for-small-fleets-without-a-big-platform/); the app's job is to resume cleanly, keep the screen awake and tell the user not to walk away.

## Where the app sits between device and cloud

For many products the phone is the device's only route to the internet. The app then has to buffer readings without signal, upload them later without duplicates, and carry configuration back to the device.

Give every reading a device-side timestamp or sequence number, so the backend can de-duplicate and order data regardless of when the phone delivered it. Keep the app thin: it should relay and display, while business rules live in the backend, where you can change them without waiting for app store review. We described that split in more detail in [one IoT backend for the device, dashboard and mobile app](https://miloperovic.com/journal/one-iot-backend-for-the-device-dashboard-and-mobile-app/).

## Testing across real phones

Simulators do not run Bluetooth in any useful way, and BLE behaviour varies with chipset, vendor Android skin and OS version. A small physical test pool catches most of the surprises:

Phone groupWhy it matters

Current and one-year-old iPhoneBackground behaviour and MTU negotiation on recent iOS

An older iPhone on the oldest iOS you supportPermission prompts and Core Bluetooth differences

Google Pixel on the latest AndroidReference Android behaviour and new permission rules

A Samsung mid-range phoneVendor battery optimisation that kills background work

A budget Android phone on an older versionLocation-based scan permissions and weaker Bluetooth stacks

Run the boring scenarios on every one: first-time onboarding, app killed during a transfer, device rebooted while connected, Bluetooth toggled off and on, phone left overnight. Most field complaints come from these, not from exotic edge cases.

## What we would do before writing the first screen

- Agree a versioned GATT profile between firmware and app developers, including the 20-byte fallback.

- Write down the background promise ("syncs while the app is closed", or not) and prove it on both platforms with a prototype.

- Decide on bonding, and design the reset and recovery path before the happy path.

- Model the connection as a state machine with queued operations, timeouts and backoff.

- Make the device report its own serial number, so identity never depends on the platform.

- Buy the test phones early and run the boring scenarios every release.
