当前位置：首页 > news >正文

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

news 2025/9/20 5:56:33

1. 功能概述

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

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

2. 前后端交互接口

2.1 开启蓝牙服务

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

前端调用方法：

openBleServer() {const options = {serviceUUID: "0000ff11-0000-1000-8000-00805f9b34fb", // 自定义服务 UUIDwriteCharacteristicUUID: "0000fff1-0000-1000-8000-00805f9b34fb", // 写特征值 UUIDdeviceName: "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", // 写特征值 UUIDdata: "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"}}
}