# ble-tool

**Repository Path**: jameschenbo/ble-tool

## Basic Information

- **Project Name**: ble-tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BLE Tool - 蓝牙调试工具

一款功能强大的 Android BLE（蓝牙低功耗）调试应用，支持设备扫描、连接、数据通信、配网和 OTA 升级。

## 功能特性

### 1. BLE 调试
- 扫描附近 BLE 设备
- 按设备名称前缀过滤
- 连接 BLE 设备
- **GATT 服务可展开**：每个服务下展示特征值；整块 GATT 区域可收起以腾出空间给数据日志
- 默认展开**最后一个**服务；GATT 与数据日志约 **32% / 68%** 纵向分区
- 接收 Notify/Indicate 数据
- 发送数据（HEX/ASCII 格式）
- 数据显示格式切换（HEX/ASCII）
- **数据日志「解析协议」**：可选将 RX 中的完整协议包（含自动去除 2 字节 BLE 传输头）解析为可读字段；支持 **`cmd=0x01`**、12 字节 `value`（详见测试文档）
- 调试页进入时自动清理上次残留通知数据
- Data Log 独立清理按钮（顶部重复清理入口已移除）；离开调试页时释放 GATT 连接

BLE 调试/测试模块详细说明见：[doc/BLE_TEST_MODULE.md](doc/BLE_TEST_MODULE.md)

### 2. BLE 配网 ✅
- 自动获取当前 WiFi SSID
- 自动识别 2.4G/5G 频段
- WiFi 密码输入
- **设备 UUID 验证** - 自动检查目标设备是否匹配
- **设备编号读取** - 读取并显示设备编号
- **完整配网协议** - 基于 BLE 通信协议实现
  - 0x75 读取设备编号
  - 0x72 发送 WiFi SSID
  - 0x73 发送 WiFi 密码
  - 0x74 开始配网
- 配网状态实时显示
- 配网成功/失败提示
- 配网成功后自动返回扫描页（默认 3 秒倒计时）

配网模块详细说明见：[doc/BLE_PROVISION_MODULE.md](doc/BLE_PROVISION_MODULE.md)

### 3. BLE OTA 升级 ✅
- **固件文件选择器** - 支持选择 .bin 文件
- **OTA 升级协议** - 基于 BLE 通信协议实现
  - 0x7A OTA 升级开始
  - 0x7B OTA 升级传输数据
  - 0x7C OTA 升级结束
- 升级进度显示
- 升级状态日志
- **设备 UUID 验证** - 自动检查目标设备是否匹配

### 4. BLE UUID 统一配置 ✅
- 所有 UUID 集中在 `BleConfig.kt` 管理
- 方便修改和维护

## BLE 通信协议

### 数据包格式

**完整数据包（逻辑层）**
```
┌──────────┬────┬────────┬──────────────┬───────┐
│ cmd_type │cmd │ length │ value       │ crc8  │
│ 1字节   │1字节│ 1字节  │ length字节  │ 1字节 │
└──────────┴────┴────────┴──────────────┴───────┘
```

**BLE 传输包（物理层）**
```
┌────────────┬────────────┬──────────────────────┐
│ package_num│package_seq│ 数据片段             │
│ 1字节     │ 1字节     │ 最多18字节          │
└────────────┴────────────┴──────────────────────┘
```

### 命令定义

| cmd_type | 方向 | 说明 |
|----------|------|------|
| 0x01 | APP → 设备 | APP 读设备数据 |
| 0x02 | APP → 设备 | APP 写设备数据 |
| 0x11 | 设备 → APP | 设备应答 APP 读数据 |
| 0x12 | 设备 → APP | 设备应答 APP 写数据 |
| 0x13 | 设备 → APP | 设备主动通知 APP |

| cmd | 说明 |
|-----|------|
| 0x01 | 设备状态类上报（调试页「解析协议」按 12 字节 `value` 展开，见 [doc/BLE_TEST_MODULE.md](doc/BLE_TEST_MODULE.md)） |
| 0x72 | WiFi SSID 操作 |
| 0x73 | WiFi 密码操作 |
| 0x74 | 开始配网 |
| 0x75 | 设备编号操作 |
| 0x7A | OTA 升级开始 |
| 0x7B | OTA 升级传输数据 |
| 0x7C | OTA 升级结束 |

### 配网流程
```
1. 连接设备 → 2. 读取设备编号 (0x75) → 3. 发送 SSID (0x72)
       → 4. 发送密码 (0x73) → 5. 开始配网 (0x74) → 6. 提示结果
```

### OTA 流程
```
1. 连接设备 → 2. 发送 OTA_START (0x7A) → 3. 循环发送 OTA_TRANS (0x7B)
       → 4. 发送 OTA_END (0x7C) → 5. 设备重启 → 6. 提示结果
```

## 项目结构

```
ble-tool/
├── app/
│   └── src/main/
│       ├── kotlin/com/ble/tool/
│       │   ├── BleToolApplication.kt     # Application 类
│       │   ├── MainActivity.kt           # 主入口
│       │   ├── bluetooth/
│       │   │   ├── BleManager.kt         # BLE 核心管理类
│       │   │   ├── BleConfig.kt          # UUID 配置
│       │   │   ├── BleNetworkConfigManager.kt  # 配网协议实现
│       │   │   └── BleOtaManager.kt      # OTA 协议实现
│       │   ├── data/
│       │   │   ├── model/                # 数据模型
│       │   │   └── repository/           # DataFormatter、BleProtocolLogParser
│       │   ├── ui/
│       │   │   ├── BleApp.kt             # 导航配置
│       │   │   ├── device/               # 设备详情页
│       │   │   ├── scan/                 # 扫描页面
│       │   │   ├── provision/            # 配网页面
│       │   │   └── ota/                  # OTA 页面
│       │   └── util/
│       │       └── WifiUtils.kt           # WiFi 工具类
│       └── AndroidManifest.xml
├── doc/                                   # 专题文档（协议、模块说明）
├── build.gradle.kts                       # Gradle 构建配置
├── settings.gradle.kts
├── gradle/                                # Gradle Wrapper
└── local.properties                        # 本地配置（勿提交）
```

## 技术栈

- **语言**: Kotlin
- **UI 框架**: Jetpack Compose
- **架构**: MVVM + Hilt 依赖注入
- **异步**: Kotlin Coroutines + Flow
- **导航**: Jetpack Navigation Compose
- **Min SDK**: 26 (Android 8.0)
- **Target SDK**: 34 (Android 14)

## 编译构建

### 环境要求
- Java 17
- Android SDK 34
- Gradle 8.2

### 构建命令

```bash
# Debug 构建
./gradlew assembleDebug

# Release 构建
./gradlew assembleRelease

# 或使用本地 Gradle
/opt/gradle-8.2/bin/gradle assembleDebug
```

### 签名

Debug APK 使用默认 debug keystore 签名：
- keystore: `~/.android/debug.keystore`
- alias: `androiddebugkey`
- 密码: `android`

## 权限说明

| 权限 | 用途 |
|------|------|
| `BLUETOOTH` | 蓝牙基础功能 |
| `BLUETOOTH_ADMIN` | 蓝牙扫描 |
| `BLUETOOTH_SCAN` | BLE 扫描 (Android 12+) |
| `BLUETOOTH_CONNECT` | BLE 连接 (Android 12+) |
| `ACCESS_FINE_LOCATION` | 位置（BLE 扫描需要） |
| `ACCESS_WIFI_STATE` | 获取 WiFi 状态 |
| `CHANGE_WIFI_STATE` | WiFi 控制 |

## 版本历史

### v0.2.4 (2026-05-08)
- ✅ 调试页：GATT 按服务可展开特征值；整块 GATT 可收起；默认展开最后一项服务；GATT/数据日志分区比例优化
- ✅ 数据日志：新增「解析协议」开关；支持完整逻辑包 CRC 校验、`cmd=0x01` 十二字节 `value` 分组展示（含 BLE 传输头自动剥离）
- ✅ 解析展示：`sleep` 十进制、音乐通道（蓝牙/本地）、加热状态开/关、挡位 0～3、音乐 ID 为 status2 bit6～bit2 十进制（0～31）等
- ✅ 文档：`doc/BLE_TEST_MODULE.md` 同步界面与解析说明
- ✅ 版本号：`app/build.gradle.kts` 的 `versionName` 与本节 **v0.2.4** 一致；扫描页标题与 `MainActivity` 活动标题展示为 `应用名 (0.2.4)`
- ✅ 项目总览文档合并至本仓库根目录 `README.md`

### v0.2.3 (2026-04-22)
- ✅ 修复 BLE 调试连接流误断连问题（连接成功后不再被自动断开）
- ✅ 修复扫描停止仅改 UI 状态的问题（改为真正取消扫描任务）
- ✅ 修复 Notify 按钮 UI 状态与实际启用结果不一致的问题
- ✅ 修复调试页 Data Log 首次进入显示上次残留通知数据的问题
- ✅ 调试页文案统一为简体中文

### v0.2.2 (2026-04-22)
- ✅ 修复 Kotlin 2.x 下 Compose 编译器插件配置
- ✅ 升级 Hilt 到 2.58，修复 metadata 兼容问题
- ✅ 优化 BLE 配网时序：串行写入、写入回调等待、命令超时处理
- ✅ 修复读取设备编号重复触发导致的首次进入异常
- ✅ 配网成功后自动返回扫描页，退出页面统一释放 BLE 资源

### v0.2.1 (2026-04-22)
- ✅ 配网流程优化
- ✅ 添加写入完成回调
- ✅ 修复 ACK 响应处理（支持空 value）
- ✅ 修复空格输入验证
- ⚠️ 发送密码指令存在时序问题（待修复）

### v0.2.0 (2026-04-20)
- ✅ BLE 配网协议完整实现
- ✅ BLE OTA 升级协议完整实现
- ✅ 设备 UUID 验证功能
- ✅ 设备编号读取显示
- ✅ 固件文件选择器
- ✅ UUID 统一配置文件
- ✅ 配网状态实时显示
- ✅ OTA 升级进度显示

### v0.1.0 (2024-04-19)
- 初始版本
- BLE 扫描和连接
- 设备服务和特征值查看
- 数据收发功能
- WiFi SSID 自动获取
- BLE 配网界面
- BLE OTA 界面
- 多模式切换（调试/配网/OTA）

## 已知问题

1. 部分设备：5G WiFi 配网兼容性
2. 部分厂商：需要开启"安装未知应用"权限

## 待完善功能

- [ ] 补充配网模块自动化回归测试用例

## 日志调试

在 Android Studio Logcat 中过滤以下 TAG：

| TAG | 说明 |
|-----|------|
| `BleNetworkConfig` | 配网协议日志 |
| `BleOta` | OTA 升级日志 |
| `BleManager` | BLE 底层通信 |

## License

MIT License