跳到主要内容

Android OTA SDK 1.0.0 接入指南

SDK Version: 1.0.0

交付范围​

Android OTA SDK 是独立 Gradle library OTA SDK 1.0.0，客户 Maven 交付坐标为 com.xtalk:ota-sdk:1.0.0，最低 Android 8.0（API 26），Java 17。SDK 是 OTA 状态机、固件校验、分包、重试、取消和进度的唯一实现；App/UI 只提供设备传输与 RF lease，并显示 SDK 状态。

支持：

  • TurMass / TK8620 / TK8625：BLE 或 UART AT transport。
  • BT5632F：Bluetrum BLE FOTA。
  • 内置固件或客户传入的 ByteArray。
  • StateFlow<XTalkOtaState> 中严格为 0–100 的 progressPercent。

SDK 版本与固件版本相互独立。SDK 初始版本是 1.0.0；内置固件保持生产文件名， 不会跟随 SDK 重命名。完整固件清单随对应固件交付物提供。

Gradle 接入​

从交付清单指定的客户专用 Maven 仓库消费：

dependencies {
  implementation("com.xtalk:ota-sdk:1.0.0")
}
./gradlew --no-daemon :ota-sdk:testDebugUnitTest
./gradlew --no-daemon :ota-sdk:verifyOtaSdkReleasePublication

第二条命令会发布到本机 staging Maven 仓库，并用只依赖上述 Maven 坐标、开启 minify 的独立 consumer 构建 Release APK。

初始化与宿主职责​

val catalog = XTalkOtaFirmwareCatalog.from(applicationContext)

val turMass = XTalkTurMassOtaManager(
  firmwareCatalog = catalog,
  transport = hostTurMassTransport,
  leaseProvider = hostRfLeaseProvider,
)

val bluetooth = XTalkBluetoothFotaManager(
  context = applicationContext,
  firmwareCatalog = catalog,
  leaseProvider = hostRfLeaseProvider,
)

宿主必须实现：

  • XTalkTurMassTransport：按当前设备通道打开串行命令会话。BLE adapter 复用已认证的 BLE AT 通道；UART adapter 复用独占串口。SDK 发送 OTA AT 命令，宿主不可再做一套分包。
  • XTalkOtaLeaseProvider：OTA 开始前申请排他的 RF lease；PTT、文件传输、Mesh 发送 等冲突操作必须暂停或返回 busy；结束、失败、取消后释放。
  • BT5632F 调用前提供当前连接 MAC 和精确硬件版本。
  • 升级成功后重连设备、重新 authentication，再做初始化与版本回读。

设备必须已连接、供电稳定且电量满足产品阈值。BLE OTA 需要系统蓝牙权限；UART OTA 需要宿主已获得串口权限并能可靠取消挂起命令。

使用内置固件​

TurMass（BLE/UART 由 transport 决定）：

val result = turMass.startBuiltInFirmware()

BT5632F 根据硬件版本自动选择固件：

val result = bluetooth.startBuiltInFirmware(
  macAddress = device.address,
  hardwareVersion = "HW_V3.23.1",
)

不支持的硬件版本返回 XTalkOtaError.UnsupportedHardware，不得猜测或降级选择固件。

使用自定义固件数据​

val turMassResult = turMass.startFirmware(customerHexBytes)
val bluetoothResult = bluetooth.startFirmware(device.address, customerFotBytes)

自定义数据不会写入内置 catalog；调用方负责来源、型号匹配和发布授权。空数据或非法 HEX 返回 InvalidFirmware。

进度与 UI​

lifecycleScope.launch {
  repeatOnLifecycle(Lifecycle.State.STARTED) {
    turMass.state.collect { otaState ->
      progressBar.progress = otaState.progress.progressPercent
      statusView.text = otaState.progress.phase.name
      cancelButton.isEnabled = !otaState.isTerminal
      if (otaState.requiresReconnectAndAuthentication) {
        reconnectAndAuthenticate()
      }
    }
  }
}

progressPercent 永远在 0–100。COMPLETED 为 100；失败/取消保留最后可靠进度。 UI 不得自行按字节数再计算第二套百分比。取消使用 turMass.cancel() 或 bluetooth.cancel()。

错误表​

XTalkOtaError含义/处理
InvalidFirmware数据为空、HEX 非法或校验不符；停止并更换正确固件。
FirmwareNotFoundSDK 内置资源缺失；检查发布包完整性。
UnsupportedHardwareBT5632F 硬件版本无映射；禁止强刷。
NotConnected设备/MAC 无效；重连后重试。
BusyOTA 或 RF lease 被占用；等待当前业务结束。
TransportUnavailableBLE/UART/vendor 通道不可用。
TransportDisconnected升级中断连；重新发现设备并核对版本。
Timeout命令或 vendor ready 超时；检查距离、供电和链路。
DeviceRejected设备明确拒绝命令；不要无限重试。
VendorFailure(code)Bluetrum vendor 错误，记录 code。
Cancelled用户或宿主取消。
InternalFailure未归类异常；保留脱敏日志并上报。

混淆、日志与发布​

SDK 自带 consumer ProGuard 规则，独立 minified consumer 已作为发布门禁。宿主不要删除 vendor callback 类；若额外收紧规则，应再次运行 verifyOtaSdkReleasePublication。 日志只记录 phase、百分比、错误码和目标类型，不记录固件字节、认证密钥或完整设备隐私数据。

一次 SDK 返回成功不等于完整产品闭环：必须等待设备重启，执行 reconnect、 authentication、初始化、版本回读后，UI 才能显示升级完成。