iOS OTA SDK 1.0.0 接入指南

SDK Version: 1.0.0

Package 与支持范围

iOS OTA 是第六个真实本地 Swift Package：

Product / Module：XTalkOtaSdk
SDK 版本：1.0.0
最低系统：iOS 17

它与 XTalkMeshSdk、LowLatencyPtt、XTalkBleSdk、XTalkDeviceAuthSdk、 XTalkFileTransferSdk 并列，不是前两个 Package 中的子目录。SDK 负责 TurMass/TK8620/TK8625 OTA 和 BT5632F BLE FOTA，并内置生产固件与 AB_FOTA binary target。App/UI 不再拥有 OTA 分包、CRC、vendor callback 或固件资源副本。

SDK 版本与固件版本独立。SDK 是 1.0.0，固件仍保留原文件名和版本；详见固件交付物附带的 OTA 固件清单。

SwiftPM 接入

在 Xcode 中选择 File → Add Package Dependencies → Add Local，添加 Packages/XTalkOtaSdk，然后把 product XTalkOtaSdk 链接到 App target：

import XTalkOtaSdk

Package manifest 形式：

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

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

BLE、认证或文件传输模块。

初始化与宿主职责

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

宿主实现 XTalkTurMassTransport 与 XTalkTurMassCommandSession，把 SDK 的串行 AT 命令接到已认证的 BLE 命令通道或独占 UART 通道。SDK 负责 OTA 协议和分包，adapter 不得复制协议状态机。

宿主还要实现 XTalkOtaLeaseProvider。每次 OTA 必须先取得排他的 RF lease，阻止 PTT、Mesh 发送、文件传输等同时使用无线资源；成功、失败、取消都必须释放。

内置固件

TurMass：

let result = await turMass.startBuiltInFirmware()

BT5632F 按精确硬件版本选择：

let result = await bluetooth.startBuiltInFirmware(
    targetIdentifier: peripheral.identifier,
    hardwareVersion: "HW_V3.23.1"
)

未知硬件返回 XTalkOtaError.unsupportedHardware，不得猜测固件。

自定义 Data

let turMassResult = await turMass.startFirmware(customerHexData)
let bluetoothResult = await bluetooth.startFirmware(
    targetIdentifier: peripheral.identifier,
    firmware: customerFotData
)

自定义 Data 不加入内置 catalog；调用方负责固件来源、目标型号、版本策略与授权。

AsyncStream 进度与 UI

let events = turMass.events
let observer = Task { @MainActor in
    for await event in events {
        guard case .stateChanged(let state) = event else { continue }
        progressValue = state.progress.progressPercent // 严格 0–100
        phaseText = String(describing: state.progress.phase)
        if state.requiresReconnectAndAuthentication {
            await reconnectAndAuthenticate()
        }
    }
}

let result = await turMass.startBuiltInFirmware()
await turMass.cancel() // 取消按钮
observer.cancel()

progressPercent 是 UI 唯一百分比来源；完成时为 100，失败/取消保留最后可靠值。成功状态的 requiresReconnectAndAuthentication 为 true：设备重启后必须 reconnect、 authentication、初始化和版本回读，完成这些步骤后 UI 才能宣布升级完成。

错误表

`XTalkOtaError`	处理
`.invalidFirmware`	拒绝空、非法或校验错误数据。
`.firmwareNotFound`	检查 Package resources 是否完整。
`.unsupportedHardware`	停止升级，取得正式硬件映射。
`.notConnected`	重连目标设备。
`.busy`	等待当前 OTA 或 RF lease。
`.transportUnavailable`	恢复 BLE/UART/vendor 通道。
`.transportDisconnected`	重新发现设备并做版本回读。
`.timeout`	检查距离、供电和 ready/AT 响应。
`.deviceRejected`	停止自动重试，检查设备状态。
`.vendorFailure(code)`	记录脱敏 vendor code。
`.cancelled`	用户或宿主已取消。
`.internalFailure`	保留脱敏诊断信息并上报。

Package 与支持范围​

SwiftPM 接入​

初始化与宿主职责​

内置固件​

自定义 Data​

AsyncStream 进度与 UI​

错误表​