We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
Advanced filters
API versionAll
DeviceAll
Atomic service APIsNot filter by this

@ohos.bluetooth.connection (Bluetooth Connection Module)

Last updated: 2026-06-02 07:02
Content overview
Modules to Import
ProfileConnectionState
ProfileId
ProfileUuids12+
MajorClass
MajorMinorClass
BluetoothAddress21+
connection.pairDevice
connection.pairDevice
connection.pairDevice21+
connection.getRemoteDeviceName
connection.getRemoteDeviceName16+
connection.getRemoteDeviceClass
connection.getRemoteDeviceTransport20+
connection.getRemoteProfileUuids12+
connection.getRemoteProfileUuids12+
connection.getLocalName
connection.getPairedDevices
connection.getPairState11+
connection.getProfileConnectionState
connection.setDevicePairingConfirmation
connection.setDevicePinCode
connection.setDevicePinCode
connection.setLocalName(deprecated)
connection.setBluetoothScanMode
connection.getBluetoothScanMode
connection.startBluetoothDiscovery
connection.stopBluetoothDiscovery
connection.isBluetoothDiscovering11+
connection.setRemoteDeviceName12+
connection.getRemoteDeviceBatteryInfo12+
connection.on('batteryChange')12+
connection.off('batteryChange')12+
connection.on('bluetoothDeviceFind')
connection.off('bluetoothDeviceFind')
connection.on('bondStateChange')
connection.off('bondStateChange')
connection.on('pinRequired')
connection.off('pinRequired')
connection.on('discoveryResult')18+
connection.off('discoveryResult')18+
connection.onScanModeChange23+
connection.offScanModeChange23+
connection.getLastConnectionTime15+
connection.connectAllowedProfiles16+
connection.connectAllowedProfiles16+
connection.getVirtualAddressByHash24+
BondStateParam
PinRequiredParam
DeviceClass
BatteryInfo12+
BluetoothTransport
ScanMode
BondState
UnbondCause12+
DeviceChargeState12+
DiscoveryResult18+
HashAlgorithmType24+
Expand

The connection module provides capabilities for pairing with, connecting to, and querying the status of Bluetooth devices.

NOTE

The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

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

ProfileConnectionState

type ProfileConnectionState = constant.ProfileConnectionState

Defines the connection status of the Bluetooth profile. Supported Bluetooth profiles include Advanced Audio Distribution Profile (A2DP), Hands-Free Profile (HFP), and Human Interface Device (HID).

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Type Description
constant.ProfileConnectionState Connection status of the Bluetooth profile.

ProfileId

type ProfileId = constant.ProfileId

Enumerates Bluetooth profiles.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Type Description
constant.ProfileId Bluetooth profile.

ProfileUuids12+

type ProfileUuids = constant.ProfileUuids

Defines the UUID of the Bluetooth profile.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Type Description
constant.ProfileUuids Defines the UUID of the Bluetooth profile.

MajorClass

type MajorClass = constant.MajorClass

Defines the Bluetooth device major class. This is a standard field in the Bluetooth protocol.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Type Description
constant.MajorClass Bluetooth device major class.

MajorMinorClass

type MajorMinorClass = constant.MajorMinorClass

Defines the Bluetooth device subclass, which is further classified based on MajorClass. This is a standard field in the Bluetooth protocol.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Type Description
constant.MajorMinorClass Bluetooth device subclass.

BluetoothAddress21+

type BluetoothAddress = common.BluetoothAddress

Defines the address information of a Bluetooth device, including the address and address type.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Type Description
common.BluetoothAddress Address information of the Bluetooth device.

connection.pairDevice

pairDevice(deviceId: string, callback: AsyncCallback<void>): void

Initiates pairing with the peer Bluetooth device. This API uses an asynchronous callback to return the result.

  • If you do not know the address type of the target device, you are advised to call this API to initiate pairing.
  • You can obtain the Bluetooth pairing status from the callback of on('bondStateChange').

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer Bluetooth device, for example, XX:XX:XX:XX:XX:XX.
callback AsyncCallback<void> Yes Callback used to return the result. If the pairing is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// callback
try {
    connection.pairDevice('11:22:33:44:55:66', (err: BusinessError) => {
        console.info('pairDevice, device name err:' + JSON.stringify(err));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.pairDevice

pairDevice(deviceId: string): Promise<void>

Initiates pairing with the peer Bluetooth device. This API uses a promise to return the result.

  • If you do not know the address type of the target device, you are advised to call this API to initiate pairing.
  • You can obtain the Bluetooth pairing status from the callback of on('bondStateChange').

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer Bluetooth device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// promise
try {
    connection.pairDevice('11:22:33:44:55:66').then(() => {
        console.info('pairDevice');
    }, (error: BusinessError) => {
        console.error('pairDevice: errCode:' + error.code + ',errMessage' + error.message);
    })

} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.pairDevice21+

pairDevice(deviceId: BluetoothAddress): Promise<void>

Initiates pairing with the peer Bluetooth device. This API uses a promise to return the result.

  • If you know the MAC address and address type of the target device, you are advised to call this API to initiate pairing.
  • You can obtain the Bluetooth pairing status from the callback of on('bondStateChange').

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId BluetoothAddress Yes Address information of the peer Bluetooth device, including the address and address type.

Return value

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.ConnectivityKit';
// promise
try {
    let btAddr: common.BluetoothAddress = {
        "address": '11:22:33:44:55:66', // Actual or virtual MAC address of the target device.
        "addressType": common.BluetoothAddressType.REAL, // Address type of the target device.
    }
    connection.pairDevice(btAddr).then(() => {
        console.info('pairDevice');
    }, (error: BusinessError) => {
        console.error('errCode: ' + error.code + ', errMessage' + error.message);
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteDeviceName

getRemoteDeviceName(deviceId: string): string

Obtains the name of the peer Bluetooth device.

  • Starting from API version 21, this API can be used to obtain the device name by using the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
string Device name (a string) obtained.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX');
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteDeviceName16+

getRemoteDeviceName(deviceId: string, alias?: boolean): string

Obtains the name of the peer device. The alias parameter is optional.

  • Starting from API version 21, this API can be used to obtain the device name by using the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 16.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.
alias boolean No

Whether to obtain the alias of the peer device.

- If alias is present, the application determines whether to obtain the alias of the peer device. The value true means to obtain the alias, and the value false means to obtain the original name .

- If alias is not present, the default value is true, which means to obtain the alias of the peer device.

Return value

Expand
Type Description
string Device name (a string) obtained.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Failed to obtain the name or alias of the peer Bluetooth device.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX', true);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteDeviceClass

getRemoteDeviceClass(deviceId: string): DeviceClass

Obtains the class of the peer Bluetooth device.

  • Starting from API version 18, this API does not verify the ohos.permission.ACCESS_BLUETOOTH permission.
  • Starting from API version 21, this API can be used to obtain the device class by using the actual MAC address of the peer device.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
DeviceClass Class of the peer device.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let remoteDeviceClass: connection.DeviceClass = connection.getRemoteDeviceClass('XX:XX:XX:XX:XX:XX');
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteDeviceTransport20+

getRemoteDeviceTransport(deviceId: string): BluetoothTransport

Obtains the transport type of the peer Bluetooth device.

  • Starting from API version 21, this API can be used to obtain the transport type of the peer device by using the actual MAC address of the peer device.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
BluetoothTransport Transport type of the peer device.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Get transport failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let transport: connection.BluetoothTransport = connection.getRemoteDeviceTransport('XX:XX:XX:XX:XX:XX');
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteProfileUuids12+

getRemoteProfileUuids(deviceId: string, callback: AsyncCallback<Array<ProfileUuids>>): void

Obtains the profile of the peer Bluetooth device based on the specified UUID. This API uses an asynchronous callback to return the result.

  • You are advised to use this API only for paired devices.
  • Starting from API version 21, this API can be used to obtain the profile of the peer Bluetooth device based on the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.
callback AsyncCallback<Array<ProfileUuids>> Yes Callback used to return the result. If the operation is successful, err is undefined, and the set of supported profiles is returned. Otherwise, err is an error object.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX', (err: BusinessError, data: Array<connection.ProfileUuids>) => {
        console.info('getRemoteProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteProfileUuids12+

getRemoteProfileUuids(deviceId: string): Promise<Array<ProfileUuids>>

Obtains the profile of the peer Bluetooth device based on the specified UUID. This API uses a promise to return the result.

  • You are advised to use this API only for paired devices.
  • Starting from API version 21, this API can be used to obtain the profile of the peer Bluetooth device based on the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
Promise<Array<ProfileUuids>> Promise used to return the set of supported profiles.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX').then(() => {
        console.info('getRemoteProfileUuids');
    }, (err: BusinessError) => {
        console.error('getRemoteProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getLocalName

getLocalName(): string

Obtains the name of the local Bluetooth device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Expand
Type Description
string Name of the local Bluetooth device.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let localName: string = connection.getLocalName();
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getPairedDevices

getPairedDevices(): Array<string>

Obtains the addresses of paired Bluetooth devices.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Expand
Type Description
Array<string>

Addresses of paired Bluetooth devices.

For security purposes, the device addresses obtained are virtual MAC addresses.

- The virtual addresses of paired Bluetooth devices will not change.

- If Bluetooth is disabled and then enabled again, the virtual address will change immediately.

- If the pairing is canceled, the Bluetooth subsystem will determine when to change the address based on the actual usage of the address. If the address is being used by another application, the address will not change immediately.

- To persistently save the addresses, call access.addPersistentDeviceId.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let devices: Array<string> = connection.getPairedDevices();
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getPairState11+

getPairState(deviceId: string): BondState

Obtains the pairing status of the peer Bluetooth device.

  • Starting from API version 21, this API can be used to obtain the pairing status of the peer Bluetooth device based on the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
BondState Bluetooth pairing state obtained.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let res: connection.BondState = connection.getPairState("XX:XX:XX:XX:XX:XX");
    console.info('getPairState: ' + res);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getProfileConnectionState

getProfileConnectionState(profileId?: ProfileId): ProfileConnectionState

Obtains the connection status of a Bluetooth profile. The ProfileId parameter is optional.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
profileId ProfileId No

Bluetooth profile. If ProfileId is present, the connection status of the specified profile is returned. If ProfileId is not present, the connection status of all supported profiles is returned in the following order:

- If a profile is connected, STATE_CONNECTED is returned.

- If a profile is being connected, STATE_CONNECTING is returned.

- If a profile is being disconnected, STATE_DISCONNECTING is returned.

- If none of the preceding conditions is met, STATE_DISCONNECTED is returned.

Return value

Expand
Type Description
ProfileConnectionState Connection status of the profile.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Incorrect parameter types.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900004 Profile not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { constant } from '@kit.ConnectivityKit';
try {
    let result: connection.ProfileConnectionState = connection.getProfileConnectionState(constant.ProfileId.PROFILE_A2DP_SOURCE);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.setDevicePairingConfirmation

setDevicePairingConfirmation(deviceId: string, accept: boolean): void

Confirms the pairing request from the peer Bluetooth device.

  • You can obtain the pairing status of the peer Bluetooth device from the callback of on('pinRequired').

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH (available only for system applications)

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.
accept boolean Yes Whether to accept the pairing request from the peer device. The value true means to accept the pairing request, and the value false means the opposite.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// Subscribe to the pinRequired event and configure the pairing confirmation after receiving a pairing request from the peer device.
function onReceivePinRequiredEvent(data: connection.PinRequiredParam) { // data is the input parameter for the pairing request.
    console.info('pin required  = '+ JSON.stringify(data));
    connection.setDevicePairingConfirmation(data.deviceId, true);
}
try {
    connection.on('pinRequired', onReceivePinRequiredEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.setDevicePinCode

setDevicePinCode(deviceId: string, code: string, callback: AsyncCallback<void>): void

Sets the PIN used to complete Bluetooth pairing. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes MAC address of the peer device, for example, XX:XX:XX:XX:XX:XX.
code string Yes PIN code entered by the user. The value is a string of 0 (not included) to 16 (included) characters, for example, 12345.
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// callback
try {
    connection.setDevicePinCode('11:22:33:44:55:66', '12345', (err: BusinessError) => {
        console.info('setDevicePinCode,device name err: ' + JSON.stringify(err));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.setDevicePinCode

setDevicePinCode(deviceId: string, code: string): Promise<void>

Sets the PIN used to complete Bluetooth pairing. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes MAC address of the peer device, for example, XX:XX:XX:XX:XX:XX.
code string Yes PIN code entered by the user. The value is a string of 0 (not included) to 16 (included) characters, for example, 12345.

Return value

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// promise
try {
    connection.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => {
        console.info('setDevicePinCode');
    }, (error: BusinessError) => {
        console.error('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message);
    })

} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.setLocalName(deprecated)

setLocalName(name: string): void

Sets the name of the local Bluetooth device. The value cannot be an empty string. If the value is an empty string, the operation will fail.

NOTE

This API is supported since API version 10 and deprecated since API version 12. No substitute is provided.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
name string Yes Bluetooth name. The value is a string of 0 (not included) to 248 (included) bytes.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.setLocalName('device_name');
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.setBluetoothScanMode

setBluetoothScanMode(mode: ScanMode, duration: number): void

Sets the Bluetooth scan mode, which determines whether the local device can be connected or discovered. This API is used together with the onScanModeChange API to listen for Bluetooth scan mode change events in real time.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
mode ScanMode Yes Bluetooth scan mode to set. If the scan times out (duration is not 0) when the scan mode is SCAN_MODE_GENERAL_DISCOVERABLE, the scan mode will be reset to SCAN_MODE_CONNECTABLE.
duration number Yes Duration during which the device can be discovered, in milliseconds. If the value is set to 0, the device can be discovered permanently.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    // The device can be discovered and connected only when the discoverable and connectable mode is used.
    connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getBluetoothScanMode

getBluetoothScanMode(): ScanMode

Obtains the Bluetooth scan mode. This API is used together with the onScanModeChange API to listen for Bluetooth scan mode change events in real time.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Expand
Type Description
ScanMode Bluetooth scan mode obtained.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let scanMode: connection.ScanMode = connection.getBluetoothScanMode();
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.startBluetoothDiscovery

startBluetoothDiscovery(): void

Starts a Bluetooth scan for device discovery.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
function onReceiveEvent(data: Array<string>) {
    console.info('data length' + data.length);
}
try {
    connection.on('bluetoothDeviceFind', onReceiveEvent);
    connection.startBluetoothDiscovery();
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.stopBluetoothDiscovery

stopBluetoothDiscovery(): void

Stops the Bluetooth scan.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    connection.stopBluetoothDiscovery();
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.isBluetoothDiscovering11+

isBluetoothDiscovering(): boolean

Checks whether the local Bluetooth device is in the device scanning state.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Expand
Type Description
boolean Whether Bluetooth discovery is in process. The value true indicates that Bluetooth discovery is in process, and the value false indicates the opposite.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
    let res: boolean = connection.isBluetoothDiscovering();
    console.info('isBluetoothDiscovering: ' + res);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.setRemoteDeviceName12+

setRemoteDeviceName(deviceId: string, name: string): Promise<void>

Sets the name of the peer Bluetooth device. The value cannot be an empty string. If the value is an empty string, the operation will fail. This API uses a promise to return the result.

  • You are advised to use this API only for paired devices.
  • Starting from API version 21, this API can be used to set the name of the peer Bluetooth device based on the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes MAC address of the peer device, for example, XX:XX:XX:XX:XX:XX.
name string Yes Name of the peer device. The value is a string of 0 (not included) to 64 (included) bytes.

Return value

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
2900001 Service stopped.
2900003 Bluetooth disabled.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// promise
try {
    connection.setRemoteDeviceName('11:22:33:44:55:66', 'RemoteDeviceName').then(() => {
        console.info('setRemoteDeviceName success');
    }, (error: BusinessError) => {
        console.error('setRemoteDeviceName: errCode: ' + error.code + ',errMessage' + error.message);
    })
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getRemoteDeviceBatteryInfo12+

getRemoteDeviceBatteryInfo(deviceId: string): Promise<BatteryInfo>

Obtains the battery level of the peer Bluetooth device. This API uses a promise to return the result.

  • You can obtain the battery level of the peer Bluetooth device from the callback of on('batteryChange').
  • Starting from API version 21, this API can be used to obtain the battery level of the peer Bluetooth device based on the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes MAC address of the peer Bluetooth device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
Promise<BatteryInfo> Promise used to return the battery level information.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
2900001 Service stopped.
2900003 Bluetooth disabled.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// promise
try {
    connection.getRemoteDeviceBatteryInfo('11:22:33:AA:BB:FF').then((data: connection.BatteryInfo) => {
        console.info('getRemoteDeviceBatteryInfo success, DeviceType:' + JSON.stringify(data));
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.on('batteryChange')12+

on(type: 'batteryChange', callback: Callback<BatteryInfo>): void

Subscribes to battery change events of the peer device. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes Event type. The value batteryChange indicates the battery change event. This event is triggered when the battery level of the peer device changes.
callback Callback<BatteryInfo> Yes Callback used to return the battery level information.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => {
    console.info('BatteryInfo = '+ JSON.stringify(data));
}
try {
    connection.on('batteryChange', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.off('batteryChange')12+

off(type: 'batteryChange', callback?: Callback<BatteryInfo>): void

Unsubscribes from battery change events of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes Event type. The value batteryChange indicates the battery change event.
callback Callback<BatteryInfo> No

Callback for the unsubscription notification.

If this parameter is specified, it must be the same as the callback in connection.on('batteryChange'). If this parameter is not specified, all callbacks corresponding to the event type are unsubscribed.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => {
    console.info('BatteryInfo = '+ JSON.stringify(data));
}
try {
    connection.on('batteryChange', onReceiveEvent);
    connection.off('batteryChange', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.on('bluetoothDeviceFind')

on(type: 'bluetoothDeviceFind', callback: Callback<Array<string>>): void

Subscribes to scan result reporting events of Bluetooth devices. This API uses an asynchronous callback to return the result.

  • This API applies to both classic Bluetooth devices and BLE devices.

  • This API provides only the device address.

  • You are advised to use connection.on('discoveryResult') (supported since API version 18), which can obtain more detailed device information, including the device address, signal strength, name, and type.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes Event type. The value bluetoothDeviceFind indicates a scan result reporting event. A device scan starts when connection.startBluetoothDiscovery is called. This event is triggered when a device is discovered.
callback Callback<Array<string>> Yes

Callback used to return the set of device addresses.

For security purposes, the device addresses obtained are virtual MAC addresses.

- The virtual addresses of paired Bluetooth devices will not change.

- If Bluetooth is disabled and then enabled again, the virtual address will change immediately.

- If the pairing is canceled, the Bluetooth subsystem will determine when to change the address based on the actual usage of the address. If the address is being used by another application, the address will not change immediately.

- To persistently save the addresses, call access.addPersistentDeviceId.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
function onReceiveEvent(data: Array<string>) { // data is an array of Bluetooth device addresses.
    console.info('bluetooth device find = '+ JSON.stringify(data));
}
try {
    connection.on('bluetoothDeviceFind', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.off('bluetoothDeviceFind')

off(type: 'bluetoothDeviceFind', callback?: Callback<Array<string>>): void

Unsubscribes from Bluetooth scan result reporting events.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes Event type. The value bluetoothDeviceFind indicates a scan result reporting event.
callback Callback<Array<string>> No

Callback for the unsubscription notification.

If this parameter is specified, it must be the same as the callback in connection.on('bluetoothDeviceFind'). If this parameter is not specified, all callbacks corresponding to the event type are unsubscribed.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
function onReceiveEvent(data: Array<string>) {
    console.info('bluetooth device find = '+ JSON.stringify(data));
}
try {
    connection.on('bluetoothDeviceFind', onReceiveEvent);
    connection.off('bluetoothDeviceFind', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.on('bondStateChange')

on(type: 'bondStateChange', callback: Callback<BondStateParam>): void

Subscribes to Bluetooth pairing status change events. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes

Event type. The value bondStateChange indicates a Bluetooth pairing status change event.

This event is triggered when connection.pairDevice is called to initiate pairing or the local device receives a pairing request from another device.
callback Callback<BondStateParam> Yes Callback used to return the pairing status.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
function onReceiveEvent(data: connection.BondStateParam) { // data, as the input parameter of the callback, indicates the pairing state.
    console.info('pair state = '+ JSON.stringify(data));
}
try {
    connection.on('bondStateChange', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.off('bondStateChange')

off(type: 'bondStateChange', callback?: Callback<BondStateParam>): void

Unsubscribes from Bluetooth pairing status change events.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes Event type. The value bondStateChange indicates a Bluetooth pairing status change event.
callback Callback<BondStateParam> No

Callback for the unsubscription notification.

If this parameter is specified, it must be the same as the callback in connection.on('bondStateChange'). If this parameter is not specified, all callbacks corresponding to the event type are unsubscribed.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
function onReceiveEvent(data: connection.BondStateParam) {
    console.info('bond state = '+ JSON.stringify(data));
}
try {
    connection.on('bondStateChange', onReceiveEvent);
    connection.off('bondStateChange', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.on('pinRequired')

on(type: 'pinRequired', callback: Callback<PinRequiredParam>): void

Subscribes to pairing request events. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes

Event type. The value pinRequired indicates a pairing request event.

This event is triggered when connection.pairDevice is called to initiate pairing or the local device receives a pairing request from another device.
callback Callback<PinRequiredParam> Yes Callback used to return the pairing request.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
function onReceiveEvent(data: connection.PinRequiredParam) { // data is the pairing request parameter.
    console.info('pin required = '+ JSON.stringify(data));
}
try {
    connection.on('pinRequired', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.off('pinRequired')

off(type: 'pinRequired', callback?: Callback<PinRequiredParam>): void

Unsubscribes from pairing request events.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes Event type. The value pinRequired indicates a pairing request event.
callback Callback<PinRequiredParam> No

Callback for the unsubscription notification.

If this parameter is specified, it must be the same as the callback in connection.on('pinRequired'). If this parameter is not specified, all callbacks corresponding to the event type are unsubscribed.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
function onReceiveEvent(data: connection.PinRequiredParam) {
    console.info('pin required = '+ JSON.stringify(data));
}
try {
    connection.on('pinRequired', onReceiveEvent);
    connection.off('pinRequired', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.on('discoveryResult')18+

on(type: 'discoveryResult', callback: Callback<Array<DiscoveryResult>>): void

Subscribes to scan result reporting events of Bluetooth devices. This API uses an asynchronous callback to return the result.

  • This API applies to both classic Bluetooth devices and BLE devices.

  • The reported information includes the device address, signal strength, name, and type.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes Event type. The value discoveryResult indicates a scan result reporting event. A device scan starts when connection.startBluetoothDiscovery is called. This event is triggered when a device is discovered.
callback Callback<Array<DiscoveryResult>> Yes Callback used to return the set of scan results.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
let onReceiveEvent: (data: Array<connection.DiscoveryResult>) => void = (data: Array<connection.DiscoveryResult>) => { // data is an array of Bluetooth devices discovered.
    console.info('bluetooth device find = '+ JSON.stringify(data));
}
try {
    connection.on('discoveryResult', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.off('discoveryResult')18+

off(type: 'discoveryResult', callback?: Callback<Array<DiscoveryResult>>): void

Unsubscribes from the Bluetooth device discovered.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
type string Yes Event type. The value discoveryResult indicates a scan result reporting event.
callback Callback<Array<DiscoveryResult>> No

Callback for the unsubscription notification.

If this parameter is specified, it must be the same as the callback in connection.on('discoveryResult'). If this parameter is not specified, all callbacks corresponding to the event type are unsubscribed.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
let onReceiveEvent: (data: Array<connection.DiscoveryResult>) => void = (data: Array<connection.DiscoveryResult>) => { // data is an array of Bluetooth devices discovered.
    console.info('bluetooth device find = '+ JSON.stringify(data));
}
try {
    connection.on('discoveryResult', onReceiveEvent);
    connection.off('discoveryResult', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.onScanModeChange23+

onScanModeChange(callback: Callback<ScanMode>): void

Subscribes to Bluetooth scan mode change events. This API uses an asynchronous callback to return the result. If such events are subscribed to, after the current Bluetooth scan mode is changed by calling setBluetoothScanMode, the callback containing the latest scan mode will be received.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
callback Callback<ScanMode> Yes Callback used to return the latest Bluetooth scan mode.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900099 Operation failed.

Example

function ScanModeChangeEvent(scanMode: connection.ScanMode) {
    console.info(`Scan mode has changed, new mode: ${scanMode}`);
}
try {
    connection.onScanModeChange(ScanModeChangeEvent);
} catch (err) {
    console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
}

connection.offScanModeChange23+

offScanModeChange(callback?: Callback<ScanMode>): void

Unsubscribes from Bluetooth scan mode change events.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
callback Callback<ScanMode> No

Callback for the unsubscription notification.

If this parameter is passed, the value must be the same as that in connection.onScanModeChange. If this parameter is not passed, all callbacks for the Bluetooth scan mode change will be unregistered.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported.
2900099 Operation failed.

Example

function ScanModeChangeEvent(scanMode: connection.ScanMode) {
    console.info(`Scan mode has changed, new mode: ${scanMode}`);
}
try {
    connection.offScanModeChange(ScanModeChangeEvent);
} catch (err) {
    console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
}

connection.getLastConnectionTime15+

getLastConnectionTime(deviceId: string): Promise<number>

Obtains the latest connection time of the peer Bluetooth device. This API uses a promise to return the result.

  • Starting from API version 21, this API can be used to obtain the latest connection time of the peer Bluetooth device based on the actual MAC address of the peer device.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes MAC address of the peer device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
Promise<number> Promise used to return the latest connection time of the peer Bluetooth device, in the UNIX timestamp format.

Error codes

For details about the error codes, see Bluetooth Error Codes.

Expand
ID Error Message
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
// promise
try {
    connection.getLastConnectionTime('11:22:33:44:55:66').then((time: number) => {
        console.info(`connectionTime: ${time}`);
    });
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.connectAllowedProfiles16+

connectAllowedProfiles(deviceId: string, callback: AsyncCallback<void>): void

Obtains the profiles supported by the peer device. Supported profiles include A2DP, HFP, and HID. This API uses an asynchronous callback to return the result.

  • Call connection.pairDevice to initiate pairing first. This API can be called only once within 30 seconds after each pairing is initiated.
  • Upon successful pairing, you are advised to call getRemoteProfileUuids to query the profiles supported by the target device. This API is called only if the target device supports the profile required by the application.
  • Starting from API version 21, this API can be used to perform profile connection using the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
  connection.connectAllowedProfiles('68:13:24:79:4C:8C', (err: BusinessError) => {
    if (err) {
      console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
      return;
    }
    console.info('connectAllowedProfiles');
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.connectAllowedProfiles16+

connectAllowedProfiles(deviceId: string): Promise<void>

Obtains the profiles supported by the peer device. Supported profiles include A2DP, HFP, and HID. This API uses a promise to return the result.

  • Call connection.pairDevice to initiate pairing first. This API can be called only once within 30 seconds after each pairing is initiated.
  • Upon successful pairing, you are advised to call getRemoteProfileUuids to query the profiles supported by the target device. This API is called only if the target device supports the profile required by the application.
  • Starting from API version 21, this API can be used to perform profile connection using the actual MAC address of the peer device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
deviceId string Yes Address of the peer device, for example, XX:XX:XX:XX:XX:XX.

Return value

Expand
Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900001 Service stopped.
2900003 Bluetooth disabled.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
try {
  connection.connectAllowedProfiles('68:13:24:79:4C:8C').then(() => {
      console.info('connectAllowedProfiles');
    }, (err: BusinessError) => {
      console.error('connectAllowedProfiles:errCode' + err.code + ', errMessage: ' + err.message);
  });
} catch (err) {
  console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

connection.getVirtualAddressByHash24+

getVirtualAddressByHash(algorithmType: HashAlgorithmType, hashValue: string): string

Obtains the virtual MAC address of a paired device based on the hash of its actual MAC address.

When HashAlgorithmType is set to HASH_ALGORITHM_SHA256, the hash (a 64-digit hexadecimal value) is generated based on the actual MAC address in uppercase using the SHA-256 algorithm. The last 32 bits of the hash are used as the input. The letters in the hash are case insensitive.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Expand
Name Type Mandatory Description
algorithmType HashAlgorithmType Yes Hash algorithm type.
hashValue string Yes Hash value, for example, c10b57deb2e1aafd255596e0d4fd6789.

Return value

Expand
Type Description
string Virtual MAC address of the device corresponding to the hash, for example, XX:XX:XX:XX:XX:XX. The returned address is in uppercase.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

Expand
ID Error Message
201 Permission denied.
801 Capability not supported. Failed to call the API when the short-range chip is not inserted on 2in1 device.
2900003 Bluetooth disabled.
2900015 Parameter format mismatch with specification.
2900016 Device unpaired.
2900099 Internal system error. For example, IPC error. Detailed error messages can be used to assist in locating the problem.

Example

// If the queried actual address is 11:22:33:44:55:AA,
// the corresponding 64-bit hash is d2204cb9b6d3d3962cc90fa54130efb4c10b57deb2e1aafd255596e0d4fd6789.
// If HashAlgorithmType is set to HASH_ALGORITHM_SHA256, the last 32 bits of the hash are used.
let hashValue: string = "c10b57deb2e1aafd255596e0d4fd6789";
try {
  let addr: string = connection.getVirtualAddressByHash(connection.HashAlgorithmType.HASH_ALGORITHM_SHA256, hashValue);
} catch (err) {
  console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
}

BondStateParam

Defines the parameters for the pairing status.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Type Read-Only Optional Description
deviceId string No No Address of the peer device.
state BondState No No Pairing status.
cause12+ UnbondCause No No Reason why the pairing fails.

PinRequiredParam

Defines the parameters of a pairing request.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Type Read-Only Optional Description
deviceId string No No Address of the peer device.
pinCode string No No PIN used for pairing.

DeviceClass

Represents the class of a Bluetooth device.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Type Read-Only Optional Description
majorClass MajorClass No No Main class. This is a standard field in the Bluetooth protocol.
majorMinorClass MajorMinorClass No No Subclass, which is further classified based on the major class. This is a standard field in the Bluetooth protocol.
classOfDevice number No No Class of the Bluetooth device. This is a standard field in the Bluetooth protocol. It includes the MajorClass, MajorMinorClass, and supported major services.

BatteryInfo12+

Describes the battery level of a device.

Only devices that support the Attention (AT) command (including +XEVENT and IPHONEACCEV) defined by the Bluetooth protocol can report valid battery level information.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Type Read-Only Optional Description
batteryLevel number No No

Battery level.

If the value is -1, no battery level information is available.
leftEarBatteryLevel number No No

Battery level of the left earbud if the device is a Bluetooth earphone.

If the value is -1, no battery level information is available.
leftEarChargeState DeviceChargeState No No Charging status of the left earbud if the device is a Bluetooth earbud.
rightEarBatteryLevel number No No

Battery level of the right earbud if the device is a Bluetooth earphone.

If the value is -1, no battery level information is available.
rightEarChargeState DeviceChargeState No No Charging status of the right earbud if the device is a Bluetooth earbud.
boxBatteryLevel number No No

Battery level of the earbud compartment if the device is a Bluetooth earphone.

If the value is -1, no battery level information is available.
boxChargeState DeviceChargeState No No Charging status of the earbud compartment if the device is a Bluetooth earbud.

BluetoothTransport

Enumerates the device transmission modes.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Value Description
TRANSPORT_BR_EDR 0 Legacy Bluetooth basic rate/enhanced data rate (BR/EDR) mode.
TRANSPORT_LE 1 BLE mode.
TRANSPORT_DUAL20+ 2 BR/EDR and BLE modes. You can select either the BR/EDR or BLE mode for communication.
TRANSPORT_UNKNOWN20+ 3 Unknown transport mode.

ScanMode

Enumerates the scan modes. The scan mode determines whether the device is discoverable or connectable.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Value Description
SCAN_MODE_NONE 0 Undiscoverable and unconnectable mode.
SCAN_MODE_CONNECTABLE 1 Connectable mode.
SCAN_MODE_GENERAL_DISCOVERABLE 2 General discoverable mode, allowing for long-term discovery.
SCAN_MODE_LIMITED_DISCOVERABLE 3 Limited discoverable mode, allowing for discovery within a specific timeframe.
SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE 4 Connectable and general discoverable mode.
SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE 5 Connectable and limited discoverable mode.

BondState

Enumerates the device pairing states.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Value Description
BOND_STATE_INVALID 0 Unpaired state.
BOND_STATE_BONDING 1 Pairing state.
BOND_STATE_BONDED 2 Paired state.

UnbondCause12+

Enumerates the possible causes of a pairing failure.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Value Description
USER_REMOVED 0 The user proactively removes the device. If BondState is BOND_STATE_BONDED, the pairing is successful.
REMOTE_DEVICE_DOWN 1 The peer device is offline. For example, the Bluetooth of the peer device is disabled.
AUTH_FAILURE 2 Authentication failed. For example, the keys of the devices at both ends do not match.
AUTH_REJECTED 3 Authentication rejected. For example, the peer device rejects the pairing request.
INTERNAL_ERROR 4 Internal error. For example, the device does not support pairing, or the pairing times out.

DeviceChargeState12+

Enumerates the device charging states.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Value Description
DEVICE_NORMAL_CHARGE_NOT_CHARGED 0 A device that does not support super-fast charging is currently not charging.
DEVICE_NORMAL_CHARGE_IN_CHARGING 1 A device that does not support super-fast charging is currently charging.
DEVICE_SUPER_CHARGE_NOT_CHARGED 2 A device that supports super-fast charging is currently not charging.
DEVICE_SUPER_CHARGE_IN_CHARGING 3 A device that supports super-fast charging is currently charging.

DiscoveryResult18+

Defines the device discovery result.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Type Read-Only Optional Description
deviceId string No No

Address of the discovered device.

For security purposes, the device addresses obtained are virtual MAC addresses.

- The virtual addresses of paired Bluetooth devices will not change.

- If Bluetooth is disabled and then enabled again, the virtual address will change immediately.

- If the pairing is canceled, the Bluetooth subsystem will determine when to change the address based on the actual usage of the address. If the address is being used by another application, the address will not change immediately.

- To persistently save the addresses, call access.addPersistentDeviceId.
rssi number No No Signal strength, in dBm.
deviceName string No No Device name.
deviceClass DeviceClass No No Device class.

HashAlgorithmType24+

Enumerates the hash algorithm types.

The hash algorithm is a mathematical function that performs complex calculations on input data to generate a unique and fixed-length string (hash value). It is commonly used in scenarios such as data integrity verification and digital signatures.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Communication.Bluetooth.Core

Expand
Name Value Description
HASH_ALGORITHM_SHA256 0 SHA-256 hash algorithm.
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in References
Enter a keyword.