Bluetooth
NOTE
The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.The Bluetooth module provides Classic Bluetooth capabilities and Bluetooth Low Energy (BLE) scan and advertising.
Modules to Import
import bluetooth from '@ohos.bluetooth';
Required Permissions
ohos.permission.USE_BLUETOOTH
ohos.permission.MANAGE_BLUETOOTH
ohos.permission.DISCOVER_BLUETOOTH
ohos.permission.LOCATION
bluetooth.enableBluetooth8+
enableBluetooth(): boolean
Enables Bluetooth.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
boolean | Returns true if Bluetooth is enabled; returns false otherwise. |
Example
let enable = bluetooth.enableBluetooth();
bluetooth.disableBluetooth8+
disableBluetooth(): boolean
Disables Bluetooth.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
boolean | Returns true if Bluetooth is disabled; returns false otherwise. |
Example
let disable = bluetooth.disableBluetooth();
bluetooth.getLocalName8+
getLocalName(): string
Obtains the name of the local Bluetooth device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
string | Name of the local Bluetooth device obtained. |
Example
let localName = bluetooth.getLocalName();
bluetooth.getState
getState(): BluetoothState
Obtains the Bluetooth state.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
BluetoothState | Bluetooth state obtained. |
Example
let state = bluetooth.getState();
bluetooth.getBtConnectionState
getBtConnectionState(): ProfileConnectionState
Obtains the profile connection state of this Bluetooth device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
ProfileConnectionState | Profile connection state obtained. |
Example
let connectionState = bluetooth.getBtConnectionState();
bluetooth.setLocalName8+
setLocalName(name: string): boolean
Sets the name of the local Bluetooth device.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Bluetooth device name to set. It cannot exceed 248 bytes. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let ret = bluetooth.setLocalName('device_name');
bluetooth.pairDevice
pairDevice(deviceId: string): boolean
Initiates Bluetooth pairing.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Address of the remote device to pair, for example, XX:XX:XX:XX:XX:XX. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
// The address can be scanned.
let result = bluetooth.pairDevice("XX:XX:XX:XX:XX:XX");
bluetooth.getProfileConnState8+
getProfileConnState(profileId: ProfileId): ProfileConnectionState
Obtains the connection status of a profile.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
ProfileId | profileId | Yes | ID of the target profile, for example, PROFILE_A2DP_SOURCE. |
Return value
Type | Description |
---|---|
ProfileConnectionState | Profile connection state obtained. |
Example
let result = bluetooth.getProfileConnState(PROFILE_A2DP_SOURCE);
bluetooth.cancelPairedDevice8+
cancelPairedDevice(deviceId: string): boolean
Cancels a paired remote device.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Address of the remote device to cancel, for example, XX:XX:XX:XX:XX:XX. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let result = bluetooth.cancelPairedDevice("XX:XX:XX:XX:XX:XX");
bluetooth.getRemoteDeviceName8+
getRemoteDeviceName(deviceId: string): string
Obtains the name of the remote Bluetooth device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Address of the target remote device, for example, XX:XX:XX:XX:XX:XX. |
Return value
Type | Description |
---|---|
string | Device name (a string) obtained. |
Example
let remoteDeviceName = bluetooth.getRemoteDeviceName("XX:XX:XX:XX:XX:XX");
bluetooth.getRemoteDeviceClass8+
getRemoteDeviceClass(deviceId: string): DeviceClass
Obtains the type of the remote Bluetooth device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Address of the target remote device, for example, XX:XX:XX:XX:XX:XX. |
Return value
Type | Description |
---|---|
DeviceClass | Type of a remote device obtained. |
Example
let remoteDeviceClass = bluetooth.getRemoteDeviceClass("XX:XX:XX:XX:XX:XX");
bluetooth.getPairedDevices8+
getPairedDevices(): Array<string>
Obtains the Bluetooth pairing list.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
Array<string> | List of the addresses of the paired Bluetooth devices. |
Example
let devices = bluetooth.getPairedDevices();
bluetooth.setBluetoothScanMode8+
setBluetoothScanMode(mode: ScanMode, duration: number): boolean
Sets the Bluetooth scan mode so that the device can be discovered by a remote device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
mode | ScanMode | Yes | Bluetooth scan mode to set. |
duration | number | Yes | Duration (in seconds) in which the device can be discovered. The value 0 indicates unlimited time. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
// The device can be discovered and connected only when the discoverable and connectable mode is used.
let result = bluetooth.setBluetoothScanMode(ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100);
bluetooth.getBluetoothScanMode8+
getBluetoothScanMode(): ScanMode
Obtains the Bluetooth scan mode.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
ScanMode | Bluetooth scan mode obtained. |
Example
let scanMode = bluetooth.getBluetoothScanMode();
bluetooth.startBluetoothDiscovery8+
startBluetoothDiscovery(): boolean
Starts Bluetooth scan to discover remote devices.
Required permissions: ohos.permission.USE_BLUETOOTH and ohos.permission.LOCATION
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let deviceId;
function onReceiveEvent(data) {
deviceId = data;
}
bluetooth.on('bluetoothDeviceFind', onReceiveEvent);
let result = bluetooth.startBluetoothDiscovery();
bluetooth.stopBluetoothDiscovery8+
stopBluetoothDiscovery(): boolean
Stops Bluetooth scan.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let result = bluetooth.stopBluetoothDiscovery();
bluetooth.setDevicePairingConfirmation8+
setDevicePairingConfirmation(device: string, accept: boolean): boolean
Sets the device pairing confirmation.
Required permissions: ohos.permission.MANAGE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
device | string | Yes | Address of the target remote device, for example, XX:XX:XX:XX:XX:XX. |
accept | boolean | Yes | Whether to accept the pairing request. The value true means to accept the pairing request, and the value false means the opposite. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
// Subscribe to the pinRequired event and configure the pairing confirmation after receiving a pairing request from the remote device.
function onReceivePinRequiredEvent(data) { // data is the input parameter for the pairing request.
console.info('pin required = '+ JSON.stringify(data));
bluetooth.setDevicePairingConfirmation(data.deviceId, true);
}
bluetooth.on("pinRequired", onReceivePinRequiredEvent);
bluetooth.on('bluetoothDeviceFind')8+
on(type: "bluetoothDeviceFind", callback: Callback<Array<string>>): void
Subscribes to the Bluetooth device discovery events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value bluetoothDeviceFind indicates an event reported when a Bluetooth device is discovered. |
callback | Callback<Array<string>> | Yes | Callback invoked to return the discovered devices. You need to implement this callback. |
Return value
No value is returned.
Example
function onReceiveEvent(data) { // data is a set of Bluetooth device addresses.
console.info('bluetooth device find = '+ JSON.stringify(data));
}
bluetooth.on('bluetoothDeviceFind', onReceiveEvent);
bluetooth.off('bluetoothDeviceFind')8+
off(type: "bluetoothDeviceFind", callback?: Callback<Array<string>>): void
Unsubscribes from the Bluetooth device discovery events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value bluetoothDeviceFind indicates an event reported when a Bluetooth device is discovered. |
callback | Callback<Array<string>> | No | Callback used to report the discovered devices. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('bluetooth device find = '+ JSON.stringify(data));
}
bluetooth.on('bluetoothDeviceFind', onReceiveEvent);
bluetooth.off('bluetoothDeviceFind', onReceiveEvent);
bluetooth.on('pinRequired')8+
on(type: "pinRequired", callback: Callback<PinRequiredParam>): void
Subscribes to the pairing request events of the remote Bluetooth device.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value pinRequired indicates a pairing request event. |
callback | Callback<PinRequiredParam> | Yes | Callback invoked to return the pairing request. You need to implement this callback. |
Return value
No value is returned.
Example
function onReceiveEvent(data) { // data is the pairing request parameter.
console.info('pin required = '+ JSON.stringify(data));
}
bluetooth.on('pinRequired', onReceiveEvent);
bluetooth.off('pinRequired')8+
off(type: "pinRequired", callback?: Callback<PinRequiredParam>): void
Unsubscribes from the pairing request events of the remote Bluetooth device.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value pinRequired indicates a pairing request event. |
callback | Callback<PinRequiredParam> | No | Callback used to report the Bluetooth pairing request. The input parameter is the pairing request parameter. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('pin required = '+ JSON.stringify(data));
}
bluetooth.on('pinRequired', onReceiveEvent);
bluetooth.off('pinRequired', onReceiveEvent);
bluetooth.on('bondStateChange')8+
on(type: "bondStateChange", callback: Callback<BondStateParam>): void
Subscribes to the Bluetooth pairing state change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value bondStateChange indicates a Bluetooth pairing state change event. |
callback | Callback<BondStateParam> | Yes | Callback invoked to return the pairing state. You need to implement this callback. |
Return value
No value is returned.
Example
function onReceiveEvent(data) { // data, as the input parameter of the callback, indicates the pairing state.
console.info('pair state = '+ JSON.stringify(data));
}
bluetooth.on('bondStateChange', onReceiveEvent);
bluetooth.off('bondStateChange')8+
off(type: "bondStateChange", callback?: Callback<BondStateParam>): void
Unsubscribes from the Bluetooth pairing state change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value bondStateChange indicates a Bluetooth pairing state change event. |
callback | Callback<BondStateParam> | No | Callback used to report the change of the Bluetooth pairing state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('bond state = '+ JSON.stringify(data));
}
bluetooth.on('bondStateChange', onReceiveEvent);
bluetooth.off('bondStateChange', onReceiveEvent);
bluetooth.on('stateChange')8+
on(type: "stateChange", callback: Callback<BluetoothState>): void
Subscribes to the Bluetooth connection state change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value stateChange indicates a Bluetooth connection state change event. |
callback | Callback<BluetoothState> | Yes | Callback invoked to return the Bluetooth connection state. You need to implement this callback. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('bluetooth state = '+ JSON.stringify(data));
}
bluetooth.on('stateChange', onReceiveEvent);
bluetooth.off('stateChange')8+
off(type: "stateChange", callback?: Callback<BluetoothState>): void
Unsubscribes from the Bluetooth connection state change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value stateChange indicates a Bluetooth connection state change event. |
callback | Callback<BluetoothState> | No | Callback used to report the Bluetooth connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('bluetooth state = '+ JSON.stringify(data));
}
bluetooth.on('stateChange', onReceiveEvent);
bluetooth.off('stateChange', onReceiveEvent);
bluetooth.sppListen8+
sppListen(name: string, option: SppOption, callback: AsyncCallback<number>): void
Creates a server listening socket.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Name of the service. |
option | SppOption | Yes | Serial port profile (SPP) listening configuration. |
callback | AsyncCallback<number> | Yes | Callback invoked to return the server socket ID. |
Example
let serverNumber = -1;
function serverSocket(code, number) {
console.log('bluetooth error code: ' + code.code);
if (code.code == 0) {
console.log('bluetooth serverSocket Number: ' + number);
serverNumber = number;
}
}
let sppOption = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0};
bluetooth.sppListen('server1', sppOption, serverSocket);
bluetooth.sppAccept8+
sppAccept(serverSocket: number, callback: AsyncCallback<number>): void
Listens for a connection to be made to this socket from the client and accepts it.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
serverSocket | number | Yes | Server socket ID. |
callback | AsyncCallback<number> | Yes | Callback invoked to return the client socket ID. |
Example
let clientNumber = -1;
function acceptClientSocket(code, number) {
console.log('bluetooth error code: ' + code.code);
if (code.code == 0) {
console.log('bluetooth clientSocket Number: ' + number);
// The obtained clientNumber is used as the socket ID for subsequent read/write operations on the server.
clientNumber = number;
}
}
bluetooth.sppAccept(serverNumber, acceptClientSocket);
bluetooth.sppConnect8+
sppConnect(device: string, option: SppOption, callback: AsyncCallback<number>): void
Initiates an SPP connection to a remote device from the client.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
device | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX. |
option | SppOption | Yes | Configuration for connecting to the SPP client. |
callback | AsyncCallback<number> | Yes | Callback invoked to return the client socket ID. |
Example
let clientNumber = -1;
function clientSocket(code, number) {
if (code.code != 0) {
return;
}
console.log('bluetooth serverSocket Number: ' + number);
// The obtained clientNumber is used as the socket ID for subsequent read/write operations on the client.
clientNumber = number;
}
let sppOption = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0};
bluetooth.sppConnect('XX:XX:XX:XX:XX:XX', sppOption, clientSocket);
bluetooth.sppCloseServerSocket8+
sppCloseServerSocket(socket: number): void
Closes the listening socket of the server.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
socket | number | Yes | ID of the listening socket on the server. The ID is obtained by sppListen. |
Example
bluetooth.sppCloseServerSocket(serverNumber);
bluetooth.sppCloseClientSocket8+
sppCloseClientSocket(socket: number): void
Closes the client socket.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
Name | Type | Mandatory | Description |
socket | number | Yes | Client socket ID, which is obtained by sppAccept or sppConnect. |
Example
bluetooth.sppCloseClientSocket(clientNumber);
bluetooth.sppWrite8+
sppWrite(clientSocket: number, data: ArrayBuffer): boolean
Writes data to the remote device through the socket.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
clientSocket | number | Yes | Client socket ID, which is obtained by sppAccept or sppConnect. |
data | ArrayBuffer | Yes | Data to write. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let arrayBuffer = new ArrayBuffer(8);
let data = new Uint8Array(arrayBuffer);
data[0] = 123;
let ret = bluetooth.sppWrite(clientNumber, arrayBuffer);
if (ret) {
console.log('spp write successfully');
} else {
console.log('spp write failed');
}
bluetooth.on('sppRead')8+
on(type: "sppRead", clientSocket: number, callback: Callback<ArrayBuffer>): void
Subscribes to the SPP read request events.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value sppRead indicates an SPP read request event. |
clientSocket | number | Yes | Client socket ID, which is obtained by sppAccept or sppConnect. |
callback | Callback<ArrayBuffer> | Yes | Callback invoked to return the data read. |
Return value
No value is returned.
Example
function dataRead(dataBuffer) {
let data = new Uint8Array(dataBuffer);
console.log('bluetooth data is: ' + data[0]);
}
bluetooth.on('sppRead', clientNumber, dataRead);
bluetooth.off('sppRead')8+
off(type: "sppRead", clientSocket: number, callback?: Callback<ArrayBuffer>): void
Unsubscribes from the SPP read request events.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value sppRead indicates an SPP read request event. |
clientSocket | number | Yes | Client socket ID, which is obtained by sppAccept or sppConnect. |
callback | Callback<ArrayBuffer> | No | Callback used to report an SPP read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
bluetooth.off('sppRead', clientNumber);
bluetooth.getProfile8+
getProfile(profileId: ProfileId): A2dpSourceProfile | HandsFreeAudioGatewayProfile
Obtains a profile object.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
ProfileId | profileId | Yes | ID of the profile to obtain, for example, PROFILE_A2DP_SOURCE. |
Return value
Type | Description |
---|---|
A2dpSourceProfile or HandsFreeAudioGatewayProfile | Profile object obtained. Only A2dpSourceProfile and HandsFreeAudioGatewayProfile are supported. |
Example
let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE);
bluetooth.BLE
bluetooth.BLE.createGattServer
createGattServer(): GattServer
Creates a GattServer instance.
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
GattServer | GattServer instance created. Before using a method of the server, you must create a GattSever instance. |
Example
let gattServer = bluetooth.BLE.createGattServer();
bluetooth.BLE.createGattClientDevice
createGattClientDevice(deviceId: string): GattClientDevice
Creates a GattClientDevice instance.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX. |
Return value
Type | Description |
---|---|
GattClientDevice | GattClientDevice instance created. Before using a method of the client, you must create a GattClientDevice instance. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
bluetooth.BLE.getConnectedBLEDevices
getConnectedBLEDevices(): Array<string>
Obtains the BLE devices connected to this device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
Array<string> | Addresses of the BLE devices connected to this device. |
Example
let result = bluetooth.BLE.getConnectedBLEDevices();
bluetooth.BLE.startBLEScan
startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void
Starts a BLE scan.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH, ohos.permission.MANAGE_BLUETOOTH, and ohos.permission.LOCATION
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
filters | Array<ScanFilter> | Yes | Criteria for filtering the scan result. Set this parameter to null if you do not want to filter the scan result. |
options | ScanOptions | No | Scan options. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('BLE scan device find result = '+ JSON.stringify(data));
}
bluetooth.BLE.on("BLEDeviceFind", onReceiveEvent);
bluetooth.BLE.startBLEScan(
[{
deviceId:"XX:XX:XX:XX:XX:XX",
name:"test",
serviceUuid:"00001888-0000-1000-8000-00805f9b34fb"
}],
{
interval: 500,
dutyMode: bluetooth.ScanDuty.SCAN_MODE_LOW_POWER,
matchMode: bluetooth.MatchMode.MATCH_MODE_AGGRESSIVE,
}
);
bluetooth.BLE.stopBLEScan
stopBLEScan(): void
Stops the BLE scan.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
No value is returned.
Example
bluetooth.BLE.stopBLEScan();
bluetooth.BLE.on('BLEDeviceFind')
on(type: "BLEDeviceFind", callback: Callback<Array<ScanResult>>): void
Subscribe to the BLE device discovery events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value BLEDeviceFind indicates an event reported when a BLE device is discovered. |
callback | Callback<Array<ScanResult>> | Yes | Callback invoked to return the discovered devices. You need to implement this callback. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('bluetooth device find = '+ JSON.stringify(data));
}
bluetooth.BLE.on('BLEDeviceFind', onReceiveEvent);
bluetooth.BLE.off('BLEDeviceFind')
off(type: "BLEDeviceFind", callback?: Callback<Array<ScanResult>>): void
Unsubscribes from the BLE device discovery events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value BLEDeviceFind indicates an event reported when a BLE device is discovered. |
callback | Callback<Array<ScanResult>> | No | Callback used to report the discovered devices. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('bluetooth device find = '+ JSON.stringify(data));
}
bluetooth.BLE.on('BLEDeviceFind', onReceiveEvent);
bluetooth.BLE.off('BLEDeviceFind', onReceiveEvent);
BaseProfile
Provides the profile base class.
getConnectionDevices8+
getConnectionDevices(): Array<string>
Obtains the connected devices.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
No value is returned.
Return value
Type | Description |
Array<string> | List of addresses of the connected devices. |
getDeviceState8+
getDeviceState(device: string): ProfileConnectionState
Obtains the connection status of the profile.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
device | string | Yes | Address of the target device. |
|
Return value
Type | Description |
ProfileConnectionState | Profile connection state obtained. |
A2dpSourceProfile
Before using a method of A2dpSourceProfile, you need to create an instance of this class by using the getProfile() method.
connect8+
connect(device: string): boolean
Sets up an Advanced Audio Distribution Profile (A2DP) connection.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
device | string | Yes | Address of the remote device to connect. |
|
Return value
Type | Description |
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE)
let ret = a2dpSrc.connect('XX:XX:XX:XX:XX:XX');
disconnect8+
disconnect(device: string): boolean
Disconnects an A2DP connection.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
device | string | Yes | Address of the remote device to disconnect. |
|
Return value
Type | Description |
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE);
let ret = a2dpSrc.disconnect('XX:XX:XX:XX:XX:XX');
A2dpSourceProfile.on('connectionStateChange')8+
on(type: "connectionStateChange", callback: Callback<StateChangeParam>): void
Subscribes to the A2DP connection status change events.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value connectionStateChange indicates an A2DP connection state change event. |
callback | Callback<StateChangeParam> | Yes | Callback invoked to return the A2DP connection state change event. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('a2dp state = '+ JSON.stringify(data));
}
A2dpSourceProfile.on('connectionStateChange', onReceiveEvent);
A2dpSourceProfile.off('connectionStateChange')8+
off(type: "connectionStateChange", callback: Callback<StateChangeParam>): void
Unsubscribes from the A2DP connection status change events.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value connectionStateChange indicates an A2DP connection state change event. |
callback | Callback<StateChangeParam> | Yes | Callback used to return the A2DP connection state change event. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('a2dp state = '+ JSON.stringify(data));
}
A2dpSourceProfile.off('connectionStateChange', onReceiveEvent);
getPlayingState
getPlayingState(device: string): PlayingState
Obtains the playing status of a device.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
device | string | Yes | Address of the target device. |
Return value
Type | Description |
PlayingState | Playing status obtained. |
Example
let a2dpSrc = bluetooth.getProfile(PROFILE_A2DP_SOURCE);
let state = a2dpSrc.getPlayingState('XX:XX:XX:XX:XX:XX');
HandsFreeAudioGatewayProfile
Before using a method of HandsFreeAudioGatewayProfile, you need to create an instance of this class by using the getProfile() method.
connect8+
connect(device: string): boolean
Sets up a Hands-free Profile (HFP) connection of a device.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
device | string | Yes | Address of the target device. |
|
Return value
Type | Description |
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY);
let ret = hfpAg.connect('XX:XX:XX:XX:XX:XX');
disconnect8+
disconnect(device: string): boolean
Disconnects the HFP connection of a device.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
device | string | Yes | Address of the target device. |
|
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let hfpAg = bluetooth.getProfile(PROFILE_HANDS_FREE_AUDIO_GATEWAY);
let ret = hfpAg.disconnect('XX:XX:XX:XX:XX:XX');
HandsFreeAudioGatewayProfile.on('connectionStateChange')8+
on(type: "connectionStateChange", callback: Callback<StateChangeParam>): void
Subscribes to the HFP connection status change events.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value connectionStateChange indicates an HFP connection state change event. |
callback | Callback<StateChangeParam> | Yes | Callback invoked to return the HFP connection state change event. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('hfp state = '+ JSON.stringify(data));
}
HandsFreeAudioGatewayProfile.on('connectionStateChange', onReceiveEvent);
HandsFreeAudioGatewayProfile.off('connectionStateChange')8+
off(type: "connectionStateChange", callback: Callback<StateChangeParam>): void
Unsubscribes from the HFP connection status change events.
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value connectionStateChange indicates an HFP connection state change event. |
callback | Callback<StateChangeParam> | Yes | Callback used to return the HFP connection state change event. |
Return value
No value is returned.
Example
function onReceiveEvent(data) {
console.info('hfp state = '+ JSON.stringify(data));
}
HandsFreeAudioGatewayProfile.off('connectionStateChange', onReceiveEvent);
GattServer
Implements the Generic Attribute Profile (GATT) server. Before using a method of this class, you need to create a GattServer instance using the createGattServer() method.
startAdvertising
startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void
Starts BLE advertising.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
setting | AdvertiseSetting | Yes | Settings related to BLE advertising. |
advData | AdvertiseData | Yes | Content of the BLE advertisement packet. |
advResponse | AdvertiseData | No | Response to the BLE scan request. |
Return value
No value is returned.
Example
let manufactureValueBuffer = new Uint8Array(4);
manufactureValueBuffer[0] = 1;
manufactureValueBuffer[1] = 2;
manufactureValueBuffer[2] = 3;
manufactureValueBuffer[3] = 4;
let serviceValueBuffer = new Uint8Array(4);
serviceValueBuffer[0] = 4;
serviceValueBuffer[1] = 6;
serviceValueBuffer[2] = 7;
serviceValueBuffer[3] = 8;
console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer));
console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer));
let gattServer = bluetooth.BLE.createGattServer();
gattServer.startAdvertising({
interval:150,
txPower:60,
connectable:true,
},{
serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
manufactureData:[{
manufactureId:4567,
manufactureValue:manufactureValueBuffer.buffer
}],
serviceData:[{
serviceUuid:"00001888-0000-1000-8000-00805f9b34fb",
serviceValue:serviceValueBuffer.buffer
}],
},{
serviceUuids:["00001889-0000-1000-8000-00805f9b34fb"],
manufactureData:[{
manufactureId:1789,
manufactureValue:manufactureValueBuffer.buffer
}],
serviceData:[{
serviceUuid:"00001889-0000-1000-8000-00805f9b34fb",
serviceValue:serviceValueBuffer.buffer
}],
});
stopAdvertising
stopAdvertising(): void
Stops BLE advertising.
Required permissions: ohos.permission.DISCOVER_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
No value is returned.
Example
let server = bluetooth.BLE.createGattServer();
server.stopAdvertising();
addService
addService(service: GattService): boolean
Adds a service to this GATT server.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
service | GattService | Yes | Service to add. Settings related to BLE advertising. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
// Create descriptors.
let descriptors = [];
let arrayBuffer = new ArrayBuffer(8);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 11;
let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00001830-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer};
descriptors[0] = descriptor;
// Create characteristics.
let characteristics = [];
let arrayBufferC = new ArrayBuffer(8);
let cccV = new Uint8Array(arrayBufferC);
cccV[0] = 1;
let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors};
let characteristicN = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptorsN};
characteristics[0] = characteristic;
// Create a gattService instance.
let gattService = {serviceUuid:'00001810-0000-1000-8000-00805F9B34FB', isPrimary: true, characteristics:characteristics, includeServices:[]};
let gattServer = bluetooth.BLE.createGattServer();
let ret = gattServer.addService(gattService);
if (ret) {
console.log("add service successfully");
} else {
console.log("add service failed");
}
removeService
removeService(serviceUuid: string): boolean
Removes a service from this GATT server.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
serviceUuid | string | Yes | Universally unique identifier (UUID) of the service to remove, for example, 00001810-0000-1000-8000-00805F9B34FB. |
Return value
Type | Description |
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let server = bluetooth.BLE.createGattServer();
server.removeService('00001810-0000-1000-8000-00805F9B34FB');
close
close(): void
Closes this GATT server to unregister it from the protocol stack. After this method is called, this GattServer cannot be used.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Example
let server = bluetooth.BLE.createGattServer();
server.close();
notifyCharacteristicChanged
notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): boolean
Notifies the connected client device when a characteristic value changes.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Address of the client that receives notifications, for example, XX:XX:XX:XX:XX:XX. |
notifyCharacteristic | NotifyCharacteristic | Yes | New characteristic value. |
Return value
Type | Description |
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let notifyCharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: notifyCcc.characteristicValue, confirm: false};
let server = bluetooth.BLE.createGattServer();
server.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacteristic);
sendResponse
sendResponse(serverResponse: ServerResponse): boolean
Sends a response to a read or write request from the GATT client.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
serverResponse | ServerResponse | Yes | Response returned by the GATT server. |
Return value
Type | Description |
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
/* send response */
let arrayBufferCCC = new ArrayBuffer(8);
let cccValue = new Uint8Array(arrayBufferCCC);
cccValue[0] = 1123;
let serverResponse = {
"deviceId": "XX:XX:XX:XX:XX:XX",
"transId": 0,
"status": 0,
"offset": 0,
"value": arrayBufferCCC,
};
let gattServer = bluetooth.BLE.createGattServer();
let ret = gattServer.sendResponse(serverResponse);
if (ret) {
console.log('bluetooth sendResponse successfully');
} else {
console.log('bluetooth sendResponse failed');
}
on('characteristicRead')
on(type: "characteristicRead", callback: Callback<CharacteristicReadReq>): void
Subscribes to the characteristic read request events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value characteristicRead indicates a characteristic read request event. |
callback | Callback<CharacteristicReadReq> | Yes | Callback invoked to return a characteristic read request from the GATT client. |
Return value
No value is returned.
Example
let arrayBufferCCC = new ArrayBuffer(8);
let cccValue = new Uint8Array(arrayBufferCCC);
cccValue[0] = 1123;
function ReadCharacteristicReq(CharacteristicReadReq) {
let deviceId = CharacteristicReadReq.deviceId;
let transId = CharacteristicReadReq.transId;
let offset = CharacteristicReadReq.offset;
let characteristicUuid = CharacteristicReadReq.characteristicUuid;
let serverResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC};
let ret = gattServer.sendResponse(serverResponse);
if (ret) {
console.log('bluetooth sendResponse successfully');
} else {
console.log('bluetooth sendResponse failed');
}
}
let gattServer = bluetooth.BLE.createGattServer();
gattServer.on("characteristicRead", ReadCharacteristicReq);
off('characteristicRead')
off(type: "characteristicRead", callback?: Callback<CharacteristicReadReq>): void
Unsubscribes from the characteristic read request events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value characteristicRead indicates a characteristic read request event. |
callback | Callback<CharacteristicReadReq> | No | Callback used to report a characteristic read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
let gattServer = bluetooth.BLE.createGattServer();
gattServer.off("characteristicRead");
on('characteristicWrite')
on(type: "characteristicWrite", callback: Callback<CharacteristicWriteReq>): void
Subscribes to the characteristic write request events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value characteristicWrite indicates a characteristic write request event. |
callback | Callback<CharacteristicWriteReq> | Yes | Callback invoked to return a characteristic write request from the GATT client. |
Return value
No value is returned.
Example
let arrayBufferCCC = new ArrayBuffer(8);
let cccValue = new Uint8Array(arrayBufferCCC);
function WriteCharacteristicReq(CharacteristicWriteReq) {
let deviceId = CharacteristicWriteReq.deviceId;
let transId = CharacteristicWriteReq.transId;
let offset = CharacteristicWriteReq.offset;
let isPrep = CharacteristicWriteReq.isPrep;
let needRsp = CharacteristicWriteReq.needRsp;
let value = new Uint8Array(CharacteristicWriteReq.value);
let characteristicUuid = CharacteristicWriteReq.characteristicUuid;
cccValue[0] = value[0];
let serverResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC};
let ret = gattServer.sendResponse(serverResponse);
if (ret) {
console.log('bluetooth sendResponse successfully');
} else {
console.log('bluetooth sendResponse failed');
}
}
let gattServer = bluetooth.BLE.createGattServer();
gattServer.on("characteristicWrite", WriteCharacteristicReq);
off('characteristicWrite')
off(type: "characteristicWrite", callback?: Callback<CharacteristicWriteReq>): void
Unsubscribes from the characteristic write request events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value characteristicWrite indicates a characteristic write request event. |
callback | Callback<CharacteristicWriteReq> | No | Callback used to report a characteristic write request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
let gattServer = bluetooth.BLE.createGattServer();
gattServer.off("characteristicWrite");
on('descriptorRead')
on(type: "descriptorRead", callback: Callback<DescriptorReadReq>): void
Subscribes to the descriptor read request events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value descriptorRead indicates a descriptor read request event. |
callback | Callback<DescriptorReadReq> | Yes | Callback invoked to return a descriptor read request from the GATT client. |
Return value
No value is returned.
Example
let arrayBufferDesc = new ArrayBuffer(8);
let descValue = new Uint8Array(arrayBufferDesc);
descValue[0] = 1101;
function ReadDescriptorReq(DescriptorReadReq) {
let deviceId = DescriptorReadReq.deviceId;
let transId = DescriptorReadReq.transId;
let offset = DescriptorReadReq.offset;
let descriptorUuid = DescriptorReadReq.descriptorUuid;
let serverResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc};
let ret = gattServer.sendResponse(serverResponse);
if (ret) {
console.log('bluetooth sendResponse successfully');
} else {
console.log('bluetooth sendResponse failed');
}
}
let gattServer = bluetooth.BLE.createGattServer();
gattServer.on("descriptorRead", ReadDescriptorReq);
off('descriptorRead')
off(type: "descriptorRead", callback?: Callback<DescriptorReadReq>): void
Unsubscribes from the descriptor read request events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value descriptorRead indicates a descriptor read request event. |
callback | Callback<DescriptorReadReq> | No | Callback used to report a descriptor read request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
let gattServer = bluetooth.BLE.createGattServer();
gattServer.off("descriptorRead");
on('descriptorWrite')
on(type: "descriptorWrite", callback: Callback<DescriptorWriteReq>): void
Subscribes to the descriptor write request events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value descriptorWrite indicates a descriptor write request event. |
callback | Callback<DescriptorWriteReq> | Yes | Callback invoked to return a descriptor write request from the GATT client. |
Return value
No value is returned.
Example
let arrayBufferDesc = new ArrayBuffer(8);
let descValue = new Uint8Array(arrayBufferDesc);
function WriteDescriptorReq(DescriptorWriteReq) {
let deviceId = DescriptorWriteReq.deviceId;
let transId = DescriptorWriteReq.transId;
let offset = DescriptorWriteReq.offset;
let isPrep = DescriptorWriteReq.isPrep;
let needRsp = DescriptorWriteReq.needRsp;
let value = new Uint8Array(DescriptorWriteReq.value);
let descriptorUuid = DescriptorWriteReq.descriptorUuid;
descValue[0] = value[0];
let serverResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc};
let ret = gattServer.sendResponse(serverResponse);
if (ret) {
console.log('bluetooth sendResponse successfully');
} else {
console.log('bluetooth sendResponse failed');
}
}
let gattServer = bluetooth.BLE.createGattServer();
gattServer.on("descriptorRead", WriteDescriptorReq);
off('descriptorWrite')
off(type: "descriptorWrite", callback?: Callback<DescriptorWriteReq>): void
Unsubscribes from the descriptor write request events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value descriptorWrite indicates a descriptor write request event. |
callback | Callback<DescriptorWriteReq> | No | Callback used to report a descriptor write request event. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
let gattServer = bluetooth.BLE.createGattServer();
gattServer.off("descriptorWrite");
on('connectStateChange')
on(type: "connectStateChange", callback: Callback<BLEConnectChangedState>): void
Subscribes to the BLE connection state change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value connectStateChange indicates a BLE connection state change event. |
callback | Callback<BLEConnectChangedState> | Yes | Callback invoked to return the BLE connection state. |
Return value
No value is returned.
Example
function Connected(BLEConnectChangedState) {
let deviceId = BLEConnectChangedState.deviceId;
let status = BLEConnectChangedState.state;
}
let gattServer = bluetooth.BLE.createGattServer();
gattServer.on("connectStateChange", Connected);
off('connectStateChange')
off(type: "connectStateChange", callback?: Callback<BLEConnectChangedState>): void
Unsubscribes from the BLE connection state change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value connectStateChange indicates a BLE connection state change event. |
callback | Callback<BLEConnectChangedState> | No | Callback used to report the BLE connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
let gattServer = bluetooth.BLE.createGattServer();
gattServer.off("connectStateChange");
GattClientDevice
Implements the GATT client. Before using a method of this class, you must create a GattClientDevice instance using the createGattClientDevice(deviceId: string) method.
connect
connect(): boolean
Initiates a connection to the remote BLE device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
boolean | Returns true if the connection is successful; returns false otherwise. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let ret = device.connect();
disconnect
disconnect(): boolean
Disconnects from the remote BLE device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let ret = device.disconnect();
close
close(): boolean
Closes this GATT client to unregister it from the protocol stack. After this method is called, this GattClientDevice instance cannot be used.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let ret = device.close();
getServices
getServices(callback: AsyncCallback<Array<GattService>>): void
Obtains all services of the remote BLE device. This method uses an asynchronous callback to return the result.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Array<GattService>> | Yes | Callback invoked to return the services obtained. |
Return value
No value is returned.
Example
// Callback
function getServices(code, gattServices) {
if (code.code == 0) {
let services = gattServices;
console.log('bluetooth code is ' + code.code);
console.log("bluetooth services size is ", services.length);
for (let i = 0; i < services.length; i++) {
console.log('bluetooth serviceUuid is ' + services[i].serviceUuid);
}
}
}
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.connect();
device.getServices(getServices);
getServices
getServices(): Promise<Array<GattService>>
Obtains all services of the remote BLE device. This method uses a promise to return the result.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Return value
Type | Description |
---|---|
Promise<Array<GattService>> | Promise used to return the services obtained. |
Example
// Promise
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.connect();
let services = device.getServices();
console.log("bluetooth services size is ", services.length);
for (let i = 0; i < services.length; i++) {
console.log('bluetooth serviceUuid is ' + services[i].serviceUuid);
}
readCharacteristicValue
readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void
Reads the characteristic value of the specific service of the remote BLE device. This method uses an asynchronous callback to return the result.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
characteristic | BLECharacteristic | Yes | Characteristic value to read. |
callback | AsyncCallback<BLECharacteristic> | Yes | Callback invoked to return the characteristic value read. |
Return value
No value is returned.
Example
function readCcc(code, BLECharacteristic) {
if (code.code != 0) {
return;
}
console.log('bluetooth characteristic uuid: ' + BLECharacteristic.characteristicUuid);
let value = new Uint8Array(BLECharacteristic.characteristicValue);
console.log('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]);
}
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let descriptors = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc};
descriptors[0] = descriptor;
let bufferCCC = new ArrayBuffer(8);
let cccV = new Uint8Array(bufferCCC);
cccV[0] = 1;
let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: bufferCCC, descriptors:descriptors};
device.readCharacteristicValue(characteristic, readCcc);
readCharacteristicValue
readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic>
Reads the characteristic value of the specific service of the remote BLE device. This method uses a promise to return the result.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
characteristic | BLECharacteristic | Yes | Characteristic value to read. |
Return value
Type | Description |
Promise<BLECharacteristic> | Promise used to return the characteristic value read. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let descriptors = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc};
descriptors[0] = descriptor;
let bufferCCC = new ArrayBuffer(8);
let cccV = new Uint8Array(bufferCCC);
cccV[0] = 1;
let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: bufferCCC, descriptors:descriptors};
device.readCharacteristicValue(characteristic);
readDescriptorValue
readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void
Reads the descriptor contained in the specific characteristic of the remote BLE device. This method uses an asynchronous callback to return the result.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
descriptor | BLEDescriptor | Yes | Descriptor to read. |
callback | AsyncCallback<BLECharacteristic> | Yes | Callback invoked to return the descriptor read. |
Return value
No value is returned.
Example
function readDesc(code, BLEDescriptor) {
if (code.code != 0) {
return;
}
console.log('bluetooth descriptor uuid: ' + BLEDescriptor.descriptorUuid);
let value = new Uint8Array(BLEDescriptor.descriptorValue);
console.log('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]);
}
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc};
device.readDescriptorValue(descriptor, readDesc);
readDescriptorValue
readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor>
Reads the descriptor contained in the specific characteristic of the remote BLE device. This method uses a promise to return the result.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
descriptor | BLEDescriptor | Yes | Descriptor to read. |
Return value
Type | Description |
Promise<BLEDescriptor> | Promise used to return the descriptor read. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc};
device.readDescriptorValue(descriptor);
writeCharacteristicValue
writeCharacteristicValue(characteristic: BLECharacteristic): boolean
Writes a characteristic value to the remote BLE device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
characteristic | BLECharacteristic | Yes | Binary value and other parameters of the BLE device characteristic. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let descriptors = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc};
descriptors[0] = descriptor;
let bufferCCC = new ArrayBuffer(8);
let cccV = new Uint8Array(bufferCCC);
cccV[0] = 1;
let characteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: bufferCCC, descriptors:descriptors};
let retWriteCcc = device.writeCharacteristicValue(characteristic);
if (retWriteCcc) {
console.log('write characteristic successfully');
} else {
console.log('write characteristic failed');
}
writeDescriptorValue
writeDescriptorValue(descriptor: BLEDescriptor): boolean
Writes binary data to the specific descriptor of the remote BLE device.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
descriptor | BLEDescriptor | Yes | Binary value and other parameters of the BLE device descriptor. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 22;
let descriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc};
let retWriteDesc = device.writeDescriptorValue(descriptor);
if (retWriteDesc) {
console.log('bluetooth write descriptor successfully');
} else {
console.log('bluetooth write descriptor failed');
}
setBLEMtuSize
setBLEMtuSize(mtu: number): boolean
Sets the maximum transmission unit (MTU) that can be transmitted between the GATT client and its remote BLE device. This method can be used only after a connection is set up by calling connect.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
mtu | number | Yes | MTU to set, which ranges from 22 to 512 bytes. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setBLEMtuSize(128);
setNotifyCharacteristicChanged
setNotifyCharacteristicChanged(characteristic: BLECharacteristic, enable: boolean): boolean
Sets the function of notifying the GATT client when the characteristic value of the remote BLE device changes.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
characteristic | BLECharacteristic | Yes | BLE characteristic to listen for. |
enable | boolean | Yes | Whether to enable the notify function. The value true means to enable the notify function, and the value false means the opposite. |
Return value
Type | Description |
---|---|
boolean | Returns true if the operation is successful; returns false otherwise. |
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setNotifyCharacteristicChanged(notifyCcc, false);
on('BLECharacteristicChange')
on(type: "BLECharacteristicChange", callback: Callback<BLECharacteristic>): void
Subscribes to the BLE characteristic change events. The client can receive a notification from the server only after the setNotifyCharacteristicChanged method is called.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value BLECharacteristicChange indicates a characteristic value change event. |
callback | Callback<BLECharacteristic> | Yes | Callback invoked to return the characteristic value changes. |
Return value
No value is returned.
Example
function CharacteristicChange(CharacteristicChangeReq) {
let serviceUuid = CharacteristicChangeReq.serviceUuid;
let characteristicUuid = CharacteristicChangeReq.characteristicUuid;
let value = new Uint8Array(CharacteristicChangeReq.characteristicValue);
}
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.on('BLECharacteristicChange', CharacteristicChange);
off('BLECharacteristicChange')
off(type: "BLECharacteristicChange", callback?: Callback<BLECharacteristic>): void
Unsubscribes from the BLE characteristic change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value BLECharacteristicChange indicates a characteristic value change event. |
callback | Callback<BLECharacteristic> | No | Callback used to report the characteristic value. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.off('BLECharacteristicChange');
on('BLEConnectionStateChange')
on(type: "BLEConnectionStateChange", callback: Callback<BLEConnectChangedState>): void
Subscribes to the BLE connection state change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value BLEConnectionStateChange indicates a BLE connection state change event. |
callback | Callback<BLEConnectChangedState> | Yes | Callback invoked to return the BLE connection state. |
Return value
No value is returned.
Example
function ConnectStateChanged(state) {
console.log('bluetooth connect state changed');
let connectState = state.state;
}
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.on('BLEConnectionStateChange', ConnectStateChanged);
off('BLEConnectionStateChange')
off(type: "BLEConnectionStateChange", callback?: Callback<BLEConnectChangedState>): void
Unsubscribes from the BLE connection state change events.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value BLEConnectionStateChange indicates a BLE connection state change event. |
callback | Callback<BLEConnectChangedState> | No | Callback used to report the BLE connection state. If this parameter is not set, this method unsubscribes from all callbacks corresponding to type. |
Return value
No value is returned.
Example
let device = bluetooth.BLE.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.off('BLEConnectionStateChange');
getDeviceName
getDeviceName(callback: AsyncCallback<string>): void
Obtains the name of the remote BLE device. This method uses an asynchronous callback to return the result.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<string> | Yes | Callback invoked to return the remote BLE device name obtained. |
Return value
No value is returned.
Example
// callback
let gattClient = bluetooth.BLE.createGattClientDevice("XX:XX:XX:XX:XX:XX");
let deviceName = gattClient.getDeviceName((err, data)=> {
console.info('device name err ' + JSON.stringify(err));
console.info('device name' + JSON.stringify(data));
})
getDeviceName
getDeviceName(): Promise<string>
Obtains the name of the remote BLE device. This method uses a promise to return the result.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
Promise<string> | Promise used to return the remote BLE device name. |
Example
// promise
let gattClient = bluetooth.BLE.createGattClientDevice("XX:XX:XX:XX:XX:XX");
let ret = device.connect();
let deviceName = gattClient.getDeviceName().then((data) => {
console.info('device name' + JSON.stringify(data));
})
getRssiValue
getRssiValue(callback: AsyncCallback<number>): void
Obtains the received signal strength indication (RSSI) of the remote BLE device. This method uses an asynchronous callback to return the result. It can be used only after a connection is set up by calling connect.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<number> | Yes | Callback invoked to return the RSSI, in dBm. |
Return value
No value is returned.
Example
// callback
let gattClient = bluetooth.BLE.createGattClientDevice("XX:XX:XX:XX:XX:XX");
let ret = device.connect();
let rssi = gattClient.getRssiValue((err, data)=> {
console.info('rssi err ' + JSON.stringify(err));
console.info('rssi value' + JSON.stringify(data));
})
getRssiValue
getRssiValue(): Promise<number>
Obtains the RSSI of the remote BLE device. This method uses a promise to return the result. It can be used only after a connection is set up by calling connect.
Required permissions: ohos.permission.USE_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
Promise<number> | Promise used to return the RSSI, in dBm. |
Example
// promise
let gattClient = bluetooth.BLE.createGattClientDevice("XX:XX:XX:XX:XX:XX");
let rssi = gattClient.getRssiValue().then((data) => {
console.info('rssi' + JSON.stringify(data));
})
ScanMode8+
Enumerates the scan modes.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
SCAN_MODE_NONE | 0 | No scan mode. |
SCAN_MODE_CONNECTABLE | 1 | Connectable mode. |
SCAN_MODE_GENERAL_DISCOVERABLE | 2 | General discoverable mode. |
SCAN_MODE_LIMITED_DISCOVERABLE | 3 | Limited discoverable mode. |
SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | General connectable and discoverable mode. |
SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | Limited connectable and discoverable mode. |
BondState8+
Enumerates the pairing states.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
BOND_STATE_INVALID | 0 | Invalid pairing. |
BOND_STATE_BONDING | 1 | Pairing. |
BOND_STATE_BONDED | 2 | Paired. |
SppOption8+
Defines the SPP configuration parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
uuid | string | Yes | Yes | UUID of the SPP. |
secure | boolean | Yes | Yes | Whether it is a secure channel. |
type | SppType | Yes | Yes | Type of the SPP link. |
SppType8+
Enumerates the SPP link types.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
SPP_RFCOMM | 0 | Radio frequency communication (RFCOMM) link type. |
GattService
Defines the GATT service API parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
serviceUuid | string | Yes | Yes | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
isPrimary | boolean | Yes | Yes | Whether the service is a primary service. The value true means a primary service. |
characteristics | Array<BLECharacteristic> | Yes | Yes | List of characteristics of the service. |
includeServices | Array<GattService> | Yes | Yes | Services on which the service depends. |
BLECharacteristic
Defines the characteristic API parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
serviceUuid | string | Yes | Yes | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, 00002a11-0000-1000-8000-00805f9b34fb. |
characteristicValue | ArrayBuffer | Yes | Yes | Binary value of the characteristic. |
descriptors | Array<BLEDescriptor> | Yes | Yes | List of descriptors of the characteristic. |
BLEDescriptor
Defines the descriptor API parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
serviceUuid | string | Yes | Yes | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, 00002a11-0000-1000-8000-00805f9b34fb. |
descriptorUuid | string | Yes | Yes | UUID of the descriptor, for example, 00002902-0000-1000-8000-00805f9b34fb. |
descriptorValue | ArrayBuffer | Yes | Yes | Binary value of the descriptor. |
NotifyCharacteristic
Defines the parameters in the notifications sent when the server characteristic value changes.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
serviceUuid | string | Yes | Yes | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, 00002a11-0000-1000-8000-00805f9b34fb. |
characteristicValue | ArrayBuffer | Yes | Yes | Binary value of the characteristic. |
confirm | boolean | Yes | Yes | Whether the notification needs to be confirmed by the remote end. For a notification, set it to true. In this case, the remote end must confirm the receipt of the notification. For an indication, set it to false. In this case, the remote end does not need to confirm the receipt of the notification. |
CharacteristicReadReq
Defines the parameters of the CharacteristicReadReq event received by the server.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | Address of the remote device that sends the CharacteristicReadReq event, for example, XX:XX:XX:XX:XX:XX. |
transId | number | Yes | No | Transmission ID of the read request. The response returned by the server must use the same transmission ID. |
offset | number | Yes | No | Position from which the characteristic value is read. For example, k means to read from the kth byte. The response returned by the server must use the same offset. |
characteristicUuid | string | Yes | No | UUID of the characteristic, for example, 00002a11-0000-1000-8000-00805f9b34fb. |
serviceUuid | string | Yes | No | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
CharacteristicWriteReq
Defines the parameters of the CharacteristicWriteReq event received by the server.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | Address of the remote device that sends the CharacteristicWriteReq event, for example, XX:XX:XX:XX:XX:XX. |
transId | number | Yes | No | Transmission ID of the write request. The response returned by the server must use the same transmission ID. |
offset | number | Yes | No | Start position for writing the characteristic value. For example, k means to write from the kth byte. The response returned by the server must use the same offset. |
descriptorUuid | string | Yes | No | UUID of the descriptor, for example, 00002902-0000-1000-8000-00805f9b34fb. |
characteristicUuid | string | Yes | No | UUID of the characteristic, for example, 00002a11-0000-1000-8000-00805f9b34fb. |
serviceUuid | string | Yes | No | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
DescriptorReadReq
Defines the parameters of the DescriptorReadReq event received by the server.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | Address of the remote device that sends a DescriptorReadReq event, for example, XX:XX:XX:XX:XX:XX. |
transId | number | Yes | No | Transmission ID of the read request. The response returned by the server must use the same transmission ID. |
offset | number | Yes | No | Position from which the descriptor is read. For example, k means to read from the kth byte. The response returned by the server must use the same offset. |
descriptorUuid | string | Yes | No | UUID of the descriptor, for example, 00002902-0000-1000-8000-00805f9b34fb. |
characteristicUuid | string | Yes | No | UUID of the characteristic, for example, 00002a11-0000-1000-8000-00805f9b34fb. |
serviceUuid | string | Yes | No | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
DescriptorWriteReq
Defines the parameters of the DescriptorWriteReq event received by the server.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | Address of the remote device that sends a DescriptorWriteReq event, for example, XX:XX:XX:XX:XX:XX. |
transId | number | Yes | No | Transmission ID of the write request. The response returned by the server must use the same transmission ID. |
offset | number | Yes | No | Start position for writing the descriptor. For example, k means to write from the kth byte. The response returned by the server must use the same offset. |
isPrep | boolean | Yes | No | Whether the write request is executed immediately. |
needRsp | boolean | Yes | No | Whether to send a response to the GATT client. |
value | ArrayBuffer | Yes | No | Binary value of the descriptor to write. |
descriptorUuid | string | Yes | No | UUID of the descriptor, for example, 00002902-0000-1000-8000-00805f9b34fb. |
characteristicUuid | string | Yes | No | UUID of the characteristic, for example, 00002a11-0000-1000-8000-00805f9b34fb. |
serviceUuid | string | Yes | No | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
ServerResponse
Defines the parameters of the server's response to the GATT client's read/write request.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | Address of the remote device, for example, XX:XX:XX:XX:XX:XX. |
transId | number | Yes | No | Transmission ID of the request. The value must be the same as the ID carried in the read/write request received. |
status | number | Yes | No | Response state. Set this parameter to 0, which indicates a normal response. |
offset | number | Yes | No | Start read/write position. The value must be the same as the offset carried in the read/write request. |
value | ArrayBuffer | Yes | No | Binary data in the response. |
BLEConnectChangedState
Defines the parameters of BLEConnectChangedState.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | Address of the remote device, for example, XX:XX:XX:XX:XX:XX. |
state | ProfileConnectionState | Yes | Yes | BLE connection state. |
ProfileConnectionState
Enumerates the profile connection states.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
STATE_DISCONNECTED | 0 | Disconnected. |
STATE_CONNECTING | 1 | Connecting. |
STATE_CONNECTED | 2 | Connected. |
STATE_DISCONNECTING | 3 | Disconnecting. |
ScanFilter
Defines the scan filter parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | Yes | Address of the BLE device to filter, for example, XX:XX:XX:XX:XX:XX. |
name | string | Yes | Yes | Name of the BLE device to filter. |
serviceUuid | string | Yes | Yes | UUID of the service, for example, 00001888-0000-1000-8000-00805f9b34fb. |
ScanOptions
Defines the scan configuration parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
interval | number | Yes | Yes | Delay in reporting the scan result. The default value is 0. |
dutyMode | ScanDuty | Yes | Yes | Scan duty. The default value is SCAN_MODE_LOW_POWER. |
matchMode | MatchMode | Yes | Yes | Hardware filtering match mode. The default value is MATCH_MODE_AGGRESSIVE. |
ScanDuty
Enumerates the scan duty options.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
SCAN_MODE_LOW_POWER | 0 | Low-power mode, which is the default value. |
SCAN_MODE_BALANCED | 1 | Balanced mode. |
SCAN_MODE_LOW_LATENCY | 2 | Low-latency mode. |
MatchMode
Enumerates the hardware match modes of BLE scan filters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
MATCH_MODE_AGGRESSIVE | 1 | Hardware reports the scan result with a lower threshold of signal strength and few number of matches in a duration. This is the default value. |
MATCH_MODE_STICKY | 2 | Hardware reports the scan result with a higher threshold of signal strength and sightings. |
ScanResult
Defines the scan result.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | Address of the scanned device, for example, XX:XX:XX:XX:XX:XX. |
rssi | number | Yes | No | RSSI of the device. |
data | ArrayBuffer | Yes | No | Advertisement packets sent by the device. |
BluetoothState
Enumerates the Bluetooth states.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
STATE_OFF | 0 | Bluetooth is turned off. |
STATE_TURNING_ON | 1 | Bluetooth is being turned on. |
STATE_ON | 2 | Bluetooth is turned on. |
STATE_TURNING_OFF | 3 | Bluetooth is being turned off. |
STATE_BLE_TURNING_ON | 4 | The LE-only mode is being turned on for Bluetooth. |
STATE_BLE_ON | 5 | Bluetooth is in LE-only mode. |
STATE_BLE_TURNING_OFF | 6 | The LE-only mode is being turned off for Bluetooth. |
AdvertiseSetting
Defines the BLE advertising parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
interval | number | Yes | Yes | Interval for BLE advertising. The minimum value is 32 slots (20 ms). The maximum value is 16777215 slots. The default value is 1600 slots (1s). |
txPower | number | Yes | Yes | Transmit power, in dBm. The value range is -127 to 1. The default value is -7. |
connectable | boolean | Yes | Yes | Whether the advertisement is connectable. The default value is true. |
AdvertiseData
Defines the content of a BLE advertisement packet.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
serviceUuids | Array<string> | Yes | Yes | List of service UUIDs to broadcast. |
manufactureData | Array<ManufactureData> | Yes | Yes | List of manufacturers to broadcast. |
serviceData | Array<ServiceData> | Yes | Yes | List of service data to broadcast. |
ManufactureData
Defines the content of a BLE advertisement packet.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
manufactureId | Array<string> | Yes | Yes | Manufacturer ID allocated by the Bluetooth SIG. |
manufactureValue | ArrayBuffer | Yes | Yes | Manufacturer data. |
ServiceData
Defines the service data contained in an advertisement packet.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
serviceUuid | string | Yes | Yes | Service UUID. |
serviceValue | ArrayBuffer | Yes | Yes | Service data. |
PinRequiredParam8+
Defines the pairing request parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | ID of the device to pair. |
pinCode | string | Yes | No | Key for the device pairing. |
StateChangeParam8+
Defines the profile state change parameters.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceId | string | Yes | No | Address of a Bluetooth device. |
state | ProfileConnectionState | Yes | No | Profile connection state of the device. |
DeviceClass8+
Defines the class of a Bluetooth device.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
majorClass | MajorClass | Yes | No | Major classes of Bluetooth devices. |
majorMinorClass | MajorMinorClass | Yes | No | Major and minor classes of Bluetooth devices. |
classOfDevice | number | Yes | No | Class of the device. |
MajorClass8+
Enumerates the major classes of Bluetooth devices.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
MAJOR_MISC | 0x0000 | Miscellaneous device. |
MAJOR_COMPUTER | 0x0100 | Computer. |
MAJOR_PHONE | 0x0200 | Mobile phone. |
MAJOR_NETWORKING | 0x0300 | Network device. |
MAJOR_AUDIO_VIDEO | 0x0400 | Audio or video device. |
MAJOR_PERIPHERAL | 0x0500 | Peripheral device. |
MAJOR_IMAGING | 0x0600 | Imaging device. |
MAJOR_WEARABLE | 0x0700 | Wearable device. |
MAJOR_TOY | 0x0800 | Toy. |
MAJOR_HEALTH | 0x0900 | Health device. |
MAJOR_UNCATEGORIZED | 0x1F00 | Unclassified device. |
MajorMinorClass8+
Enumerates the major and minor classes of Bluetooth devices.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
COMPUTER_UNCATEGORIZED | 0x0100 | Unclassified computer. |
COMPUTER_DESKTOP | 0x0104 | Desktop computer. |
COMPUTER_SERVER | 0x0108 | Server. |
COMPUTER_LAPTOP | 0x010C | Laptop. |
COMPUTER_HANDHELD_PC_PDA | 0x0110 | Hand-held computer. |
COMPUTER_PALM_SIZE_PC_PDA | 0x0114 | Palmtop computer. |
COMPUTER_WEARABLE | 0x0118 | Wearable computer. |
COMPUTER_TABLET | 0x011C | Tablet. |
PHONE_UNCATEGORIZED | 0x0200 | Unclassified mobile phone. |
PHONE_CELLULAR | 0x0204 | Portable phone. |
PHONE_CORDLESS | 0x0208 | Cordless phone. |
PHONE_SMART | 0x020C | Smartphone. |
PHONE_MODEM_OR_GATEWAY | 0x0210 | Modem or gateway phone. |
PHONE_ISDN | 0x0214 | ISDN phone. |
NETWORK_FULLY_AVAILABLE | 0x0300 | Device with network fully available. |
NETWORK_1_TO_17_UTILIZED | 0x0320 | Device used on network 1 to 17. |
NETWORK_17_TO_33_UTILIZED | 0x0340 | Device used on network 17 to 33. |
NETWORK_33_TO_50_UTILIZED | 0x0360 | Device used on network 33 to 50. |
NETWORK_60_TO_67_UTILIZED | 0x0380 | Device used on network 60 to 67. |
NETWORK_67_TO_83_UTILIZED | 0x03A0 | Device used on network 67 to 83. |
NETWORK_83_TO_99_UTILIZED | 0x03C0 | Device used on network 83 to 99. |
NETWORK_NO_SERVICE | 0x03E0 | Device without network service |
AUDIO_VIDEO_UNCATEGORIZED | 0x0400 | Unclassified audio or video device. |
AUDIO_VIDEO_WEARABLE_HEADSET | 0x0404 | Wearable audio or video headset. |
AUDIO_VIDEO_HANDSFREE | 0x0408 | Hands-free audio or video device. |
AUDIO_VIDEO_MICROPHONE | 0x0410 | Audio or video microphone. |
AUDIO_VIDEO_LOUDSPEAKER | 0x0414 | Audio or video loudspeaker. |
AUDIO_VIDEO_HEADPHONES | 0x0418 | Audio or video headphones. |
AUDIO_VIDEO_PORTABLE_AUDIO | 0x041C | Portable audio or video device. |
AUDIO_VIDEO_CAR_AUDIO | 0x0420 | In-vehicle audio or video device. |
AUDIO_VIDEO_SET_TOP_BOX | 0x0424 | Audio or video STB device. |
AUDIO_VIDEO_HIFI_AUDIO | 0x0428 | High-fidelity speaker device. |
AUDIO_VIDEO_VCR | 0x042C | Video cassette recording (VCR) device. |
AUDIO_VIDEO_VIDEO_CAMERA | 0x0430 | Camera. |
AUDIO_VIDEO_CAMCORDER | 0x0434 | Camcorder |
AUDIO_VIDEO_VIDEO_MONITOR | 0x0438 | Audio or video monitor. |
AUDIO_VIDEO_VIDEO_DISPLAY_AND_LOUDSPEAKER | 0x043C | Video display or loudspeaker. |
AUDIO_VIDEO_VIDEO_CONFERENCING | 0x0440 | Video conferencing device. |
AUDIO_VIDEO_VIDEO_GAMING_TOY | 0x0448 | Audio or video gaming toy. |
PERIPHERAL_NON_KEYBOARD_NON_POINTING | 0x0500 | Non-keyboard or non-pointing peripheral device. |
PERIPHERAL_KEYBOARD | 0x0540 | Keyboard device. |
PERIPHERAL_POINTING_DEVICE | 0x0580 | Pointing peripheral device. |
PERIPHERAL_KEYBOARD_POINTING | 0x05C0 | Keyboard pointing device. |
PERIPHERAL_UNCATEGORIZED | 0x0500 | Unclassified peripheral device. |
PERIPHERAL_JOYSTICK | 0x0504 | Peripheral joystick. |
PERIPHERAL_GAMEPAD | 0x0508 | Peripheral game pad |
PERIPHERAL_REMOTE_CONTROL | 0x05C0 | Peripheral remote control device |
PERIPHERAL_SENSING_DEVICE | 0x0510 | Peripheral sensing device. |
PERIPHERAL_DIGITIZER_TABLET | 0x0514 | Peripheral digitizer tablet. |
PERIPHERAL_CARD_READER | 0x0518 | Peripheral card reader. |
PERIPHERAL_DIGITAL_PEN | 0x051C | Peripheral digital pen. |
PERIPHERAL_SCANNER_RFID | 0x0520 | Peripheral RFID scanner. |
PERIPHERAL_GESTURAL_INPUT | 0x0522 | Gesture input device. |
IMAGING_UNCATEGORIZED | 0x0600 | Unclassified imaging device. |
IMAGING_DISPLAY | 0x0610 | Imaging display device. |
IMAGING_CAMERA | 0x0620 | Imaging camera device. |
IMAGING_SCANNER | 0x0640 | Imaging scanner. |
IMAGING_PRINTER | 0x0680 | Imaging printer. |
WEARABLE_UNCATEGORIZED | 0x0700 | Unclassified wearable device. |
WEARABLE_WRIST_WATCH | 0x0704 | Smart watch. |
WEARABLE_PAGER | 0x0708 | Wearable pager. |
WEARABLE_JACKET | 0x070C | Smart jacket. |
WEARABLE_HELMET | 0x0710 | Wearable helmet. |
WEARABLE_GLASSES | 0x0714 | Wearable glasses. |
TOY_UNCATEGORIZED | 0x0800 | Unclassified toy. |
TOY_ROBOT | 0x0804 | Toy robot. |
TOY_VEHICLE | 0x0808 | Toy vehicle. |
TOY_DOLL_ACTION_FIGURE | 0x080C | Humanoid toy doll. |
TOY_CONTROLLER | 0x0810 | Toy controller. |
TOY_GAME | 0x0814 | Toy gaming device. |
HEALTH_UNCATEGORIZED | 0x0900 | Unclassified health devices. |
HEALTH_BLOOD_PRESSURE | 0x0904 | Blood pressure device. |
HEALTH_THERMOMETER | 0x0908 | Thermometer |
HEALTH_WEIGHING | 0x090C | Body scale. |
HEALTH_GLUCOSE | 0x0910 | Blood glucose monitor. |
HEALTH_PULSE_OXIMETER | 0x0914 | Pulse oximeter. |
HEALTH_PULSE_RATE | 0x0918 | Heart rate monitor. |
HEALTH_DATA_DISPLAY | 0x091C | Health data display. |
HEALTH_STEP_COUNTER | 0x0920 | Step counter. |
HEALTH_BODY_COMPOSITION_ANALYZER | 0x0924 | Body composition analyzer. |
HEALTH_PEAK_FLOW_MOITOR | 0x0928 | Hygrometer. |
HEALTH_MEDICATION_MONITOR | 0x092C | Medication monitor. |
HEALTH_KNEE_PROSTHESIS | 0x0930 | Prosthetic knee. |
HEALTH_ANKLE_PROSTHESIS | 0x0934 | Prosthetic ankle. |
HEALTH_GENERIC_HEALTH_MANAGER | 0x0938 | Generic health management device. |
HEALTH_PERSONAL_MOBILITY_DEVICE | 0x093C | Personal mobility device. |
PlayingState8+
Enumerates the A2DP playing states.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
STATE_NOT_PLAYING | 0x0000 | Not playing. |
STATE_PLAYING | 0x0001 | Playing. |
ProfileId8+
Enumerates the Bluetooth profile IDs.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Default Value | Description |
---|---|---|
PROFILE_A2DP_SOURCE | 0x0001 | A2DP profile. |
PROFILE_HANDS_FREE_AUDIO_GATEWAY | 0x0004 | HFP profile. |