Skip to content

Core Device Info Details

Jump to bottom
Mr.P edited this page Aug 30, 2026 · 4 revisions

Get Device Details

Read the information currently available on an AIBuds device. Device details are exposed as properties on the device object; there is no single getDeviceDetails request or DeviceDetails result model.

Use DeviceConvertible for identity, firmware, connection, and advertisement information. If the device also conforms to DeviceInfoAPI, you can read its battery status, reported capabilities, hardware configuration, language setting, call status, storage information, and media counts.

Prerequisites

Before reading device details:

  • Obtain a DeviceConvertible instance from your scan, stored-device, or connection flow.
  • Wait until the device is connected and ready when you need the latest device-reported values.
  • Treat optional properties as unavailable until the SDK or device has supplied them.

Current snapshot

Reading these properties does not send a Bluetooth command. The values represent the SDK's current snapshot and may come from discovery data, persisted device data, or information received during the active connection.

API Reference

Framework

AIBuds.xcframework

Import

In the files where you want to use the SDK, import the main framework:

Swift

import AIBuds

Objective-C

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

Protocol

Device details are exposed by two protocols. DeviceConvertible provides the base device snapshot. DeviceInfoAPI provides additional device-information properties when the connected device supports that protocol.

Swift

/// Defines the persistent identity and capabilities of an AIBuds device.
protocol DeviceConvertible: NSObjectProtocol, NSSecureCoding

/// The protocol for device information related API.
protocol DeviceInfoAPI: DeviceAPI

Objective-C

/// Defines the persistent identity and capabilities of an AIBuds device.
@protocol AIBudsDeviceConvertible <NSSecureCoding, NSObject>

/// The protocol for device information related API.
@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>

Properties

Base device properties

These properties are available through DeviceConvertible.

Category Properties Notes
Identity name, uuid, bluetoothName, macAddress, product The device name and identifiers currently known to the SDK.
Hardware deviceModel, deviceSerialNum, formatedProjNumber Optional values reported by supported devices.
Firmware firmwareVersion, formatedFirmwareVersion, coProcessorFirmwareVersion formatedFirmwareVersion is the display-oriented main firmware string used by the Demo.
Connection connectionState, deviceState, isConnectedAndReady, isBusy, lastConnectTime Use isConnectedAndReady before relying on live device state.
Binding bindUserId, userBindTime, isAlreadyUnbind, shouldAutoReconnectWhenAppLaunch Binding and reconnection state maintained by the SDK.
Advertisement advertisementDataString, advertisementRawData, manufacturerData, manufacturerHexDataString, timestampOfAdvertisementData Values derived from the most recently received advertisement data.
Presentation thumbnail, screenName, customContent Optional values that can be used by the host application UI.

Device information properties

After confirming conformance to DeviceInfoAPI, the following additional snapshot values are available.

Property Type Description
batteryStatusInfo BatteryStatusModel? Real-time information for the device's battery components.
deviceCapabilities DeviceCapabilities? Normalized feature flags reported by the device, or nil until valid capability information is received.
hardwareConfiguration DeviceHardwareConfiguration Physical input hardware and on-device guidance requirements reported for the device.
languageSetting DeviceLanguage The current device language.
supportedLanguages [NSNumber] Raw DeviceLanguage values supported by the device.
callStatus CallStatus The current call status.
storageInfo StorageInfoModel? Used and free storage values, in MB.
mediaCountInfo MediaCountInfoModel? Photo, video, and audio file counts.
isSupportAdjustRecordDuration Bool Whether maximum recording duration can be configured.
aiSolutionCapabilities AIBudsAISolutionCapabilities AI capabilities reported for the device.
coprocessorModel CoprocessorModel The device's co-processor model.
imageEnhancementPostProcessingAlgorithm ImageEnhancementPostProcessingAlgorithm Image-enhancement algorithm currently reported by the device; defaults to .general.
recommendedMaxVideoRecordingDurationOptions [NSNumber] Device-recommended maximum video-recording duration options in minutes; defaults to [1, 3, 9, 12].
recommendedMaxAudioRecordingDurationOptions [NSNumber] Device-recommended maximum audio-recording duration options in minutes; defaults to [30, 60, 120].
minimumBatteryLevelForMediaOperations Int Minimum battery percentage for photo, video, audio, and file-transfer operations; defaults to 30. OTA uses separate rules.

Common status values

batteryStatusInfo may contain any component supported by the product:

BatteryComponent Meaning
.glass Glasses body
.leftEarbud / .rightEarbud Left or right earbud
.chargingCase Charging case
.mainSpeaker / .sideSpeaker Main or side speaker
.headphones Over-ear headphones
.unknown Component is unavailable or unrecognized

Use the fields on deviceCapabilities to decide whether to expose TWS, spatial audio, multipoint, ANC, the on-device voice assistant, bass engine, live streaming, Ximalaya, or the factory-test chirp. Do not infer these features from product alone. A nil value means that the SDK has not received valid capability information; it does not mean that every feature is unsupported.

hardwareConfiguration describes how the product can be operated:

Property Meaning
hasTouchInput The device has a touch input surface.
hasPhysicalButtonInput The device has physical button input.
requiresOnDeviceVoiceAssistantGuidance The host app should provide guidance for using the on-device voice assistant.

callStatus uses CallStatus:

Value Meaning
.notInCall No call is active.
.ringing An incoming call is ringing.
.inCall A call is active.
.threeWayRinging A three-way call is ringing, when supported.
.aiChat The device reports an AI conversation as its current call-channel activity.
.unknown Call state is unavailable or unrecognized.

Usage Examples

Read Device Details

The following examples follow the same approach as the SDK Demo's DeviceInfoDetailsController: read the base device properties first, then conditionally include DeviceInfoAPI properties.

Swift

import AIBuds

typealias DeviceDetail = (label: String, value: String)

func formattedDate(_ date: Date?, unavailable: String) -> String {
    guard let date else { return unavailable }

    let formatter = DateFormatter()
    formatter.dateStyle = .medium
    formatter.timeStyle = .medium
    return formatter.string(from: date)
}

func deviceDetails(for device: DeviceConvertible) -> [DeviceDetail] {
    let unavailable = "N/A"
    var details: [DeviceDetail] = [
        ("Device Name", device.name),
        ("UUID", device.uuid.uuidString),
        ("Bluetooth Name", device.bluetoothName ?? unavailable),
        ("MAC Address", device.macAddress ?? unavailable),
        ("Product", String(describing: device.product)),
        ("Device Model", device.deviceModel ?? unavailable),
        ("Serial Number", device.deviceSerialNum ?? unavailable),
        ("Firmware Version", device.formatedFirmwareVersion ?? unavailable),
        ("Co-processor Firmware", device.coProcessorFirmwareVersion ?? unavailable),
        ("Project Number", device.formatedProjNumber ?? unavailable),
        ("Last Connection", formattedDate(device.lastConnectTime, unavailable: unavailable)),
        ("Auto Reconnect", device.shouldAutoReconnectWhenAppLaunch ? "Yes" : "No"),
        ("Advertisement Data", device.advertisementDataString ?? unavailable),
        ("Manufacturer Data", device.manufacturerHexDataString ?? unavailable),
        (
            "Advertisement Timestamp",
            formattedDate(device.timestampOfAdvertisementData, unavailable: unavailable)
        ),
        ("Screen Name", device.screenName ?? unavailable),
        ("Custom Content", device.customContent ?? unavailable),
    ]

    guard let info = device as? DeviceInfoAPI else {
        return details
    }

    let supportedLanguages = info.supportedLanguages
        .compactMap { DeviceLanguage(rawValue: $0.intValue) }
        .map { String(describing: $0) }
        .joined(separator: ", ")

    details.append(contentsOf: [
        ("Battery Status", info.batteryStatusInfo?.description ?? unavailable),
        ("Device Capabilities", info.deviceCapabilities?.description ?? unavailable),
        ("Hardware Configuration", info.hardwareConfiguration.description),
        ("Language", String(describing: info.languageSetting)),
        ("Supported Languages", supportedLanguages.isEmpty ? unavailable : supportedLanguages),
        ("Call Status", String(describing: info.callStatus)),
        ("Storage", info.storageInfo?.description ?? unavailable),
        ("Media Count", info.mediaCountInfo?.description ?? unavailable),
        ("Adjustable Recording Duration", info.isSupportAdjustRecordDuration ? "Yes" : "No"),
        ("AI Capabilities", String(describing: info.aiSolutionCapabilities)),
        ("Co-processor Model", String(describing: info.coprocessorModel)),
        (
            "Image Enhancement",
            String(describing: info.imageEnhancementPostProcessingAlgorithm)
        ),
        ("Recommended Video Duration Options", info.recommendedMaxVideoRecordingDurationOptions.description),
        ("Recommended Audio Duration Options", info.recommendedMaxAudioRecordingDurationOptions.description),
        ("Minimum Media Battery", "\(info.minimumBatteryLevelForMediaOperations)%"),
    ])

    return details
}

Objective-C

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

- (NSArray<NSDictionary<NSString *, NSString *> *> *)deviceDetailsForDevice:
    (id<AIBudsDeviceConvertible>)device {
    NSString *unavailable = @"N/A";
    NSMutableArray<NSDictionary<NSString *, NSString *> *> *details = [NSMutableArray array];

    void (^addDetail)(NSString *, id _Nullable) = ^(NSString *label, id _Nullable value) {
        [details addObject:@{
            @"label" : label,
            @"value" : value ? [value description] : unavailable,
        }];
    };

    addDetail(@"Device Name", device.name);
    addDetail(@"UUID", device.uuid.UUIDString);
    addDetail(@"Bluetooth Name", device.bluetoothName);
    addDetail(@"MAC Address", device.macAddress);
    addDetail(@"Product", @(device.product));
    addDetail(@"Device Model", device.deviceModel);
    addDetail(@"Serial Number", device.deviceSerialNum);
    addDetail(@"Firmware Version", device.formatedFirmwareVersion);
    addDetail(@"Co-processor Firmware", device.coProcessorFirmwareVersion);
    addDetail(@"Project Number", device.formatedProjNumber);
    addDetail(@"Last Connection", device.lastConnectTime);
    addDetail(@"Auto Reconnect", device.shouldAutoReconnectWhenAppLaunch ? @"Yes" : @"No");
    addDetail(@"Advertisement Data", device.advertisementDataString);
    addDetail(@"Manufacturer Data", device.manufacturerHexDataString);
    addDetail(@"Advertisement Timestamp", device.timestampOfAdvertisementData);
    addDetail(@"Screen Name", device.screenName);
    addDetail(@"Custom Content", device.customContent);

    id<AIBudsDeviceInfoAPI> info = (id<AIBudsDeviceInfoAPI>)device;
    if ([info conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
        addDetail(@"Battery Status", info.batteryStatusInfo);
        addDetail(@"Device Capabilities", info.deviceCapabilities);
        addDetail(@"Hardware Configuration", info.hardwareConfiguration);
        addDetail(@"Language", @(info.languageSetting));
        addDetail(@"Supported Languages", info.supportedLanguages);
        addDetail(@"Call Status", @(info.callStatus));
        addDetail(@"Storage", info.storageInfo);
        addDetail(@"Media Count", info.mediaCountInfo);
        addDetail(@"Adjustable Recording Duration",
                  info.isSupportAdjustRecordDuration ? @"Yes" : @"No");
        addDetail(@"AI Capabilities", @(info.aiSolutionCapabilities));
        addDetail(@"Co-processor Model", @(info.coprocessorModel));
        addDetail(@"Image Enhancement", @(info.imageEnhancementPostProcessingAlgorithm));
        addDetail(@"Recommended Video Duration Options", info.recommendedMaxVideoRecordingDurationOptions);
        addDetail(@"Recommended Audio Duration Options", info.recommendedMaxAudioRecordingDurationOptions);
        addDetail(@"Minimum Media Battery",
                  [NSString stringWithFormat:@"%ld%%",
                                             (long)info.minimumBatteryLevelForMediaOperations]);
    }

    return details;
}

Render the returned rows using your application's own view model and localization. The Demo uses a table view and converts enum values into localized display strings.

Refresh Storage or Media Information

storageInfo and mediaCountInfo are snapshot properties. If your screen requires a fresh value, request an update first and then read the corresponding property after the operation succeeds.

Swift

guard let info = device as? DeviceInfoAPI else { return }

info.requestQueryStorageInfo { success, error in
    guard success else {
        print(error?.localizedDescription ?? "Storage query failed")
        return
    }

    print(info.storageInfo?.description ?? "Storage information is unavailable")
}

Objective-C

id<AIBudsDeviceInfoAPI> info = (id<AIBudsDeviceInfoAPI>)self.device;
if ([info conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
    [info requestQueryStorageInfoWithCompletion:^(BOOL success, NSError *_Nullable error) {
        if (!success) {
            NSLog(@"Storage query failed: %@", error.localizedDescription);
            return;
        }

        NSLog(@"%@", info.storageInfo);
    }];
}

Use requestQueryMediaCountInfo(_:) in Swift or requestQueryMediaCountInfoWithCompletion: in Objective-C when you need to refresh mediaCountInfo.

Error Handling

Property access itself does not return an asynchronous error. Explicit refresh operations report failures through their completion handlers. Handle unavailable information by:

  1. Checking device.isConnectedAndReady when live values are required.
  2. Confirming protocol conformance before reading DeviceInfoAPI properties.
  3. Handling optional properties without assuming every device model reports every value; treat a nil deviceCapabilities value as unknown rather than unsupported.
  4. Treating advertisement fields as the latest received advertisement snapshot.
  5. Handling success and error for explicit refresh operations such as storage or media-count queries.

Best Practices

  1. Check Protocol Conformance: Confirm DeviceInfoAPI support before reading its extended properties.

  2. Gate Features by Reported Values: Prefer the normalized flags in deviceCapabilities, the recommended recording-duration arrays, and minimumBatteryLevelForMediaOperations over product-name checks or hard-coded limits.

  3. Treat Values as a Snapshot: Do not assume every property was refreshed at the same time.

  4. Handle Optional Values: Display an unavailable state instead of inventing fallback device data.

  5. Refresh Only When Needed: Use the storage and media-count query methods when the screen requires current values.

  6. Localize Display Values: Convert products, languages, call status, and other enums into user-facing localized text.

Notes

  • Device capabilities and available fields vary by product and firmware. DeviceProduct.headphones identifies over-ear headphones, while BatteryComponent.headphones identifies their battery entry.
  • supportedLanguages contains NSNumber values that map to DeviceLanguage.rawValue.
  • StorageInfoModel reports usedSpaceInMB and freeSpaceInMB.
  • MediaCountInfoModel reports photoCount, videoCount, and audioCount.
  • Prefer model properties over parsing description when your UI needs individual values.

AIBuds SDK documentation · Full documentation · API Reference

AIBuds SDK iOS Wiki

Clone this wiki locally