Wi‑Fi onboarding for connected devices

The box has a QR code. That's the whole manual.

pairble gets your product onto Wi‑Fi in about thirty seconds. The phone scans the code, the device lists the networks it can actually reach, and the password travels encrypted over Bluetooth. No app to install, on iPhone, Android or a computer.

Try the live demo Add it to your firmware

Open source · Apache‑2.0

Supported today: ESP32, C2, C3, C5, C6 and S3 on ESP-IDF 5.1+, and the Raspberry Pi Pico W and Pico 2 W on Arduino. More chips and platforms are on the way.

What your customer sees, step by step

Point the camera at the code

Set up Wi‑FiOpen

Choose your Wi‑Fi

Smith
Office
Corner Café

Smith

Wi‑Fi password•••••••••• JoinJoining…

Done, the device is online

How it works

Four steps, about thirty seconds

Everything the person does is scan, tap and type one password. Everything else happens between the phone and the device.

Phone

Encrypted Bluetooth

Device OfflineOnline

Wi‑Fi

Router

QR code

The camera reads the device's name and secret
The phone finds the device over Bluetooth
The device scans and sends back the networks it sees
The password goes encrypted, the device joins and confirms

Scan the code
With the ordinary camera app. The code holds the device's name and a secret that proves the person has the device in hand, in the part of the address that never leaves the phone.
Nothing to install
An iPhone opens an App Clip, a small piece of an app that appears from the camera and disappears afterwards. Android phones and computers open a web page that can talk Bluetooth.
The device lists the networks
The device scans for itself, so the list shows only networks it can really join: on a band it supports and within range. Nobody picks a network the device can't connect to.
Encrypted, and confirmed
The password goes over an encrypted Bluetooth session. The device tries it and reports back within about twenty seconds: online, wrong password, or network not found.

Features

Made for people who will never read your manual

Each of these exists because something went wrong during setup on real hardware, and we made sure it can't anymore.

No app to install

Why Every extra step before setup loses customers, and "download our app" is the biggest one. Everyone already knows how to scan a QR code with the camera.

For example A customer unboxes a lamp, points the camera at the sticker, and the setup card slides up. No App Store, no account.

Works from a computer too

Why Setting devices up at a desk, in a lab or at the end of a production line is quicker with a keyboard. Chrome or Edge on a computer with Bluetooth, which almost every modern laptop has, does the same job as a phone.

For example An installer opens the setup links from the delivery sheet on a laptop and sets up twenty sensors one after another.

Only networks that will work

Why The phone's list of networks is not the device's. Showing what the device itself hears removes the most common support ticket: someone picked a network the device can't join – a 5 GHz network on a chip that only does 2.4 GHz, say.

For example The home has "Novák" and "Novák 5G". The page offers only the one the device can join.

Errors people understand

Why "Connection failed" sends people to support. pairble tells a wrong password from a network that is out of reach, answers in about twenty seconds rather than a minute, and lets people fix it without starting over.

For example A typo in the password: the page says so, the person corrects it, the device joins. Same session, no restart.

A plan B is built in

Why No Bluetooth, no internet on the phone to fetch the App Clip, an old browser? At the same time as Bluetooth, the device opens its own Wi‑Fi network with the setup page stored in its flash.

For example A cottage with no signal: a second QR code joins the phone to the device's network and the setup page opens by itself.

Survives a new router

Why Routers get replaced and passwords get changed. When the stored network stops answering, setup reopens by itself, and nothing is erased, so a router that was only restarting costs nothing.

For example The internet provider swaps the router. Two minutes later the device is ready to be set up again: scan the same sticker, pick the new network, done.

Secure by default

Why An encrypted session keyed by a secret unique to each unit. That secret stays out of server logs, and the Wi‑Fi password is never written to any log.

For example Support asks for a device log. It shows the network's name, never its password.

Speaks ten languages

Why The setup page and the App Clip follow the phone's language: English, Czech, Slovak, German, Polish, French, Spanish, Italian, Portuguese and Dutch.

For example A German phone sees "WLAN einrichten", a French one "Configurer le Wi‑Fi", with no setting to change.

Code

Real code, straight from the examples

Every sample was built and run on an ESP32-S3. The output under it is what the device actually printed.

Add the component

Run this in your ESP-IDF project. The component manager fetches pairble and its one dependency on the next build.

shell

# in your project's directory
idf.py add-dependency "pairble/pairble"

Output

Executing action: add-dependency
NOTICE: Created "~/myproduct/main/idf_component.yml"
NOTICE: Successfully added dependency "pairble/pairble": "*" to component "main"
Done

One call does it all

With a network stored, the device connects. Without one, it opens setup and prints the address to put in the QR code. On first boot it also creates the unit's secret and keeps it.

#include "esp_log.h"
#include "pairble.h"

void app_main(void)
{
    /* Connects if a network is stored, otherwise opens setup. */
    ESP_ERROR_CHECK(pairble_start(NULL));

    /* This address goes into the QR code on the box. */
    ESP_LOGI("example", "QR code: %s", pairble_setup_url());
}

Output

I (544) pairble: generated a proof of possession for this unit
I (674) pairble: advertising as PAIRBLE-BA6550
I (684) pairble: setup: https://pairble.com/s#name=PAIRBLE-BA6550&pop=FRXCVAA75NDV
I (824) pairble: SoftAP "PAIRBLE-BA6550" up at 192.168.4.1 alongside BLE; free heap 167352 B
I (824) pairble: wifi qr: WIFI:S:PAIRBLE-BA6550;T:WPA;P:FRXCVAA75NDV;;
I (834) example: QR code: https://pairble.com/s#name=PAIRBLE-BA6550&pop=FRXCVAA75NDV

Arduino and PlatformIO

The same component as an Arduino library, for arduino-esp32 3.x. Arduino's WiFi object knows about the connection, so HTTPClient and the rest work as usual. It also builds for the Raspberry Pi Pico W and Pico 2 W (arduino-pico) with the same API: there, call pairble_loop() from loop().

platformio.ini

; PlatformIO needs the pioarduino platform for arduino-esp32 3.x.
[env:esp32]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
framework = arduino
board = esp32dev
board_build.partitions = huge_app.csv
lib_deps = pairble/pairble-arduino

Arduino

#include <WiFi.h>
#include <pairble.h>

void setup()
{
  Serial.begin(115200);
  // Connects if a network is stored, otherwise opens setup.
  ESP_ERROR_CHECK(pairble_start(NULL));
  Serial.printf("QR code: %s\n", pairble_setup_url());
}

void loop()
{
  // Arduino's WiFi works as usual once pairble is online.
  static bool online;
  if (!online && WiFi.status() == WL_CONNECTED)
  {
    online = true;
    Serial.printf("online at %s\n", WiFi.localIP().toString().c_str());
  }
  delay(100);
}

Output

QR code: https://pairble.com/s#name=PAIRBLE-BA6550&pop=K3F9Q2M7ZX4P
online at 192.168.1.171

In an existing application

pairble leaves anything the application has already set up alone. The callback tells you when to blink an LED and when to start your own work.

#include "esp_log.h"
#include "pairble.h"

static const char *TAG = "lamp";

static void on_pairble(pairble_event_t event, pairble_fail_reason_t reason, void *ctx)
{
    switch (event) {
    case PAIRBLE_EVENT_STARTED:   /* Setup is open, waiting for a phone. */
        ESP_LOGI(TAG, "setup open - blink the LED");
        break;
    case PAIRBLE_EVENT_FAILED:    /* The phone shows the same message. */
        ESP_LOGW(TAG, "%s", reason == PAIRBLE_FAIL_WRONG_PASSWORD ? "wrong password"
                                                                  : "network not found");
        break;
    case PAIRBLE_EVENT_ONLINE:
        ESP_LOGI(TAG, "online - start the lamp's own work");
        break;
    case PAIRBLE_EVENT_OFFLINE:   /* pairble keeps retrying, and reopens setup after two minutes. */
        ESP_LOGW(TAG, "offline - LED red");
        break;
    default:
        break;
    }
}

void app_main(void)
{
    pairble_config_t config = PAIRBLE_CONFIG_DEFAULT();
    config.name_prefix = "LAMP-";   /* Advertises as LAMP-XXXXXX. */
    config.event_cb = on_pairble;
    ESP_ERROR_CHECK(pairble_start(&config));
    ESP_LOGI(TAG, "device %s", pairble_device_name());
}

Output

I (664) pairble: advertising as LAMP-BA6550
I (664) pairble: setup: https://pairble.com/s#name=LAMP-BA6550&pop=FRXCVAA75NDV
I (814) pairble: SoftAP "LAMP-BA6550" up at 192.168.4.1 alongside BLE; free heap 167344 B
I (814) pairble: wifi qr: WIFI:S:LAMP-BA6550;T:WPA;P:FRXCVAA75NDV;;
I (824) lamp: setup open - blink the LED
I (824) lamp: device LAMP-BA6550

Let people switch networks

Hold a button, or call one function from your own menu. The device stays on its current network until a phone connects, and replaces it only once the new one works.

sdkconfig

# Hold the BOOT button (GPIO 0) for 5 seconds to reopen setup.
CONFIG_PAIRBLE_SETUP_BUTTON_GPIO=0
CONFIG_PAIRBLE_SETUP_BUTTON_HOLD_SECONDS=5

#include "pairble.h"

/* Your own "Change Wi-Fi network" menu item. */
void menu_change_network(void)
{
    ESP_ERROR_CHECK(pairble_open_setup());
}

Output

I (584) pairble: credentials stored, connecting
W (3054) pairble: offline: network not found (reason 201), retrying
I (6634) menu: Change Wi-Fi network
I (6664) pairble: setup: https://pairble.com/s#name=PAIRBLE-BA6550&pop=FRXCVAA75NDV
I (6664) pairble: advertising as PAIRBLE-BA6550
I (6834) pairble: SoftAP "PAIRBLE-BA6550" up at 192.168.4.1 alongside BLE; free heap 165152 B
I (6844) pairble: wifi qr: WIFI:S:PAIRBLE-BA6550;T:WPA;P:FRXCVAA75NDV;;
I (6844) pairble: setup opened; staying on "Novák" until a phone connects
I (6954) pairble: trying the stored network "Novák" again

Settings for a product

Your own Bluetooth identity, a secret printed on the label, and a way back into setup for devices without a button. The setup address stays pairble.com, free in production too.

sdkconfig

# Your own Bluetooth service, so browsers offer only your devices.
CONFIG_PAIRBLE_SERVICE_UUID="7c3e6a51-2f0d-4b8e-9a61-5d2c8e4f1b07"
# The secret comes printed on the label (@pairble/cli), never generated.
CONFIG_PAIRBLE_POP_GENERATE=n
# What your customer sees in the list of devices.
CONFIG_PAIRBLE_NAME_PREFIX="LAMP-"
# No button? Switching it on three times in a row reopens setup.
CONFIG_PAIRBLE_POWER_CYCLE_COUNT=3

Output

I (683) pairble: advertising as LAMP-BA6550
I (693) pairble: setup open as LAMP-BA6550 (URL not logged: CONFIG_PAIRBLE_LOG_SETUP_URL)
I (853) pairble: SoftAP "LAMP-BA6550" up at 192.168.4.1 alongside BLE; free heap 166936 B
I (853) example: QR code: https://pairble.com/s#name=LAMP-BA6550&pop=FRXCVAA75NDV

One command per unit on the production line

Reads nothing from the device: give it the MAC and it creates the secret, the QR code for the label and the file that puts the secret on the chip.

The secret is random, so yours will differ.

shell

# The MAC is printed by: esptool.py read_mac
npx @pairble/cli unit --mac 20:6e:f1:ba:65:50 --prefix LAMP- --out unit-0001

Output

LAMP-BA6550
  url     https://pairble.com/s#name=LAMP-BA6550&pop=4QKQ0EWQBG92
  wifi    WIFI:S:LAMP-BA6550;T:WPA;P:4QKQ0EWQBG92;;
  files   unit-0001/qr.svg, wifi-qr.svg, nvs.csv, unit.json

Put the PoP on the chip (default partition table: nvs at 0x9000, 0x6000 bytes):
  python $IDF_PATH/components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py generate unit-0001/nvs.csv unit-0001/nvs.bin 0x6000
  esptool.py --port <port> write_flash 0x9000 unit-0001/nvs.bin

unit.json holds the PoP in clear text. Keep it with the production records, not in the repository.

The settings that matter

All of them live in menuconfig under "pairble". The defaults suit a development board.

Option	Default	What it does
`PAIRBLE_SETUP_URL`	`https://pairble.com/s`	The address in the QR code. pairble.com is free to use, in production too.
`PAIRBLE_SERVICE_UUID`	`021a9004-…`	The Bluetooth service the device advertises during setup.
`PAIRBLE_NAME_PREFIX`	`PAIRBLE-`	The start of the device's name; the end comes from its MAC address.
`PAIRBLE_POP_GENERATE`	`y`	Create the secret on first boot. Turn it off when the secret is printed on a label.
`PAIRBLE_SOFTAP`	`y`	Also offer setup over the device's own Wi‑Fi network.
`PAIRBLE_IMPROV_UART`	`n`	Also speak Improv Wi‑Fi over USB serial, for web installers such as ESP Web Tools.
`PAIRBLE_RECOVERY_AFTER_SECONDS`	`120`	Reopen setup after this many seconds offline. 0 means never.
`PAIRBLE_SETUP_BUTTON_GPIO`	`-1`	A button that reopens setup when held. -1 means none.
`PAIRBLE_POWER_CYCLE_COUNT`	`3`	Switch it on this many times quickly to reopen setup. 0 means never.
`PAIRBLE_BT_MEMORY`	`RELEASE_CLASSIC`	What happens to Bluetooth memory after setup.
`PAIRBLE_LOG_SETUP_URL`	`= POP_GENERATE`	Write the setup address, which contains the secret, to the log.

Guides

Step by step, from real situations

A lamp with a printed label

The classic product: the secret is created at the factory and printed on the box, never generated by the device.

In sdkconfig.defaults, set your own Bluetooth service and turn off secret generation (see "Product config" above).
At the end of the production line, read the unit's MAC address with esptool.py read_mac.
Run @pairble/cli unit with that MAC. It creates the secret, the QR code and the NVS file.
Write the NVS file to the chip with the two commands the tool prints.
Print the QR code on the label and on the box, with the device's name underneath for anyone who has to type it.
At home, the customer scans the box and the lamp is online half a minute later.

A device with a display

A thermostat or a clock can show its own QR code, so there is nothing to print.

Keep secret generation on. On first boot the device creates its secret and keeps it.
In your event callback, on PAIRBLE_EVENT_STARTED, draw pairble_setup_url() as a QR code.
For phones without Bluetooth, draw pairble_wifi_qr() next to it, which joins the device's own network.
On PAIRBLE_EVENT_SUCCESS, clear the codes and show the device's normal screen.

The customer changed their router

What happens without anyone touching the firmware, and what the person sees.

The stored network disappears. The device keeps trying, less often as time goes on, and your callback gets PAIRBLE_EVENT_OFFLINE with the reason. A good moment to turn an LED red.
After two minutes offline, setup reopens over Bluetooth and the device's own network. The old network is still tried every thirty seconds.
The customer scans the same sticker as on day one and picks the new network.
Only once the device has joined does the new network replace the old one. If the old router was only restarting, setup simply closes again.

An iPhone with no internet

In a basement or a holiday cottage, the phone can't download the App Clip. The device's own network takes over.

Scan the second QR code, the one for Wi‑Fi. The phone offers to join the device's network, protected by the same secret.
The setup page usually opens by itself. If it doesn't, open http://192.168.4.1 in the browser.
Pick the home network from the list the device found and type the password.
The device joins, the phone returns to its usual network, and the device's own network switches off.

Setting up at a desk

No phone needed: a laptop with Bluetooth and Chrome or Edge does the same.

Open the device's setup link on the computer. It is the address from the QR code, found in the production records or in the device's log.
Click Connect. The browser shows a list of nearby devices; choose the one with the name from the label.
Pick the network and type the password, exactly as on a phone.
Close the tab and move on to the next device. pairble lets go of the device as soon as you are done.

FAQ

Questions and troubleshooting

Why only 2.4 GHz networks?

Most of the chips supported today have a 2.4 GHz radio only (the ESP32-C5 also does 5 GHz). Because the device scans for itself, the list only shows networks it can really use, so nobody has to know about frequencies.

Why does the iPhone use an App Clip instead of the web page?

Safari on iPhone and iPad cannot talk to Bluetooth devices. An App Clip is Apple's way of running a small part of an app straight from the camera, without installing it. If the phone has no internet to fetch it, the device's own Wi‑Fi network works instead.

Can I set a device up from a computer?

Yes, with Chrome or Edge on Windows, macOS or ChromeOS and a computer with Bluetooth, which almost all modern laptops have. On Linux, Chrome's Bluetooth support may need to be switched on first. Firefox and Safari do not support Bluetooth on the web.

Does it work with web installers such as ESP Web Tools?

Yes. With PAIRBLE_IMPROV_UART on (in Arduino, call pairbleImprovSerial(Serial)) the device speaks Improv Wi‑Fi over USB, so the installer can set the network straight after flashing. As over Bluetooth, the old network stays until the new one works. It is off by default.

The phone doesn't find the device.

Check that Bluetooth is on and the device is within a few metres. While one phone or tab is connected, the device is invisible to everyone else. The setup page and the App Clip let go after two idle minutes, and the device itself drops an idle client after five. If nothing helps, switch the device off and on again.

It says the code doesn't match the device.

The code belongs to a different unit, or was typed in wrong. Codes are case-sensitive. Scan the code printed on the device itself, not a photo of someone else's box.

The page says the browser can't use Bluetooth.

Firefox and the browsers built into apps like Facebook or WhatsApp do not support Bluetooth. The page offers a button that opens it in Chrome.

What is supported today?

Every ESP32 with Bluetooth LE on ESP-IDF 5.1 or later: ESP32, C2, C3, C5, C6 and S3, including Arduino projects built on ESP-IDF. The ESP32-S2 has no Bluetooth, so the build stops with a clear error rather than producing a product that can't be set up. On Arduino, also the Raspberry Pi Pico W and Pico 2 W (arduino-pico with Bluetooth). More chips and platforms are on the way.

How much flash and memory does it take?

pairble itself is about 35 KB of flash, including the setup page in ten languages. The rest of a typical 1.1 MB firmware is ESP-IDF's Wi‑Fi and Bluetooth stacks, which any connected product needs. While setup is open it uses about 90 KB of RAM, and gives all of it back afterwards.

What if the power goes out during setup?

The network that worked before is kept aside until the new one is confirmed. After a power cut in the middle of an attempt, the device goes back to the old network on the next start.

How secure is it?

The phone and the device agree on a key with X25519, mix in the unit's 60-bit secret and encrypt with AES. The device's own network uses WPA2 with the same secret, and its setup page only answers devices connected to it. Whoever holds the code from the label can set the device up; that is the point, so keep labels off photos.

Can I use pairble.com in production, or my own domain?

pairble.com is free to use, in production too, with no limits: the setup page and the App Clip are ready. Your own domain is possible, but an iPhone then needs an App Clip of your own, approved by Apple and ideally part of your own app. Write to [email protected] and we will help you set it up.

What does it cost?

Nothing. pairble is open source under the Apache 2.0 licence, and that covers commercial products.

The box has a QR code. That's the whole manual.

Four steps, about thirty seconds

Scan the code

Nothing to install

The device lists the networks

Encrypted, and confirmed

Made for people who will never read your manual

No app to install

Works from a computer too

Only networks that will work

Errors people understand

A plan B is built in

Survives a new router

Secure by default

Speaks ten languages

Real code, straight from the examples

Add the component

One call does it all

Arduino and PlatformIO

In an existing application

Let people switch networks

Settings for a product

One command per unit on the production line

The settings that matter

Step by step, from real situations

A lamp with a printed label

A device with a display

The customer changed their router

An iPhone with no internet

Setting up at a desk

Questions and troubleshooting