目录

Device Discovery

Introduction

This document describes how to implement the Bluetooth device discovery capabilities, such as scanning for nearby devices, setting the Bluetooth scan mode, and retrieving information about paired devices.

How to Develop

[h2]Applying for Required Permissions

Apply for the ohos.permission.ACCESS_BLUETOOTH permission. For details about how to configure and apply for permissions, see Declaring Permissions and Requesting User Authorization.

[h2]Importing Required Modules

Import the connection and BusinessError modules.

import { connection } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';

[h2]Scanning for Nearby Bluetooth Devices

This function allows your application to scan for nearby Bluetooth devices and obtain partial information about them. This process can also be referred to as search, discovery, or find. Only nearby Bluetooth devices that are in a discoverable state can be scanned by the local Bluetooth device.

1. Subscribing to Scan Result Reporting Events

// Define the callback for scan result reporting events.
function onReceiveEvent(data: Array<connection.DiscoveryResult>) {
  console.info('bluetooth device: '+ JSON.stringify(data));
}

try {
  // Subscribe to scan result reporting events.
  connection.on('discoveryResult', onReceiveEvent);
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
// Define the callback for scan result reporting events.
function onReceiveEvent(data: Array<string>) {
  console.info('bluetooth device: '+ JSON.stringify(data));
}

try {
  // Subscribe to scan result reporting events.
  connection.on('bluetoothDeviceFind', onReceiveEvent);
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

2. Initiating a Device Scan

A scan process takes about 12 seconds after being initiated. The application can initiate pairing, connection, and data transmission with the discovered Bluetooth device. For details, see Device Pairing and SPP-based Connection and Data Transmission.

try {
  // Check whether scanning is in progress on the local device.
  let scan = connection.isBluetoothDiscovering();
  if (!scan) {
    // Start scanning for devices if a scan is not in progress.
    connection.startBluetoothDiscovery();
  }
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

3. Stopping the Device Scan

Scanning is a process that consumes a large amount of Bluetooth hardware resources. When the expected Bluetooth device is discovered, the device scanning must be stopped before a connection is initiated.

// Define the callback for scan result reporting events.
function onReceiveEvent(data: Array<string>) {
  console.info('bluetooth device: '+ JSON.stringify(data));
}

try {
  // Check whether scanning is in progress on the local device.
  let scan = connection.isBluetoothDiscovering();
  if (scan) {
    // Stop scanning for devices if a scan is in progress.
    connection.stopBluetoothDiscovery();
  }
  // If scanning is no longer needed, unsubscribe from scan result reporting events.
  connection.off('bluetoothDeviceFind', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

[h2]Setting the Bluetooth Scan Mode of the Local Device

The Bluetooth scan mode of the local device determines whether the local device can be scanned or connected by other Bluetooth devices. Typically, non-system applications do not need to concern themselves with this mode, as the system settings application will handle its configuration.

try {
  // Obtain the current scan mode of the local device.
  let scanMode: connection.ScanMode = connection.getBluetoothScanMode();
  console.info('scanMode: ' + scanMode);
  if (scanMode != connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE) {
    // Set the scan mode of the local device to SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE.
    connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 0);
  }
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

[h2]Retrieving Information About Paired Devices

To streamline device scanning, check if the device is paired before initiating a scan. You can also initiate connection and data transmission processes for paired devices. For details, see Device Pairing and SPP-based Connection and Data Transmission.

try {
  // Obtain information about the paired devices.
  let devices = connection.getPairedDevices();
  console.info('pairedDevices: ' + JSON.stringify(devices));
  // If the device address is known, you can actively query whether the device is paired.
  if (devices.length > 0) {
    let pairState = connection.getPairState(devices[0]);
    console.info('device: '+ devices[0] + ' pairState is ' + pairState);
  }
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

Sample Code

import { connection } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export class DiscoveryDeviceManager {
  // Define the callback for scan result reporting events.
  onReceiveEvent = (data: Array<string>) => {
    console.info('bluetooth device: '+ JSON.stringify(data));
  };

  public startDiscovery() {
    try {
      connection.on('bluetoothDeviceFind', this.onReceiveEvent);
    } catch (err) {
      console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
    }
    try {
      // Check whether scanning is in progress on the local device.
      let scan = connection.isBluetoothDiscovering();
      if (!scan) {
        // Start scanning for devices if a scan is not in progress.
        connection.startBluetoothDiscovery();
      }
    } catch (err) {
      console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
    }
  }

  public stopDiscovery() {
    try {
      // Check whether scanning is in progress on the local device.
      let scan = connection.isBluetoothDiscovering();
      if (scan) {
        // Stop scanning for devices if a scan is in progress.
        connection.stopBluetoothDiscovery();
      }
      // If scanning is no longer needed, unsubscribe from scan result reporting events.
      connection.off('bluetoothDeviceFind', this.onReceiveEvent);
    } catch (err) {
      console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
    }
  }

  public setScanMode() {
    try {
      // Obtain the current scan mode of the local device.
      let scanMode: connection.ScanMode = connection.getBluetoothScanMode();
      console.info('scanMode: ' + scanMode);
      if (scanMode != connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE) {
        // Set the scan mode of the local device to SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE.
        connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 0);
      }
    } catch (err) {
      console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
    }
  }

  public getPairedDevices() {
    try {
      // Obtain information about the paired devices.
      let devices = connection.getPairedDevices();
      console.info('pairedDevices: ' + JSON.stringify(devices));
      // If the device address is known, you can actively query whether the device is paired.
      if (devices.length > 0) {
        let pairState = connection.getPairState(devices[0]);
        console.info('device: '+ devices[0] + ' pairState is ' + pairState);
      }
    } catch (err) {
      console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
    }
  }
}

let discoveryDeviceManager = new DiscoveryDeviceManager();
export default discoveryDeviceManager as DiscoveryDeviceManager;