# J10 Native BLE

一个基于 **Android 原生 BLE API** 的 J10 功能复刻项目。

这个项目的目标是：在保留 `j10_new` 主要业务功能的前提下，**完全移除 EasyBLE 库依赖**，改为使用 Android 系统原生的 `BluetoothLeScanner`、`BluetoothGatt` 等 API 实现扫描、连接与 EQ 控制。

## 项目特点

- 基于 **Android 原生 BLE API** 实现，不依赖第三方 BLE 库
- 支持 **BLE 扫描 / 连接 / 断开 / 读写 / Notify**
- 支持 **Android 10+**
- 支持 **Android 12+ 蓝牙权限模型**（`BLUETOOTH_SCAN` / `BLUETOOTH_CONNECT`）
- 保留原项目的 **EQ 控制逻辑**
- 已完成 Gradle 构建链路整理，可直接构建 Debug APK

## 当前功能

### 1. 扫描页面
入口页面为 `ScanActivity`

支持：
- 自动检查蓝牙权限
- 蓝牙开启状态判断
- BLE 设备扫描
- 扫描结果按 MAC 去重
- 展示设备名称 / MAC 地址 / RSSI
- 点击设备进入 EQ 控制页

### 2. EQ 控制页面
控制页面为 `EqActivity`

支持：
- 自动连接选中的 BLE 设备
- 显示连接状态
- 音量调节（SeekBar）
- 4 个 EQ 模式切换按钮
- 菜单断开 / 重连

## 技术栈

- Android Gradle Plugin: `8.3.1`
- Gradle Wrapper: `8.5`
- Kotlin Plugin: `1.9.0`
- compileSdk: `34`
- minSdk: `29`
- targetSdk: `34`
- Java: `17+`

## 环境要求

### Android Studio / JDK
建议使用较新的 Android Studio。

项目当前在 `gradle.properties` 中指定了：

```properties
org.gradle.java.home=C:\Program Files\Android\Android Studio\jbr
```

也就是说，默认使用 Android Studio 自带的 JBR。

如果你的 Android Studio 不在这个路径，请把它改成你机器上的实际 JDK / JBR 路径，否则 Gradle 可能会因为 Java 版本不对而构建失败。

### Android SDK
请确保本机已安装：
- Android SDK Platform 34
- Android SDK Build-Tools（与 Android Studio 默认安装保持一致即可）
- Platform Tools

### local.properties
项目构建依赖本地 Android SDK 路径。
如果 `local.properties` 不存在或路径不对，请在项目根目录创建 / 修改：

```properties
sdk.dir=你的AndroidSDK路径
```

Windows 示例：

```properties
sdk.dir=C:\Users\你的用户名\AppData\Local\Android\Sdk
```

## 快速开始

### 方式一：Android Studio
1. 打开 Android Studio
2. 选择 `Open` 并打开项目目录 `d:\projects\j10_native`
3. 等待 Gradle Sync 完成
4. 连接 Android 设备或启动模拟器
5. 运行 `app`

### 方式二：命令行构建
在项目根目录执行：

```bat
gradlew.bat clean assembleDebug
```

构建成功后，APK 位于：

```text
app\build\outputs\apk\debug\app-debug.apk
```

## 项目结构

```text
j10_native/
├─ app/
│  ├─ src/main/
│  │  ├─ java/com/wandersnail/bledemo/
│  │  │  ├─ ble/
│  │  │  │  ├─ BleManager.java
│  │  │  │  ├─ BleDevice.java
│  │  │  │  ├─ BleConnectionState.java
│  │  │  │  └─ BleCallback.java
│  │  │  ├─ Constants.java
│  │  │  ├─ MyApplication.java
│  │  │  ├─ ScanActivity.java
│  │  │  └─ EqActivity.java
│  │  ├─ res/
│  │  └─ AndroidManifest.xml
├─ gradle/
├─ build.gradle
├─ settings.gradle
├─ gradle.properties
├─ gradlew
├─ gradlew.bat
└─ README.md
```

## 核心实现说明

### BleManager
`BleManager` 是整个项目的 BLE 核心层，主要职责：

- 初始化蓝牙适配器
- 监听蓝牙开关状态
- 使用 `BluetoothLeScanner` 扫描设备
- 使用 `BluetoothGatt` 建立连接
- 自动进行服务发现
- 提供特征读 / 写能力
- 提供 Notify / Indicate 开关能力
- 所有回调统一切回主线程

当前设计为：
- **单例**
- **单连接模型**
- 通过 `BleCallback` 分发事件

### 扫描行为
- 扫描 API：`BluetoothLeScanner.startScan()`
- 扫描模式：`SCAN_MODE_BALANCED`
- 自动停止时间：约 `15 秒`
- 去重方式：按设备 MAC 地址去重

### 连接行为
- 连接 API：`connectGatt(..., BluetoothDevice.TRANSPORT_LE)`
- 连接超时：约 `10 秒`
- 连接成功后自动发现 GATT Services

## BLE 权限说明

### Android 10+
扫描 BLE 设备时需要定位权限：
- `ACCESS_FINE_LOCATION`

### Android 12+
还需要：
- `BLUETOOTH_SCAN`
- `BLUETOOTH_CONNECT`

项目中已经在 `AndroidManifest.xml` 中声明相关权限，并在 `ScanActivity` 中进行运行时申请。

## BLE / EQ 协议说明

### UUID 常量
定义位置：`Constants.java`

#### 电量服务
- Service UUID: `0000180f-0000-1000-8000-00805f9b34fb`
- Characteristic UUID: `00002a19-0000-1000-8000-00805f9b34fb`

#### EQ 服务
- Service UUID: `e093f3b5-00a3-a9e5-9eca-40016e0edc24`
- Characteristic UUID: `e093f3b5-00a3-a9e5-9eca-40036e0edc24`

### EQ 写入协议
#### 音量命令
格式：

```text
[0xAA, 0x01, 0x00, sendVol]
```

说明：
- `SeekBar` 范围：`0 ~ 30`
- 实际发送值：`sendVol = 30 - progress`

#### 模式命令
格式：

```text
[0xAA, 0x02, 0x00, modeId]
```

当前模式按钮映射：
- `0`：Quiet
- `1`：Noise
- `2`：Out door
- `3`：Tv streamer

## 与 j10_new 的区别

| 项目 | j10_new | j10_native |
|---|---|---|
| BLE 实现 | EasyBLE 库 | Android 原生 BLE API |
| 扫描 | EasyBLE 封装 | `BluetoothLeScanner` |
| 连接 | EasyBLE 封装 | `BluetoothGatt` |
| 读写 | EasyBLE Builder | 原生 Characteristic 读写 |
| 回调机制 | 库内事件分发 | `BleCallback` 接口回调 |
| 依赖结构 | 含 BLE library 模块 | 仅 app 模块 + AndroidX |

## 已验证状态

当前项目已完成以下验证：

- `gradlew.bat -v` 可正常执行
- `gradlew.bat app:dependencies --configuration debugCompileClasspath` 可正常解析依赖
- `gradlew.bat clean assembleDebug` 构建成功

## 已知说明

- 当前构建时仍可能看到部分 **deprecated API** 提示，但**不影响 APK 生成**
- 项目现在更适合做功能复刻与协议验证；如果要继续产品化，建议再补：
  - README 截图
  - release 签名配置模板
  - 更完整的错误处理与重连策略
  - 更细的 BLE 协议文档

## 后续建议

如果后面还要继续整理，这几个方向最值：

1. 清理 deprecated API 警告
2. 补 Release 构建与签名模板
3. 给 BLE 通信加更清晰的日志和错误码映射
4. 增加断线重连与设备过滤策略

---

如果你只是想直接跑起来，这份 README 已经够用了；如果你想把它交给别人继续接手，也不至于让对方边看边骂。