Cihaz Firmware Güncellemesi

Cihaz OTA, desteklenen AIBuds cihazındaki ana firmware’i günceller. Cihazın kamera modülünü güncelleyen Camera OTA’dan ayrı bir işlemdir.

Ana uygulama güncelleme kontrolünü, indirmeyi, bütünlük doğrulamasını ve cihaz modeli uyumluluk denetimini tamamladıktan sonra uyumlu yerel firmware paketini sağlar. SDK paketi aktarır ve kurar, başlangıç sonucunu bildirir, 0.0 ile 1.0 arasındaki ilerlemeyi iletir ve nihai güncelleme sonucunu ortalama aktarım hızıyla birlikte döndürür. startHandler yalnızca OTA görevinin başladığını doğrular; kesin sonuç için completionHandler kullanın.

Animated workflow

Cihaz OTA aktarım akışı

Önce ürün girdisini doğrulayın; ardından ana firmware güncellemesini başlatma, aktarma ve tamamlama işini SDK’ya bırakın.

01Ana uygulama

H

Paketi Doğrula

Bütünlüğü, firmware uyumluluğunu ve yerel yolun okunabilirliğini doğrulayın.

02Ana uygulama

H

Pili Denetle

Başlatmadan hemen önce geçerli cihaz pilini otaBatteryLimit ile karşılaştırın.

03Ana uygulama

H

Protokolü Seç

Varsayılan overload’u veya ürünün gerektirdiği OTA protokol yapılandırmasını kullanın.

04SDK

S

OTA Görevini Başlat

Yerel paketi gönderin; başlangıcın kabul edilmesiyle nihai başarıyı birbirinden ayırın.

05SDK + cihaz

%

Aktar ve Kur

Normalize edilmiş ilerleme 0.0’dan 1.0’a giderken bağlantıyı kararlı tutun.

ilerleme · 0.0...1.0

06Kesin sonuç

✓

Nihai Tamamlanma

Completion işleyicisindeki başarı, ortalama aktarım hızı ve hata değerlerini kullanın.

↳Başlangıç callback’inin başarılı olması firmware güncellemesinin tamamlandığı anlamına gelmez; nihai completion callback’ini bekleyin.

Ön Koşullar

• Cihaz bağlıdır ve DeviceOtaAPI protokolüne uyar.
• Desteklenen protokolü otaProtocolCapability ile belirleyin; firmware dosya adından tahmin etmeyin.
• FitCloud Pro veya Jieli için cihazı bağlamadan önce eşleşen OTA eklentisini yükleyip kaydedin.
• Cihaz pili en az yüzde otaBatteryLimit düzeyindedir.
• filePath, bu cihaza ait doğru ve eksiksiz firmware paketini gösterir.
• İşlem tamamlanana kadar uygulamayı etkin, bağlantıyı kararlı tutun.

AI desteğiyle uygulayın

AI ile geliştirin

Bu iş akışını AI ile uygulayın

Resmî “AIBuds Ürün Yazılımını Güncelleme” becerisini kullanarak iş akışını uygulamanıza uyarlayın.

https://docs-aibuds.github.io/tr/skills/update-aibuds-firmware adresini okuyup yönergeleri izleyin. Bu beceriyle “AIBuds Ürün Yazılımını Güncelleme” iş akışını iOS projesinde uygulayıp doğrulayın.

Resmî beceriyi görüntüle↗

API Referansı

Framework

AIBuds.xcframework

İçe Aktarma

Swift

Swift

import AIBuds
import AIBudsFoundation

Objective-C

Objective-C

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

Protokol

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 Referansındaki otaProtocolCapability, otaBatteryLimit öğelerine ve startOta overload’larına bakın.

Cihaz Yeteneği

Cihaz hazır olduktan sonra otaProtocolCapability değerini okuyun ve seçilebilir protokolleri bununla sınırlayın.

Swift	Objective-C	Ham değer	Desteklenen protokol
.none	AIBudsOtaProtocolCapabilityNone	-1	Bildirilen OTA desteği yoktur.
.abmate	AIBudsOtaProtocolCapabilityAbmate	0	ABMate. Yetenek bildirilmediğinde de fallback olarak kullanılır.
.fitcloudPro	AIBudsOtaProtocolCapabilityFitcloudPro	1	FitCloud Pro. FitCloud Pro eklentisi gerekir.
.abmateAndFitcloudPro	AIBudsOtaProtocolCapabilityAbmateAndFitcloudPro	2	ABMate ve FitCloud Pro; yalnızca kayıtlı seçenekleri gösterin.
.jieli	AIBudsOtaProtocolCapabilityJieli	3	Jieli tek bankalı OTA. Jieli eklentisi gerekir.

OTA Yapılandırması

OtaConfiguration, yapılandırılmış overload’un kullandığı BLE OTA protokolünü seçer. otaProtocol özelliğinin varsayılanı .abmate değeridir.

Swift	Objective-C	Ham değer	Anlamı
.abmate	AIBudsOtaProtocolKindAbmate	0	ABMate OTA protokolü.
.fitcloudPro	AIBudsOtaProtocolKindFitcloudPro	1	FitCloud Pro OTA protokolü.
.jieli	AIBudsOtaProtocolKindJieli	2	Jieli tek bankalı OTA protokolü.

Protokolü firmware dosyasından tahmin ederek seçmeyin. Bağlı cihazın ve ürün entegrasyonunun gerektirdiği protokolü kullanın.

İsteğe Bağlı OTA Eklentileri

FitCloud Pro ve Jieli ayrı CocoaPods subspec'leridir. SDK'nın gerekli BLE characteristic'lerini keşfedip subscribe olabilmesi için cihazı bağlamadan önce eklentileri kaydedin. AIBudsSDK/AllInOne her ikisini de otomatik olarak yükleyip kaydeder.

Ruby

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

Swift

import AIBuds
import AIBudsFitCloudProOTA
import AIBudsJieliOTA

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

Modüler entegrasyonda yalnızca ürününüzün sunduğu uygulamaları kaydedin. Aynı OtaProtocolKind için sonraki bir kayıt önceki eklentinin yerini alır. Kullanılabilirliği AIBudsSDK.otaPlugin(for:) ile denetleyin veya kaydı kaldırmak için AIBudsSDK.removeOtaPlugin(for:) kullanın.

Dönüş Değeri

Overload’ların hiçbiri doğrudan değer döndürmez. startHandler OTA görevinin başlayıp başlamadığını, progressHandler normalize edilmiş ilerlemeyi bildirir; completionHandler ise kesin sonuçla ortalama aktarım hızını sağlar.

Kullanım Örnekleri

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

Açık Bir OTA Protokolü Kullanma

Yapılandırılmış overload’u yalnızca ürün entegrasyonunuz bağlı cihazın hangi OTA protokolünü gerektirdiğini biliyorsa kullanın.

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

Hata Yönetimi

OTA hataları AIBudsSDK.OtaErrorDomain ile SdkOtaErrorCode kullanır.

Kodlar	Tipik durum
unknown	SDK hatayı daha ayrıntılı sınıflandıramaz.
otaTaskAlreadyRunning	Başka bir OTA görevi zaten etkindir.
otaTaskCreateFailedDueToFileNotFound	Yerel firmware yolu mevcut değildir.
otaTaskStartFailedDueToFileReadError, otaTaskStartFailedDueToFileHandleCreateError	Paket açılamaz veya okunamaz.
otaTaskStartFailedDueToInvalidFileHashData	Firmware hash verisi geçersizdir.
otaTaskStartFailedDueToGetOtaInfoError	Gerekli OTA meta verileri alınamaz.
otaTaskStartFailedDueToInvalidOffsetAddress, otaTaskStartFailedDueToInvalidBlockSize	Aktarım meta verileri geçersizdir.
otaTaskStartFailedDueToNotAllowUpdate	Cihaz geçerli durumunda güncellemeye izin vermez.
otaTaskSendDataFailedDueToFileHandleIsNil, otaTaskSendDataFailedDueToSeekFileHandleFailed, otaTaskSendDataFailedDueToReadFileDataFailed, otaTaskSendDataFailedDueToOtaInfoIsNil	SDK firmware verilerini okumaya veya göndermeye devam edemez.
otaTaskFailedDueToDeviceReportKeyMismatch, otaTaskFailedDueToDeviceReportCrcError, otaTaskFailedDueToDeviceReportSeqError, otaTaskFailedDueToDeviceReportDataLengthError	Cihaz aktarılan veriyi reddeder veya bütünlük/sıra sorunu bildirir.
otaTaskFailedDueToDeviceDisconnect, otaTaskFailedDueToTimeout	Cihazın bağlantısı kesilir veya işlem zaman aşımına uğrar.

startHandler hatasıyla aktarım başladıktan sonraki hatayı ayırın. Doğrulanmamış paketle otomatik yeniden denemeyin; önce cihaz modelini, firmware sürümünü, paket bütünlüğünü, pili, protokol seçimini ve bağlantıyı yeniden doğrulayın.

En İyi Uygulamalar

1. SDK’yı çağırmadan önce güncelleme bulma, indirme, imza veya bütünlük doğrulaması ve cihaz modeli uyumluluk denetimlerini tamamlayın.
2. otaBatteryLimit değerini yalnızca güncelleme arayüzünü gösterirken değil, başlatmadan hemen önce denetleyin.
3. OTA, Camera OTA, Media File Import veya uzun süren diğer cihaz işlemlerinin eşzamanlı çalışmasını önleyin.
4. Callback’ler başka bir kuyruktan gelebileceği için kullanıcı arayüzü güncellemelerini ana kuyruğa yönlendirin.
5. startHandler değerini yalnızca görevin başladığına dair onay olarak değerlendirin; completionHandler başarılı olmadan güncelleme başarısı bildirmeyin.
6. Nihai tamamlanmaya kadar uygulamayı etkin, cihaz bağlantısını kararlı tutun; yeniden bağlandıktan sonra bildirilen firmware sürümünü doğrulayın.

Notlar

• İlerleme 0.0...1.0 aralığına normalize edilmiştir; SDK sonucunu değiştirmeden arayüzdeki gösterimi güvenli biçimde sınırlandırın.
• avgSpeed, yalnızca nihai completion işleyicisi tarafından kB/s cinsinden bildirilir.
• OtaConfiguration.otaProtocol varsayılan olarak .abmate kullanır; .fitcloudPro veya .jieli değerini yalnızca otaProtocolCapability ve yüklü eklenti desteklediğinde seçin.
• SDK, OTA iptal yöntemi sunmaz. Demo’daki İptal düğmesi yalnızca yerel kullanıcı arayüzü durumunu sıfırlar; SDK işlemini iptal ediyormuş gibi belgelenmemelidir.