BLE setup apps: why pairing is the most-reviewed screen in the app

Open the store reviews for almost any connected product and the complaints cluster in one place: “cannot connect”, “stuck on searching”, “asks for location for no reason”. Setup is the first thing the user does, it involves a phone, a radio, a home network and a physical device, and any of them can fail. Whatever else the app does well, this screen sets the rating.

A flow with few steps

A reliable onboarding sequence is short and each step has one job:

1. Ask for the permissions needed, with a plain reason, just before they are used.
2. Scan and show only devices that advertise your service UUID, sorted by signal strength, with the model and last digits of the serial.
3. Connect over BLE, and confirm the right unit, for example by blinking an LED or reading a code off the label.
4. Send Wi-Fi details, wait for the result, then show success.

Show progress and a visible way to retry. The user should never have to restart the app.

Handing over Wi-Fi credentials

The phone writes the SSID and password to a BLE characteristic, usually encrypted at the link layer. Use LE Secure Connections where both sides support it, or an application-level exchange such as the protocol ESP-IDF provides for Wi-Fi provisioning. Devices only support 2.4 GHz in many cases, so the app should say that when it lists networks, because a phone on a 5 GHz network is a common failure. Never log the password, and clear it from memory after use.

The device should report a result code back: network not found, wrong password, no IP address, cloud unreachable. These are different faults with different fixes.

Error messages people can act on

“Connection failed” is useless. Say what to try: move the phone within a metre of the device, check the password, check the router is on 2.4 GHz, hold the button for five seconds to reset. Tie each message to a specific cause the firmware can detect.

Android and iOS differ

On Android 12 and later, scanning needs the nearby devices permissions, and you can declare that you do not derive location from scans. On older Android versions, BLE scanning needs location permission and location services switched on, which confuses users. On iOS, the Bluetooth permission needs a usage description string, and iOS does not expose the device’s Bluetooth address, so identify units through the advertised name or manufacturer data. Handle the cases where the user denies a permission, and link them to system settings.

Test on many phones

Test on a spread of Android makes and iOS versions, with the phone close, far, and with weak Wi-Fi. A setup flow that works on a developer’s flagship phone often fails on a low-cost handset.

What this does not fix

A good app cannot rescue a device with a weak antenna or a firmware that stops advertising after a timeout. Treat the app and the device as one product and test them together.

---

If your setup flow is generating poor reviews, book a discovery call, and see our cloud, apps and dashboards and embedded firmware work.