UWB HALインターフェース

AOSPウルトラワイドバンド (UWB) スタックは、 FiRa で定義された UCI インターフェイスをHAL サーフェスとして使用します。 HAL インターフェイスは、不透明なパイプ ( IUwbChip::sendUciMessage()およびIUwbClientCallback::onUciMessage() ) を使用して、UWB コマンド インターフェイス (UCI) コマンド、応答、および通知を送受信します。すべての Android UWB ベンダーは、FiRa 仕様で定義されたすべてのメッセージをサポートする必要があります。 UWB フレームワークには下位互換性があり、UWB ベンダーがデバイスに実装するすべての UCI バージョンで動作します。 AOSP UWB フレームワークはモジュールであるため、主要な FiRa 標準リリースを対象としたドラフト UCI 仕様から承認された変更リクエスト (CR) のサポートを選択的に追加することもできます。実装されたそのようなドラフト CR は変更される可能性があります。

インターフェースの定義

UWB HAL インターフェイスは、安定した AIDL を使用して定義されます。メイン インターフェイスはandroid.hardware.uwbパッケージを使用します。

以下は、 android.hardware.uwbパッケージ内の 2 つの主要なインターフェイスです。

IUwbChip.aidl

package android.hardware.uwb;

interface IUwbChip {

 String getName();

 void open(in android.hardware.uwb.IUwbClientCallback clientCallback);

 void close();

 void coreInit();

 void sessionInit(int sessionId);

 int getSupportedAndroidUciVersion();

 int sendUciMessage(in byte[] data);

}

IUwbClientCallback.aidl

package android.hardware.uwb;

interface IUwbClientCallback {

 oneway void onUciMessage(in byte[] data);

 oneway void onHalEvent(in android.hardware.uwb.UwbEvent event, in android.hardware.uwb.UwbStatus status);

}

UWB フレームワークからの HAL 呼び出しフロー

次の図は、UWB スタックの初期化、UWB スタックの初期化解除、および UWB セッションの開始および停止プロセスの UWB フレームワークからの呼び出しフローを示しています。

UWBスタックの初期化

図 1. UWB スタック初期化コール フロー (UWB 切り替えオン)

UWBスタックの初期化解除

図 2. UWB スタック初期化解除コール フロー (UWB 切り替えオフ)

UWBセッションの開始と停止

図 3. UWB セッションの開始/停止フロー

UWB 国コードの設定

図 1 に示すように、UWB フレームワークは、ベンダー スペース UCI コマンドANDROID_SET_COUNTRY_CODE (GID= 0xC 、OID= 0x1 ) を使用して、UWB スタックの初期化中に UWB 国コードを構成します。 UWB フレームワークは、次のソース (優先順位でリストされています) を使用して UWB 国コードを決定しようとします。 UWB フレームワークは、国コードが決定される最初のソースで停止します。

  1. 国コードを上書きする: adb シェル コマンド (ローカルまたは自動テスト) によって強制される国コード。
  2. 電話の国コード: 携帯電話を通じて取得された国コード。異なるコードを返す SIM が複数ある場合、選択される国コードは非決定的です。
  3. Wi-Fi 国コード: Wi-Fi を通じて取得された国コード (80211.ad)。
  4. 最後に知られた電話の国コード: 携帯電話を通じて取得された最後に知られた国コード。異なるコードを返す SIM が複数ある場合、選択される国コードは非決定的です。
  5. 場所の国コード: LocationManager融合型場所プロバイダーから取得された国コード。
  6. OEM のデフォルトの国コード: デバイスの製造元によって設定された国コード。

UWB フレームワークが UWB 国コードを特定できない場合、 DEFAULT_COUNTRY_CODE ("00")の値を指定してANDROID_SET_COUNTRY_CODE UCI コマンドを呼び出し、UWB スタックの状態がDISABLEDあることを UWB アプリに通知します。その後、UWB フレームワークが有効な国コードを特定できると、 ANDROID_SET_COUNTRY_CODEコマンドを使用して新しい国コードを構成し、UWB スタックがREADYあることを UWB アプリに通知します。

国の規制により UWB が使用できない場合、UWB コントローラーはSTATUS_CODE_ANDROID_REGULATION_UWB_OFFステータス コードを返します。その後、UWB フレームワークは、UWB スタックの状態がDISABLEDあることを UWB アプリに通知します。

ユーザーが別の国に旅行すると、UWB フレームワークはANDROID_SET_COUNTRY_CODE UCI コマンドを使用して新しい国コードを構成します。 UWB コントローラーから返されるステータス コード (新しい国の UWB 規制に基づく) によっては、UWB スタックの状態が変化する可能性があります。

FIRA UCI 仕様で定義されたコマンド形式

UCI 制御パケットのフォーマットについては、 UCI 仕様のセクション 4.4.2を参照してください。

インターフェースのバージョン管理

UCI 仕様により、UWB ベンダーは、 UCI_GET_DEVICE_INFO_RSPおよびUCI_GET_CAPS_INFO_RSPコマンドを使用して、デバイスによって実装された UCI スタックのバージョンを公開できます。フレームワークはこれらのコマンドを使用してデバイスの UCI バージョンを取得し、それに応じて動作を変更します。

UWB モジュールでサポートされるドラフト CR のリスト

FiRa 2.0 の次のドラフト CR は、 UWB モジュールバージョン #330810000 でサポートされています。

Android UCI インターフェース (FiRa ベンダー部分)

UCI 仕様では、仕様で定義されたすべてのメッセージに対してグループ識別子 (GID) とオペコード識別子 (OID) のセットが定義されています。この仕様では、ベンダー使用専用に予約された GID のセットも予約されています。 AOSP UWB スタックは、仕様で定義されていない Android 固有のコマンドに、これらのベンダー GID と OID の一部を使用します。詳細については、 UCI 仕様のセクション 8.4を参照してください。

Android で使用されるこれらのベンダー メッセージは、 android.hardware.uwb.fira_android HAL パッケージで定義されています。

ベンダーインターフェースのバージョン管理

UWB ベンダーは、 IUwbChip.getSupportedAndroidUciVersion()を通じて、デバイスでサポートされているandroid.hardware.uwb.fira_android HAL パッケージのバージョンを公開する必要があります。フレームワークは、このバージョン情報を使用して下位互換性を処理します。

Android GID と OID のリスト

次の表に、Android の GID と OID を示します。 GID 0xEおよび0xF 、Android OEM が使用するために予約されています。

性同一性障害OID意味
ANDROID = 0xC ANDROID_GET_POWER_STATS = 0x0 UWB 電力関連の統計を取得するためにコマンドと応答によって使用されます。 UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERYが1に設定されている場合にのみサポートされます。
ANDROID_SET_COUNTRY_CODE = 0x1

現在の規制国コードを設定するために使用されます (SIM または Wi-Fi を使用して決定されるか、OEM によってハードコーディングされます)。国コードは、ISO-3166 国コードに対応する 2 バイト値として送信されます。値00は、国コードが不明であることを示すために使用されます。

ANDROID_RANGE_DIAGNOSTICS = 0x2 UWB 測距診断統計を取得するために通知によって使用されます。 UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICSが1に設定されている場合にのみサポートされます。
OEM = 0xE,0xF 0x00 - 0x3F OEM 使用のために予約されています。

UCI 仕様で定義されたメッセージに対するベンダー拡張

このセクションでは、UCI 仕様で定義されたメッセージに対するベンダー拡張の詳細について説明します。

SESSION_SET_APP_CONFIG_[CMD|RSP] および SESSION_GET_APP_CONFIG_[CMD|RSP]

以下は、 APP_CONFIGの TLV のベンダー予約部分の AOSP スタックによって定義されるタイプ長値 (TLV) です。

  • GID: 0001b (UWB セッション構成グループ)
  • OID: 000011b ( SESSION_SET_APP_CONFIG_CMD )
  • OID: 000100b ( SESSION_GET_APP_CONFIG_CMD )

次の表に、UWB セッション構成メッセージのパラメーターを示します。

パラメータ名長さ
(オクテット)		鬼ごっこ
(ID)		ベンダーインターフェースのバージョン説明
NB_OF_RANGE_MEASUREMENTS 1 0xE3 1 AOA_RESULT_REQが0xF0に設定されている場合のインターリーブ率。 UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVINGが1に設定されている場合にのみサポートされます。
NB_OF_AZIMUTH_MEASUREMENTS 1 0xE4 1
NB_OF_ELEVATION_MEASUREMENTS 1 0xE5 1
ENABLE_DIAGNOSTICS 1 0xE8 2

診断レポートを有効または無効にする 1 バイトの値。このパラメータは、 CORE_GET_CAPS_INFO_RSP診断レポート機能がサポートされていることを示す値1のSUPPORTED_DIAGNOSTICSを返した場合にのみ設定します。

値:

  • 1 : 機能が有効です
  • 0 : 機能は無効です

DIAGRAMS_FRAME_REPORTS_FIELDS 1 または 4 0xE9 2

診断レポートを構成するための 1 バイトまたは 4 バイトのビットマスク。このビットマスクは、Android 14 以降では 1 バイト、Android 13 以前では 4 バイトです。

このパラメータは、 CORE_GET_CAPS_INFO_RSPが診断レポート機能がサポートされていることを示す値1のSUPPORTED_DIAGNOSTICSを返した場合にのみ設定します。

ビット定義:

  • b0 (0x01) : RSSI フィールドをアクティブにする
  • b1 (0x02) : AoA フィールドをアクティブにする
  • b2 (0x04) : CIR フィールドをアクティブにする

CORE_GET_CAPS_INFO_RSP

以下は、 CAPS_INFOの TLV のベンダー予約部分で AOSP スタックによって定義される TLV です。

  • GID: 0000b (UWB コア グループ)
  • OID: 000011b ( CORE_GET_CAPS_INFO_RSP )

次の表に、UWB 機能メッセージのパラメーターを示します。

パラメータ名長さ
(オクテット)		鬼ごっこ
(ID)		ベンダーインターフェースのバージョン説明
SUPPORTED_POWER_STATS_QUERY 1 0xC0 1

電力統計クエリのサポートを示す 1 バイトの値。

値:

  • 1 : サポートされている機能
  • 0 : 機能はサポートされていません
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

アンテナ インターリーブ機能のサポートを示す 1 バイトの値。

値:

  • 1 : サポートされている機能
  • 0 : 機能はサポートされていません
SUPPORTED_MIN_RANGING_INTERVAL_MS 4 0xE4 2サポートされている最小測距間隔をミリ秒単位で示す 4 バイトの値。
SUPPORTED_RANGE_DATA_NTF_CONFIG 4 0xE5 2サポートされているRANGE_DATA_NTF_CONFIG値を示す 4 バイトのビットマスク。各ビットがSET_APP_CFG_CMDのRANGE_DATA_NTF_CONFIGで使用される値に対応するビットマスク。
SUPPORTED_RSSI_REPORTING 1 0xE6 2

RSSI レポートのサポートを示す 1 バイトの値。

値:

  • 1 : サポートされている機能
  • 0 : 機能はサポートされていません
SUPPORTED_DIAGNOSTICS 1 0xE7 2

診断レポートのサポートを示す 1 バイトの値。

値:

  • 1 : サポートされている機能
  • 0 : 機能はサポートされていません
SUPPORTED_MIN_SLOT_DURATION_RSTU 4 0xE8 2 RSTU でサポートされている最小スロット期間を示す 4 バイトの値。
SUPPORTED_MAX_RANGING_SESSION_NUMBER 4 0xE9 2サポートされている FiRa 測距セッションの最大数を示す 4 バイトの値。
SUPPORTED_CHANNELS_AOA 2 0xEA 2

AoA をサポートするチャネルを示す 2 バイトのビットマスク。ビットマスク内の各1は、特定の UWB チャネルに対応します。

値:

  • 0x01 : チャネル 5 がサポートされています
  • 0x02 : チャンネル 6 をサポート
  • 0x04 : チャネル 8 をサポート
  • 0x08 : チャネル 9 をサポート
  • 0x10 : チャネル 10 をサポート
  • 0x20 : チャネル 12 をサポート
  • 0x40 : チャネル 13 をサポート
  • 0x80 : チャネル 14 をサポート

ステータスコード

以下はベンダースペースのステータスコードです。これらは、UWB サブシステム (UWBS) によって UCI 応答 ( SESSION_START_RSPなど) で返されます。

ステータスコード価値説明
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

他の CCC または FiRa 測距セッションとの競合により、現在の測距セッションを開始できない場合に返されるステータス コード。

STATUS_REGULATION_UWB_OFF 0x53

UWB 規制上の理由により、現在のレンジング セッションを開始できない場合に返されるステータス コード。

SESSION_STATUS_NTF の状態変更理由コード

以下は、 SESSION_STATUS_NTFの UWBS によって返されるステータス フィールドのベンダー スペースで定義されている状態変更理由コードです。この通知は、レンジング セッションの状態が変化したとき (たとえば、 ACTIVEからIDLEに)、UWBS によって送信されます。

状態変更理由コード価値説明
REASON_ERROR_INVALID_CHANNEL_WITH_AOA 0x80

構成されたチャネルが AoA レンジングをサポートしていないため、セッション状態が変更されました。

REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x81

他の CCC または FiRa 測距セッションとの競合により、セッション状態が変更されました。

REASON_REGULATION_UWB_OFF 0x82

規制上の理由により UWB を無効にする必要があるため、セッション状態が変更されました。