Bluetooth onboarding for a connected hardware product

The scenario

Consider a connected device that needs an initial setup through a mobile app before joining a network. The example would guide a person from finding the intended device to confirming that configuration succeeded. It would treat discovery, account ownership, and network connectivity as separate steps instead of one indefinite connecting screen.

Discover the intended device

The device would expose a documented setup service and advertise only the information needed for discovery. The app would narrow results using the service identifier and an explicit selection step. A nearby Bluetooth name would not be treated as proof of device identity.

The mobile flow would handle permission denial, Bluetooth being disabled, and the app moving to the background. Android and iOS lifecycle handling would remain native to each platform. The shared product specification would describe the same visible states without assuming both operating systems behave identically.

Use an explicit setup protocol

A versioned GATT contract would describe commands, responses, size limits, and error codes. A setup session could begin with an ownership check tied to a device-specific onboarding credential. Sensitive configuration would need appropriate transport and application-layer protection; successful BLE discovery alone would not establish a trusted session.

Configuration would be staged, validated, and committed through an explicit command. The app would receive a structured acknowledgement and then check the resulting device state. Credentials would be excluded from diagnostic messages, crash reports, and ordinary analytics.

Make interruption recoverable

The app would distinguish a lost BLE connection from a rejected configuration and a device that accepted settings but could not reach the network. Each state would have a useful next action, such as retrying discovery, correcting input, or resetting an unfinished setup session.

If the app disappears after commit, a later session would query whether setup finished before sending the same configuration again. Tests would cover two nearby devices, repeated commands, a device reset, and a person switching apps halfway through onboarding.

What to validate

• The selected physical device matches the setup session.
• Permissions can be denied without trapping the interface.
• Interrupted setup can resume without exposing credentials.
• A confirmed configuration is distinguished from working network access.

The tradeoff

BLE is useful for nearby setup, but adds platform and radio conditions to the product. A QR-assisted or wired flow may be simpler for some devices. The onboarding method should match how and where the hardware will be installed.