xdz-app/capability-ble

BLE 蓝牙能力层集成说明

概述

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

快速开始

方式一：最简单（推荐）

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. 获取服务实例

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

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

2. 扫描设备

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

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

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

// 准备用户信息
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 便捷方法（推荐）

// 设防/撤防
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 通用方法（高级用法）

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

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

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

4.3 查询车辆信息

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 系统控制指令（其他）

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

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

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

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

4.5 系统设置指令

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. 接收数据

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. 断开连接

bleService.disconnect()

完整使用示例

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

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

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秒

示例：

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: 错误回调

示例：

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: 错误回调

示例：

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

startScan(callback: (BLEDevice) -> Unit)

开始扫描 BLE 设备（用于分步操作）。

参数：

• callback: 扫描结果回调，每次发现设备时调用

示例：

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)

发送自定义指令（用于系统设置等）。

示例：

val command = BLECommand(
    functionCode = BLEConstants.FUNCTION_CODE_SYSTEM_SETTING,
    instructionType = 0x01.toByte(),
    applicationData = byteArrayOf(0x01)
)

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

数据接收

setDataReceivedListener(listener: DataCallback)

设置数据接收监听器。

示例：

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

常量定义

用户类型

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

功能码

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 中添加蓝牙相关权限：

   <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