跳到主要内容

摄像头固件更新

摄像头 OTA 用于更新受支持设备摄像头模块的固件，与设备主固件更新相互独立。

宿主 App 提供兼容的本地摄像头固件包。SDK 随后协调完整升级流程：配置设备热点、进入 Camera OTA 模式、启动本地 HTTP 服务器、向设备发送固件 URL、传输固件包并刷写摄像头固件。界面可通过阶段回调展示当前操作，最终升级结果以完成回调为准。

Animated workflow

摄像头 OTA 升级流程

宿主 App 验证本地固件包后，由 SDK 协调传输和刷写，并通过完成回调返回最终结果。

宿主 App

验证固件包

验证完整性、摄像头型号兼容性和本地路径可读性。

SDK + 设备

配置热点

准备摄像头 OTA 流程使用的设备网络。

设备

进入 OTA 模式

将摄像头模块切换到固件更新模式。

SDK

连接热点

加入分阶段更新会话提供的 SSID。

SDK

启动 HTTP 服务器

向设备提供所选本地固件包。

SDK → 设备

发送固件 URL

发送供设备请求的本地 HTTP URL。

进度阶段

传输固件

设备下载固件数据期间持续提供固件包。

.transferring · 0...100
进度阶段

刷写固件

摄像头模块写入已传输的固件，请勿中断。

.flashing · 0...100
最终结果

完成升级

以最终回调而非传输进度作为升级结果。

最终升级结果以完成回调为准。

前提条件​

  • 设备已连接，并遵循 DeviceCameraOtaAPI。
  • 本地固件路径可读，且固件包与摄像头硬件匹配。
  • App 可以加入设备热点、访问本地网络，并保持本地 HTTP 服务器可用。
  • 避免媒体导入、摄像头 OTA 或其他热点流程同时运行。

使用 AI 辅助实现

使用 AI 开发

让 AI 帮助实现此工作流

使用官方“更新 AIBuds 相机固件”技能，根据你的 App 完成实现。

请阅读并遵循 https://docs-aibuds.github.io/zh-Hans/skills/update-aibuds-camera-firmware，使用该技能在当前 iOS 项目中完成“更新 AIBuds 相机固件”，并验证结果。
查看官方技能

API 参考​

框架​

AIBuds.xcframework

导入​

Swift
import AIBuds
import AIBudsFoundation

协议​

DeviceCameraOtaAPI 协议继承自 DeviceAPI，当前提供一个执行完整摄像头 OTA 流程的实例方法。

实例方法​

Swift
/// Start camera OTA upgrade.
///
/// - Parameters:
///   - filePath: The readable local path of the camera firmware file.
///   - configureHotspotStartingHandler: Called when hotspot configuration starts.
///   - hotspotConfigureCompletionHandler: Called when hotspot configuration completes.
///     - success: `true` if configuration succeeded; otherwise `false`.
///     - error: The failure information, or `nil` if configuration succeeded.
///   - enterCameraOtaModeStartingHandler: Called when entry into camera OTA mode starts.
///   - enterCameraOtaModeCompletedHandler: Called when entry into camera OTA mode completes.
///     - success: `true` if the device entered OTA mode; otherwise `false`.
///     - error: The failure information, or `nil` if entry succeeded.
///   - waitingForHotspotOpenHandler: Called while waiting for the device hotspot to open.
///   - connectDeviceHotspotStartingHandler: Called when connecting to the device hotspot starts.
///     - ssid: The SSID of the device hotspot.
///   - deviceHotspotConnectCompletionHandler: Called when the hotspot connection completes.
///     - success: `true` if the connection succeeded; otherwise `false`.
///     - error: The failure information, or `nil` if the connection succeeded.
///   - httpServerStartingHandler: Called when the local HTTP server is starting.
///   - httpServerStartCompletionHandler: Called when the HTTP server start attempt completes.
///     - success: `true` if the server started; otherwise `false`.
///     - error: The failure information, or `nil` if the server started.
///   - sendingFirmwareUrlHandler: Called before sending the firmware URL to the device.
///     - firmwareUrl: The local HTTP URL that will be sent.
///   - firmwareUrlSendCompletionHandler: Called when firmware URL delivery completes.
///     - success: `true` if the URL was sent; otherwise `false`.
///     - error: The failure information, or `nil` if delivery succeeded.
///   - startCompletionHandler: Called when the Camera OTA start command completes.
///     - success: `true` if the update started; otherwise `false`.
///     - error: The failure information, or `nil` if the update started.
///   - fileTransferStartedHandler: Called when firmware transfer starts.
///   - fileTransferCompletedHandler: Called when firmware transfer completes.
///   - waitingForFlashingHandler: Called while the device is preparing to flash.
///   - flashingStartedHandler: Called when firmware flashing starts.
///   - flashingCompletedHandler: Called when firmware flashing completes.
///   - phaseProgressHandler: Reports progress for transfer and flashing.
///     - phase: `.transferring` or `.flashing`.
///     - progress: The phase progress in the range `0...100`.
///   - completionHandler: Called when the complete Camera OTA workflow finishes.
///     - success: `true` if the upgrade succeeded; otherwise `false`.
///     - error: The failure information, or `nil` if the upgrade succeeded.
func startCameraOta(
    withFilePath filePath: String,
    configureHotspotStartingHandler: AIBudsCameraOtaConfigureHotspotStartingHandler?,
    hotspotConfigureCompletionHandler: AIBudsCameraOtaHotspotConfigureCompletionHandler?,
    enterCameraOtaModeStartingHandler: AIBudsEnterCameraOtaModeStartingHandler?,
    enterCameraOtaModeCompletedHandler: AIBudsEnterCameraOtaModeCompletionHandler?,
    waitingForHotspotOpenHandler: AIBudsCameraOtaStartingToWaitForHotspotOpenHandler?,
    connectDeviceHotspotStartingHandler: AIBudsCameraOtaConnectDeviceHotspotStartingHandler?,
    deviceHotspotConnectCompletionHandler: AIBudsCameraOtaDeviceHotspotConnectCompletionHandler?,
    httpServerStartingHandler: AIBudsCameraOtaHttpServerStartingHandler?,
    httpServerStartCompletionHandler: AIBudsCameraOtaHttpServerStartCompletionHandler?,
    sendingFirmwareUrlHandler: AIBudsCameraOtaSendingFirmwareUrlHandler?,
    firmwareUrlSendCompletionHandler: AIBudsCameraOtaFirmwareUrlSendCompletionHandler?,
    startCompletionHandler: AIBudsCameraOtaStartCompletionHandler?,
    fileTransferStartedHandler: AIBudsCameraOtaFileTransferStartedHandler?,
    fileTransferCompletedHandler: AIBudsCameraOtaFileTransferCompletedHandler?,
    waitingForFlashingHandler: AIBudsCameraOtaWaitingForFlashingHandler?,
    flashingStartedHandler: AIBudsCameraOtaFlashingStartedHandler?,
    flashingCompletedHandler: AIBudsCameraOtaFlashingCompletedHandler?,
    phaseProgressHandler: AIBudsCameraOtaPhaseProgressHandler?,
    completionHandler: AIBudsCameraOtaCompletionHandler?
)

请参阅 API Reference 中的 startCameraOta。

返回值​

此方法不直接返回值。启动、阶段切换、进度和最终结果均通过提供的处理器传递。

流程阶段​

以下是摄像头 OTA 流程的回调阶段，并不是 CameraOtaProgressPhase 的取值。

阶段相关处理器
配置热点configureHotspotStartingHandler, hotspotConfigureCompletionHandler
进入摄像头 OTA 模式enterCameraOtaModeStartingHandler, enterCameraOtaModeCompletedHandler
连接设备热点waitingForHotspotOpenHandler, connectDeviceHotspotStartingHandler, deviceHotspotConnectCompletionHandler
启动本地 HTTP 服务器httpServerStartingHandler, httpServerStartCompletionHandler
发送固件 URLsendingFirmwareUrlHandler, firmwareUrlSendCompletionHandler
启动更新startCompletionHandler
传输固件fileTransferStartedHandler, fileTransferCompletedHandler
准备并刷写waitingForFlashingHandler, flashingStartedHandler, flashingCompletedHandler
完成completionHandler

进度阶段​

CameraOtaProgressPhase 仅包含两个公开值。progress 参数为当前阶段报告的 0 至 100 整数。

SwiftObjective-C原始值含义
.transferringAIBudsCameraOtaProgressPhaseTransferring1固件文件传输进度。
.flashingAIBudsCameraOtaProgressPhaseFlashing2摄像头固件刷写进度。

使用示例​

示例保留 SDK Demo 提供的全部回调。生产代码应在主队列更新 UI。

Swift
guard let cameraOtaDevice = device as? DeviceCameraOtaAPI else {
    print("Camera OTA is not supported")
    return
}

cameraOtaDevice.startCameraOta(
    withFilePath: filePath,
    configureHotspotStartingHandler: {
        print("Configuring device hotspot")
    },
    hotspotConfigureCompletionHandler: { success, error in
        print(
            success
                ? "Hotspot configured"
                : "Hotspot configuration failed: \(error?.localizedDescription ?? "Unknown error")")
    },
    enterCameraOtaModeStartingHandler: {
        print("Entering Camera OTA mode")
    },
    enterCameraOtaModeCompletedHandler: { success, error in
        print(
            success
                ? "Camera OTA mode ready"
                : "Could not enter Camera OTA mode: \(error?.localizedDescription ?? "Unknown error")"
        )
    },
    waitingForHotspotOpenHandler: {
        print("Waiting for device hotspot")
    },
    connectDeviceHotspotStartingHandler: { ssid in
        print("Connecting to \(ssid)")
    },
    deviceHotspotConnectCompletionHandler: { success, error in
        print(
            success
                ? "Device hotspot connected"
                : "Hotspot connection failed: \(error?.localizedDescription ?? "Unknown error")")
    },
    httpServerStartingHandler: {
        print("Starting local HTTP server")
    },
    httpServerStartCompletionHandler: { success, error in
        print(
            success
                ? "HTTP server ready"
                : "HTTP server failed: \(error?.localizedDescription ?? "Unknown error")")
    },
    sendingFirmwareUrlHandler: { firmwareURL in
        print("Sending firmware URL: \(firmwareURL)")
    },
    firmwareUrlSendCompletionHandler: { success, error in
        print(
            success
                ? "Firmware URL sent"
                : "URL delivery failed: \(error?.localizedDescription ?? "Unknown error")")
    },
    startCompletionHandler: { success, error in
        print(
            success
                ? "Camera OTA started"
                : "Camera OTA could not start: \(error?.localizedDescription ?? "Unknown error")")
    },
    fileTransferStartedHandler: {
        print("Firmware transfer started")
    },
    fileTransferCompletedHandler: {
        print("Firmware transfer completed")
    },
    waitingForFlashingHandler: {
        print("Waiting for flashing")
    },
    flashingStartedHandler: {
        print("Firmware flashing started")
    },
    flashingCompletedHandler: {
        print("Firmware flashing completed")
    },
    phaseProgressHandler: { phase, progress in
        switch phase {
        case .transferring:
            print("Transfer: \(progress)%")
        case .flashing:
            print("Flashing: \(progress)%")
        }
    },
    completionHandler: { success, error in
        if success {
            print("Camera OTA completed successfully")
        } else {
            print("Camera OTA failed: \(error?.localizedDescription ?? "Unknown error")")
        }
    }
)

错误处理​

摄像头 OTA 错误使用 AIBudsSDK.CameraOtaErrorDomain 和 SdkCameraOtaErrorCode。公开枚举涵盖本地文件验证、网络或热点故障、任务生命周期故障、进入 OTA 模式失败和固件 URL 发送失败。

代码常见情况
unknown, networkRequestFailed, networkTimeoutSDK 无法进一步细分错误，或网络活动失败。
cameraOtaFileNotFound, invalidCameraOtaFile, cameraOtaTaskCreateFailedDueToFileNotFound所选本地固件路径不存在或固件包无效。
hotspotDisconnectedDuringTransfer, invalidHotspotConfig设备热点无法可靠使用。
stageTwoTimeout, interruptedByShutdownOrLowBattery刷写接近完成时停滞，或设备中断更新。
cameraOtaTaskAlreadyRunning已有另一个摄像头 OTA 任务正在运行。
4003...4009任务在设备连接、超时、热点设置、进入 OTA 模式、HTTP 服务或 URL 发送期间失败。
5001...5010设备因命令、存储、权限、通道或状态问题拒绝进入 OTA 模式或接收固件 URL。

应展示具体失败阶段，而不是笼统的更新错误。刷写开始后，不要自动重试、断开连接、关机或启动其他热点流程。SDK 当前没有规定可安全重试的时机；重新提供固件包前，应先确认设备恢复状态和摄像头固件版本。

最佳实践​

  1. 调用 API 前验证本地文件存在；固件包真实性和摄像头型号兼容性仍由宿主产品负责。
  2. 避免媒体文件导入、摄像头 OTA 或其他热点流程同时运行。
  3. 保持 App 活跃和本地 HTTP 服务器可访问，直至最终完成。
  4. 回调可能来自其他队列，因此 UI 更新应派发到主队列。
  5. 将 startCompletionHandler 视为 OTA 操作的启动结果，而不是最终升级成功。
  6. 以 completionHandler 作为最终结果，并在重新连接后验证摄像头固件状态。

注意事项​

  • 摄像头 OTA 使用本地固件路径；SDK 不查询远程更新服务，也不下载固件包。
  • phaseProgressHandler 仅报告传输和刷写进度，其他流程阶段使用各自的专用回调。
  • 传输进度达到 100 并不表示摄像头 OTA 已完成，随后仍需刷写固件并等待最终回调。
  • 公开 SDK 契约当前未定义安全的自动重试行为。