鸿蒙BLE开发实战指南

最新推荐文章于 2025-12-02 00:52:42 发布

原创最新推荐文章于 2025-12-02 00:52:42 发布 · 815 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #华为

鸿蒙系统开发入门指南

开发环境搭建

安装DevEco Studio 3.1及以上版本，配置Node.js 16+和OpenJDK 11环境。在SDK Manager中下载HarmonyOS 3.1/4.0 API版本，创建项目时选择"Application->Empty Ability"模板。

配置build.gradle文件确保包含最新依赖：

dependencies {
    implementation 'io.openharmony.tpc.thirdlib:ble:1.0.2'
}

基础工程结构解析

典型鸿蒙应用包含以下目录结构：

entry/src/main
- ets/
  - pages/ # 页面组件
  - ability/ # 能力模块
- resources/ # 资源文件
- config.json # 应用配置

示例config.json片段：

"abilities": [
  {
    "name": "MainAbility",
    "type": "page",
    "label": "$string:mainability_label"
  }
]

BLE通信实现详解

权限声明

在config.json中添加蓝牙权限：

"reqPermissions": [
  {
    "name": "ohos.permission.DISCOVER_BLUE_TOOTH",
    "reason": "BLE扫描需要"
  }
]

BLE核心类封装

创建BLE管理类处理连接流程：

// BLEManager.ts
import ble from '@ohos.bluetooth.ble';

export class BLEManager {
  private scanCallback: ble.BleScanCallback = {
    onScanResult: (device: ble.ScanResult) => {
      console.log(`发现设备: ${device.deviceId}`);
    }
  };

  startScan(): void {
    ble.startBLEScan([], {
      interval: 500,
      dutyMode: ble.ScanDuty.SCAN_DUTY_LOW_POWER
    }, this.scanCallback);
  }

  connect(deviceId: string): void {
    ble.createGattClientDevice(deviceId).then(client => {
      client.connect().then(() => {
        console.log('连接成功');
        this.discoverServices(client);
      });
    });
  }

  private discoverServices(client: ble.GattClientDevice): void {
    client.getServices().then(services => {
      services.forEach(service => {
        console.log(`服务UUID: ${service.serviceUuid}`);
      });
    });
  }
}

页面集成示例

主页面对接BLE功能：

// Index.ets
import { BLEManager } from '../model/BLEManager';

@Entry
@Component
struct Index {
  private bleManager: BLEManager = new BLEManager();

  build() {
    Column() {
      Button('开始扫描')
        .onClick(() => {
          this.bleManager.startScan();
        })
      
      List({ space: 10 }) {
        ListItem() {
          Text('设备1')
            .onClick(() => {
              this.bleManager.connect('00:11:22:33:44:55');
            })
        }
      }
    }
  }
}

关键API深度解析

特征值读写操作

实现特征值监听和写入：

// 特征值操作示例
const WRITE_UUID = '0000FF01-0000-1000-8000-00805F9B34FB';

writeCharacteristic(client: ble.GattClientDevice, value: number[]): void {
  client.getServices().then(services => {
    services[0].getCharacteristics().then(chars => {
      chars[0].writeValue(value).then(() => {
        console.log('写入成功');
      });
    });
  });
}

subscribeCharacteristic(client: ble.GattClientDevice): void {
  client.on('characteristicChange', (char: ble.GattCharacteristic) => {
    console.log(`收到数据: ${char.value}`);
  });
}

连接状态管理

处理连接状态变化：

// 连接状态监听
monitorConnection(client: ble.GattClientDevice): void {
  client.on('connectionStateChange', (state: ble.ProfileConnectionState) => {
    if (state === ble.ProfileConnectionState.STATE_DISCONNECTED) {
      console.log('连接断开');
    }
  });
}

调试与优化技巧

常见问题排查

蓝牙扫描无结果：检查设备是否开启可发现模式
连接失败：确认目标设备支持BLE 4.0+协议
服务发现失败：检查UUID是否与设备文档一致

性能优化建议

扫描周期不宜过短（建议300-1000ms）
及时释放不再使用的GattClient实例
批量读写操作使用队列控制

完整示例项目可参考OpenHarmony官方样例库中的BluetoothDemo工程，其中包含服务发现、数据读写、通知订阅等完整实现流程。实际开发时应根据具体设备协议调整UUID和数据处理逻辑。

鸿蒙BLE开发与ESP32 BLE通信实现

环境准备

鸿蒙开发需使用DevEco Studio 3.1及以上版本，ESP32开发推荐使用Arduino IDE或PlatformIO。确保ESP32固件支持BLE 4.2及以上协议。

鸿蒙端BLE配置

在config.json中添加权限声明：

{
  "reqPermissions": [
    {
      "name": "ohos.permission.USE_BLUETOOTH"
    },
    {
      "name": "ohos.permission.DISCOVER_BLUETOOTH"
    }
  ]
}

初始化BLE适配器代码：

BluetoothHost host = BluetoothHost.getDefaultHost(context);
host.enableBt(); // 启用蓝牙

ESP32 BLE服务端配置

使用Arduino BLE库创建GATT服务：

#include <BLEDevice.h>
#include <BLEServer.h>

#define SERVICE_UUID        "4FAFC201-1FB5-459E-8FCC-C5C9C331914B"
#define CHARACTERISTIC_UUID "BEB5483E-36E1-4688-B7F5-EA07361B26A8"

BLEServer* pServer;
BLEService* pService;
BLECharacteristic* pCharacteristic;

void setup() {
  BLEDevice::init("ESP32_BLE_Server");
  pServer = BLEDevice::createServer();
  pService = pServer->createService(SERVICE_UUID);
  pCharacteristic = pService->createCharacteristic(
                      CHARACTERISTIC_UUID,
                      BLECharacteristic::PROPERTY_READ |
                      BLECharacteristic::PROPERTY_WRITE
                    );
  pCharacteristic->setValue("Hello Harmony");
  pService->start();
  BLEAdvertising* pAdvertising = pServer->getAdvertising();
  pAdvertising->start();
}

鸿蒙端扫描与连接

实现设备扫描回调：

BluetoothHost host = BluetoothHost.getDefaultHost(context);
BluetoothRemoteDevice remoteDevice;
host.registerScanCallback(new ScanCallback() {
  @Override
  public void onScanFailed(int errorCode) {
    // 处理扫描失败
  }

  @Override
  public void onScanResult(BluetoothRemoteDevice device) {
    if("ESP32_BLE_Server".equals(device.getName())){
      remoteDevice = device;
      host.stopScan();
    }
  }
});
host.startScan();

数据通信实现

鸿蒙端特征值读写操作：

// 连接GATT
GattClient client = remoteDevice.connectGatt(context, false, new GattClientCallback() {
  @Override
  public void onConnectionStateChanged(int state) {
    if(state == BluetoothProfile.STATE_CONNECTED){
      client.discoverServices(); // 发现服务
    }
  }

  @Override
  public void onServicesDiscovered(int status) {
    UUID serviceUuid = UUID.fromString("4FAFC201-1FB5-459E-8FCC-C5C9C331914B");
    UUID charUuid = UUID.fromString("BEB5483E-36E1-4688-B7F5-EA07361B26A8");
    GattService service = client.getService(serviceUuid);
    GattCharacteristic characteristic = service.getCharacteristic(charUuid);
    
    // 读取特征值
    client.readCharacteristic(characteristic);
    
    // 写入特征值
    characteristic.setValue("Hello ESP32".getBytes());
    client.writeCharacteristic(characteristic);
  }
});