Android OTA SDK 1.0.0 Integration

SDK Version: 1.0.0

Scope

The Android customer-Maven artifact is com.xtalk:ota-sdk:1.0.0 (:ota-sdk in this repository), with minSdk 26 and Java 17. It is the only owner of OTA validation, packetization, retry, cancellation, state, and progress. The host supplies device adapters and an exclusive RF lease; UI observes the SDK.

Supported paths are TurMass/TK8620/TK8625 over a host BLE or UART AT transport, and BT5632F through the packaged Bluetrum BLE backend. Built-in and caller-provided firmware are supported. SDK version 1.0.0 is independent from firmware versions.

Dependency and verification

dependencies {
  implementation("com.xtalk:ota-sdk:1.0.0")
}

The publication gate stages the Maven artifact and builds a minified independent consumer. The SDK includes consumer ProGuard rules.

Construction

val catalog = XTalkOtaFirmwareCatalog.from(applicationContext)
val turMass = XTalkTurMassOtaManager(catalog, hostTransport, hostRfLeaseProvider)
val bluetooth = XTalkBluetoothFotaManager(
  applicationContext,
  catalog,
  hostRfLeaseProvider,
)

XTalkTurMassTransport opens one serialized AT session. A BLE adapter must reuse the authenticated BLE command channel; a UART adapter must own the serial port. The SDK, not the adapter or UI, creates OTA packets. XTalkOtaLeaseProvider must grant an exclusive RF lease and release it on every terminal path.

Built-in and custom firmware

val turMassResult = turMass.startBuiltInFirmware()
val btResult = bluetooth.startBuiltInFirmware(
  macAddress = device.address,
  hardwareVersion = "HW_V3.13.1",
)

val customTurMassResult = turMass.startFirmware(customHexBytes)
val customBtResult = bluetooth.startFirmware(device.address, customFotBytes)

An unknown BT5632F hardware version returns XTalkOtaError.UnsupportedHardware; the host must never guess a firmware. Custom bytes remain outside the built-in catalog.

StateFlow and cancellation

lifecycleScope.launch {
  manager.state.collect { state ->
    renderProgress(state.progress.progressPercent) // always 0–100
    renderPhase(state.progress.phase)
    if (state.requiresReconnectAndAuthentication) reconnectAndAuthenticate()
  }
}

manager.cancel()

progressPercent is the single UI progress source. Completion is 100; failure and cancellation preserve the last reliable value. A successful engine result still requires device reboot, reconnect, authentication, initialization, and version readback.

Error reference

`XTalkOtaError`	Action
`InvalidFirmware`	Reject empty, malformed, or mismatched input.
`FirmwareNotFound`	Verify SDK resources and packaging.
`UnsupportedHardware`	Do not flash; obtain an approved mapping.
`NotConnected`	Reconnect and retry.
`Busy`	Wait for the current OTA/RF lease owner.
`TransportUnavailable`	Restore the BLE/UART/vendor channel.
`TransportDisconnected`	Rediscover and read back the device version.
`Timeout`	Check power, range, and command readiness.
`DeviceRejected`	Stop automatic retry and inspect device state.
`VendorFailure(code)`	Record the vendor code in redacted logs.
`Cancelled`	User or host cancellation.
`InternalFailure`	Record redacted diagnostics and escalate.

Hardware testing requires a stable power source, the required Bluetooth/serial permissions, the correct target model, and a host recovery flow. See the device-side release checklist supplied with the firmware delivery.

Scope​

Dependency and verification​

Construction​

Built-in and custom firmware​

StateFlow and cancellation​

Error reference​