Device 펌웨어 업데이트

Device OTA updates main firmware running on 지원되는 AIBuds device. It 입니다 separate 에서 Camera OTA, which updates 기기's camera module.

호스트 앱 supplies compatible 로컬 firmware package 후에 completing its own update 확인, download, integrity verification, 및 device-model validation. SDK transfers 및 installs package, 보고서 startup 성공, streams 진행률 에서 0.0 1.0, 및 반환합니다 final upgrade result 사용해 average transfer speed. Treat startHandler 만 as confirmation OTA task started; 사용 completionHandler as authoritative final result.

Animated workflow

Device OTA delivery path

Validate product input first, then let SDK 시작, transfer, 및 complete main-펌웨어 업데이트.

호스트 앱

Validate Package

검증 integrity, firmware compatibility, 및 readable 로컬 path.

호스트 앱

확인 Battery

Compare 현재 device battery 사용해 otaBatteryLimit immediately 전에 starting.

호스트 앱

선택 Protocol

사용 default overload 또는 product-required OTA protocol 설정.

SDK

시작 OTA Task

Submit 로컬 package 및 distinguish 시작 acceptance 에서 final 성공.

SDK + device

Transfer & Install

Keep 연결 stable 동안 normalized 진행률 advances 에서 0.0 1.0.

진행률 · 0.0...1.0

Authoritative result

Final Completion

사용 성공, average transfer speed, 및 오류 에서 완료 핸들러.

successful 시작 콜백 입니다 아닌 successful 펌웨어 업데이트; wait 위한 final completion.

사전 요구 사항

기기 입니다 connected 및 conforms DeviceOtaAPI.
지원 프로토콜은 otaProtocolCapability로 확인하고 펌웨어 파일 이름으로 추측하지 마세요.
FitCloud Pro 또는 Jieli는 기기 연결 전에 해당 OTA 플러그인을 설치하고 등록하세요.
Device battery 입니다 at least otaBatteryLimit percent.
filePath points correct, complete firmware package 위한 이 device.
Keep 앱 active 및 연결 stable until completion.

AI를 활용해 구현

AI로 구현

AI로 이 워크플로 구현

공식 “AIBuds 펌웨어 업데이트” 스킬을 사용해 앱에 맞게 구현하세요.

https://docs-aibuds.github.io/ko/skills/update-aibuds-firmware을 읽고 지침을 따르세요. 이 스킬로 “AIBuds 펌웨어 업데이트”을 이 iOS 프로젝트에 구현하고 검증하세요.

공식 스킬 보기

API Reference

Framework

AIBuds.xcframework

Import

Swift
Objective-C

import AIBuds
import AIBudsFoundation

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.h>

프로토콜

Swift
Objective-C

/// The protocol for device OTA upgrade API.
protocol DeviceOtaAPI: DeviceAPI {
    /// The OTA protocol capability reported by the device.
    /// Defaults to `.abmate` when the device does not report this capability.
    var otaProtocolCapability: OtaProtocolCapability { get }

    /// OTA battery limit, 0...100, unit: percent.
    var otaBatteryLimit: Int { get }

    /// Start OTA upgrade.
    /// - Parameters:
    ///   - filePath: Upgrade file path.
    ///   - startHandler: Upgrade start callback.
    ///     - success: Whether the OTA task started successfully.
    ///     - error: Failure information, or `nil` if the task started.
    ///   - progressHandler: Upgrade progress callback.
    ///     - progress: Progress value in the range `0.0...1.0`.
    ///   - completionHandler: Final upgrade completion callback.
    ///     - success: Whether the upgrade succeeded.
    ///     - avgSpeed: Average transfer speed in kB/s.
    ///     - error: Failure information, or `nil` if the upgrade succeeded.
    func startOta(
        withFilePath filePath: String,
        startHandler: AIBudsOtaStartCompletionHandler?,
        progressHandler: AIBudsOtaProgressHandler?,
        completionHandler: AIBudsOtaCompletionHandler?
    )

    /// Start OTA upgrade with an explicit transfer protocol configuration.
    /// - Parameters:
    ///   - filePath: Upgrade file path.
    ///   - configuration: OTA protocol configuration.
    ///   - startHandler: Upgrade start callback.
    ///     - success: Whether the OTA task started successfully.
    ///     - error: Failure information, or `nil` if the task started.
    ///   - progressHandler: Upgrade progress callback.
    ///     - progress: Progress value in the range `0.0...1.0`.
    ///   - completionHandler: Final upgrade completion callback.
    ///     - success: Whether the upgrade succeeded.
    ///     - avgSpeed: Average transfer speed in kB/s.
    ///     - error: Failure information, or `nil` if the upgrade succeeded.
    func startOta(
        withFilePath filePath: String,
        configuration: OtaConfiguration,
        startHandler: AIBudsOtaStartCompletionHandler?,
        progressHandler: AIBudsOtaProgressHandler?,
        completionHandler: AIBudsOtaCompletionHandler?
    )
}

/// The protocol for device OTA upgrade API.
@protocol AIBudsDeviceOtaAPI <AIBudsDeviceAPI>
/// The OTA protocol capability reported by the device.
/// Defaults to `AIBudsOtaProtocolCapabilityAbmate` when the device does not report it.
@property(nonatomic, readonly) AIBudsOtaProtocolCapability otaProtocolCapability;

/// OTA battery limit, 0...100, unit: percent.
@property(nonatomic, readonly) NSInteger otaBatteryLimit;

/// Start OTA upgrade from a local firmware path.
///
/// - Parameters:
///   - filePath: The readable local firmware file path.
///   - startHandler: Called when the OTA start attempt completes.
///     - success: `YES` if the OTA task started; otherwise `NO`.
///     - error: Failure information, or `nil` if the task started.
///   - progressHandler: Called when OTA progress changes.
///     - progress: Progress in the range `0.0...1.0`.
///   - completionHandler: Called when the OTA operation finishes.
///     - success: `YES` if the upgrade succeeded; otherwise `NO`.
///     - avgSpeed: Average transfer speed in kB/s.
///     - error: Failure information, or `nil` if the upgrade succeeded.
- (void)startOtaWithFilePath:(NSString *_Nonnull)filePath
                startHandler:(AIBudsOtaStartCompletionHandler _Nullable)startHandler
             progressHandler:(AIBudsOtaProgressHandler _Nullable)progressHandler
           completionHandler:(AIBudsOtaCompletionHandler _Nullable)completionHandler;

/// Start OTA upgrade with an explicit transfer protocol configuration.
///
/// - Parameters:
///   - filePath: The readable local firmware file path.
///   - configuration: The OTA protocol configuration required by the device.
///   - startHandler: Called when the OTA start attempt completes.
///     - success: `YES` if the OTA task started; otherwise `NO`.
///     - error: Failure information, or `nil` if the task started.
///   - progressHandler: Called when OTA progress changes.
///     - progress: Progress in the range `0.0...1.0`.
///   - completionHandler: Called when the OTA operation finishes.
///     - success: `YES` if the upgrade succeeded; otherwise `NO`.
///     - avgSpeed: Average transfer speed in kB/s.
///     - error: Failure information, or `nil` if the upgrade succeeded.
- (void)startOtaWithFilePath:(NSString *_Nonnull)filePath
               configuration:(AIBudsOtaConfiguration *_Nonnull)configuration
                startHandler:(AIBudsOtaStartCompletionHandler _Nullable)startHandler
             progressHandler:(AIBudsOtaProgressHandler _Nullable)progressHandler
           completionHandler:(AIBudsOtaCompletionHandler _Nullable)completionHandler;
@end

API Reference에서 otaProtocolCapability, otaBatteryLimit 및 startOta overload를 참조하세요.

기기 기능

기기가 준비된 후 otaProtocolCapability를 읽어 선택 가능한 프로토콜을 제한하세요.

Swift	Objective-C	Raw value	지원 프로토콜
`.none`	`AIBudsOtaProtocolCapabilityNone`	`-1`	보고된 OTA 지원이 없습니다.
`.abmate`	`AIBudsOtaProtocolCapabilityAbmate`	`0`	ABMate. 기능이 보고되지 않을 때의 fallback이기도 합니다.
`.fitcloudPro`	`AIBudsOtaProtocolCapabilityFitcloudPro`	`1`	FitCloud Pro. FitCloud Pro 플러그인이 필요합니다.
`.abmateAndFitcloudPro`	`AIBudsOtaProtocolCapabilityAbmateAndFitcloudPro`	`2`	ABMate와 FitCloud Pro. 등록된 선택지만 표시하세요.
`.jieli`	`AIBudsOtaProtocolCapabilityJieli`	`3`	Jieli 단일 뱅크 OTA. Jieli 플러그인이 필요합니다.

OTA 설정

OtaConfiguration 은 설정 기반 overload에서 사용할 BLE OTA 프로토콜을 선택합니다. 해당 otaProtocol 속성의 기본값은 .abmate.

Swift	Objective-C	Raw value	의미
`.abmate`	`AIBudsOtaProtocolKindAbmate`	`0`	ABMate OTA 프로토콜입니다.
`.fitcloudPro`	`AIBudsOtaProtocolKindFitcloudPro`	`1`	FitCloud Pro OTA 프로토콜입니다.
`.jieli`	`AIBudsOtaProtocolKindJieli`	`2`	Jieli 단일 뱅크 OTA 프로토콜입니다.

하지 마세요 선택 protocol by guessing 에서 firmware file. 사용 protocol required by connected device 및 product integration.

선택적 OTA 플러그인

FitCloud Pro와 Jieli는 별도의 CocoaPods subspec입니다. SDK가 필요한 BLE characteristic을 찾아 subscribe할 수 있도록 기기 연결 전에 플러그인을 등록하세요. AIBudsSDK/AllInOne은 두 플러그인을 자동으로 설치하고 등록합니다.

pod 'AIBudsSDK/FitCloudProOTA'
pod 'AIBudsSDK/JieliOTA'

import AIBuds
import AIBudsFitCloudProOTA
import AIBudsJieliOTA

AIBudsSDK.registerOtaPlugin(FitCloudProOtaSDK.otaPlugin)
AIBudsSDK.registerOtaPlugin(JieliOtaSDK.otaPlugin)

모듈식 통합에서는 제품에 포함된 구현만 등록하세요. 동일한 OtaProtocolKind를 나중에 등록하면 이전 플러그인이 교체됩니다. AIBudsSDK.otaPlugin(for:)로 가용성을 확인하거나 AIBudsSDK.removeOtaPlugin(for:)로 등록을 해제하세요.

반환값

Neither overload 반환합니다 value directly. startHandler 보고서 whether OTA task started, progressHandler 보고서 normalized 진행률, 및 completionHandler 제공합니다 authoritative final result 및 average transfer speed.

사용 예제

Swift
Objective-C

guard let device = device as? DeviceOtaAPI else { return }
guard deviceBatteryPercent >= device.otaBatteryLimit else {
    print("Charge the device before updating")
    return
}

device.startOta(
    withFilePath: firmwareURL.path,
    startHandler: { success, error in
        if !success { print(error?.localizedDescription ?? "OTA failed to start") }
    },
    progressHandler: { progress in
        print("OTA: \(Int(progress * 100))%")
    },
    completionHandler: { success, averageSpeed, error in
        print(
            success
                ? "OTA completed at \(averageSpeed) kB/s"
                : (error?.localizedDescription ?? "OTA failed"))
    })

id<AIBudsDeviceOtaAPI> device = (id<AIBudsDeviceOtaAPI>)self.device;
if (![device conformsToProtocol:@protocol(AIBudsDeviceOtaAPI)])
    return;

[device startOtaWithFilePath:firmwareURL.path
    startHandler:^(BOOL success, NSError *_Nullable error) {
        if (!success)
            NSLog(@"OTA failed to start: %@", error.localizedDescription);
    }
    progressHandler:^(CGFloat progress) {
        NSLog(@"OTA: %.0f%%", progress * 100);
    }
    completionHandler:^(BOOL success, CGFloat averageSpeed, NSError *_Nullable error) {
        if (success) {
            NSLog(@"OTA completed at %.2f kB/s", averageSpeed);
        } else {
            NSLog(@"OTA failed: %@", error.localizedDescription);
        }
    }];

사용 Explicit OTA Protocol

사용 configured overload 만 때 your product integration knows which OTA protocol connected device 필요합니다.

Swift
Objective-C

let configuration = OtaConfiguration()
configuration.otaProtocol = .fitcloudPro

device.startOta(
    withFilePath: firmwareURL.path,
    configuration: configuration,
    startHandler: { success, error in
        if !success {
            print(error?.localizedDescription ?? "OTA failed to start")
        }
    },
    progressHandler: { progress in
        print("OTA: \(Int(progress * 100))%")
    },
    completionHandler: { success, averageSpeed, error in
        print(
            success
                ? "OTA completed at \(averageSpeed) kB/s"
                : (error?.localizedDescription ?? "OTA failed"))
    }
)

AIBudsOtaConfiguration *configuration = [[AIBudsOtaConfiguration alloc] init];
configuration.otaProtocol = AIBudsOtaProtocolKindFitcloudPro;

[device startOtaWithFilePath:firmwareURL.path
    configuration:configuration
    startHandler:^(BOOL success, NSError *_Nullable error) {
        if (!success)
            NSLog(@"OTA failed to start: %@", error.localizedDescription);
    }
    progressHandler:^(CGFloat progress) {
        NSLog(@"OTA: %.0f%%", progress * 100);
    }
    completionHandler:^(BOOL success, CGFloat averageSpeed, NSError *_Nullable error) {
        if (success) {
            NSLog(@"OTA completed at %.2f kB/s", averageSpeed);
        } else {
            NSLog(@"OTA failed: %@", error.localizedDescription);
        }
    }];

오류 처리

OTA 오류 사용 AIBudsSDK.OtaErrorDomain 및 SdkOtaErrorCode.

코드	일반적인 상황
`unknown`	SDK cannot classify 오류 more narrowly.
`otaTaskAlreadyRunning`	Another OTA task 입니다 already active.
`otaTaskCreateFailedDueToFileNotFound`	로컬 firmware path 하지 않습니다 exist.
`otaTaskStartFailedDueToFileReadError`, `otaTaskStartFailedDueToFileHandleCreateError`	package cannot be opened 또는 읽기.
`otaTaskStartFailedDueToInvalidFileHashData`	Firmware hash data 입니다 invalid.
`otaTaskStartFailedDueToGetOtaInfoError`	필수 OTA 메타데이터를 가져올 수 없습니다.
`otaTaskStartFailedDueToInvalidOffsetAddress`, `otaTaskStartFailedDueToInvalidBlockSize`	Transfer metadata 입니다 invalid.
`otaTaskStartFailedDueToNotAllowUpdate`	기기 하지 않습니다 allow update 에서 its 현재 state.
`otaTaskSendDataFailedDueToFileHandleIsNil`, `otaTaskSendDataFailedDueToSeekFileHandleFailed`, `otaTaskSendDataFailedDueToReadFileDataFailed`, `otaTaskSendDataFailedDueToOtaInfoIsNil`	SDK cannot continue reading 또는 sending firmware data.
`otaTaskFailedDueToDeviceReportKeyMismatch`, `otaTaskFailedDueToDeviceReportCrcError`, `otaTaskFailedDueToDeviceReportSeqError`, `otaTaskFailedDueToDeviceReportDataLengthError`	기기 rejects transferred data 또는 보고서 integrity/sequence problem.
`otaTaskFailedDueToDeviceDisconnect`, `otaTaskFailedDueToTimeout`	기기 disconnects 또는 operation times out.

Distinguish startHandler 실패 에서 실패 후에 transfer begins. 하지 마세요 재시도 automatically 사용해 unverified package; revalidate 기기 모델, 펌웨어 버전, package integrity, battery, protocol selection, 및 연결 first.

권장 사항

Complete update discovery, download, signature 또는 integrity verification, 및 device-model compatibility checks 전에 calling SDK.
확인 otaBatteryLimit immediately 전에 starting, 아닌 만 때 presenting update UI.
Prevent concurrent OTA, Camera OTA, 미디어 파일 Import, 또는 other long-running device operations.
Dispatch UI updates 메인 큐 because 콜백 may arrive on another queue.
Treat startHandler as task-시작 confirmation 만; 하지 마세요 보고서 upgrade 성공 until completionHandler succeeds.
Keep 앱 active 및 기기 연결 stable 통해 final completion, then 검증 reported 펌웨어 버전 후에 reconnecting.

참고

진행률 입니다 normalized 0.0...1.0; clamp UI presentation defensively 없이 changing SDK result.
avgSpeed 입니다 reported 에서 kB/s 만 by final 완료 핸들러.
OtaConfiguration.otaProtocol의 기본값은 .abmate입니다. .fitcloudPro 또는 .jieli는 otaProtocolCapability와 설치된 플러그인이 지원할 때만 선택하세요.
SDK 하지 않습니다 expose OTA cancellation method. Demo's 취소 button resets its 로컬 UI state 및 반드시 아닌 be documented as cancelling SDK operation.

Validate Package

확인 Battery

선택 Protocol

시작 OTA Task

Transfer & Install

Final Completion

사전 요구 사항​

AI를 활용해 구현

API Reference​

Framework​

Import​

프로토콜​

기기 기능​

OTA 설정​

선택적 OTA 플러그인​

반환값​

사용 예제​

사용 Explicit OTA Protocol​

오류 처리​

권장 사항​

참고​

사전 요구 사항

API Reference

Framework

Import

프로토콜

기기 기능

OTA 설정

선택적 OTA 플러그인

반환값

사용 예제

사용 Explicit OTA Protocol

오류 처리

권장 사항

참고