Bluetooth Device Pairing

Last Updated on : 2026-02-02 02:51:29download

In the HarmonyOS system, Bluetooth devices currently support only two types of Bluetooth pairing methods.

Bluetooth type	Description	Example
Bluetooth Low Energy (LE)	A point-to-point connection is created between a Bluetooth or Bluetooth LE device and a mobile phone.	Body fat scales, wrist-worn trackers, thermostats, electric toothbrushes, and smart locks
Combo devices	Devices that support both Bluetooth and other protocols, such as Wi-Fi and Bluetooth LE combo, can be paired over Bluetooth.	Bluetooth mesh gateways, IP cameras (IPCs), and devices that support Bluetooth and Wi-Fi combo

Functional description

The Bluetooth module supports device pairing functionality, enabling device scanning, discovery, and pairing operations.

Request Bluetooth permission

Request the Bluetooth permission ohos.permission.ACCESS_BLUETOOTH. For more information on configuring and requesting permissions, see Declaring Permissions and Requesting User Authorization.

API example for Bluetooth device pairing

For more information, see Device Pairing.

Scan for Bluetooth devices

Implement the scan result listener

  scanListener: TSmartScannerListener = {
    onDeviceFound: (scanResult: TSmartScannerResult): void => {
      // Implement the relevant logic.
    }
  };

Construct the scanner instance

// Create a scanner instance using the scan listener
this.scanner = new TSmartScannerBuilder(this.scanListener);
// Set the scan timeout and method (Bluetooth scanning mode)
this.scanner.setScanTimeout(120000).addScanMode(TSmartScanMode.SCAN_MODE_BLE);

Start scanning

this.scanner.startScan();

Stop scanning

this.scanner.stopScan();

Scan results

Based on the scan results returned by TSmartScannerResult in the Implement a listener for scan results section, decide whether to proceed with Bluetooth pairing or combo pairing. The parameters are described as follows:

Name	Type	Required	Description
uniqueId	string	Yes	The unique ID of the specified device.
productId	string	Yes	The product ID.
deviceType	TSmartDeviceType	Yes	The device type. For more information, see the explanation below the table.
name	string	Yes	The device name. The value is obtained via a network request. If the request fails, it will default to `New Device`.
icon	string	Yes	The URL of a device icon. The value is obtained via a network request. If the request fails, it will default to an empty string.
scannedBleDevice	Device	No	This value is present when it is a Bluetooth device or a combo device.

TSmartDeviceType

export enum TSmartDeviceType {
  BLE,              // Bluetooth device
  WIFI_BLE,         // Combo device
  WIRED             // Wired device
}

Pairing

Implement methods in the pairing listener

activatorListener: ITSmartActivatorListener = {
    onActiveSetpAndError: (step: TSmartActivatorStep, error?: Error, device?: TSmartDeviceModel) => {
      // Implement the relevant logic.
    },

    onActiveSuccess: (deviceModel: TSmartDeviceModel) => {
      // Handle the logic for successful pairing, such as updating the UI and navigating to the next page.
    },
};

Create a pairing instance

For a Bluetooth LE device (scanResult.deviceType= TSmartDeviceType.BLE), create a Bluetooth LE pairing instance as follows:

const activatorBuilder = TSmartActivator.buildBleActivatorBuilder(homeId, 120000,listener)
this.activator = TSmartActivator.createActivator(activatorBuilder);
// Add a device to be paired
this.activator.appendDevice(scanResult.scannedBleDevice)

For a combo device (scanResult.deviceType = TSmartDeviceType.WIFI_BLE), create a combo pairing instance as follows:

const activatorBuilder = TSmartActivator.buildBleWifiActivatorBuilder(
                homeId,
                this.ssid,
                this.password,
                120000,
                listener,
              )
this.activator = TSmartActivator.createActivator(activatorBuilder);
// Add a device to be paired
this.activator.appendDevice(scanResult.scannedBleDevice)

Start pairing

this.activator.startActive()

Stop pairing

this.activator.stopActive()

Prev DocSub-Device Pairing

Next DocScan QR Code on Device