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 フレームワークは、国コードを判定した最初のソースで停止します。
- オーバーライド国コード: adb shell コマンド(ローカルまたは自動テスト)により強制される国コード。
- 電話国コード: 携帯電話から取得した国コード。複数の SIM があり、それぞれ異なるコードを返す場合、選ばれる国コードは非決定的になります。
- Wi-Fi 国コード: Wi-Fi(80211.ad)から取得した国コード。
- 直近の電話国コード: 最後に携帯電話から取得した国コード。複数の SIM があり、それぞれ異なるコードを返す場合、選ばれる国コードは非決定的になります。
- 位置情報国コード:
LocationManager
Fused Location Provider から取得した国コード。 - 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 バイトの値で送信されます。値 |
|
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 バイトの値。 値:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 または 4 | 0xE9 |
2 | 診断レポートを設定する 1 バイトまたは 4 バイトのビットマスク。このビットマスクは Android 14 以降の場合は 1 バイト、Android 13 以前の場合は 4 バイトです。 このパラメータは、 ビット定義:
|
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 バイトの値。 値:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | アンテナ インターリーブ機能のサポートの有無を示す 1 バイトの値。 値:
|
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 バイトの値。 値:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | 診断レポートのサポートの有無を示す 1 バイトの値。 値:
|
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 バイトのビットマスク。ビットマスクの各 値:
|
ステータス コード
ベンダー スペースのステータス コードは次のとおりです。これらは 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 を無効にする必要があるため、セッション ステータスが変更されました。 |