Сведения об устройстве

Читайте доступные сведения об устройстве AIBuds непосредственно из свойств объекта устройства. Единого запроса getDeviceDetails и модели результата DeviceDetails нет.

Идентификаторы, прошивка, подключение и рекламные данные доступны через DeviceConvertible. Если устройство также соответствует DeviceInfoAPI, можно прочитать состояние батареи, заявленные возможности, аппаратную конфигурацию, язык, состояние вызова, сведения о памяти и количество медиафайлов.

Предварительные условия

Перед чтением сведений об устройстве:

Получите экземпляр DeviceConvertible в ходе сканирования, из сохранённых устройств или после подключения.
Если нужны актуальные данные от устройства, дождитесь его подключения и готовности.
Считайте необязательные свойства недоступными, пока SDK или устройство не передаст их значения.

:::info Текущий снимок Чтение этих свойств не отправляет Bluetooth-команду. Значения отражают текущий снимок SDK и могут поступать из данных обнаружения, сохранённых данных устройства или активного подключения. :::

Справочник API

Фреймворк

AIBuds.xcframework

Импорт

В файлах, где используется SDK, импортируйте основной фреймворк:

Swift
Objective-C

import AIBuds

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

Протоколы

Сведения предоставляют два протокола. DeviceConvertible содержит базовый снимок устройства, а DeviceInfoAPI — дополнительные свойства, если подключённое устройство поддерживает этот протокол.

Swift
Objective-C

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

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

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

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

Свойства

Базовые свойства устройства

Эти свойства доступны через DeviceConvertible.

Категория	Свойства	Примечания
Идентификация	`name`, `uuid`, `bluetoothName`, `macAddress`, `product`	Имя и идентификаторы устройства, известные SDK.
Аппаратная часть	`deviceModel`, `deviceSerialNum`, `formatedProjNumber`	Необязательные значения, сообщаемые поддерживаемыми устройствами.
Прошивка	`firmwareVersion`, `formatedFirmwareVersion`, `coProcessorFirmwareVersion`	`formatedFirmwareVersion` — отображаемая строка основной прошивки, используемая в Demo.
Подключение	`connectionState`, `deviceState`, `isConnectedAndReady`, `isBusy`, `lastConnectTime`	Перед использованием текущего состояния проверяйте `isConnectedAndReady`.
Привязка	`bindUserId`, `userBindTime`, `isAlreadyUnbind`, `shouldAutoReconnectWhenAppLaunch`	Состояние привязки и повторного подключения, которое ведёт SDK.
Рекламные данные	`advertisementDataString`, `advertisementRawData`, `manufacturerData`, `manufacturerHexDataString`, `timestampOfAdvertisementData`	Значения из последних полученных рекламных данных.
Отображение	`thumbnail`, `screenName`, `customContent`	Необязательные значения для интерфейса приложения.

Дополнительные сведения

После проверки соответствия DeviceInfoAPI становятся доступны следующие дополнительные значения снимка.

Свойство	Тип	Описание
`batteryStatusInfo`	`BatteryStatusModel?`	Текущие сведения о компонентах батареи устройства.
`deviceCapabilities`	`DeviceCapabilities?`	Нормализованные флаги возможностей устройства; `nil`, пока не получены достоверные сведения.
`hardwareConfiguration`	`DeviceHardwareConfiguration`	Физические средства ввода и требования к подсказкам, заявленные устройством.
`languageSetting`	`DeviceLanguage`	Текущий язык устройства.
`supportedLanguages`	`[NSNumber]`	Исходные значения `DeviceLanguage`, поддерживаемые устройством.
`callStatus`	`CallStatus`	Текущее состояние вызова.
`storageInfo`	`StorageInfoModel?`	Занятое и свободное пространство в МБ.
`mediaCountInfo`	`MediaCountInfoModel?`	Количество фото, видео и аудиофайлов.
`isSupportAdjustRecordDuration`	`Bool`	Можно ли настраивать максимальную длительность записи.
`aiSolutionCapabilities`	`AIBudsAISolutionCapabilities`	AI-возможности, заявленные устройством.
`coprocessorModel`	`CoprocessorModel`	Модель сопроцессора устройства.
`imageEnhancementPostProcessingAlgorithm`	`ImageEnhancementPostProcessingAlgorithm`	Текущий алгоритм постобработки изображения; по умолчанию `.general`.
`recommendedMaxVideoRecordingDurationOptions`	`[NSNumber]`	Рекомендуемые варианты максимальной длительности видеозаписи в минутах; по умолчанию `[1, 3, 9, 12]`.
`recommendedMaxAudioRecordingDurationOptions`	`[NSNumber]`	Рекомендуемые варианты максимальной длительности аудиозаписи в минутах; по умолчанию `[30, 60, 120]`.
`minimumBatteryLevelForMediaOperations`	`Int`	Минимальный заряд для фото, видео, аудио и передачи файлов; по умолчанию `30` процентов. Для OTA действуют отдельные правила.

Основные значения состояния

batteryStatusInfo может содержать любой компонент, поддерживаемый устройством:

`BatteryComponent`	Значение
`.glass`	Корпус очков
`.leftEarbud` / `.rightEarbud`	Левый или правый наушник
`.chargingCase`	Зарядный футляр
`.mainSpeaker` / `.sideSpeaker`	Основной или боковой динамик
`.headphones`	Полноразмерные наушники
`.unknown`	Компонент недоступен или не распознан

Используйте поля deviceCapabilities, чтобы включать TWS, пространственный звук, многоточечное подключение, ANC, встроенного голосового помощника, усиление басов, потоковое видео, Ximalaya и тестовый сигнал. Не определяйте эти функции только по product. Значение nil означает, что достоверные сведения ещё не получены, а не отсутствие поддержки всех функций.

hardwareConfiguration описывает способы управления устройством:

Свойство	Значение
`hasTouchInput`	Есть сенсорная поверхность ввода.
`hasPhysicalButtonInput`	Есть физические кнопки.
`requiresOnDeviceVoiceAssistantGuidance`	Приложение должно показать инструкции для встроенного голосового помощника.

Для callStatus используется CallStatus:

Значение	Описание
`.notInCall`	Активного вызова нет.
`.ringing`	Поступает входящий вызов.
`.inCall`	Вызов активен.
`.threeWayRinging`	Поступает трёхсторонний вызов, если он поддерживается.
`.aiChat`	Устройство сообщает об AI-диалоге как о текущей активности канала вызова.
`.unknown`	Состояние вызова недоступно или не распознано.

Примеры использования

Чтение сведений

Примеры повторяют подход DeviceInfoDetailsController из Demo SDK: сначала читаются базовые свойства, затем при поддержке добавляются свойства DeviceInfoAPI.

Swift
Objective-C

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
}

#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;
}

Отображайте полученные строки через собственную модель представления и локализацию приложения. Demo использует таблицу и преобразует значения перечислений в локализованные строки.

Обновление сведений о памяти и медиафайлах

storageInfo и mediaCountInfo — свойства снимка. Если экрану нужны актуальные значения, сначала запросите обновление, а после успешной операции прочитайте соответствующее свойство.

Swift
Objective-C

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

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

Используйте requestQueryMediaCountInfo(_:) в Swift или requestQueryMediaCountInfoWithCompletion: в Objective-C, когда требуется обновить mediaCountInfo.

Обработка ошибок

Само чтение свойств не возвращает асинхронную ошибку. Явные операции обновления сообщают сбои через обработчики завершения. При недоступных данных:

Проверяйте device.isConnectedAndReady, если нужны текущие значения.
Перед чтением свойств DeviceInfoAPI проверяйте соответствие протоколу.
Обрабатывайте необязательные свойства, не предполагая, что каждая модель сообщает все значения; считайте nil в deviceCapabilities неизвестным состоянием, а не отсутствием поддержки.
Считайте рекламные поля последним полученным снимком рекламных данных.
Для явных обновлений, например запросов памяти или количества файлов, обрабатывайте success и error.

Примечания

Возможности и доступные поля зависят от продукта и версии прошивки. DeviceProduct.headphones обозначает полноразмерные наушники, а BatteryComponent.headphones — их батарею.
supportedLanguages содержит значения NSNumber, соответствующие DeviceLanguage.rawValue.
StorageInfoModel предоставляет usedSpaceInMB и freeSpaceInMB.
MediaCountInfoModel предоставляет photoCount, videoCount и audioCount.
Если интерфейсу нужны отдельные значения, используйте свойства модели, а не разбор description.

Предварительные условия​

Справочник API​

Фреймворк​

Импорт​

Протоколы​

Свойства​

Базовые свойства устройства​

Дополнительные сведения​

Основные значения состояния​

Примеры использования​

Чтение сведений​

Обновление сведений о памяти и медиафайлах​

Обработка ошибок​

Рекомендации​

Примечания​