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 shell コマンド（ローカルまたは自動テスト）により強制される国コード。
  2. 電話国コード: 携帯電話から取得した国コード。複数の SIM があり、それぞれ異なるコードを返す場合、選ばれる国コードは非決定的になります。
  3. Wi-Fi 国コード: Wi-Fi（80211.ad）から取得した国コード。
  4. 直近の電話国コード: 最後に携帯電話から取得した国コード。複数の SIM があり、それぞれ異なるコードを返す場合、選ばれる国コードは非決定的になります。
  5. 位置情報国コード: LocationManager Fused Location Provider から取得した国コード。
  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 スタックは、これらのベンダーの GID と OID の一部を、仕様で定義されていない Android 固有のコマンドで使用します。詳しくは、UCI 仕様のセクション 8.4 をご覧ください。

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

ベンダー インターフェースのバージョニング

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

Android の GID と OID のリスト

次の表は、Android の GID と OID のリストです。GID の 0xE と 0xF は、Android OEM が使用するために予約されています。

GID 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 が SUPPORTED_DIAGNOSTICS を診断レポート機能がサポートされていることを示す値 1 で返した場合のみこのパラメータを設定します。

値:

  • 1: 機能は有効
  • 0: 機能は無効
DIAGRAMS_FRAME_REPORTS_FIELDS 1 または 4 0xE9 2

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

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

ビット定義:

  • 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 をサポート

ステータス コード

ベンダー スペースのステータス コードは次のとおりです。これらは UCI レスポンス（SESSION_START_RSP など）で UWB サブシステム（UWBS）によって返されます。

ステータス コード 値 説明
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 を無効にする必要があるため、セッション ステータスが変更されました。