IoT device onboarding: how BLE and WiFi setup works from unboxing to cloud

12 Oct 2026 By Shreya P T

IoT device onboarding is the sequence that takes a device from its box to a working connection with the owner’s network and your cloud: discovery, pairing, WiFi provisioning, authentication and registration. For consumer products the most dependable pattern is BLE for the first conversation and WiFi for everything after: the phone finds the device over Bluetooth Low Energy, hands it the WiFi credentials over an encrypted link, the device joins the network, and the cloud binds it to the owner’s account. This guide covers each stage of that flow, the alternatives (SoftAP, QR codes, Matter), the specific points where onboarding fails in real homes, and how to design the firmware and app so that a first-time setup succeeds in under two minutes.

The short version

Onboarding is five handoffs: discovery, secure channel, WiFi provisioning, network join, and registration. Each needs its own status message and its own recovery path.
Use Bluetooth Low Energy for the local conversation and WiFi for everything after; the phone keeps its own internet connection throughout.
Let the device scan for networks and report specific failures (not found, wrong password, no IP, no internet, clock not set) so the app can tell the user what to fix.
Keep the BLE link open until the device has reached the cloud, and make onboarding mode re-enterable after a reset or a lost network.

What IoT onboarding has to accomplish

Onboarding is five handoffs, and each one can fail independently.

Discovery. The phone or gateway finds the specific device in front of the user, not a neighbor’s.
Secure channel. The two sides establish an encrypted link so credentials are never sent in the clear.
Provisioning. The device receives network credentials (WiFi SSID and password) and any configuration it needs to reach the internet.
Network join. The device connects to WiFi, obtains an address, resolves DNS and reaches your backend.
Registration and binding. The cloud authenticates the device, issues it an identity and associates it with the user’s account.

A good onboarding flow reports which of the five steps it is on, because a user who sees “Connecting to WiFi” and then “WiFi password rejected” can fix the problem. A user who sees a spinner for 90 seconds and then “Setup failed” cannot.

Onboarding modes compared

Mode	How the phone talks to the device	Strengths	Weaknesses
BLE provisioning	Phone connects over Bluetooth LE, writes WiFi credentials to GATT characteristics	Phone stays on its own WiFi; works on iOS and Android; device can report progress live	Needs a BLE radio; BLE stack bugs on phones
SoftAP	Device starts its own WiFi hotspot; phone joins it and posts credentials to a local web server	No BLE radio needed	Phone loses internet during setup; iOS prompts and captive-portal handling are fragile
QR code or sound	Device displays or hears credentials	Minimal device hardware	One-way; no feedback from the device; passwords visible
Matter commissioning	Standardized BLE plus Thread or WiFi commissioning with a setup code	Interoperable with major ecosystems	Larger stack, certification cost
Pre-provisioned (cellular, Ethernet)	No user step; device has connectivity from the factory	Zero-touch	Hardware cost; not for home WiFi products

For a product that sits in a home and talks to a phone, BLE provisioning gives the best user experience and the best diagnostics, which is why it is the default for most consumer devices and the pattern this guide describes in detail. Our post on WiFi provisioning over BLE covers the GATT design we settled on.

Stage 1: discovery over BLE

A device in onboarding mode advertises over BLE with a recognizable service UUID and a short name that includes part of its serial number. The app scans for that UUID, filters by signal strength so the device in the user’s hand ranks above one in the next room, and shows the match.

Two details decide whether discovery works. First, the device must actually be advertising: a device that only enters onboarding mode on first boot will never be found by a user who set it up once, factory reset it and tried again, so define a clear way to re-enter onboarding mode (a button hold, or automatically when WiFi credentials are missing). Second, the app needs the right permissions: Android requires location or nearby-devices permission for BLE scanning, and iOS requires Bluetooth permission, and both must be requested before the scan starts with an explanation the user understands. The post on why your Bluetooth device is invisible to your app lists the other reasons a scan returns nothing.

Stage 2: pairing and the secure channel

Credentials should never cross BLE in plain text; anyone within radio range could capture the home WiFi password. Two options exist. BLE’s own LE Secure Connections pairing with numeric comparison or passkey entry provides an encrypted link, but the OS pairing dialogs are inconsistent across phones and confuse users. The more common approach in consumer products is application-layer encryption: the device and app run a key agreement (for example, ECDH with a proof-of-possession secret printed on the device or encoded in a QR code), then encrypt the provisioning payload with the derived key. The printed secret is what proves the user has physical access to the device, which is what stops a neighbor from provisioning it.

Whichever route is chosen, the device should expose a protocol version characteristic so that an app from 2027 can still provision a device manufactured in 2025.

Stage 3: WiFi provisioning

The app sends the SSID and password (and optionally a static IP configuration or a preferred band) to the device, which attempts to join. Three practices make this stage dependable.

Let the device scan. Have the device report the networks it can see with signal strengths, and have the app show that list rather than the phone’s own list. A 5 GHz-only network the phone is on may be invisible to a 2.4 GHz-only device, and showing the phone’s list leads to a guaranteed failure. The SSID the user picks should come from what the device can reach.

Report specific failures. The device should distinguish “network not found”, “wrong password” (authentication failure), “associated but no IP” (DHCP failure) and “connected but no internet” (DNS or captive portal). Each has a different fix, and the app can only guide the user if it knows which one happened.

Keep BLE alive until WiFi is confirmed. The temptation is to drop the Bluetooth link the moment the credentials are written. Hold it until the device has an IP address and has reached your backend, so that progress and errors flow back to the app over the channel that already works. The handoff from a local link to a global one is covered in local Bluetooth, global WiFi: onboarding an EverBowl.

Store credentials in encrypted persistent storage on the device, and store a fallback: if the primary network disappears for a long period (a router replacement), the device should re-enter onboarding mode on its own rather than staying unreachable.

Stage 4: network join and connectivity check

Joining WiFi is not the same as being online. After association, the device needs an address (DHCP), time (SNTP, required for TLS certificate validation), DNS resolution and a successful TLS handshake with your backend. Each step needs its own timeout and its own status code back to the app.

Two home-network conditions cause most support tickets. Captive portals and guest networks that require a browser login block devices that have no browser; detect this by fetching a known URL and checking for a redirect. Routers with client isolation or band steering can disconnect a 2.4 GHz device minutes after it joins; a device that logs the disconnect reason code and reports it on the next connection helps diagnose this without a site visit.

Stage 5: registration and account binding

Once online, the device authenticates to the cloud. The strongest pattern is a per-device certificate or key pair provisioned at manufacture, so the device proves its identity without any secret from the user. The cloud then needs to bind the device to the account of the person who set it up, and the binding must prove that the person had physical access, otherwise anyone who knows a serial number could claim a device.

The usual proof is a short-lived claim token: the app requests one from the cloud while signed in, passes it to the device over the encrypted BLE channel, and the device presents it when it registers. The cloud sees a device identity plus a token minted for a specific user and completes the binding. A device sold second-hand needs the reverse: a factory reset must clear the binding on the device and the cloud must allow the previous owner to release it.

Where onboarding fails in real homes

The flow above is what the lab tests. Homes add the following, in roughly descending order of frequency.

Wrong password, typed confidently. Show the password field with a reveal toggle, and have the device report an authentication failure distinctly so the app can say “the password was rejected” instead of “setup failed”.
5 GHz-only or mesh networks. Devices with 2.4 GHz radios cannot see them. Scan from the device and tell the user when the network they expect is not visible.
BLE connection drops mid-provisioning. Phones aggressively manage BLE connections. Design the protocol so every step is idempotent and can be resumed after a reconnect; the techniques in bulletproof BLE reconnects for iOS and Android apply directly.
Permissions denied. A user who declined Bluetooth or location permission sees an empty scan. Detect the denied state and deep-link to the settings screen.
Device already provisioned. A device that joined WiFi during a failed earlier attempt and no longer advertises. Make onboarding mode re-enterable and show the user how.
Time not set. TLS fails with a certificate error that looks like a network error. Set time before the first TLS attempt and report “clock not synchronized” explicitly.

Each failure above has a specific message the app can show. The post on fixing onboarding by reducing uncertainty, not steps explains why specific status messages mattered more than removing screens.

Onboarding in EverBowl™

EverBowl™ learns how a dog eats and drinks only after it is on the home network, so onboarding is the one moment the owner is actively involved with the firmware. The bowl advertises itself over Bluetooth, the app connects to it over BLE, the two sides hand off the WiFi credentials, and the app stays with the bowl until it is on the network and talking to the cloud. From that point on the record builds itself, visit by visit, without the owner doing anything. EverBowl does not diagnose anything; the value is the record, and the record cannot start until the first minute in the kitchen goes right, which is why that minute gets a disproportionate share of engineering effort. ## Conclusion

IoT device onboarding works when each of its five handoffs (discovery, secure channel, provisioning, network join, registration) is observable and recoverable on its own. Use BLE for the local conversation and WiFi for the global one, encrypt credentials with proof of physical access, let the device scan for networks, report specific failures, and keep the local link alive until the cloud confirms the device is online. The result is a setup that finishes in under two minutes for most homes and tells the user exactly what to fix in the rest.

FAQs

What is IoT device onboarding?

The process of taking a new device from unboxing to a working, authenticated connection with the owner’s network and the manufacturer’s cloud: discovery, pairing, network provisioning, connectivity and account binding.

What is WiFi provisioning over BLE?

A setup method where a phone app connects to the device over Bluetooth Low Energy, establishes an encrypted session, and sends the home WiFi name and password so the device can join the network. The phone stays on its own WiFi throughout.

BLE provisioning or SoftAP: which is better?

BLE provisioning is better for consumer products with a phone app because the phone keeps internet access, both platforms support it, and the device can report progress live. SoftAP avoids the need for a BLE radio but forces the phone to switch networks, which is fragile on iOS.

Why does my IoT device fail to connect to WiFi during setup?

The most common reasons are a mistyped password, a 5 GHz-only or mesh network that a 2.4 GHz device cannot see, a captive portal or guest network, or a device clock that is not set so TLS fails. A device that reports which step failed makes the fix obvious.

How do you secure IoT onboarding?

Encrypt the provisioning channel with a key derived from a secret that proves physical access (printed code or QR), give each device its own identity for cloud authentication, bind the device to a user with a short-lived claim token, and clear the binding on factory reset.

What is onboarding mode on an IoT device?

A state in which the device advertises itself for setup (over BLE or as a WiFi hotspot) and accepts provisioning. Devices should enter it on first boot, after a factory reset, and when stored network credentials stop working.