HarmonyOS Bluetooth Protocol Stack Development: Best Practices for Smart Accessory Connectivity

The Bluetooth connectivity feature is almost standard for all smart devices, and in the HarmonyOS system, the optimized Bluetooth protocol stack allows developers to achieve a smoother and more energy-efficient device interconnection experience. Whether you want to develop a smart watch application or create a smart home system that collaborates across devices, mastering HarmonyOS Bluetooth development is an essential skill. This article will introduce you to the basics and practical skills of HarmonyOS Bluetooth development, helping you get started quickly.

Basics of HarmonyOS Bluetooth Architecture

The Bluetooth architecture of HarmonyOS is significantly different from that of Android. HarmonyOS adopts a layered design, including the application layer, framework layer, service layer, and adaptation layer. The most notable feature is the unified device discovery and connection management based on a distributed soft bus, which simplifies multi-device collaboration.

Bluetooth protocols are mainly divided into two categories:

• Classic Bluetooth: Used for scenarios with larger data transmission
• Bluetooth Low Energy (BLE): Suitable for long-term operation with small data transmission

A common mistake beginners make is not distinguishing between the usage scenarios of these two protocols, leading to applications with excessive power consumption or unstable connections. Just as you wouldn’t use a truck to deliver a letter or a bicycle to move houses, choosing the appropriate Bluetooth protocol is crucial.

Bluetooth Device Discovery and Pairing

Searching for nearby Bluetooth devices is the first step. HarmonyOS provides the <span>BluetoothHost</span> class to implement this functionality:

 1import bluetooth from '@ohos.bluetooth';
 2
 3// Check if Bluetooth is available
 4if (!bluetooth.isAvailable()) {
 5  console.error('Bluetooth is not available, please check the device');
 6  return;
 7}
 8
 9// Enable Bluetooth
10bluetooth.enableBluetooth();
11
12// Start searching for devices
13try {
14  // Register scan listener
15  bluetooth.on('bluetoothDeviceFind', (device) => {
16    console.info(`Device found: ${device.deviceName}, MAC: ${device.deviceId}`);
17    // Here you can add the device to the list
18  });
19
20  // Start discovery, timeout 30 seconds
21  bluetooth.startBluetoothDiscovery();
22  setTimeout(() => {
23    bluetooth.stopBluetoothDiscovery();  // Stop searching
24  }, 30000);
25} catch (err) {
26  console.error(`Bluetooth search failed: ${err.code}, ${err.message}`);
27}

Note: Searching for Bluetooth devices requires location permissions, as the physical location of Bluetooth devices is associated with the user’s location. When developing applications, ensure that the corresponding permissions are added in <span>module.json5</span>:

 1"requestPermissions": [
 2  {
 3    "name": "ohos.permission.LOCATION",
 4    "reason": "Location permission is required to search for nearby Bluetooth devices",
 5    "usedScene": {
 6      "abilities": ["EntryAbility"],
 7      "when": "inuse"
 8    }
 9  },
10  {
11    "name": "ohos.permission.USE_BLUETOOTH",
12    "reason": "Bluetooth functionality is required"
13  }
14]

Practical BLE Device Communication

Bluetooth Low Energy (BLE) uses the GATT protocol for communication, based on the concepts of characteristics and services. Imagine a service as a folder, and characteristics as the files inside it, where each file can be read or written.

Below is an example of connecting to and reading temperature sensor data from a BLE device:

 1import bluetooth from '@ohos.bluetooth';
 2
 3async function connectAndReadTemperature(deviceId) {
 4  try {
 5    // Connect to the device
 6    await bluetooth.createGattClientConnection(deviceId);
 7
 8    // UUID of the temperature service (example UUID, use the standard UUID provided by the device in actual development)
 9    const serviceUuid = '00002a1c-0000-1000-8000-00805f9b34fb';
10    const characteristicUuid = '00002a1d-0000-1000-8000-00805f9b34fb';
11
12    // Get services
13    const services = await bluetooth.getServices(deviceId);
14    const targetService = services.find(s => s.uuid === serviceUuid);
15
16    if (!targetService) {
17      console.error('Temperature service not found');
18      return;
19    }
20
21    // Get characteristics
22    const characteristics = await bluetooth.getCharacteristics(deviceId, targetService.serviceUuid);
23    const tempCharacteristic = characteristics.find(c => c.uuid === characteristicUuid);
24
25    if (!tempCharacteristic) {
26      console.error('Temperature characteristic not found');
27      return;
28    }
29
30    // Read temperature data
31    const value = await bluetooth.readCharacteristicValue(deviceId, serviceUuid, characteristicUuid);
32
33    // Parse data (varies by device protocol)
34    const temperature = parseTemperature(value);
35    console.info(`Current temperature: ${temperature}°C`);
36
37  } catch (err) {
38    console.error(`Operation failed: ${err.code}, ${err.message}`);
39  } finally {
40    // Disconnect after completion
41    bluetooth.disconnectGattConnection(deviceId);
42  }
43}
44
45// Parse temperature data based on device protocol
46function parseTemperature(buffer) {
47  // Assume temperature data is a signed integer of two bytes, unit is 0.1°C
48  const view = new DataView(buffer.buffer);
49  return view.getInt16(0, true) / 10; // true indicates little-endian
50}

Common Issues and Solutions

1. Unstable Connection Issues

Is the Bluetooth connection intermittent? It may be caused by signal interference or power management policies. Solutions:

• Ensure the distance between devices does not exceed 10 meters
• Avoid interference sources such as Wi-Fi routers and microwaves
• Disable the system’s power management during critical operations:

1// Use power management to keep Bluetooth connection stable
2import power from '@ohos.power';
3
4// Prevent sleep before important operations
5power.keepScreenOn(true);
6
7// Restore normal sleep policy after operation is complete
8power.keepScreenOn(false);

1. Data Parsing Errors

Received data but displayed garbled? It is likely a byte order (Endianness) issue. Different devices may use different byte orders, just as some countries drive on the left and others on the right. The solution is to use DataView to correctly specify the byte order:

1// Assume the received data is a 16-bit integer in little-endian
2function parseData(buffer) {
3  const view = new DataView(buffer.buffer);
4
5  // The second parameter true indicates little-endian, false indicates big-endian
6  const value = view.getInt16(0, true);
7  return value;
8}

Real Application Case

I developed a HarmonyOS application for a smart bracelet project, communicating with the bracelet via Bluetooth BLE to synchronize step count and heart rate data. The biggest challenge was maintaining a long-term Bluetooth connection without excessive battery drain.

The key technique was to adopt a reasonable polling interval: the bracelet’s motion data was synchronized every 30 seconds, while heart rate data was actively retrieved only when the user checked it. This strategy reduced the application’s battery consumption by about 40%, significantly enhancing user experience.

Development Recommendations

1. First, thoroughly understand the device protocol specifications. Device manufacturers usually provide Bluetooth communication protocol documents, and reading them in detail can save a lot of debugging time.

2. Use the HiLog tool in DevEco Studio for log analysis. In complex Bluetooth communication processes, comprehensive logs are key to troubleshooting.

3. Testing should fully consider various scenarios: weak signal environments, frequently entering and exiting Bluetooth range, connection status after the phone is locked, etc.

4. Implement a graceful reconnection mechanism, avoiding manual user intervention. A good reconnection strategy should be exponential backoff (gradually increasing retry intervals).

When starting Bluetooth development, you can first use market Bluetooth debugging tools (like LightBlue) to simulate device behavior, allowing basic development without physical hardware.

What challenges have you encountered while developing HarmonyOS Bluetooth applications? Have you found any conveniences compared to traditional Android Bluetooth development? Feel free to share your experiences in the comments!