メインコンテンツまでスキップ

デバイス詳細情報の取得

AIBuds デバイスで現在利用できる情報を読み取ります。デバイス詳細はデバイスオブジェクトのプロパティとして公開されており、単一の getDeviceDetails 要求や DeviceDetails 結果モデルはありません。

識別情報、ファームウェア、接続、アドバタイズ情報には DeviceConvertible を使用します。デバイスが DeviceInfoAPI にも準拠している場合は、バッテリー状態、報告された機能、ハードウェア構成、言語設定、通話状態、ストレージ情報、メディア件数も読み取れます。

前提条件​

デバイス詳細を読み取る前に、次の条件を確認してください。

  • スキャン、保存済みデバイス、または接続フローから DeviceConvertible インスタンスを取得していること。
  • デバイスが報告する最新値が必要な場合は、接続が完了して操作可能になるまで待つこと。
  • SDK またはデバイスから値が提供されるまでは、任意プロパティを未取得として扱うこと。

:::info 現在のスナップショット これらのプロパティを読み取っても Bluetooth コマンドは送信されません。値は SDK が現在保持しているスナップショットであり、検出データ、保存済みデバイスデータ、または接続中に受信した情報に由来する場合があります。 :::

API リファレンス​

フレームワーク​

AIBuds.xcframework

インポート​

SDK を使用するファイルで、メインフレームワークをインポートします。

Swift
import AIBuds

プロトコル​

デバイス詳細は 2 つのプロトコルで公開されます。DeviceConvertible は基本的なデバイススナップショットを提供し、接続先デバイスが対応している場合は DeviceInfoAPI が追加のデバイス情報プロパティを提供します。

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

プロパティ​

基本デバイスプロパティ​

次のプロパティは DeviceConvertible から取得できます。

カテゴリプロパティ備考
識別情報name, uuid, bluetoothName, macAddress, productSDK が現在把握しているデバイス名と識別子。
ハードウェアdeviceModel, deviceSerialNum, formatedProjNumber対応デバイスから報告される任意の値。
ファームウェアfirmwareVersion, formatedFirmwareVersion, coProcessorFirmwareVersionformatedFirmwareVersion は Demo でも使用される表示用のメインファームウェア文字列。
接続connectionState, deviceState, isConnectedAndReady, isBusy, lastConnectTimeデバイスの現在状態を利用する前に isConnectedAndReady を確認します。
バインドbindUserId, userBindTime, isAlreadyUnbind, shouldAutoReconnectWhenAppLaunchSDK が管理するバインド状態と再接続状態。
アドバタイズadvertisementDataString, advertisementRawData, manufacturerData, manufacturerHexDataString, timestampOfAdvertisementData最後に受信したアドバタイズデータから得られる値。
表示thumbnail, screenName, customContentホストアプリの UI で利用できる任意の値。

デバイス情報プロパティ​

DeviceInfoAPI への準拠を確認すると、次の追加スナップショット値を利用できます。

プロパティ型説明
batteryStatusInfoBatteryStatusModel?デバイスの各バッテリー構成要素の現在情報。
deviceCapabilitiesDeviceCapabilities?デバイスが報告する正規化された機能フラグ。有効な機能情報を受信するまでは nil。
hardwareConfigurationDeviceHardwareConfigurationデバイスが報告する物理入力ハードウェアとガイダンス要件。
languageSettingDeviceLanguage現在のデバイス言語。
supportedLanguages[NSNumber]デバイスが対応する DeviceLanguage の raw value。
callStatusCallStatus現在の通話状態。
storageInfoStorageInfoModel?使用済み容量と空き容量（MB）。
mediaCountInfoMediaCountInfoModel?写真、動画、音声ファイルの件数。
isSupportAdjustRecordDurationBool最大録音時間を設定できるかどうか。
aiSolutionCapabilitiesAIBudsAISolutionCapabilitiesデバイスから報告された AI 機能。
coprocessorModelCoprocessorModelデバイスのコプロセッサーモデル。
imageEnhancementPostProcessingAlgorithmImageEnhancementPostProcessingAlgorithmデバイスが現在報告している画像補正後処理アルゴリズム。既定値は .general。
recommendedMaxVideoRecordingDurationOptions[NSNumber]デバイス推奨の動画最大録画時間の選択肢（分）。既定値は [1, 3, 9, 12]。
recommendedMaxAudioRecordingDurationOptions[NSNumber]デバイス推奨の音声最大録音時間の選択肢（分）。既定値は [30, 60, 120]。
minimumBatteryLevelForMediaOperationsInt写真、動画、音声、ファイル転送に必要な最低バッテリー残量（%）。既定値は 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通話状態が未取得または認識不能です。

使用例​

デバイス詳細を読み取る​

次の例は SDK Demo の DeviceInfoDetailsController と同じ方針で、基本デバイスプロパティを先に読み取り、対応時に DeviceInfoAPI プロパティを追加します。

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
}

返された行は、アプリ独自のビューモデルとローカライズを使って表示してください。Demo ではテーブルビューを使用し、列挙値をローカライズ済みの表示文字列へ変換しています。

ストレージまたはメディア情報を更新する​

storageInfo と mediaCountInfo はスナップショットプロパティです。画面で最新値が必要な場合は、先に更新を要求し、処理成功後に対応するプロパティを読み取ります。

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

Swift の requestQueryMediaCountInfo(_:) または Objective-C の requestQueryMediaCountInfoWithCompletion: を使用して、mediaCountInfo を更新します。

エラー処理​

プロパティの読み取り自体は非同期エラーを返しません。明示的な更新処理の失敗は完了ハンドラーで通知されます。取得できない情報は次のように扱います。

  1. 現在値が必要な場合は device.isConnectedAndReady を確認します。
  2. DeviceInfoAPI プロパティを読む前にプロトコル準拠を確認します。
  3. すべてのデバイスモデルが全項目を報告するとは限らないため、任意プロパティを安全に扱います。nil の deviceCapabilities は非対応ではなく不明として扱います。
  4. アドバタイズ項目は最後に受信したスナップショットとして扱います。
  5. ストレージやメディア件数などの明示的な更新処理では success と error を処理します。

ベストプラクティス​

  1. プロトコル準拠を確認する: 拡張プロパティを読む前に DeviceInfoAPI 対応を確認します。

  2. 報告値で機能を制御する: 製品名や固定値ではなく、deviceCapabilities の正規化されたフラグ、推奨録画・録音時間、minimumBatteryLevelForMediaOperations を優先します。

  3. 値をスナップショットとして扱う: すべてのプロパティが同時に更新されたとは限りません。

  4. 任意値を適切に扱う: 推測したデバイスデータで補わず、未取得状態を表示します。

  5. 必要なときだけ更新する: 画面で現在値が必要な場合にストレージやメディア件数の問い合わせメソッドを使用します。

  6. 表示値をローカライズする: 製品、言語、通話状態などの列挙値をユーザー向けのローカライズ済みテキストへ変換します。

注意事項​

  • デバイス機能と利用可能な項目は、製品とファームウェアによって異なります。DeviceProduct.headphones はオーバーイヤーヘッドホン製品を、BatteryComponent.headphones はそのバッテリー項目を示します。
  • supportedLanguages には NSNumber 値が含まれ、DeviceLanguage.rawValue に対応します。
  • StorageInfoModel は usedSpaceInMB と freeSpaceInMB を提供します。
  • MediaCountInfoModel は photoCount、videoCount、audioCount を提供します。
  • UI で個別の値が必要な場合は、description を解析せずモデルプロパティを使用してください。