# BLE 蓝牙能力层集成说明

## 概述

`capability-ble` 模块封装了新大洲本田蓝牙协议，提供简洁的高级 API 供业务模块调用。所有底层细节（连接、握手、配对、分包、加密等）都在能力层内部完成，业务层只需要调用简单的 API 即可。

## 快速开始

### 方式一：最简单（推荐）

```kotlin
import com.narutohuo.xindazhou.ble.factory.BLEServiceFactory
import com.narutohuo.xindazhou.ble.api.BLEService

class VehicleControlActivity : AppCompatActivity() {
    
    private lateinit var bleService: BLEService
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // 获取服务实例并一键初始化连接
        bleService = BLEServiceFactory.create(this)
        
        val userId = getUserId() // 16字节，从用户信息获取
        val userType = BLEConstants.USER_TYPE_OWNER
        
        // 一键完成：初始化监听 + 扫描 + 连接 + 握手
        bleService.initializeAndConnect(
            userId = userId,
            userType = userType,
            onConnected = {
                // 连接成功，已自动完成握手和配对，可以直接使用
                showToast("连接成功")
                setupControls()
            },
            onDisconnected = {
                showToast("连接已断开")
            },
            onDataReceived = { data ->
                // 处理接收到的数据
                handleReceivedData(data)
            },
            onError = { error ->
                showError(error)
            }
        )
    }
    
    private fun setupControls() {
        // 设防
        btnDefense.setOnClickListener {
            bleService.setDefense(enabled = true) { response ->
                if (response.success) showToast("设防成功")
            }
        }
        
        // 上电
        btnPower.setOnClickListener {
            bleService.powerOn { response ->
                if (response.success) showToast("上电成功")
            }
        }
    }
    
    override fun onDestroy() {
        super.onDestroy()
        if (bleService.isConnected()) {
            bleService.disconnect()
        }
    }
}
```

### 方式二：分步操作（更灵活）

### 1. 获取服务实例

```kotlin
import com.narutohuo.xindazhou.ble.factory.BLEServiceFactory
import com.narutohuo.xindazhou.ble.api.BLEService

// 在任何地方获取单例实例
val bleService: BLEService = BLEServiceFactory.create(context)
```

### 2. 扫描设备

```kotlin
// 开始扫描
bleService.startScan { device ->
    // 找到设备
    println("发现设备: ${device.name}, MAC: ${device.address}")
}

// 停止扫描（通常在找到设备后或超时后调用）
bleService.stopScan()
```

### 3. 连接设备（自动完成握手和配对）

```kotlin
// 准备用户信息
val userId = ByteArray(16) { /* 从用户信息获取 */ }
val userType = BLEConstants.USER_TYPE_OWNER // 0x02=车主

// 连接设备（连接成功即表示已完成握手和配对）
val device = BLEDevice(
    name = "新大洲",
    address = "AA:BB:CC:DD:EE:FF",
    rssi = -50
)

bleService.connect(device, userId, userType) { response ->
    if (response.success) {
        // 连接成功，已自动完成握手和配对，可以直接使用
        println("连接成功")
    } else {
        // 连接失败
        println("连接失败: ${response.errorMessage}")
    }
}
```

### 4. 发送指令

连接成功后，就可以发送各种指令了。推荐使用便捷方法，更简单易用：

#### 4.1 便捷方法（推荐）

```kotlin
// 设防/撤防
bleService.setDefense(enabled = true) { response ->
    if (response.success) {
        println("设防成功")
    }
}

// 上电/下电
bleService.powerOn { response ->
    if (response.success) {
        println("上电成功")
    }
}

bleService.powerOff { response ->
    if (response.success) {
        println("下电成功")
    }
}

// 寻车
bleService.findCar { response ->
    if (response.success) {
        println("寻车成功")
    }
}

// 座桶锁
bleService.unlockSeat { response ->
    if (response.success) {
        println("座桶锁已打开")
    }
}

// 龙头锁
bleService.unlockHandlebar { response ->
    if (response.success) {
        println("龙头锁已打开")
    }
}

bleService.lockHandlebar { response ->
    if (response.success) {
        println("龙头锁已关闭")
    }
}

// 尾箱锁
bleService.unlockTrunk { response ->
    if (response.success) {
        println("尾箱锁已打开")
    }
}

bleService.lockTrunk { response ->
    if (response.success) {
        println("尾箱锁已关闭")
    }
}

// 感应解锁开关
bleService.setSensorUnlock(enabled = true) { response ->
    if (response.success) {
        println("感应解锁已开启")
    }
}

// 氛围灯开关
bleService.setAmbientLight(enabled = true) { response ->
    if (response.success) {
        println("氛围灯已开启")
    }
}

// 氛围灯颜色（RGB）
bleService.setAmbientLightColor(r = 255, g = 0, b = 0) { response ->
    if (response.success) {
        println("氛围灯颜色已设置为红色")
    }
}

// 自动下电时间（秒）
bleService.setAutoPowerOffTime(timeSeconds = 300) { response ->
    if (response.success) {
        println("自动下电时间已设置为300秒")
    }
}

// 蓝牙音箱音量（0-100）
bleService.setSpeakerVolume(volume = 50) { response ->
    if (response.success) {
        println("音量已设置为50%")
    }
}
```

#### 4.2 通用方法（高级用法）

如果需要更灵活的控制，可以使用通用方法：

```kotlin
import com.narutohuo.xindazhou.ble.model.AppControlInstruction

// 应用控制指令
bleService.sendAppControlCommand(
    instructionType = AppControlInstruction.SET_DEFENSE,
    data = byteArrayOf(0x01)
) { response ->
    // 处理响应
}
```

#### 4.3 查询车辆信息

```kotlin
bleService.queryVehicleInfo { response ->
    if (response.success && response.data != null) {
        // 解析车辆信息
        val data = response.data!!
        // 根据协议文档解析数据
        // data[0]: 设防状态
        // data[1]: 上电状态
        // data[2]: 门锁状态
        // ...
    } else {
        println("查询失败: ${response.errorMessage}")
    }
}
```

#### 4.4 系统控制指令（其他）

对于便捷方法未覆盖的指令，可以使用通用方法：

```kotlin
import com.narutohuo.xindazhou.ble.model.SystemControlInstruction

// 被盗锁定开关
bleService.sendSystemControlCommand(
    instructionType = SystemControlInstruction.STOLEN_LOCK,
    data = byteArrayOf(0x01) // 0x01=开启, 0x00=关闭
) { response ->
    // 处理响应
}

// 更多指令类型请查看 SystemControlInstruction 对象
```

#### 4.5 系统设置指令

```kotlin
import com.narutohuo.xindazhou.ble.config.BLEConstants
import com.narutohuo.xindazhou.ble.model.BLECommand

// 钥匙学码
val command = BLECommand(
    functionCode = BLEConstants.FUNCTION_CODE_SYSTEM_SETTING,
    instructionType = 0x01.toByte(),
    applicationData = byteArrayOf(0x01)
)

bleService.sendCommand(command) { response ->
    // 处理响应
}

// 震动灵敏度设置
val command = BLECommand(
    functionCode = BLEConstants.FUNCTION_CODE_SYSTEM_SETTING,
    instructionType = 0x02.toByte(),
    applicationData = byteArrayOf(3) // 1-5级
)

bleService.sendCommand(command) { response ->
    // 处理响应
}
```

### 5. 接收数据

```kotlin
import com.narutohuo.xindazhou.ble.callback.DataCallback

bleService.setDataReceivedListener(object : DataCallback {
    override fun onDataReceived(data: ByteArray) {
        // 处理接收到的数据（通常是JSON格式）
        val jsonString = String(data, Charsets.UTF_8)
        println("收到数据: $jsonString")
        
        // 解析JSON并处理业务逻辑
        // ...
    }
})
```

### 6. 断开连接

```kotlin
bleService.disconnect()
```

## 完整使用示例

### 方式三：分步操作（更灵活）

如果需要更精细的控制，可以分步操作：

```kotlin
class VehicleControlActivity : AppCompatActivity() {
    
    private lateinit var bleService: BLEService
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // 1. 获取服务实例
        bleService = BLEServiceFactory.create(this)
        
        // 2. 设置数据接收监听
        bleService.setDataReceivedListener(object : DataCallback {
            override fun onDataReceived(data: ByteArray) {
                handleReceivedData(data)
            }
        })
        
        // 3. 扫描设备
        scanDevices()
    }
    
    private fun scanDevices() {
        bleService.startScan { device ->
            // 找到设备，停止扫描
            bleService.stopScan()
            
            // 连接设备
            connectToDevice(device)
        }
        
        // 10秒后自动停止扫描
        Handler(Looper.getMainLooper()).postDelayed({
            bleService.stopScan()
        }, 10000)
    }
    
    private fun connectToDevice(device: BLEDevice) {
        val userId = getUserId() // 16字节
        val userType = BLEConstants.USER_TYPE_OWNER
        
        bleService.connect(device, userId, userType) { response ->
            if (response.success) {
                // 连接成功，已自动完成握手和配对
                onConnected()
            } else {
                showError("连接失败: ${response.errorMessage}")
            }
        }
    }
    
    private fun onConnected() {
        // 连接成功后，可以发送各种指令
        // ...
    }
    
    override fun onDestroy() {
        super.onDestroy()
        if (bleService.isConnected()) {
            bleService.disconnect()
        }
    }
}
```

## API 参考

### 基础连接功能

#### `initializeAndConnect(...)` ⭐⭐⭐ 最推荐，最简单
一键完成所有初始化、监听设置、扫描、连接、握手，最简单的方式。

**参数：**
- `userId`: 用户ID（16字节）
- `userType`: 用户类型（0x01=最高权限, 0x02=车主, 0x03=分享用户）
- `onConnected`: 连接成功回调（已自动完成握手和配对）
- `onDisconnected`: 断开连接回调（可选）
- `onDataReceived`: 数据接收回调（可选）
- `onError`: 错误回调（可选）
- `scanTimeoutMs`: 扫描超时时间（毫秒），默认10秒

**示例：**
```kotlin
bleService.initializeAndConnect(
    userId = getUserId(),
    userType = BLEConstants.USER_TYPE_OWNER,
    onConnected = {
        // 连接成功，已自动完成握手和配对，可以直接使用
        showToast("连接成功")
    },
    onDisconnected = {
        showToast("连接已断开")
    },
    onDataReceived = { data ->
        // 处理接收到的数据
        handleData(data)
    },
    onError = { error ->
        showError(error)
    }
)
```

#### `scanAndConnect(...)` ⭐⭐ 推荐使用
一键完成扫描+连接+握手。

**参数：**
- `userId`: 用户ID（16字节）
- `userType`: 用户类型（0x01=最高权限, 0x02=车主, 0x03=分享用户）
- `scanTimeoutMs`: 扫描超时时间（毫秒），默认10秒
- `onScanning`: 扫描中回调（可选）
- `onDeviceFound`: 找到设备回调（可选）
- `onConnected`: 连接成功回调（已自动完成握手和配对）
- `onError`: 错误回调

**示例：**
```kotlin
bleService.scanAndConnect(
    userId = getUserId(),
    userType = BLEConstants.USER_TYPE_OWNER,
    onScanning = { showToast("正在扫描...") },
    onDeviceFound = { device -> showToast("找到设备: ${device.name}") },
    onConnected = { 
        // 连接成功，已自动完成握手和配对，可以直接使用
        showToast("连接成功")
    },
    onError = { error -> showError(error) }
)
```

#### `setConnectionListener(...)` ⭐ 推荐使用
设置连接状态监听器，自动监听连接/断开事件。

**参数：**
- `onConnected`: 连接成功回调
- `onDisconnected`: 断开连接回调
- `onError`: 错误回调

**示例：**
```kotlin
bleService.setConnectionListener(
    onConnected = { 
        // 连接成功，已自动完成握手和配对
        showToast("连接成功")
    },
    onDisconnected = { 
        showToast("连接已断开")
    },
    onError = { error -> 
        showError(error)
    }
)
```

#### `startScan(callback: (BLEDevice) -> Unit)`
开始扫描 BLE 设备（用于分步操作）。

**参数：**
- `callback`: 扫描结果回调，每次发现设备时调用

**示例：**
```kotlin
bleService.startScan { device ->
    println("发现设备: ${device.name}")
}
```

#### `stopScan()`
停止扫描设备。

#### `connect(device: BLEDevice, userId: ByteArray, userType: Byte, callback: (BLEResponse) -> Unit)`
连接设备并自动完成握手和配对（用于分步操作）。

**参数：**
- `device`: 要连接的设备
- `userId`: 用户ID（16字节）
- `userType`: 用户类型（0x01=最高权限, 0x02=车主, 0x03=分享用户）
- `callback`: 连接结果回调，连接成功表示已完成握手和配对

**注意：** 连接成功即表示已完成握手和配对，业务层无需再调用握手方法。

#### `disconnect()`
断开连接。

#### `isConnected(): Boolean`
检查是否已连接。

### 指令发送功能

#### 便捷方法（推荐）

**应用控制：**
- `setDefense(enabled: Boolean, callback)` - 设防/撤防
- `powerOn(callback)` - 上电
- `powerOff(callback)` - 下电
- `findCar(callback)` - 寻车
- `unlockSeat(callback)` - 打开座桶锁
- `unlockHandlebar(callback)` - 打开龙头锁
- `lockHandlebar(callback)` - 关闭龙头锁
- `unlockTrunk(callback)` - 打开尾箱锁
- `lockTrunk(callback)` - 关闭尾箱锁

**系统控制：**
- `setSensorUnlock(enabled: Boolean, callback)` - 设置感应解锁开关
- `setAmbientLight(enabled: Boolean, callback)` - 设置氛围灯开关
- `setAmbientLightColor(r: Int, g: Int, b: Int, callback)` - 设置氛围灯颜色
- `setAutoPowerOffTime(timeSeconds: Int, callback)` - 设置自动下电时间
- `setSpeakerVolume(volume: Int, callback)` - 设置蓝牙音箱音量

#### 通用方法（高级用法）

#### `sendAppControlCommand(instructionType: Byte, data: ByteArray, callback: (BLEResponse) -> Unit)`
发送应用控制指令（用于便捷方法未覆盖的场景）。

**常用指令类型：**
- `AppControlInstruction.SET_DEFENSE` - 设撤防
- `AppControlInstruction.POWER_ON_OFF` - 上下电
- `AppControlInstruction.FIND_CAR` - 寻车
- `AppControlInstruction.SEAT_LOCK` - 座桶锁
- `AppControlInstruction.HANDLEBAR_LOCK` - 龙头锁
- `AppControlInstruction.TRUNK_LOCK` - 尾箱锁

#### `sendSystemControlCommand(instructionType: Byte, data: ByteArray, callback: (BLEResponse) -> Unit)`
发送系统控制指令（用于便捷方法未覆盖的场景）。

**常用指令类型：**
- `SystemControlInstruction.SENSOR_UNLOCK` - 感应解锁开关
- `SystemControlInstruction.AMBIENT_LIGHT` - 氛围灯开关
- `SystemControlInstruction.AMBIENT_LIGHT_COLOR` - 氛围灯颜色
- `SystemControlInstruction.AUTO_POWER_OFF_TIME` - 自动下电时间
- `SystemControlInstruction.SPEAKER_VOLUME` - 蓝牙音箱音量
- 更多指令类型请查看 `SystemControlInstruction` 对象

#### `queryVehicleInfo(callback: (BLEResponse) -> Unit)`
查询车辆信息。

**响应数据：**
- `response.data`: 车辆信息数据（ByteArray），需要根据协议文档解析

#### `sendCommand(command: BLECommand, callback: (BLEResponse) -> Unit)`
发送自定义指令（用于系统设置等）。

**示例：**
```kotlin
val command = BLECommand(
    functionCode = BLEConstants.FUNCTION_CODE_SYSTEM_SETTING,
    instructionType = 0x01.toByte(),
    applicationData = byteArrayOf(0x01)
)

bleService.sendCommand(command) { response ->
    // 处理响应
}
```

### 数据接收

#### `setDataReceivedListener(listener: DataCallback)`
设置数据接收监听器。

**示例：**
```kotlin
bleService.setDataReceivedListener(object : DataCallback {
    override fun onDataReceived(data: ByteArray) {
        // 处理接收到的数据
    }
})
```

## 常量定义

### 用户类型
```kotlin
BLEConstants.USER_TYPE_HIGHEST  // 0x01 - 最高权限
BLEConstants.USER_TYPE_OWNER    // 0x02 - 车主
BLEConstants.USER_TYPE_SHARED   // 0x03 - 分享用户
```

### 功能码
```kotlin
BLEConstants.FUNCTION_CODE_HANDSHAKE        // 0x01 - 握手
BLEConstants.FUNCTION_CODE_APP_CONTROL    // 0x02 - 应用控制
BLEConstants.FUNCTION_CODE_SYSTEM_CONTROL  // 0x03 - 系统控制
BLEConstants.FUNCTION_CODE_SYSTEM_QUERY    // 0x04 - 系统查询
BLEConstants.FUNCTION_CODE_SYSTEM_SETTING  // 0x05 - 系统设置
```

## 注意事项

1. **单例模式**：`BLEService` 使用单例模式，全局共享同一个连接状态。

2. **自动握手**：连接时传入用户信息，连接成功即表示已完成握手和配对，无需手动调用握手方法。

3. **线程安全**：所有回调都在主线程执行，可以直接更新 UI。

4. **错误处理**：所有 API 都通过 `BLEResponse` 返回结果，需要检查 `response.success` 判断是否成功。

5. **权限要求**：需要在 `AndroidManifest.xml` 中添加蓝牙相关权限：
   ```xml
   <uses-permission android:name="android.permission.BLUETOOTH" />
   <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
   <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
   <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
   ```

6. **生命周期管理**：建议在 `onDestroy()` 中调用 `disconnect()` 断开连接。

## 架构说明

能力层内部自动处理：
- ✅ GATT 连接管理
- ✅ 服务发现
- ✅ 握手认证（连接时自动完成）
- ✅ 配对处理（连接时自动完成）
- ✅ 数据分包和组包
- ✅ ACK/REX 机制
- ✅ 超时重试
- ✅ AES 加密/解密
- ✅ 协议包构建和解析

业务层只需要：
- ✅ 调用高级 API
- ✅ 处理业务逻辑
- ✅ 更新 UI

## 更多信息

详细的协议说明请参考：`doc/蓝牙协议.md`