harmony 鸿蒙@ohos.bluetooth.ble (Bluetooth BLE Module)
@ohos.bluetooth.ble (Bluetooth BLE Module)
The ble module provides APIs for operating and managing Bluetooth.
NOTE
The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Modules to Import
import ble from '@ohos.bluetooth.ble';
ble.createGattServer
createGattServer(): GattServer
Creates a GattServer instance.
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
GattServer | GattServer instance created. |
Example
let gattServer: ble.GattServer = ble.createGattServer();
console.info('gatt success');
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 an API of the client, you must create a GattClientDevice instance. |
Example
import { BusinessError } from '@ohos.base';
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
ble.getConnectedBLEDevices
getConnectedBLEDevices(): Array<string>
Obtains the Bluetooth Low Energy (BLE) devices connected to this device.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
Array<string> | Addresses of the BLE devices connected to this device. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
try {
let result: Array<string> = ble.getConnectedBLEDevices();
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
ble.startBLEScan
startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void
Starts a BLE scan.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
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. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
function onReceiveEvent(data: Array<ble.ScanResult>) {
console.info('BLE scan device find result = '+ JSON.stringify(data));
}
try {
ble.on("BLEDeviceFind", onReceiveEvent);
let scanFilter: ble.ScanFilter = {
deviceId:"XX:XX:XX:XX:XX:XX",
name:"test",
serviceUuid:"00001888-0000-1000-8000-00805f9b34fb"
};
let scanOptions: ble.ScanOptions = {
interval: 500,
dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER,
matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE,
}
ble.startBLEScan([scanFilter],scanOptions);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
ble.stopBLEScan
stopBLEScan(): void
Stops the BLE scan.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
try {
ble.stopBLEScan();
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
ble.startAdvertising
startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void
Starts BLE advertising.
Required permissions: ohos.permission.ACCESS_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. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
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));
try {
let setting: ble.AdvertiseSetting = {
interval:150,
txPower:0,
connectable:true,
};
let manufactureDataUnit: ble.ManufactureData = {
manufactureId:4567,
manufactureValue:manufactureValueBuffer.buffer
};
let serviceDataUnit: ble.ServiceData = {
serviceUuid:"00001888-0000-1000-8000-00805f9b34fb",
serviceValue:serviceValueBuffer.buffer
};
let advData: ble.AdvertiseData = {
serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
manufactureData:[manufactureDataUnit],
serviceData:[serviceDataUnit],
};
let advResponse: ble.AdvertiseData = {
serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"],
manufactureData:[manufactureDataUnit],
serviceData:[serviceDataUnit],
};
ble.startAdvertising(setting, advData ,advResponse);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
ble.stopAdvertising
stopAdvertising(): void
Stops BLE advertising.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
try {
ble.stopAdvertising();
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
ble.on(‘BLEDeviceFind’)
on(type: ‘BLEDeviceFind’, callback: Callback<Array<ScanResult>>): void
Subscribes to BLE device discovery events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLEDeviceFind, which indicates an event of discovering a BLE device. |
callback | Callback<Array<ScanResult>> | Yes | Callback invoked to return the discovered devices. You need to implement this callback. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
function onReceiveEvent(data: Array<ble.ScanResult>) {
console.info('bluetooth device find = '+ JSON.stringify(data));
}
try {
ble.on('BLEDeviceFind', onReceiveEvent);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
ble.off(‘BLEDeviceFind’)
off(type: ‘BLEDeviceFind’, callback?: Callback<Array<ScanResult>>): void
Unsubscribes from the BLE device discovery events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLEDeviceFind, which indicates an event of discovering a BLE device. |
callback | Callback<Array<ScanResult>> | No | Callback for the BLEDeviceFind event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
function onReceiveEvent(data: Array<ble.ScanResult>) {
console.info('bluetooth device find = '+ JSON.stringify(data));
}
try {
ble.on('BLEDeviceFind', onReceiveEvent);
ble.off('BLEDeviceFind', onReceiveEvent);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
GattServer
Implements the Generic Attribute Profile (GATT) server. Before using an API of this class, you need to create a GattServer instance using createGattServer().
addService
addService(service: GattService): void
Adds a service to this GATT server.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
service | GattService | Yes | Service to add. Settings related to BLE advertising. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// Create descriptors.
let descriptors: Array<ble.BLEDescriptor> = [];
let arrayBuffer = new ArrayBuffer(8);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer};
descriptors[0] = descriptor;
// Create characteristics.
let characteristics: Array<ble.BLECharacteristic> = [];
let arrayBufferC = new ArrayBuffer(8);
let cccV = new Uint8Array(arrayBufferC);
cccV[0] = 1;
let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors};
let characteristicN: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors};
characteristics[0] = characteristic;
// Create a gattService instance.
let gattService: ble.GattService = {serviceUuid:'00001810-0000-1000-8000-00805F9B34FB', isPrimary: true, characteristics:characteristics, includeServices:[]};
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.addService(gattService);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
removeService
removeService(serviceUuid: string): void
Removes a service from this GATT server.
Required permissions: ohos.permission.ACCESS_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. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900004 | Profile is not supported. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let server: ble.GattServer = ble.createGattServer();
try {
server.removeService('00001810-0000-1000-8000-00805F9B34FB');
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
close
close(): void
Closes this GATT server to unregister it from the protocol stack. The closed GattServer instance will no longer be used.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let server: ble.GattServer = ble.createGattServer();
try {
server.close();
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
notifyCharacteristicChanged
notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic, callback: AsyncCallback<void>): void
Notifies a connected client device when a characteristic value changes. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Address of the client that receives the notifications, for example, XX:XX:XX:XX:XX:XX. |
notifyCharacteristic | NotifyCharacteristic | Yes | New characteristic value. |
callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, err is undefined; otherwise, err is an error object. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let arrayBufferC = new ArrayBuffer(8);
let notifyCharacter: ble.NotifyCharacteristic = {
serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: arrayBufferC,
confirm: true,
};
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter, (err: BusinessError) => {
if (err) {
console.info('notifyCharacteristicChanged callback failed');
} else {
console.info('notifyCharacteristicChanged callback successful');
}
});
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
notifyCharacteristicChanged
notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): Promise<void>
Notifies a connected client device when a characteristic value changes. This API uses a promise to return the result.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
deviceId | string | Yes | Address of the client that receives the notifications, for example, XX:XX:XX:XX:XX:XX. |
notifyCharacteristic | NotifyCharacteristic | Yes | New characteristic value. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let arrayBufferC = new ArrayBuffer(8);
let notifyCharacter: ble.NotifyCharacteristic = {
serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: arrayBufferC,
confirm: true,
};
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter).then(() => {
console.info('notifyCharacteristicChanged promise successfull');
});
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
sendResponse
sendResponse(serverResponse: ServerResponse): void
Sends a response to a read or write request from the GATT client.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
serverResponse | ServerResponse | Yes | Response returned by the GATT server. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
/* send response */
let arrayBufferCCC = new ArrayBuffer(8);
let cccValue = new Uint8Array(arrayBufferCCC);
cccValue[0] = 1123;
let serverResponse: ble.ServerResponse = {
deviceId: 'XX:XX:XX:XX:XX:XX',
transId: 0,
status: 0,
offset: 0,
value: arrayBufferCCC,
};
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.sendResponse(serverResponse);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
on(‘characteristicRead’)
on(type: ‘characteristicRead’, callback: Callback<CharacteristicReadRequest>): void
Subscribes to characteristic read request events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is characteristicRead, which indicates a characteristic read request event. |
callback | Callback<CharacteristicReadRequest> | Yes | Callback invoked to return a characteristic read request event from the GATT client. |
Example
import { BusinessError } from '@ohos.base';
let arrayBufferCCC = new ArrayBuffer(8);
let cccValue = new Uint8Array(arrayBufferCCC);
cccValue[0] = 1123;
let gattServer: ble.GattServer = ble.createGattServer();
function ReadCharacteristicReq(characteristicReadRequest: ble.CharacteristicReadRequest) {
let deviceId: string = characteristicReadRequest.deviceId;
let transId: number = characteristicReadRequest.transId;
let offset: number = characteristicReadRequest.offset;
let characteristicUuid: string = characteristicReadRequest.characteristicUuid;
let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC};
try {
gattServer.sendResponse(serverResponse);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
}
gattServer.on('characteristicRead', ReadCharacteristicReq);
off(‘characteristicRead’)
off(type: ‘characteristicRead’, callback?: Callback<CharacteristicReadRequest>): void
Unsubscribes from characteristic read request events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is characteristicRead, which indicates a characteristic read request event. |
callback | Callback<CharacteristicReadRequest> | No | Callback for the characteristic read request event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.off('characteristicRead');
} catch (err) {
console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message);
}
on(‘characteristicWrite’)
on(type: ‘characteristicWrite’, callback: Callback<CharacteristicWriteRequest>): void
Subscribes to characteristic write request events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is characteristicWrite, which indicates a characteristic write request event. |
callback | Callback<CharacteristicWriteRequest> | Yes | Callback invoked to return a characteristic write request from the GATT client. |
Example
import { BusinessError } from '@ohos.base';
let arrayBufferCCC = new ArrayBuffer(8);
let cccValue = new Uint8Array(arrayBufferCCC);
let gattServer: ble.GattServer = ble.createGattServer();
function WriteCharacteristicReq(characteristicWriteRequest: ble.CharacteristicWriteRequest) {
let deviceId: string = characteristicWriteRequest.deviceId;
let transId: number = characteristicWriteRequest.transId;
let offset: number = characteristicWriteRequest.offset;
let isPrepared: boolean = characteristicWriteRequest.isPrepared;
let needRsp: boolean = characteristicWriteRequest.needRsp;
let value: Uint8Array = new Uint8Array(characteristicWriteRequest.value);
let characteristicUuid: string = characteristicWriteRequest.characteristicUuid;
cccValue[0] = value[0];
let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC};
try {
gattServer.sendResponse(serverResponse);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
}
gattServer.on('characteristicWrite', WriteCharacteristicReq);
off(‘characteristicWrite’)
off(type: ‘characteristicWrite’, callback?: Callback<CharacteristicWriteRequest>): void
Unsubscribes from characteristic write request events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is characteristicWrite, which indicates a characteristic write request event. |
callback | Callback<CharacteristicWriteRequest> | No | Callback for the characteristic write request event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.off('characteristicWrite');
} catch (err) {
console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message);
}
on(‘descriptorRead’)
on(type: ‘descriptorRead’, callback: Callback<DescriptorReadRequest>): void
Subscribes to descriptor read request events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is descriptorRead, which indicates a descriptor read request event. |
callback | Callback<DescriptorReadRequest> | Yes | Callback invoked to return a descriptor read request event from the GATT client. |
Example
import { BusinessError } from '@ohos.base';
let arrayBufferDesc = new ArrayBuffer(8);
let descValue = new Uint8Array(arrayBufferDesc);
descValue[0] = 1101;
let gattServer: ble.GattServer = ble.createGattServer();
function ReadDescriptorReq(descriptorReadRequest: ble.DescriptorReadRequest) {
let deviceId: string = descriptorReadRequest.deviceId;
let transId: number = descriptorReadRequest.transId;
let offset: number = descriptorReadRequest.offset;
let descriptorUuid: string = descriptorReadRequest.descriptorUuid;
let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc};
try {
gattServer.sendResponse(serverResponse);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
}
gattServer.on('descriptorRead', ReadDescriptorReq);
off(‘descriptorRead’)
off(type: ‘descriptorRead’, callback?: Callback<DescriptorReadRequest>): void
Unsubscribes from descriptor read request events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is descriptorRead, which indicates a descriptor read request event. |
callback | Callback<DescriptorReadRequest> | No | Callback for the descriptor read request event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.off('descriptorRead');
} catch (err) {
console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message);
}
on(‘descriptorWrite’)
on(type: ‘descriptorWrite’, callback: Callback<DescriptorWriteRequest>): void
Subscribes to descriptor write request events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is descriptorWrite, which indicates a descriptor write request event. |
callback | Callback<DescriptorWriteRequest> | Yes | Callback invoked to return a descriptor write request from the GATT client. |
Example
import { BusinessError } from '@ohos.base';
let arrayBufferDesc = new ArrayBuffer(8);
let descValue = new Uint8Array(arrayBufferDesc);
let gattServer: ble.GattServer = ble.createGattServer();
function WriteDescriptorReq(descriptorWriteRequest: ble.DescriptorWriteRequest) {
let deviceId: string = descriptorWriteRequest.deviceId;
let transId: number = descriptorWriteRequest.transId;
let offset: number = descriptorWriteRequest.offset;
let isPrepared: boolean = descriptorWriteRequest.isPrepared;
let needRsp: boolean = descriptorWriteRequest.needRsp;
let value: Uint8Array = new Uint8Array(descriptorWriteRequest.value);
let descriptorUuid: string = descriptorWriteRequest.descriptorUuid;
descValue[0] = value[0];
let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc};
try {
gattServer.sendResponse(serverResponse);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
}
gattServer.on('descriptorWrite', WriteDescriptorReq);
off(‘descriptorWrite’)
off(type: ‘descriptorWrite’, callback?: Callback<DescriptorWriteRequest>): void
Unsubscribes from descriptor write request events.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is descriptorWrite, which indicates a descriptor write request event. |
callback | Callback<DescriptorWriteRequest> | No | Callback for the descriptor write request event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.off('descriptorWrite');
} catch (err) {
console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message);
}
on(‘connectionStateChange’)
on(type: ‘connectionStateChange’, callback: Callback<BLEConnectionChangeState>): void
Subscribes to BLE connection state changes.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is connectionStateChange, which indicates BLE connection state changes. |
callback | Callback<BLEConnectionChangeState> | Yes | Callback invoked to return the BLE connection state. |
Example
import { BusinessError } from '@ohos.base';
import constant from '@ohos.bluetooth.constant';
function Connected(bleConnectionChangeState: ble.BLEConnectionChangeState) {
let deviceId: string = bleConnectionChangeState.deviceId;
let status: constant.ProfileConnectionState = bleConnectionChangeState.state;
}
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.on('connectionStateChange', Connected);
} catch (err) {
console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message);
}
off(‘connectionStateChange’)
off(type: ‘connectionStateChange’, callback?: Callback<BLEConnectionChangeState>): void
Unsubscribes from BLE connection state changes.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is connectionStateChange, which indicates BLE connection state changes. |
callback | Callback<BLEConnectionChangeState> | No | Callback for the BLE connection state change. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.off('connectionStateChange');
} catch (err) {
console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message);
}
on(‘BLEMtuChange’)
on(type: ‘BLEMtuChange’, callback: Callback<number>): void
Subscribes to MTU status changes for the server.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLEMtuChange, which indicates MTU status changes. If this parameter is not set correctly, the callback cannot be registered. |
callback | Callback<number> | Yes | Callback invoked to return the number of MTU bytes. |
Example
import { BusinessError } from '@ohos.base';
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.on('BLEMtuChange', (mtu: number) => {
console.info('BLEMtuChange, mtu: ' + mtu);
});
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
off(‘BLEMtuChange’)
off(type: ‘BLEMtuChange’, callback?: Callback<number>): void
Unsubscribes from MTU status changes for the server.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLEMtuChange, which indicates MTU status changes. If this parameter is not set correctly, the callback cannot be unregistered. |
callback | Callback<number> | No | Callback for the MTU status changes. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let gattServer: ble.GattServer = ble.createGattServer();
gattServer.off('BLEMtuChange');
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
GattClientDevice
Implements the GATT client. Before using an API of this class, you must create a GattClientDevice instance using createGattClientDevice(deviceId: string).
connect
connect(): void
Connects to the remote BLE device.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.connect();
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
disconnect
disconnect(): void
Disconnects from the remote BLE device.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.disconnect();
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
close
close(): void
Closes this GATT client to unregister it from the protocol stack. The closed GattClientDevice instance will no longer be used.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900003 | Bluetooth switch is off. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.close();
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
getDeviceName
getDeviceName(callback: AsyncCallback<string>): void
Obtains the name of the remote BLE device. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.ACCESS_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. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// callback
try {
let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX");
gattClient.connect();
gattClient.getDeviceName((err: BusinessError, data: string)=> {
console.info('device name err ' + JSON.stringify(err));
console.info('device name' + JSON.stringify(data));
})
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
getDeviceName
getDeviceName(): Promise<string>
Obtains the name of the remote BLE device. This API uses a promise to return the result.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
Promise<string> | Promise used to return the remote BLE device name. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// promise
try {
let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX");
gattClient.connect();
gattClient.getDeviceName().then((data: string) => {
console.info('device name' + JSON.stringify(data));
})
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
getServices
getServices(callback: AsyncCallback<Array<GattService>>): void
Obtains all services of the remote BLE device. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Array<GattService>> | Yes | Callback invoked to return the services obtained. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// Callback
function getServices(code: BusinessError, gattServices: Array<ble.GattService>) {
if (code.code == 0) {
let services: Array<ble.GattService> = 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);
}
}
}
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.connect();
device.getServices(getServices);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
getServices
getServices(): Promise<Array<GattService>>
Obtains all services of the remote BLE device. This API uses a promise to return the result.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
Promise<Array<GattService>> | Promise used to return the services obtained. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// Promise
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.connect();
device.getServices().then((result: Array<ble.GattService>) => {
console.info('getServices successfully:' + JSON.stringify(result));
});
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
readCharacteristicValue
readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void
Reads the characteristic value of the specific service of the remote BLE device. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.ACCESS_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. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2901000 | Read forbidden. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
function readCcc(code: BusinessError, BLECharacteristic: ble.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 descriptors: Array<ble.BLEDescriptor> = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {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: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: bufferCCC, descriptors:descriptors};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.readCharacteristicValue(characteristic, readCcc);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
readCharacteristicValue
readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic>
Reads the characteristic value of the specific service of the remote BLE device. This API uses a promise to return the result.
Required permissions: ohos.permission.ACCESS_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. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2901000 | Read forbidden. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let descriptors: Array<ble.BLEDescriptor> = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {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: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: bufferCCC, descriptors:descriptors};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.readCharacteristicValue(characteristic);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
readDescriptorValue
readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void
Reads the descriptor contained in the specific characteristic of the remote BLE device. This API uses an asynchronous callback to return the result.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
descriptor | BLEDescriptor | Yes | Descriptor to read. |
callback | AsyncCallback<BLEDescriptor> | Yes | Callback invoked to return the descriptor read. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2901000 | Read forbidden. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
function readDesc(code: BusinessError, BLEDescriptor: ble.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 bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {
serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB',
descriptorValue: bufferDesc
};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.readDescriptorValue(descriptor, readDesc);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
readDescriptorValue
readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor>
Reads the descriptor contained in the specific characteristic of the remote BLE device. This API uses a promise to return the result.
Required permissions: ohos.permission.ACCESS_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. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2901000 | Read forbidden. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {
serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB',
descriptorValue: bufferDesc
};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.readDescriptorValue(descriptor);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
writeCharacteristicValue
writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void>): void
Writes a characteristic value to the remote BLE device.
Required permissions: ohos.permission.ACCESS_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. |
writeType | GattWriteType | Yes | Write type of the Bluetooth device characteristic value. |
callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the write operation is successful, err is undefined. Otherwise, err is an error object. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2901001 | Write forbidden. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let descriptors: Array<ble.BLEDescriptor> = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {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: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: bufferCCC, descriptors:descriptors};
function writeCharacteristicValueCallBack(code: BusinessError) {
if (code.code != 0) {
return;
}
console.log('bluetooth writeCharacteristicValue success');
}
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE, writeCharacteristicValueCallBack);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
writeCharacteristicValue
writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void>
Writes a characteristic value to the remote BLE device.
Required permissions: ohos.permission.ACCESS_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. |
writeType | GattWriteType | Yes | Write type of the Bluetooth device characteristic value. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the descriptor read. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2901001 | Write forbidden. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let descriptors: Array<ble.BLEDescriptor> = [];
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {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: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
characteristicValue: bufferCCC, descriptors:descriptors};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
writeDescriptorValue
writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void
Writes binary data to the specific descriptor of the remote BLE device.
Required permissions: ohos.permission.ACCESS_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. |
callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the write operation is successful, err is undefined. Otherwise, err is an error object. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2901001 | Write forbidden. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 22;
let descriptor: ble.BLEDescriptor = {
serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB',
descriptorValue: bufferDesc
};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.writeDescriptorValue(descriptor);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
writeDescriptorValue
writeDescriptorValue(descriptor: BLEDescriptor): Promise<void>
Writes binary data to the specific descriptor of the remote BLE device.
Required permissions: ohos.permission.ACCESS_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 |
---|---|
Promise<void> | Promise used to return the descriptor read. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2901001 | Write forbidden. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
let bufferDesc = new ArrayBuffer(8);
let descV = new Uint8Array(bufferDesc);
descV[0] = 22;
let descriptor: ble.BLEDescriptor = {
serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB',
descriptorValue: bufferDesc
};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.writeDescriptorValue(descriptor);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
getRssiValue
getRssiValue(callback: AsyncCallback<number>): void
Obtains the RSSI of the remote BLE device. This API 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.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<number> | Yes | Callback invoked to return the RSSI, in dBm. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// callback
try {
let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX");
gattClient.connect();
let rssi = gattClient.getRssiValue((err: BusinessError, data: number)=> {
console.info('rssi err ' + JSON.stringify(err));
console.info('rssi value' + JSON.stringify(data));
})
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
getRssiValue
getRssiValue(): Promise<number>
Obtains the RSSI of the remote BLE device. This API 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.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Return value
Type | Description |
---|---|
Promise<number> | Promise used to return the RSSI, in dBm. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// promise
try {
let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX");
gattClient.getRssiValue().then((data: number) => {
console.info('rssi' + JSON.stringify(data));
})
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
setBLEMtuSize
setBLEMtuSize(mtu: number): void
Sets the maximum transmission unit (MTU) that can be transmitted between the GATT client and its remote BLE device. This API can be used only after a connection is set up by calling connect.
Required permissions: ohos.permission.ACCESS_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. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setBLEMtuSize(128);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
setCharacteristicChangeNotification
setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void
Sets the function of notifying the GATT client when the characteristic value of the remote BLE device changes.
Required permissions: ohos.permission.ACCESS_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. |
callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// Create descriptors.
let descriptors: Array<ble.BLEDescriptor> = [];
let arrayBuffer = new ArrayBuffer(8);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer};
descriptors[0] = descriptor;
let arrayBufferC = new ArrayBuffer(8);
let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setCharacteristicChangeNotification(characteristic, false);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
setCharacteristicChangeNotification
setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void>
Sets the function of notifying the GATT client when the characteristic value of the remote BLE device changes.
Required permissions: ohos.permission.ACCESS_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 |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// Create descriptors.
let descriptors: Array<ble.BLEDescriptor> = [];
let arrayBuffer = new ArrayBuffer(8);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer};
descriptors[0] = descriptor;
let arrayBufferC = new ArrayBuffer(8);
let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setCharacteristicChangeNotification(characteristic, false);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
setCharacteristicChangeIndication
setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void
Sets the function of notifying the GATT client when the characteristic value of the remote BLE device changes.
Required permissions: ohos.permission.ACCESS_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. |
callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// Create descriptors.
let descriptors: Array<ble.BLEDescriptor> = [];
let arrayBuffer = new ArrayBuffer(8);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer};
descriptors[0] = descriptor;
let arrayBufferC = new ArrayBuffer(8);
let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setCharacteristicChangeIndication(characteristic, false);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
setCharacteristicChangeIndication
setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void>
Sets the function of notifying the GATT client when the characteristic value of the remote BLE device changes.
Required permissions: ohos.permission.ACCESS_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 |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Bluetooth Error Codes.
ID | Error Message |
---|---|
2900001 | Service stopped. |
2900099 | Operation failed. |
Example
import { BusinessError } from '@ohos.base';
// Create descriptors.
let descriptors: Array<ble.BLEDescriptor> = [];
let arrayBuffer = new ArrayBuffer(8);
let descV = new Uint8Array(arrayBuffer);
descV[0] = 11;
let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB',
descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer};
descriptors[0] = descriptor;
let arrayBufferC = new ArrayBuffer(8);
let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB',
characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors};
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.setCharacteristicChangeIndication(characteristic, false);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
on(‘BLECharacteristicChange’)
on(type: ‘BLECharacteristicChange’, callback: Callback<BLECharacteristic>): void
Subscribes to BLE characteristic changes. The client can receive a notification from the server only after the setNotifyCharacteristicChanged method is called.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLECharacteristicChange, which indicates characteristic value changes. |
callback | Callback<BLECharacteristic> | Yes | Callback invoked to return the characteristic value changes. |
Example
import { BusinessError } from '@ohos.base';
function CharacteristicChange(characteristicChangeReq: ble.BLECharacteristic) {
let serviceUuid: string = characteristicChangeReq.serviceUuid;
let characteristicUuid: string = characteristicChangeReq.characteristicUuid;
let value: Uint8Array = new Uint8Array(characteristicChangeReq.characteristicValue);
}
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.on('BLECharacteristicChange', CharacteristicChange);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
off(‘BLECharacteristicChange’)
off(type: ‘BLECharacteristicChange’, callback?: Callback<BLECharacteristic>): void
Unsubscribes from BLE characteristic changes.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLECharacteristicChange, which indicates characteristic value changes. |
callback | Callback<BLECharacteristic> | No | Callback for the characteristic value change. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.off('BLECharacteristicChange');
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
on(‘BLEConnectionStateChange’)
on(type: ‘BLEConnectionStateChange’, callback: Callback<BLEConnectionChangeState>): void
Subscribes to BLE connection state changes.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLEConnectionStateChange, which indicates BLE connection state changes. |
callback | Callback<BLEConnectionChangeState> | Yes | Callback invoked to return the BLE connection state. |
Example
import { BusinessError } from '@ohos.base';
function ConnectStateChanged(state: ble.BLEConnectionChangeState) {
console.log('bluetooth connect state changed');
let connectState: ble.ProfileConnectionState = state.state;
}
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.on('BLEConnectionStateChange', ConnectStateChanged);
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
off(‘BLEConnectionStateChange’)
off(type: ‘BLEConnectionStateChange’, callback?: Callback<BLEConnectionChangeState>): void
Unsubscribes from BLE connection state changes.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLEConnectionStateChange, which indicates BLE connection state changes. |
callback | Callback<BLEConnectionChangeState> | No | Callback for the BLE connection state change. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.off('BLEConnectionStateChange');
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
on(‘BLEMtuChange’)
on(type: ‘BLEMtuChange’, callback: Callback<number>): void
Subscribes to MTU status changes for the client.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLEMtuChange, which indicates MTU status changes. If this parameter is not set correctly, the callback cannot be registered. |
callback | Callback<number> | Yes | Callback invoked to return the number of MTU bytes. |
Example
import { BusinessError } from '@ohos.base';
try {
let gattClient: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
gattClient.on('BLEMtuChange', (mtu: number) => {
console.info('BLEMtuChange, mtu: ' + mtu);
});
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
off(‘BLEMtuChange’)
off(type: ‘BLEMtuChange’, callback?: Callback<number>): void
Unsubscribes from MTU status changes for the client.
Required permissions: ohos.permission.ACCESS_BLUETOOTH
System capability: SystemCapability.Communication.Bluetooth.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is BLEMtuChange, which indicates MTU status changes. If this parameter is not set correctly, the callback cannot be unregistered. |
callback | Callback<number> | No | Callback for the MTU status changes. If this parameter is not set, this API unsubscribes from all callbacks corresponding to type. |
Example
import { BusinessError } from '@ohos.base';
try {
let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX');
device.off('BLEMtuChange');
} catch (err) {
console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}
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. |
properties | GattProperties | Yes | Yes | Properties of the characteristic. |
BLEDescriptor
Defines the BLE descriptor.
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. |
CharacteristicReadRequest
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. |
CharacteristicWriteRequest
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. |
isPrepared | 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. |
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. |
DescriptorReadRequest
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. |
DescriptorWriteRequest
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. |
isPrepared | 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. |
BLEConnectionChangeState
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. |
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. |
deviceName | string | Yes | No | Name of the device detected. |
connectable | boolean | Yes | No | Whether the discovered device is connectable. |
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 16384 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. |
includeDeviceName | boolean | Yes | Yes | Whether the device name is contained. This parameter is optional. |
ManufactureData
Defines the content of a BLE advertisement packet.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
manufactureId | number | 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. |
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 | Service UUID of the device to filter, for example, 00001888-0000-1000-8000-00805f9b34fb. |
serviceUuidMask | string | Yes | Yes | Service UUID mask of the device to filter, for example, FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF. |
serviceSolicitationUuid | string | Yes | Yes | Service solicitation UUID of the device to filter, for example, 00001888-0000-1000-8000-00805F9B34FB. |
serviceSolicitationUuidMask | string | Yes | Yes | Service solicitation UUID mask of the device to filter, for example, FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF. |
serviceData | ArrayBuffer | Yes | Yes | Service data of the device to filter, for example, [0x90, 0x00, 0xF1, 0xF2]. |
serviceDataMask | ArrayBuffer | Yes | Yes | Service data mask of the device to filter, for example, [0xFF,0xFF,0xFF,0xFF]. |
manufactureId | number | Yes | Yes | Manufacturer ID of the device to filter, for example, 0x0006. |
manufactureData | ArrayBuffer | Yes | Yes | Manufacturer data of the device to filter, for example, [0x1F,0x2F,0x3F]. |
manufactureDataMask | ArrayBuffer | Yes | Yes | Manufacturer data mask of the device to filter, for example, [0xFF, 0xFF, 0xFF]. |
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. |
GattProperties
Defines the properties of a GATT characteristic.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Type | Mandatory | Description |
---|---|---|---|
write | boolean | Yes | Permits writes of the characteristic value (with a response). |
writeNoResponse | boolean | Yes | Permits writes of the characteristic value (without a response). |
read | boolean | Yes | Permits reads of the characteristic value. |
notify | boolean | Yes | Permits notifications of the characteristic value. |
indicate | boolean | Yes | Permits notifications of the characteristic value without acknowledgement. |
GattWriteType
Enumerates the GATT write types.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | Value | Description |
---|---|---|
WRITE | 1 | Write a characteristic value with a response from the peer device. |
WRITE_NO_RESPONSE | 2 | Write characteristic value without a response from the peer device. |
ScanDuty
Enumerates the scan duties.
System capability: SystemCapability.Communication.Bluetooth.Core
Name | 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 | 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. |
你可能感兴趣的鸿蒙文章
harmony 鸿蒙System Common Events (To Be Deprecated Soon)
harmony 鸿蒙System Common Events
harmony 鸿蒙API Reference Document Description
harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)
harmony 鸿蒙BundleStatusCallback
harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)
harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)
harmony 鸿蒙@ohos.bundle (Bundle)
harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)
- 所属分类: 后端技术
- 本文标签:
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦