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 フレームワークからの呼び出しフローを示しています。

図 1. UWB スタックの初期化の呼び出しフロー（UWB 切り替えオン）

図 2. 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 でサポートされています。

• CR 287
• CCC デジタルキー インターフェース要件に対する SUS API および UCI 仕様のサポート

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 が使用するために予約されています。

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 セッション構成メッセージのパラメータのリストです。

CORE_GET_CAPS_INFO_RSP

CAPS_INFO の TLV のベンダー予約部分で AOSP スタックにより定義されている TLV は次のとおりです。

• GID: 0000b（UWB コアグループ）
• OID: 000011b（CORE_GET_CAPS_INFO_RSP）

次の表は、UWB 機能のメッセージのパラメータのリストです。

ステータス コード

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

SESSION_STATUS_NTF のステータス変更理由コード

SESSION_STATUS_NTF で UWBS によって返されるステータス フィールドに対して、ベンダー スペースで定義されているステータス変更理由コードは次のとおりです。圏内のセッションのステータスが変更されると（ACTIVE から IDLE に変更された場合など）、この通知が UWBS によって送信されます。