MyTeam BLE Library

Android BLE 第三方传感器通用接入库。

模块

1. ble-core - BLE 客户端 API 与默认生命周期实现
2. sample-app - 扫描/连接/断开与事件观察集成示例

快速开始

1. 在 Android Studio 中打开项目 (Giraffe+ / AGP 8.5+)
2. Sync Gradle
3. 在设备/模拟器上运行 sample-app
4. 在示例页面操作：扫描 -> 连接 -> 订阅演示特征 / 写入演示特征，观察事件日志

---

第一章：权限清单

Android 版本权限要求

Android 版本	所需权限
Android 6-11	ACCESS_FINE_LOCATION
Android 12+	BLUETOOTH_SCAN + BLUETOOTH_CONNECT

权限说明

• ACCESS_FINE_LOCATION：用于 BLE 扫描（Android 6-11）
• BLUETOOTH_SCAN：用于 BLE 扫描（Android 12+）
• BLUETOOTH_CONNECT：用于 BLE 连接（Android 12+）

权限申请说明（与代码一致）

• 当前 ble-core 不内置权限申请器；调用前需由业务层先完成运行时权限申请。
• 权限声明见 sample-app/src/main/AndroidManifest.xml。
• 代码侧在以下位置默认“已具备权限”：
  • AndroidBleScanner.scan(...)（扫描）
  • BleConnectionManager.connect(...) / setCharacteristicNotification(...)（连接与通知）

---

第二章：使用步骤

步骤 1：添加依赖

dependencies {
    implementation(project(":ble-core"))
}

步骤 2：初始化客户端

val bleClient = BleClients.create(
    context = applicationContext,
    config = BleClientConfig(
        connectTimeoutMs = 10_000,
        writeTimeoutMs = 3_000,
        maxRetry = 2
    )
)

步骤 3：观察状态与事件

// 观察连接状态
bleClient.connectionState.onEach { state ->
    // 更新 UI
}.launchIn(lifecycleScope)

// 观察 BLE 事件
bleClient.events.onEach { event ->
    // 处理事件
}.launchIn(lifecycleScope)

步骤 4：扫描与连接

lifecycleScope.launch {
    bleClient.scan().collect { device ->
        bleClient.connect(device)
    }
}

步骤 5：特征订阅与写入

// 订阅通知
bleClient.subscribeCharacteristic(serviceUuid, characteristicUuid)

// 写入数据
val result = bleClient.writeCharacteristic(serviceUuid, characteristicUuid, payload)

---

第三章：常见问题

Q1: 扫描不到设备？

可能原因：

1. 权限未授予
2. 蓝牙未开启
3. 定位未开启（Android 10 以下）

解决方案：

• 检查并申请权限
• 引导用户开启蓝牙
• 引导用户开启定位

Q2: 连接失败？

可能原因：

1. 设备不在范围内
2. 设备已连接其他主机
3. 服务/特征 UUID 不存在

解决方案：

• 确保设备在可连接范围内
• 断开设备与其他连接
• 检查服务 UUID

Q3: 写入失败？

可能原因：

1. 未连接
2. 特征不支持写入
3. 超时

解决方案：

• 先建立连接
• 检查特征属性
• 增加超时时间配置

---

第四章：排障指引

1. 权限问题排查

• 先检查 Manifest 声明是否完整（见 sample-app/src/main/AndroidManifest.xml）。
• 再检查运行时是否已授予权限（Android 12-14：BLUETOOTH_SCAN / BLUETOOTH_CONNECT；Android 6-11：ACCESS_FINE_LOCATION）。

2. 动态申请权限（示例）

val permissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
    arrayOf(
        android.Manifest.permission.BLUETOOTH_SCAN,
        android.Manifest.permission.BLUETOOTH_CONNECT
    )
} else {
    arrayOf(android.Manifest.permission.ACCESS_FINE_LOCATION)
}

requestPermissionsLauncher.launch(permissions)

3. 永久拒绝处理

当用户拒绝权限且勾选“不再询问”时，引导用户进入系统设置页手动授权。

4. 错误码排查

错误码	说明	排查方向
BLUETOOTH_UNAVAILABLE	蓝牙不可用	检查设备是否支持蓝牙
PERMISSION_DENIED	权限被拒绝	检查权限是否授予
SCAN_FAILED	扫描失败	检查权限、蓝牙状态
CONNECT_TIMEOUT	连接超时	检查设备距离、重启设备
NOT_CONNECTED	未连接	先建立连接再操作
WRITE_TIMEOUT	写入超时	检查连接状态、重试

---

公共 API（任务 04）

club.knifelf.ble.core.api 中的主要类型：

• BleDevice：统一设备模型
• BleClient：入口接口（scan/connect/disconnect/write/subscribe）
• BleEvent：事件流封装（含 CharacteristicChanged 通知回流）
• ConnectionState：生命周期状态
• BleErrorCode + BleException：标准化错误表面
• BleClients.create(context, config)：Android BLE 运行时客户端工厂

支持回调和 Flow 两种风格：

• Flow: events, connectionState
• Callback: registerCallback, unregisterCallback

构建验证

cd E:\MyTeam\AndroidSensorBle
.\gradlew.bat :ble-core:assembleDebug --stacktrace
.\gradlew.bat :sample-app:assembleDebug --stacktrace
.\gradlew.bat :ble-core:testDebugUnitTest --stacktrace

收口验证 (任务 05+06)

• 示例运行路径：应用启动 -> MainActivity -> 扫描 -> 连接第一个设备 -> 订阅演示特征 / 写入演示特征 -> 观察事件日志
• 单元测试报告路径：E:\MyTeam\AndroidSensorBle\ble-core\build\reports\tests\testDebugUnitTest\index.html

当前范围边界

• 当提供 Context 时，DefaultBleClient 已接入 Android BLE 运行时
• GATT 操作编排支持：pending-op 队列、callback ACK、超时、重试、通知回调回流到 BleEvent.CharacteristicChanged
• BleClients.create(config) 仍可用作非 Context 的本地/模拟集成

测试

• 单元测试位于 ble-core/src/test
• 覆盖范围：
  • API 契约行为与状态转换
  • 异常场景：未连接/连接超时/写入超时/订阅失败
  • GATT 编排：pending 队列、ACK、超时重试
  • 通知回调从 GATT 层回流到 BleEvent.CharacteristicChanged

模块边界决策

• 决策：ble-core 是唯一的活跃交付模块。library 标记为遗留兼容模块，将被弃用。
• 时间线：
  • 2026-03-30：冻结 library 新变更，所有新功能仅在 ble-core 中
  • 2026-03-31：切换下游集成文档/脚本到 ble-core
  • 2026-04-02：集成确认后归档/移除 library