1# @system.bluetooth (Bluetooth)
2
3
4> **NOTE**
5>
6> - The APIs provided by this module are no longer maintained since API version 7. You are advised to use profile APIs of [@ohos.bluetooth.ble](js-apis-bluetooth-ble.md).
7>
8> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
9
10
11## Modules to Import
12
13
14```
15import bluetooth from '@system.bluetooth';
16```
17
18## bluetooth.startBLEScan(OBJECT)
19
20Scans for Bluetooth Low Energy (BLE) devices nearby. This operation consumes system resources. Call [bluetooth.stopBLEScan](#bluetoothstopblescanobject) to stop the scan after a BLE device is detected and connected.
21
22**System capability**: SystemCapability.Communication.Bluetooth.Lite
23
24**Parameters**
25**Table 1** StartBLEScanOptions
26
27| Name| Type| Mandatory| Description|
28| -------- | -------- | -------- | -------- |
29| interval | number | No| Interval for reporting device information, in milliseconds. The default value is **0**, which means to report the detected device immediately and report other information at the given interval.|
30| success | Function | No| Called when the operation is successful.|
31| fail | Function | No| Called when the operation fails.|
32| complete | Function | No| Called when the execution is complete.|
33
34**Example**
35
36  ```
37  bluetooth.startBLEScan({
38    interval:0,
39    success() {
40      console.log('call bluetooth.startBLEScan success.');
41    },
42    fail(code, data) {
43      console.log('call bluetooth.startBLEScan failed, code:' + code + ', data:' + data);
44    },
45    complete() {
46      console.log('call bluetooth.startBLEScan complete.');
47    }
48  });
49  ```
50
51
52## bluetooth.stopBLEScan(OBJECT)
53
54Stops scanning for BLE devices nearby. This API is used with [bluetooth.startBLEScan(OBJECT)](#bluetoothstartblescanobject) in pairs.
55
56**System capability**: SystemCapability.Communication.Bluetooth.Lite
57
58**Parameters**
59**Table 2** StopBLEScanOptions
60
61| Name| Type| Mandatory| Description|
62| -------- | -------- | -------- | -------- |
63| success | Function | No| Called when the operation is successful.|
64| fail | Function | No| Called when the operation fails.|
65| complete | Function | No| Called when the execution is complete.|
66
67**Example**
68
69  ```
70  bluetooth.stopBLEScan({
71    success() {
72      console.log('call bluetooth.stopBLEScan success.');
73    },
74    fail(data, code) {
75      console.log('call bluethooth.stopBLEScan fail, code:' + code + ', data:' + data);
76    },
77    complete() {
78      console.log('call bluethooth.stopBLEScan complete.');
79    }
80  });
81  ```
82
83
84## bluetooth.subscribeBLEFound(OBJECT)
85
86Subscribes to the newly detected BLE device. If this API is called multiple times, the last call takes effect.
87
88**System capability**: SystemCapability.Communication.Bluetooth.Lite
89
90**Parameters**
91**Table 3** SubscribeBLEFoundOptions
92
93| Name| Type| Mandatory| Description|
94| -------- | -------- | -------- | -------- |
95| success | Function | Yes| Called to report the newly detected device.|
96| fail | Function | No| Called when the operation fails.|
97
98**Table 4** Return value in success
99
100| Name| Type| Description|
101| -------- | -------- | -------- |
102| devices | Array<BluetoothDevice> | List of the newly detected BLE devices.|
103
104**Table 5** BluethoothDevice
105
106| Name| Type| Description|
107| -------- | -------- | -------- |
108| addrType | string | Device address type, which can be:<br>-&nbsp;**public**: a public address<br>-&nbsp;**random**: a random address|
109| addr | string | MAC address of the device.|
110| rssi | number | Received signal strength indicator (RSSl) of the device.|
111| txpower | string | **txpower** field in the Bluetooth advertising data.|
112| data | hex&nbsp;string | Bluetooth advertising data (including advertising data and scan response data), in a hexadecimal string.|
113
114**Example**
115
116  ```
117  bluetooth.subscribeBLEFound({
118    success(data) {
119      console.log('call bluetooth.subscribeBLEFound success, data: ${data}.');
120    },
121    fail(data, code) {
122      console.log('call bluetooth.startBLEScan failed, code:' + code + ', data:' + data);
123    }
124  });
125  ```
126
127
128## bluetooth.unsubscribeBLEFound()
129
130Unsubscribes from the newly detected devices.
131
132**System capability**: SystemCapability.Communication.Bluetooth.Lite
133
134**Example**
135
136  ```
137  bluetooth.unsubscribeBLEFound();
138  ```
139
140
141## Common Error Codes
142
143| Error Code| Description|
144| -------- | -------- |
145| 1100 | The Bluetooth adapter is not initialized.|
146| 1101 | The Bluetooth adapter is unavailable.|
147| 1102 | The specified device is not found.|
148| 1103 | Connection failed.|
149| 1104 | The specified service is not found.|
150| 1105 | The specified characteristic value is not found.|
151| 1106 | The Bluetooth device is disconnected.|
152| 1107 | The characteristic value does not support this operation.|
153| 1108 | Other exceptions reported by the system.|
154| 1109 | The system version does not support BLE.|
155