Duooomi Android BLE SDK
Duooomi 蓝牙 BLE SDK 的 Android 版本。
环境要求
SDK 集成要求（消费方最低版本）：
| 项目 | 最低要求 |
|---|---|
| Kotlin | 1.9.0+ |
| AGP | 7.4.2+ |
| minSdk | 23 (Android 6.0) |
| JDK | 11+ |
SDK 开发构建环境：
| 项目 | 要求 |
|---|---|
| Android Studio | Hedgehog (2023.1.1) 或更高 |
| Kotlin | 1.9.22 |
| AGP | 8.2.2 |
| Gradle | 8.x |
| JDK | 17 |
| compileSdk / targetSdk | 34 |
项目结构
duooomi-android-sdk/
├── sdk/ # SDK 库模块 (com.android.library)
│ └── src/main/kotlin/com/duooomi/ble/
│ ├── DuooomiBleSDK.kt # 公开 API 入口
│ ├── DuooomiBleConfig.kt # SDK 配置
│ ├── core/ # BLE 核心层 (BleClient, 类型定义, 错误类型)
│ ├── protocol/ # BLE 协议层 (帧格式, UUID, 协议管理)
│ ├── services/ # 服务层 (设备信息, 文件传输, ANI转换, 固件)
│ ├── models/ # 数据模型
│ └── utils/ # 日志工具
├── demo/ # 演示 App (Jetpack Compose)
└── build.gradle.kts
依赖
SDK 仅依赖一个外部库：
org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3
其余全部使用 Android 内置 API（BLE、JSON、HttpURLConnection）。
快速开始
1. 引入 SDK
在 settings.gradle.kts 中：
include(":sdk")
在 app 模块的 build.gradle.kts 中：
dependencies {
implementation(project(":sdk"))
}
2. 添加权限
在 AndroidManifest.xml 中添加：
<!-- Android 11 及以下 -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<!-- Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- 网络 (ANI转换/固件下载) -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
注意： 运行时仍需动态申请
BLUETOOTH_SCAN、BLUETOOTH_CONNECT（Android 12+）和ACCESS_FINE_LOCATION权限。
3. 初始化 SDK
val sdk = DuooomiBleSDK(
context = this,
config = DuooomiBleConfig(
apiKey = "YOUR_API_KEY"
)
)
4. API Key 说明
| 参数 | 说明 |
|---|---|
apiKey |
必填。用于 ANI 转换和固件查询等后端 API 鉴权。 |
apiHost |
默认 https://api.duooomi.com，一般无需修改 |
cdnHost |
默认 https://cdn.bowong.cc/，一般无需修改 |
firmwareIdentifier |
默认 duomi，设备固件标识符 |
firmwareStatus |
默认 DRAFT，可选 PUBLISHED |
aniWidth |
ANI 转换宽度，默认 360 |
aniHeight |
ANI 转换高度，默认 360 |
aniFps |
ANI 转换帧率，默认 "24" |
API 参考
可观察状态 (StateFlow)
sdk.btState // ConnectionState: IDLE, SCANNING, CONNECTING, CONNECTED, ...
sdk.discoveredDevices // List<DiscoveredDevice>
sdk.connectedDevice // DiscoveredDevice?
sdk.deviceInfo // DeviceInfo?
sdk.version // String
sdk.isActivated // Boolean
sdk.transferProgress // Int (0-100)
sdk.error // String?
扫描与连接
// 开始扫描 (自动过滤 Duooomi 设备)
sdk.scan()
// 停止扫描
sdk.stopScan()
// 连接设备 (suspend)
val device = sdk.connect(deviceId)
// 断开连接 (suspend)
sdk.disconnect()
设备操作 (均需先连接)
// 获取设备信息
val info = sdk.getDeviceInfo()
// info.brand, info.name, info.size, info.powerlevel, info.freespace, info.allspace
// 获取固件版本
val versionInfo = sdk.getVersion()
// versionInfo.version, versionInfo.type
// 绑定设备
val bindResult = sdk.bind(userId)
// bindResult.sn, bindResult.contents (设备文件列表)
// 解绑设备
sdk.unbind(userId)
// 删除设备文件
sdk.deleteFile(fileKey)
文件传输
// 传输媒体文件 (格式校验 → ANI 转换 → prepare → transfer)
sdk.transferMedia(fileUrl)
// 监听进度
sdk.transferProgress.collect { percent -> /* 0-100 */ }
支持的媒体格式： JPEG、PNG、GIF、MP4、WebM、WebP
格式校验规则：
- 优先从 URL path 提取扩展名（自动忽略查询参数）
- 无扩展名时通过 HEAD 请求检查
Content-Type - 不支持的格式抛出
DuooomiBleError.UnsupportedFormat
固件升级
// 查询最新固件
val firmware = sdk.fetchLatestFirmware(identifier, status)
// firmware?.version, firmware?.fileUrl, firmware?.fileSize
// 检查是否有新版本 (对比版本号末尾10位时间戳)
val needUpdate = sdk.hasNewerFirmware(
deviceVersion = sdk.version.value, // 当前设备版本
serverVersion = firmware?.version // 服务端最新版本
)
// 参数为空/null/格式不合法时返回 false
// 执行 OTA 升级
sdk.upgradeFirmware(firmware.fileUrl)
错误处理
所有 suspend 方法在失败时抛出 DuooomiBleError：
try {
sdk.connect(deviceId)
} catch (e: DuooomiBleError.BluetoothNotPoweredOn) { /* 蓝牙未开启 */ }
catch (e: DuooomiBleError.ConnectionFailed) { /* 连接失败 */ }
catch (e: DuooomiBleError.NotConnected) { /* 未连接 */ }
catch (e: DuooomiBleError.Timeout) { /* 超时 */ }
catch (e: DuooomiBleError.PermissionDenied) { /* 权限不足 */ }
运行 Demo
# 构建
./gradlew :demo:assembleDebug
# 安装到设备
adb install demo/build/outputs/apk/debug/demo-debug.apk
BLE 协议简述
- Service UUID:
000002c4-0000-1000-8000-00805f9b34fb - Write Characteristic:
000002c5-... - Read Characteristic (Notify):
000002c6-... - 帧格式:
[head:1][type:1][subpageTotal:2][curPage:2][dataLen:2][data:N][checksum:1] - 校验和: 二进制补码
(~sum + 1) & 0xFF - 大数据分片: 自动拆分，帧间延迟 35ms
License
Proprietary - Duooomi