iOS OTA SDK 1.0.0 Integration

SDK Version: 1.0.0

Package

product/module is XTalkOtaSdk, its SDK version is 1.0.0, and its minimum deployment target is iOS 17. It owns TurMass/TK8620/TK8625 OTA, BT5632F FOTA, the firmware resources, CRC/packet state, and the AB_FOTA binary target.

Add the local package in Xcode and link product XTalkOtaSdk, or declare:

dependencies: [
    .package(name: "XTalkOtaSdk", path: "../../Packages/XTalkOtaSdk"),
]

.target(
    name: "CustomerTarget",
    dependencies: [.product(name: "XTalkOtaSdk", package: "XTalkOtaSdk")]
)

The isolated Examples/XTalkOtaSdkConsumer proves this single-package graph.

Construction and host adapters

let catalog = XTalkOtaFirmwareCatalog()
let turMass = XTalkTurMassOtaManager(
    firmwareCatalog: catalog,
    transport: hostTurMassTransport,
    leaseProvider: hostRfLeaseProvider
)
let bluetooth = XTalkBluetoothFotaManager(
    firmwareCatalog: catalog,
    leaseProvider: hostRfLeaseProvider
)

The host implements XTalkTurMassTransport and a serialized command session over its authenticated BLE channel or exclusive UART channel. The adapter must not reimplement OTA packetization. XTalkOtaLeaseProvider grants an exclusive RF lease that blocks conflicting PTT, Mesh, and file-transfer operations and releases on success, error, and cancellation.

Built-in and custom data

let turMassResult = await turMass.startBuiltInFirmware()
let btResult = await bluetooth.startBuiltInFirmware(
    targetIdentifier: peripheral.identifier,
    hardwareVersion: "HW_V3.13.1"
)

let customTurMass = await turMass.startFirmware(customHexData)
let customBt = await bluetooth.startFirmware(
    targetIdentifier: peripheral.identifier,
    firmware: customFotData
)

Unknown hardware returns XTalkOtaError.unsupportedHardware; never guess a firmware mapping. Custom Data remains outside the built-in catalog.

AsyncStream progress and cancellation

let events = turMass.events
let observation = Task { @MainActor in
    for await event in events {
        guard case .stateChanged(let state) = event else { continue }
        renderProgress(state.progress.progressPercent) // always 0–100
        if state.requiresReconnectAndAuthentication {
            await reconnectAndAuthenticate()
        }
    }
}

await turMass.cancel()
observation.cancel()

progressPercent is the only UI percentage. A completed session reaches 100. Success requires device reboot, reconnect, authentication, initialization, and version readback before the product flow is complete.

Error reference

XTalkOtaError	Action
invalidFirmware	Reject empty, malformed, or mismatched data.
firmwareNotFound	Verify package resources.
unsupportedHardware	Stop and obtain an approved mapping.
notConnected	Reconnect the target.
busy	Wait for the OTA/RF owner.
transportUnavailable	Restore the BLE/UART/vendor channel.
transportDisconnected	Rediscover and read back the version.
timeout	Check range, power, and readiness.
deviceRejected	Stop automatic retry.
vendorFailure(code)	Record the redacted vendor code.