• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# BLE Development
2
3## Introduction
4Bluetooth advertising and scanning help discover Bluetooth-enabled devices and implement BLE communication. This topic walks you through on how to start and stop Bluetooth advertising and scanning.
5
6## When to Use
7You can use the APIs provided by the **ble** module to:
8
9- Start and stop BLE advertising.
10- Start and stop BLE scanning.
11
12## Available APIs
13
14For details about the APIs and sample code, see [@ohos.bluetooth.ble](../../reference/apis/js-apis-bluetooth-ble.md).
15
16The following table describes the related APIs.
17
18| API                            | Description                                                                      |
19| ---------------------------------- | ------------------------------------------------------------------------------ |
20| startBLEScan()                     | Starts BLE scanning.                                                              |
21| stopBLEScan()                      | Stops BLE scanning.                                                               |
22| startAdvertising()                 | Starts BLE advertising.                                                               |
23| stopAdvertising()                  | Stops BLE advertising.                                                               |
24| on(type: 'advertisingStateChange') | Subscribes to BLE advertising status.                                                               |
25| off(type: 'advertisingStateChange')| Unsubscribes from BLE advertising status.                                                           |
26| on(type: 'BLEDeviceFind')          | Subscribes to BLE device discovery events.                                                       |
27| off(type: 'BLEDeviceFind')         | Unsubscribes from the BLE device discovery events.                                                    |
28
29## How to Develop
30
31### Starting and Stopping BLE Advertising
321. Import the **ble** module.
332. Enable Bluetooth on the device.
343. Check that the SystemCapability.Communication.Bluetooth.Core capability is available.
354. Start BLE advertising. The peer device scans the advertisement.
365. Stop BLE advertising.
37
38Example:
39
40```ts
41import ble from '@ohos.bluetooth.ble';
42import { BusinessError } from '@ohos.base';
43
44// Start BLE advertising.
45let manufactureValueBuffer = new Uint8Array(4);
46manufactureValueBuffer[0] = 1;
47manufactureValueBuffer[1] = 2;
48manufactureValueBuffer[2] = 3;
49manufactureValueBuffer[3] = 4;
50let serviceValueBuffer = new Uint8Array(4);
51serviceValueBuffer[0] = 5;
52serviceValueBuffer[1] = 6;
53serviceValueBuffer[2] = 7;
54serviceValueBuffer[3] = 8;
55let setting: ble.AdvertiseSetting = {
56  interval: 150,
57  txPower: 0,
58  connectable: true
59};
60let manufactureDataUnit: ble.ManufactureData = {
61  manufactureId: 4567,
62  manufactureValue: manufactureValueBuffer.buffer
63};
64let serviceDataUnit: ble.ServiceData = {
65  serviceUuid: "00001888-0000-1000-8000-00805f9b34fb",
66  serviceValue: serviceValueBuffer.buffer
67};
68let advData: ble.AdvertiseData = {
69  serviceUuids: ["00001888-0000-1000-8000-00805f9b34fb"],
70  manufactureData: [manufactureDataUnit],
71  serviceData: [serviceDataUnit]
72};
73let advResponse: ble.AdvertiseData = {
74  serviceUuids: ["00001888-0000-1000-8000-00805f9b34fb"],
75  manufactureData: [manufactureDataUnit],
76  serviceData: [serviceDataUnit]
77};
78
79ble.startAdvertising(setting, advData, advResponse);
80console.info('startAdvertising success');
81
82// Stop BLE advertising.
83ble.stopAdvertising();
84console.info('stopAdvertising success');
85```
86For details about the error codes, see [Bluetooth Error Codes](../../reference/errorcodes/errorcode-bluetoothManager.md).
87
88**Verification**
89
901. Execute the code for starting BLE advertising.
91
92   "startAdvertising success" is logged.
93
942. Start scanning on another device that has the nrfConnect software installed.
95
96   If the device obtains the following information, the BLE advertising is started:
97
98   Manufacturer data: 0x01020304, Service Data: 0x05060708
99
1003. Stop BLE advertising.
101
102   The peer device will not receive that advertisement.
103
104### Starting and Stop BLE Scanning
1051. Import the **ble** module.
1062. Enable Bluetooth on the device.
1073. Check that the SystemCapability.Communication.Bluetooth.Core capability is available.
1084. Start BLE advertising on the peer device.
1095. Start BLE scanning on the local device.
1106. Stop BLE scanning.
111
112Example:
113
114```ts
115import ble from '@ohos.bluetooth.ble';
116import { BusinessError } from '@ohos.base';
117
118// Start BLE scanning.
119let scanFilter: ble.ScanFilter = {
120  name: 'Jackistang'
121};
122let scanOptions: ble.ScanOptions = {
123  interval: 500,
124  dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER,
125  matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE
126}
127ble.startBLEScan([scanFilter], scanOptions);
128console.info('startBleScan success')
129
130// Return the scanning result.
131ble.on('BLEDeviceFind', (data) => {
132  if (data.length > 0) {
133    console.info('BLE scan result = ' + data[0].deviceName);
134  }
135});
136
137// Stop BLE scanning.
138ble.stopBLEScan();
139console.info('stopBleScan success');
140```
141For details about the error codes, see [Bluetooth Error Codes](../../reference/errorcodes/errorcode-bluetoothManager.md).
142
143**Verification**
144
1451. Install the nrfConnect software on device B, configure BLE advertising, change the device name to **Jackistang**, and start BLE advertising.
146
1472. Start scanning on device A.
148
149   If "BLE scan result = = Jackistang" is logged every 0.5 seconds on device A, the scanning is started.
150
1513. Stop scanning on device A.
152
153   Device A will not receive "BLE scan result = = Jackistang".