uniapp安卓原生插件实现开启ble Server[外围模式]

1. 功能概述

最近公司业务要实现安卓开启ble Server实现业务功能，最初用的是差价市场的一款外围插件，用下来真是一言难尽，服务打开慢、配置臃肿一点都不好用，于是自己便开发了一款插件。本模块实现了基于 Android BLE 外围模式（Bluetooth Low Energy）技术的蓝牙服务端功能，支持：

• 开启/关闭蓝牙服务。
• 向客户端发送数据。
• 接收客户端写入的数据。
• 动态管理设备连接状态。
• 提供日志记录和回调通知机制。

---

2. 前后端交互接口

2.1 开启蓝牙服务

功能描述：初始化蓝牙服务端，设置服务 UUID、特征值 UUID 和设备名称，并开启 BLE 广播。

前端调用方法：

openBleServer() {
    const options = {
        serviceUUID: "0000ff11-0000-1000-8000-00805f9b34fb", // 自定义服务 UUID
        writeCharacteristicUUID: "0000fff1-0000-1000-8000-00805f9b34fb", // 写特征值 UUID
        deviceName: "MyBLEDevice", // 蓝牙设备名称
        allowMultipleConnections: false, // 是否允许多设备连接
        dataType: 1, // 数据类型：字符编码发送
        charsetName: "UTF-8" // 字符集
    };

    bleServer.openBleServer(options, (res) => {
        if (res.code === 0) {
            console.log("蓝牙服务启动成功！");
        } else {
            console.error(`蓝牙服务启动失败: ${res.msg}`);
        }
    });
}

2.2 关闭蓝牙服务

功能描述：停止 BLE 广播，关闭 GATT Server，并清空已连接设备列表。

前端调用方法：

closeBleServer() {
    bleServer.closeBleServer((res) => {
        if (res.code === 0) {
            console.log("蓝牙服务已关闭！");
        } else {
            console.error(`蓝牙服务关闭失败: ${res.msg}`);
        }
    });
}

2.3 向客户端写入数据

功能描述：通过指定设备地址和特征值 UUID，向客户端发送数据。

前端调用方法：

writeDataToClient() {
    const options = {
        deviceAddress: this.deviceAddress, // 目标设备地址
        characteristicUUID: "0000fff1-0000-1000-8000-00805f9b34fb", // 写特征值 UUID
        data: "Hello BLE Client!", // 要发送的数据
        dataType: 1, // 数据类型：字符编码发送
        charsetName: "UTF-8" // 字符集
    };

    bleServer.writeCharacteristicToClient(options, (res) => {
        if (res.code === 0) {
            console.log("数据写入成功！");
        } else {
            console.error(`数据写入失败: ${res.msg}`);
        }
    });
}

后端实现：

• 根据 deviceAddress 查找目标设备。
• 根据 characteristicUUID 获取对应的特征值。
• 根据 dataType 和 charsetName 对数据进行处理（原始数据、十六进制或字符编码）。
• 调用 bluetoothGattServer.notifyCharacteristicChanged 方法通知客户端数据变更。

---

2.4 接收客户端写入的数据

功能描述 ：接收客户端写入的数据，并根据配置的 dataType 进行处理。

3. 配置参数说明

参数名	类型	默认值	描述
serviceUUID	String	"0000ff11-0000-1000-8000-00805f9b34fb"	服务 UUID，用于标识蓝牙服务。
writeCharacteristicUUID	String	"0000fff1-0000-1000-8000-00805f9b34fb"	写特征值 UUID，用于写入数据。
deviceName	String	"MyBLEDevice"	蓝牙设备名称，可选配置。
allowMultipleConnections	Boolean	true	是否允许多设备连接。如果为 false，新设备连接时会断开已有连接。
dataType	Integer	-1	数据类型： -1：原始数据。 0：十六进制。 1：字符编码。
charsetName	String	"UTF-8"	字符集，仅在 dataType=1 时生效，默认为 UTF-8。

---

4. 回调通知机制

4.1 回调类型

所有回调均通过 JSON 格式返回，包含以下字段：

字段名	类型	描述
type	String	回调类型（如 "connection_state_change"）。
code	Integer	状态码： 0：成功。 <0：失败。
msg	String	提示信息。
data	Object	可选数据（如设备信息或数据负载）。

4.2 示例回调

{
    "type": "connection_state_change",
    "code": 0,
    "msg": "客户端已连接",
    "data": {
        "deviceInfo": {
            "deviceName": "Client Device",
            "deviceAddress": "XX:XX:XX:XX:XX:XX"
        }
    }
}

5. 注意事项

1. 权限管理：

   • Android 6.0 及以上版本需要动态申请位置权限。
   • Android 12 及以上版本需要额外申请蓝牙广告权限。

2. 多设备连接限制：

   • 如果设置了 allowMultipleConnections=false，则只允许一个设备连接，新设备连接时会断开已有连接。

3. 数据格式：

   • 确保 dataType 和 charsetName 配置正确，否则可能导致数据解析失败。

4. 错误处理：

   • 每个接口均返回code 和 msg，前端需根据返回值判断操作是否成功，并处理异常情况。

---