# ohos-BLE

**Repository Path**: hihopeorg/ohos-BLE

## Basic Information

- **Project Name**: ohos-BLE
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-05-12
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ohos-ble

**本项目是基于开源项目Android-BLE进行ohos化的移植和开发的，可以通过项目标签以及github地址（https://github.com/Alex-Jerry/Android-BLE ）追踪到原项目版本**

## 项目介绍

- 项目名称：ohos-ble
- 所属系列：ohos的第三方组件适配移植
- 功能：蓝牙框架,提供了扫描、连接、使能/除能通知、发送/读取数据、接收数据,读取rssi,

    设置mtu等蓝牙相关的所有操作接口,内部优化了连接队列,以及快速写入队列,并支持多服务通讯,可扩展配置蓝牙相关操作
- 项目移植状态：完成
- 调用差异：无
- 项目作者和维护人：hiphope
- 联系方式：hiphope@hoperun.com
- 原项目Doc地址：https://github.com/Alex-Jerry/Android-BLE
- 原项目基线版本:v3.2.0 sha1:f31981c99048321037e023eb4b619947049cf320
- 编程语言：Java
- 外部库依赖：无

![](./ohosBle.gif)

## 安装教程

#### 方法一：

1. 编译ohos-ble的har包library.har。

2. 启动 DevEco Studio，将编译的har包，导入工程目录“entry->libs”下。

3. 在moudle级别下的build.gradle文件中添加依赖，在dependences标签中增加对libs目录下har包的引用。

   ```
   dependencies {
       implementation fileTree(dir: 'libs', include: ['*.jar', '*.har'])
       ……
   }
   ```
   
4. 在导入的har包上点击右键，选择“Add as Library”对包进行引用，选择需要引用的模块，并点击“OK”即引用成功。

#### 方法二：

  1. 在工程的build.gradle的allprojects中，添加HAR所在的Maven仓地址:

```
 repositories {
     maven {
         url 'http://106.15.92.248:8081/repository/Releases/' 
     }
 }
```

  2. 在应用模块的build.gradle的dependencies闭包中，添加如下代码:

```
 dependencies {
     implementation 'cn.com.heaton:ohos-ble:1.0.1'
 }
```

## 使用说明
#### 接入前提示:
1. 如果项目中的设备是统一类型(服务,特征uuid相同),则推荐在初始化时把服务,特征的uuid配置完整。
2. 如果项目中需要兼容多种设备类型(服务,特征uuid不相同),则在通信时需要使用byUuid的方式进行。

#### 1.在Application中初始化
```
private void initBle() {
    Ble.options()//开启配置
        .setLogBleEnable(true)//设置是否输出打印蓝牙日志（非正式打包请设置为true，以便于调试）
        .setThrowBleException(true)//设置是否抛出蓝牙异常 （默认true）
        .setAutoConnect(false)//设置是否自动连接 （默认false）
        .setIgnoreRepeat(false)//设置是否过滤扫描到的设备(已扫描到的不会再次扫描)
        .setConnectTimeout(10 * 1000)//设置连接超时时长（默认10*1000 ms）
        .setMaxConnectNum(7)//最大连接数量
        .setScanPeriod(12 * 1000)//设置扫描时长（默认10*1000 ms）
        .setScanFilter(scanFilter)//设置扫描过滤
        .setUuidService(UUID.fromString(UuidUtils.uuid16To128("fd00")))//设置主服务的uuid（必填）
        .setUuidWriteCha(UUID.fromString(UuidUtils.uuid16To128("fd01")))//设置可写特征的uuid （必填,否则写入失败）
        .setUuidReadCha(UUID.fromString(UuidUtils.uuid16To128("fd02")))//设置可读特征的uuid （选填）
        .setUuidNotifyCha(UUID.fromString(UuidUtils.uuid16To128("fd03")))//设置可通知特征的uuid （选填，库中默认已匹配可通知特征的uuid）
        .setUuidServicesExtra(new UUID[]{BATTERY_SERVICE_UUID})//设置额外的其他服务组，如电量服务等
        .setFactory(new BleFactory() {//实现自定义BleDevice时必须设置
            @Override
            public MyDevice create(String address, String name) {
                return new MyDevice(address, name);//自定义BleDevice的子类
            }
        })
        .setBleWrapperCallback(new MyBleWrapperCallback())//设置全部蓝牙相关操作回调（例： OTA升级可以再这里实现,与项目其他功能逻辑完全解耦）
        .create(mApplication, new Ble.InitCallback() {
            @Override
            public void success() {
                BleLog.e("MainApplication", "初始化成功");
            }

            @Override
            public void failed(int failedCode) {
                BleLog.e("MainApplication", "初始化失败：" + failedCode);
            }
        });
     }
```
#### 2.开始使用
##### 1)开始扫描

```
ble.startScan(scanCallback);

BleScanCallback<BleDevice> scanCallback = new BleScanCallback<BleDevice>() {
        @Override
        public void onLeScan(final BleDevice device, int rssi, byte[] scanRecord) {
            //Scanned devices
        }

       @Override
        public void onStart() {
            super.onStart();
        }

        @Override
        public void onStop() {
            super.onStop();
        }

        @Override
        public void onScanFailed(int errorCode) {
            super.onScanFailed(errorCode);
            Log.e(TAG, "onScanFailed: "+errorCode);
        }
    };
```
##### 2)连接/断开

```
//连接设备
ble.connect(device, connectCallback);

//连接多个设备
ble.connects(devices, connectCallback);

//取消正在连接的设备
ble.cancelConnecting(device);

//取消正在连接的多个设备
ble.cancelConnectings(devices);

//断开设备
ble.disconnect(device);

//断开所有设备
ble.disconnectAll();

//连接/断开回调
private BleConnCallback<BleDevice> connectCallback = new BleConnCallback<BleDevice>() {
        @Override
        public void onConnectionChanged(BleDevice device) {

        }

        @Override
        public void onConnectTimeOut(BleDevice device) {
            super.onConnectTimeOut(device);
            Log.e(TAG, "onConnectTimeOut: " + device.getBleAddress());
        }

        @Override
        public void onConnectCancel(BleDevice device) {
            super.onConnectCancel(device);
            Log.e(TAG, "onConnectCancel: " + device.getBleName());
        }

        @Override
        public void onServicesDiscovered(BleDevice device, BluetoothGatt gatt) {
            super.onServicesDiscovered(device, gatt);
        }

        @Override
        public void onReady(BleDevice device) {
            super.onReady(device);
            //connect successful to enable notification
            ble.enableNotify(...);
        }

        @Override
        public void onConnectException(BleDevice device, int errorCode) {
            super.onConnectException(device, errorCode);

        }
    };
```


##### 3)读取数据

```
ble.read(device, new BleReadCallback<BleRssiDevice>() {
            @Override
            public void onReadSuccess(BleRssiDevice dedvice, BluetoothGattCharacteristic characteristic) {
                super.onReadSuccess(dedvice, characteristic);
            }

            @Override
            public void onReadFailed(BleRssiDevice device, int failedCode) {
                super.onReadFailed(device, failedCode);
            }
        })
```
##### 4)写入数据
```
ble.write(device, data, new BleWriteCallback<BleRssiDevice>() {
    @Override
    public void onWriteSuccess(BleRssiDevice device, BluetoothGattCharacteristic characteristic) {

    }

    @Override
    public void onWriteFailed(BleRssiDevice device, int failedCode) {
        super.onWriteFailed(device, failedCode);
    }
});

//写入大数据(文件、图片等)
byte[]data = toByteArray(getAssets().open("WhiteChristmas.bin"));
ble.writeEntity(mBle.getConnectedDevices().get(0), data, 20, 50, new BleWriteEntityCallback<BleDevice>() {
    @Override
    public void onWriteSuccess() {

    }

    @Override
    public void onWriteFailed() {

    }

    override void onWriteProgress(double progress) {

    }

    override void onWriteCancel() {

    }
});

//写入数据到队列中 (默认发送间隔50ms)
ble.writeQueue(RequestTask.newWriteTask(address, data));
//写入数据到队列中 (自定义间隔时间)
ble.writeQueueDelay(delay, RequestTask.newWriteTask(address, data));

//通过特定服务和特征值uuid写入数据
ble.writeByUuid(device, data, serviceUuid, charUuid, new BleWriteCallback<BleRssiDevice>() {
    @Override
    public void onWriteSuccess(BleRssiDevice device, BluetoothGattCharacteristic characteristic) {

    }

    @Override
    public void onWiteFailed(BleRssiDevice device, int failedCode) {
        super.onWiteFailed(device, failedCode);
    }
});
```
##### 5)移除监听(scan、connect)
```
ble.cancelCallback(connectCallback);
或
ble.cancelCallback(scanCallback);
```
##### 6)释放资源
```
 ble.released();
```


## 版本迭代

- v1.0.1


## 版权和许可信息

 Apache license version 2.0