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 シェル コマンド (ローカルまたは自動テスト) によって強制される国コード。
- 電話の国コード: 携帯電話を通じて取得された国コード。異なるコードを返す SIM が複数ある場合、選択される国コードは非決定的です。
- Wi-Fi 国コード: Wi-Fi を通じて取得された国コード (80211.ad)。
- 最後に知られた電話の国コード: 携帯電話を通じて取得された最後に知られた国コード。異なるコードを返す SIM が複数ある場合、選択される国コードは非決定的です。
- 場所の国コード:
LocationManager
融合型場所プロバイダーから取得された国コード。 - 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 バイト値として送信されます。値 | |
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 バイトのビットマスク。ビットマスク内の各 値:
|
ステータスコード
以下はベンダースペースのステータスコードです。これらは、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 を無効にする必要があるため、セッション状態が変更されました。 |