Mobile device pairing

The mobile app supports multiple pairing modes. By passing a small set of parameters, device pairing can be embedded into the mobile app in a simple and reusable way.

1. Pairing methods

The mobile app currently supports:

• Wi-Fi hotspot pairing, also called AP pairing.
• QR-code pairing.
• Bluetooth pairing.
• Associated-device pairing.

2. Wi-Fi hotspot pairing

Wi-Fi hotspot pairing is also called AP pairing. The device enters hotspot mode first. The phone connects to the device hotspot so both sides are in the same LAN. The phone encrypts and sends the token, router SSID, password, and other information to the device. It also obtains the device MAC address and sends it to the cloud for binding.

2.1 Start device AP mode

During SDK initialization, fill in the Wi-Fi name and password used by the device. After the device enters pairing mode, select the device hotspot whose name starts with fastbee-device.

Tips

This example is only for reference. Developers should understand the implementation logic and adapt it to the actual hardware. The sample code targets a WeMOS D1 R1 device with an ESP8266 Wi-Fi module. Different chips may require different operations. For the complete process, see Quick start.

String randomName = "fastbee-device" + (String)random(1000);
const char *ap_ssid = randomName.c_str();
const char *ap_password = ""; // Open network.

char sta_ssid[32] = {0};
char sta_password[64] = {0};
char sta_user_id[32] = {0};

IPAddress local_IP(192, 168, 4, 1);
IPAddress gateway(192, 168, 4, 1);
IPAddress subnet(255, 255, 255, 0);

void initApConfig();

/**
 * AP mode.
 */
void initApConfig()
{
  WiFi.mode(WIFI_AP_STA);
  WiFi.softAPConfig(local_IP, gateway, subnet);
  WiFi.softAP(ap_ssid, ap_password);
  printMsg("AP pairing started. IP: " + WiFi.softAPIP().toString() + ", hotspot: " + (String)ap_ssid);
}

2.2 Start pairing from the mobile app

Open the mobile app, select provisioning, enter the Wi-Fi name and password, then wait for the device to connect to the network and start pairing.

2.3 Single-device and multi-device pairing

AP pairing supports both single-device and multi-device flows. To configure multiple devices at the same time, switch to the multi-device page and select the target devices.

3. QR-code pairing

Generate a QR code in the management platform. The mobile app scans and parses the QR-code content, then completes device binding.

3.1 QR-code format

The management platform can generate the QR code directly. You can also use a QR-code tool to generate QR codes in batches. The format is:

{
  "type": 1,                         // Scan and bind device.
  "deviceNumber": "53030200001310000001",
  "productId": 147,
  "productName": "Hikvision monitoring product"
}

4. Bluetooth pairing

4.1 Device broadcasts BLE signal

After power-on, the device enters BLE advertising mode and sends advertising packets so the mobile app can discover it.

An advertising packet usually contains:

1. Device name, such as BLE_Device_XXXX.
2. Device UUID, used to uniquely identify the device, such as MAC address or SN.
3. Device type, such as curtain motor or hub.
4. Signal strength, RSSI.
5. Optional vendor-defined fields, such as whether the device has already been paired.

4.2 App discovers and connects to the device

The app starts BLE scanning and looks for matching devices.

The app then:

1. Matches the device and confirms identity by MAC address or SN.
2. Selects the target device.
3. Sends a connection request and enters the connected state.

If the app cannot obtain the BLE advertising data, use manual add or scan to add.

Tips

Manual add requires a Bluetooth device ID. The device ID may be different on Android and iOS.

The QR-code format for scan-to-add can be customized. The current code parses the following format:

{
  "name": "FBDevice",
  "deviceId": "EC3D43A0-4D81-03A3-71FE-DE03D818694A"
}

If more attributes need to be displayed or parsed, adjust the mobile app code accordingly.

4.3 Send Wi-Fi account and password over BLE

The app sends the Wi-Fi account and password to the Bluetooth device. The exact data format is defined by the SDK.

4.4 Hub connects to Wi-Fi

The device closes the BLE connection and enters Wi-Fi connection mode. The app waits for the device to return pairing-success data. The current wait time is 13 seconds. Adjust this value according to the actual SDK behavior when needed.

After pairing succeeds, the device connects to the FastBee platform automatically. The device can also display a custom pairing-complete status defined by the SDK. In this example, the STATE indicator stays on.

5. Associated-device pairing

Associated-device pairing can bind multiple devices in batches.

5.1 Select associated add

Open the mobile app and select associated add.

5.2 Add device and product information

Enter the related device and product information.