WiFi setup over Bluetooth

WiFi devices never need the network name and password in their firmware. The library receives them over Bluetooth Low Energy (BLE) from the ThingsLinker app or the User Portal, while the user adds the device, and saves them in flash.

When the device is in setup mode

At power-up the device:

1. joins the saved WiFi network, if it has one and the network is in range;
2. otherwise, or if the saved password is rejected, starts setup mode: it advertises over Bluetooth and waits for WiFi details.

A rejected password is cleared, so the next boot goes straight to setup mode.

In setup mode, if the WiFi details it receives do not work, the device stays in setup mode so the user can try again.

The device's Bluetooth name

In setup mode the device appears as ThingsLinker_<chip ID>, for example ThingsLinker_BC6575C55494.

You can change the first part to your brand with setBLEName(), before begin():

iot.setBLEName("AcmeSensors");   // appears as AcmeSensors_BC6575C55494
iot.begin();

A custom name affects setup in the app

The ThingsLinker app looks for devices whose name starts with ThingsLinker_. A device with a custom name can still be set up from the User Portal, which lists every nearby device to choose from, but the app will not find it. Keep the default name if your customers use the app.

Set the WiFi up again

When a user changes their router, the device must forget its network and go back into setup mode. This can be done three ways, and all of them do the same thing:

From	How	Needs
The device	Hold the reset button for 3 seconds	iot.resetButton() in setup()
The app	Open the device, tap WiFi, then Reset	The device online
The User Portal	Change WiFi on the device card, then Reset device WiFi	The device online

void setup() {
  iot.resetButton();          // hold BOOT (GPIO 0) for 3 seconds
  // iot.resetButton(41);     // or your own button, on GPIO 41
  iot.begin();
}

void loop() {
  iot.run();                  // watches the button and the app's command
}

The reset erases the saved network name and password from flash (your own saved data is kept) and restarts the device. With no network saved, it comes up in setup mode, exactly as on its first boot, and the user gives it the new network.

• Reset from the app and portal is on by default. To allow only the button, call iot.remoteReset(false) before iot.begin().
• The app and portal can only reach a device that is online. An offline device must be reset with its button, so give your product one and tell your customers about it, for example in its manual.
• You can also call iot.resetWiFi() from your own code. If the device was connected to WiFi, it restarts into setup mode, so code after the call does not run.
• GSM devices have no WiFi, so they have no reset.

Requirements on the user's side

• A 2.4 GHz WiFi network. The ESP32 cannot join 5 GHz networks.
• For the User Portal, a browser with Web Bluetooth: Chrome or Edge, on a computer or Android.