> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> 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.
| 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.|
| 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**. |
| 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**.|
| type | string | Yes| Event type. The value **pinRequired** indicates a pairing request event.|
| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | Yes| Callback invoked to return the pairing request. You need to implement this callback.|
**Return values:**
**Return value**
None.
No value is returned.
**Example:**
**Example**
```
```js
functiononReceiveEvent(data){// data is the pairing request parameter.
| type | string | Yes | Event type. The value **pinRequired** indicates a pairing request event. |
| callback | Callback<[PinRequiredParam](#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**. |
| type | string | Yes| Event type. The value **pinRequired** indicates a pairing request event.|
| callback | Callback<[PinRequiredParam](#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**.|
| type | string | Yes | Event type. The value **bondStateChange** indicates a Bluetooth pairing state change event. |
| callback | Callback<[BondState](#bondstate)> | 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**. |
| type | string | Yes| Event type. The value **bondStateChange** indicates a Bluetooth pairing state change event.|
| callback | Callback<[BondState](#bondstate)> | 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 values:**
**Return value**
None.
No value is returned.
**Example:**
**Example**
```
```js
functiononReceiveEvent(data){
console.info('bond state = '+JSON.stringify(data));
| type | string | Yes| Event type. The value **stateChange** indicates a Bluetooth connection state change event.|
| callback | Callback<[BluetoothState](#bluetoothstate)> | Yes| Callback invoked to return the Bluetooth connection state. You need to implement this callback.|
**Return values:**
**Return value**
None.
No value is returned.
**Example:**
**Example**
```
```js
functiononReceiveEvent(data){
console.info('bluetooth state = '+JSON.stringify(data));
| type | string | Yes | Event type. The value **stateChange** indicates a Bluetooth connection state change event. |
| callback | Callback<[BluetoothState](#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**. |
| type | string | Yes| Event type. The value **stateChange** indicates a Bluetooth connection state change event.|
| callback | Callback<[BluetoothState](#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 values:**
**Return value**
None.
No value is returned.
**Example:**
**Example**
```
```js
functiononReceiveEvent(data){
console.info('bluetooth state = '+JSON.stringify(data));
| 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**. |
| 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**.|
| 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. |
| deviceId | string | Yes| Address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
**Return value**
| Type| Description|
| -------- | -------- |
| [GattClientDevice](#gattclientdevice) | **GattClientDevice** instance created. Before using a method of the client, you must create a **GattClientDevice** instance.|
| filters | Array<[ScanFilter](#scanfilter)> | Yes| Criteria for filtering the scan result. Set this parameter to **null** if you do not want to filter the scan result.|
| type | string | Yes| Event type. The value **BLEDeviceFind** indicates an event reported when a BLE device is discovered.|
| callback | Callback<Array<[ScanResult](#scanresult)>> | Yes| Callback invoked to return the discovered devices. You need to implement this callback.|
| type | string | Yes| Event type. The value **BLEDeviceFind** indicates an event reported when a BLE device is discovered.|
| callback | Callback<Array<[ScanResult](#scanresult)>> | No| Callback used to report the discovered devices. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**.|
| type | string | Yes| Event type. The value **characteristicRead** indicates a characteristic read request event.|
| callback | Callback<[CharacteristicReadReq](#characteristicreadreq)> | Yes| Callback invoked to return a characteristic read request from the GATT client.|
| type | string | Yes | Event type. The value **characteristicRead** indicates a characteristic read request event. |
| callback | Callback<[CharacteristicReadReq](#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**. |
| type | string | Yes| Event type. The value **characteristicRead** indicates a characteristic read request event.|
| callback | Callback<[CharacteristicReadReq](#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**.|
| type | string | Yes| Event type. The value **characteristicWrite** indicates a characteristic write request event.|
| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | Yes| Callback invoked to return a characteristic write request from the GATT client.|
| type | string | Yes | Event type. The value **characteristicWrite** indicates a characteristic write request event. |
| callback | Callback<[CharacteristicWriteReq](#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**. |
| type | string | Yes| Event type. The value **characteristicWrite** indicates a characteristic write request event.|
| callback | Callback<[CharacteristicWriteReq](#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**.|
| type | string | Yes| Event type. The value **descriptorRead** indicates a descriptor read request event.|
| callback | Callback<[DescriptorReadReq](#descriptorreadreq)> | Yes| Callback invoked to return a descriptor read request event from the GATT client.|
| type | string | Yes | Event type. The value **descriptorRead** indicates a descriptor read request event. |
| callback | Callback<[DescriptorReadReq](#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**. |
| type | string | Yes| Event type. The value **descriptorRead** indicates a descriptor read request event.|
| callback | Callback<[DescriptorReadReq](#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**.|
| type | string | Yes| Event type. The value **descriptorWrite** indicates a descriptor write request event.|
| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | Yes| Callback invoked to return a descriptor write request from the GATT client.|
**Return values:**
**Return value**
None.
No value is returned.
**Example:**
**Example**
```
```js
letarrayBufferDesc=newArrayBuffer(8);
letdescValue=newUint8Array(arrayBufferDesc);
functionWriteDescriptorReq(DescriptorWriteReq){
...
...
@@ -1437,20 +2108,24 @@ off(type: "descriptorWrite", callback?: Callback<DescriptorWriteReq>): voi
Unsubscribes from the descriptor write request events.
| type | string | Yes | Event type. The value **descriptorWrite** indicates a descriptor write request event. |
| callback | Callback<[DescriptorWriteReq](#descriptorwritereq)> | 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**. |
| type | string | Yes| Event type. The value **descriptorWrite** indicates a descriptor write request event.|
| callback | Callback<[DescriptorWriteReq](#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**.|
| type | string | Yes | Event type. The value **connectStateChange** indicates a BLE connection state change event. |
| callback | Callback<[BLEConnectChangedState](#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**. |
| type | string | Yes| Event type. The value **connectStateChange** indicates a BLE connection state change event.|
| callback | Callback<[BLEConnectChangedState](#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 values:**
**Return value**
None.
No value is returned.
**Example:**
**Example**
```
```js
letgattServer=bluetooth.BLE.createGattServer();
gattServer.off("connectStateChange");
```
...
...
@@ -1520,18 +2203,22 @@ Implements the GATT client. Before using a method of this class, you must create
Closes this GATT client to unregister it from the protocol stack. After this method is called, this [GattClientDevice](#gattclientdevice) instance cannot be used.
Reads the descriptor contained in the specific characteristic of the peer BLE device. This method uses an asynchronous callback to return the result.
Reads the descriptor contained in the specific characteristic of the remote BLE device. This method uses an asynchronous callback to return the result.
Sets the maximum transmission unit (MTU) that can be transmitted between the GATT client and its peer BLE device. This method can be used only after a connection is set up by calling **connect**.
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](#connect).
| characteristic | [BLECharacteristic](#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.|
Subscribes to the BLE characteristic change events. The client can receive a notification from the server only after the **setNotifyCharacteristicChanged** method is called.
| type | string | Yes | Event type. The value **BLECharacteristicChange** indicates a characteristic value change event. |
| callback | Callback<[BLECharacteristic](#blecharacteristic)> | No | Callback used to report the characteristic value. If this parameter is not set, this method unsubscribes from all callbacks corresponding to **type**. |
| type | string | Yes| Event type. The value **BLECharacteristicChange** indicates a characteristic value change event.|
| callback | Callback<[BLECharacteristic](#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 values:**
**Return value**
None.
No value is returned.
**Example:**
**Example**
```
let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D');
| type | string | Yes | Event type. The value **BLEConnectionStateChange** indicates a BLE connection state change event. |
| callback | Callback<[BLEConnectChangedState](#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**. |
| type | string | Yes| Event type. The value **BLEConnectionStateChange** indicates a BLE connection state change event.|
| callback | Callback<[BLEConnectChangedState](#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 values:**
**Return value**
None.
No value is returned.
**Example:**
**Example**
```
let device = bluetooth.BLE.createGattClientDevice('8F:8F:8E:8E:6D:6D');
Obtains the received signal strength indication (RSSI) of the peer 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](#connect).
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](#connect).
@@ -2140,327 +2904,548 @@ let rssi = gattClient.getRssiValue((err, data)=> {
getRssiValue(): Promise<number>
Obtains the RSSI of the peer 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](#connect).
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](#connect).
| 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.
| 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.
| 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.
| 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.
| 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.
| Name | Type | Readable | Writable | Description |
| 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. |
| 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**.
| Name | Type | Readable | Writable | 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.
| 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.
| Name | Type | Readable | Writable | Description |
