Device firmware update

Device OTA supported AIBuds device का main firmware update करता है। यह Camera OTA से अलग है, जो device का camera module update करता है।

Host app update check, download, integrity verification और device-model validation पूरा करके compatible local firmware package देता है। SDK package transfer और install करता है, startup result बताता है, 0.0 से 1.0 तक progress देता है और average transfer speed के साथ final result लौटाता है। startHandler केवल task शुरू होने की पुष्टि है; authoritative final result के लिए completionHandler उपयोग करें।

Animated workflow

Device OTA delivery path

Validate the product input first, then let the SDK start, transfer, and complete the main-firmware update.

01Host app

H

Validate Package

Verify integrity, firmware compatibility, and the readable local path.

02Host app

H

Check Battery

Compare the current device battery with otaBatteryLimit immediately before starting.

03Host app

H

Select Protocol

Use the default overload or the product-required OTA protocol configuration.

04SDK

S

Start OTA Task

Submit the local package and distinguish start acceptance from final success.

05SDK + device

%

Transfer & Install

Keep the connection stable while normalized progress advances from 0.0 to 1.0.

progress · 0.0...1.0

06Authoritative result

✓

Final Completion

Use success, average transfer speed, and error from the completion handler.

↳A successful start callback is not a successful firmware update; wait for final completion.

आवश्यक शर्तें

• Device connected हो और DeviceOtaAPI conform करता हो।
• समर्थित protocol तय करने के लिए otaProtocolCapability का उपयोग करें; firmware filename से अनुमान न लगाएँ।
• FitCloud Pro या Jieli के लिए डिवाइस connect करने से पहले matching OTA plugin install और register करें।
• Device battery कम-से-कम otaBatteryLimit percent हो।
• filePath इस device के सही और पूरे firmware package को point करता हो।
• Completion तक app active और connection stable रखें।

AI की सहायता से लागू करें

AI से बनाएँ

इस वर्कफ़्लो को AI से लागू करें

आधिकारिक “AIBuds फ़र्मवेयर अपडेट करें” स्किल से वर्कफ़्लो को अपने ऐप के अनुसार लागू करें।

https://docs-aibuds.github.io/hi/skills/update-aibuds-firmware को पढ़ें और निर्देशों का पालन करें। इस स्किल से “AIBuds फ़र्मवेयर अपडेट करें” को इस iOS प्रोजेक्ट में लागू करें और परिणाम सत्यापित करें।

आधिकारिक स्किल देखें↗

API Reference

Framework

AIBuds.xcframework

Import

Swift

Swift

import AIBuds
import AIBudsFoundation

Objective-C

Objective-C

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

Protocol की घोषणा

Swift

Swift

/// 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?
    )
}

Objective-C

Objective-C

/// 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 overloads देखें।

डिवाइस क्षमता

डिवाइस ready होने के बाद otaProtocolCapability पढ़ें और selectable protocols को इसके अनुसार सीमित करें।

Swift	Objective-C	Raw value	समर्थित protocol
.none	AIBudsOtaProtocolCapabilityNone	-1	OTA support report नहीं हुआ।
.abmate	AIBudsOtaProtocolCapabilityAbmate	0	ABMate। Capability report न होने पर यह fallback भी है।
.fitcloudPro	AIBudsOtaProtocolCapabilityFitcloudPro	1	FitCloud Pro। FitCloud Pro plugin आवश्यक है।
.abmateAndFitcloudPro	AIBudsOtaProtocolCapabilityAbmateAndFitcloudPro	2	ABMate और FitCloud Pro; केवल registered choices दिखाएँ।
.jieli	AIBudsOtaProtocolCapabilityJieli	3	Jieli single-bank OTA। Jieli plugin आवश्यक है।

OTA configuration

OtaConfiguration configured overload का BLE OTA protocol चुनता है। इसकी otaProtocol property default रूप से .abmate है।

Swift	Objective-C	Raw value	अर्थ
.abmate	AIBudsOtaProtocolKindAbmate	0	ABMate OTA protocol।
.fitcloudPro	AIBudsOtaProtocolKindFitcloudPro	1	FitCloud Pro OTA protocol।
.jieli	AIBudsOtaProtocolKindJieli	2	Jieli single-bank OTA protocol।

Firmware file देखकर protocol का अनुमान न लगाएँ। Connected device और product integration द्वारा required protocol उपयोग करें।

वैकल्पिक OTA Plugins

FitCloud Pro और Jieli अलग CocoaPods subspecs हैं। SDK आवश्यक BLE characteristics discover और subscribe कर सके, इसके लिए डिवाइस connect करने से पहले plugins register करें। AIBudsSDK/AllInOne दोनों को अपने-आप install और register करता है।

Ruby

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

Swift

import AIBuds
import AIBudsFitCloudProOTA
import AIBudsJieliOTA

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

Modular integration में केवल वही implementations register करें जो product उपलब्ध कराता है। समान OtaProtocolKind के लिए बाद का registration पिछले plugin को replace कर देता है। Availability जाँचने के लिए AIBudsSDK.otaPlugin(for:) या unregister करने के लिए AIBudsSDK.removeOtaPlugin(for:) उपयोग करें।

Return value

कोई overload सीधे value return नहीं करता। startHandler task शुरू होने, progressHandler normalized progress और completionHandler authoritative final result व average transfer speed देता है।

उपयोग के उदाहरण

Swift

Swift

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"))
    })

Objective-C

Objective-C

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);
        }
    }];

OTA protocol स्पष्ट रूप से चुनें

Configured overload तभी उपयोग करें जब product integration को connected device का required OTA protocol पता हो।

Swift

Swift

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"))
    }
)

Objective-C

Objective-C

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);
        }
    }];

Error handling

OTA errors AIBudsSDK.OtaErrorDomain और SdkOtaErrorCode उपयोग करते हैं।

Codes	सामान्य कारण
unknown	SDK error को अधिक स्पष्ट category में नहीं रख सकता।
otaTaskAlreadyRunning	दूसरा OTA task पहले से active है।
otaTaskCreateFailedDueToFileNotFound	Local firmware path मौजूद नहीं है।
otaTaskStartFailedDueToFileReadError, otaTaskStartFailedDueToFileHandleCreateError	Package खोला या पढ़ा नहीं जा सकता।
otaTaskStartFailedDueToInvalidFileHashData	Firmware hash data invalid है।
otaTaskStartFailedDueToGetOtaInfoError	Required OTA metadata नहीं मिल पाया।
otaTaskStartFailedDueToInvalidOffsetAddress, otaTaskStartFailedDueToInvalidBlockSize	Transfer metadata invalid है।
otaTaskStartFailedDueToNotAllowUpdate	Device की मौजूदा state update allow नहीं करती।
otaTaskSendDataFailedDueToFileHandleIsNil, otaTaskSendDataFailedDueToSeekFileHandleFailed, otaTaskSendDataFailedDueToReadFileDataFailed, otaTaskSendDataFailedDueToOtaInfoIsNil	SDK firmware data पढ़ना या भेजना जारी नहीं रख सकता।
otaTaskFailedDueToDeviceReportKeyMismatch, otaTaskFailedDueToDeviceReportCrcError, otaTaskFailedDueToDeviceReportSeqError, otaTaskFailedDueToDeviceReportDataLengthError	Device transferred data reject करता है या integrity/sequence problem report करता है।
otaTaskFailedDueToDeviceDisconnect, otaTaskFailedDueToTimeout	Device disconnect हुआ या operation timeout हुआ।

startHandler failure को transfer शुरू होने के बाद की failure से अलग रखें। Unverified package से automatic retry न करें; पहले device model, firmware version, package integrity, battery, protocol selection और connection फिर validate करें।

बेहतर तरीके

1. SDK call करने से पहले update discovery, download, signature या integrity verification और device-model compatibility checks पूरे करें।
2. otaBatteryLimit शुरू करने के तुरंत पहले जाँचें, केवल update UI दिखाते समय नहीं।
3. OTA, Camera OTA, Media File Import या अन्य long-running device operations साथ न चलने दें।
4. Callbacks दूसरी queue पर आ सकते हैं, इसलिए UI updates main queue पर dispatch करें।
5. startHandler को केवल task-start confirmation मानें; completionHandler सफल होने से पहले upgrade success न दिखाएँ।
6. Final completion तक app active और device connection stable रखें, फिर reconnect होने पर reported firmware version verify करें।

ध्यान देने योग्य बातें

• Progress 0.0...1.0 में normalized है; SDK result बदले बिना UI presentation को defensively clamp करें।
• avgSpeed केवल final completion handler में kB/s में मिलता है।
• OtaConfiguration.otaProtocol default रूप से .abmate है; .fitcloudPro या .jieli केवल तभी चुनें जब otaProtocolCapability और installed plugin support करें।
• SDK OTA cancellation method expose नहीं करता। Demo का Cancel button केवल local UI state reset करता है; इसे SDK operation cancel करना न बताएँ।