Stos ultraszerokopasmowy AOSP (UWB) wykorzystuje zdefiniowany przez FiRa interfejs UCI jako powierzchnię HAL. Interfejs HAL wykorzystuje nieprzezroczysty potok ( IUwbChip::sendUciMessage()
i IUwbClientCallback::onUciMessage()
) do wysyłania i odbierania poleceń, odpowiedzi i powiadomień interfejsu poleceń UWB (UCI). Wszyscy dostawcy Androida UWB muszą obsługiwać wszystkie komunikaty zdefiniowane w specyfikacji FiRa. Struktura UWB jest kompatybilna wstecz i współpracuje z dowolną wersją UCI zaimplementowaną na urządzeniu przez dostawcę UWB. Ponieważ platforma AOSP UWB jest modułem , może również selektywnie dodawać obsługę zatwierdzonych żądań zmian (CR) z projektów specyfikacji UCI przeznaczonych dla głównych wydań standardów FiRa. Wszelkie wdrożone projekty CR mogą ulec zmianie.
Definicja interfejsu
Interfejs UWB HAL jest zdefiniowany przy użyciu stabilnego AIDL . Główny interfejs korzysta z pakietu android.hardware.uwb
.
Poniżej przedstawiono dwa główne interfejsy pakietu android.hardware.uwb
.
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);
}
Przepływ wywołań HAL z platformy UWB
Poniższe obrazy ilustrują przepływ wywołań ze struktury UWB dla inicjalizacji stosu UWB, deinicjalizacji stosu UWB oraz procesów uruchamiania i zatrzymywania sesji UWB.
Rysunek 1. Przepływ wywołań inicjujących stos UWB (włączony przełącznik UWB)
Rysunek 2. Przepływ wywołań deinicjalizacji stosu UWB (przełącznik UWB wyłączony)
Rysunek 3. Przebieg uruchamiania/zatrzymywania sesji UWB
Konfiguracja kodu kraju UWB
Jak pokazano na rysunku 1, struktura UWB konfiguruje kod kraju UWB podczas inicjalizacji stosu UWB za pomocą polecenia UCI z przestrzeni dostawcy ANDROID_SET_COUNTRY_CODE
(GID= 0xC
, OID= 0x1
). Struktura UWB próbuje określić kod kraju UWB, korzystając z następujących źródeł (wymienionych w kolejności priorytetów). Ramy UWB zatrzymują się na pierwszym źródle, w którym ustalany jest kod kraju.
- Zastąp kod kraju: kod kraju wymuszony za pomocą polecenia powłoki adb (testowanie lokalne lub automatyczne).
- Kod kraju dla telefonii: kod kraju pobrany przez sieć komórkową. Jeśli istnieje wiele kart SIM zwracających różne kody, wybrany kod kraju jest niedeterministyczny.
- Kod kraju Wi-Fi: Kod kraju pobrany przez Wi-Fi (80211.ad).
- Ostatni znany kod kraju w telefonii: ostatni znany kod kraju pobrany przez sieć komórkową. Jeśli istnieje wiele kart SIM zwracających różne kody, wybrany kod kraju jest niedeterministyczny.
- Kod kraju lokalizacji: Kod kraju pobrany od dostawcy połączonej lokalizacji
LocationManager
. - Domyślny kod kraju OEM: kod kraju ustawiony przez producenta urządzenia.
Jeśli platforma UWB nie jest w stanie określić kodu kraju UWB, wywołuje polecenie UCI ANDROID_SET_COUNTRY_CODE
z wartością DEFAULT_COUNTRY_CODE ("00")
i powiadamia aplikacje UWB, że stan stosu UWB jest DISABLED
. Później, gdy platforma UWB będzie w stanie określić prawidłowy kod kraju, konfiguruje nowy kod kraju za pomocą polecenia ANDROID_SET_COUNTRY_CODE
i powiadamia aplikacje UWB, że stos UWB jest READY
.
Jeśli nie można użyć UWB ze względu na lokalne przepisy obowiązujące w danym kraju, kontroler UWB zwraca kod stanu STATUS_CODE_ANDROID_REGULATION_UWB_OFF
. Struktura UWB powiadamia następnie aplikacje UWB, że stan stosu UWB jest DISABLED
.
Gdy użytkownik podróżuje do innego kraju, platforma UWB konfiguruje nowy kod kraju za pomocą polecenia UCI ANDROID_SET_COUNTRY_CODE
. W zależności od kodu stanu zwróconego przez kontroler UWB (w oparciu o przepisy UWB w nowym kraju) może to prowadzić do zmiany stanu stosu UWB.
Format poleceń zdefiniowany w specyfikacji FIRA UCI
Informacje na temat formatu pakietów kontrolnych UCI można znaleźć w sekcji 4.4.2 specyfikacji UCI .
Wersjonowanie interfejsu
Specyfikacja UCI umożliwia dostawcom UWB ujawnienie wersji stosu UCI zaimplementowanego przez urządzenie za pomocą poleceń UCI_GET_DEVICE_INFO_RSP
i UCI_GET_CAPS_INFO_RSP
. Struktura używa tych poleceń do pobrania wersji UCI urządzenia i odpowiedniej zmiany jego zachowania.
Lista projektów CR obsługiwanych przez moduł UWB
Następujące wersje robocze CR dla FiRa 2.0 są obsługiwane przez moduł UWB w wersji #330810000:
Interfejs Android UCI (część dostawcy FiRa)
Specyfikacja UCI definiuje zestaw identyfikatorów grupowych (GID) i identyfikatorów opcode (OID) dla wszystkich komunikatów zdefiniowanych w specyfikacji. Specyfikacja zastrzega również zestaw identyfikatorów GID zarezerwowanych wyłącznie do użytku dostawcy. Stos AOSP UWB wykorzystuje niektóre z tych identyfikatorów GID i OID dostawców dla poleceń specyficznych dla systemu Android, które nie są zdefiniowane w specyfikacji. Szczegółowe informacje można znaleźć w rozdziale 8.4 specyfikacji UCI .
Te komunikaty dostawców używane przez system Android są zdefiniowane w pakiecie HAL android.hardware.uwb.fira_android
.
Wersjonowanie interfejsu dostawcy
Dostawcy UWB muszą ujawnić wersję pakietu android.hardware.uwb.fira_android
HAL obsługiwaną na urządzeniu za pomocą IUwbChip.getSupportedAndroidUciVersion()
. Struktura wykorzystuje te informacje o wersji do obsługi zgodności wstecznej.
Lista identyfikatorów GID i OID Androida
W poniższej tabeli wymieniono identyfikatory GID i OID dla systemu Android. Identyfikatory GID 0xE
i 0xF
są zarezerwowane dla producentów OEM systemu Android.
KOŁOWACIZNA | OID | Definicja |
---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | Używane przez polecenie i odpowiedź w celu uzyskania statystyk związanych z zasilaniem UWB. Obsługiwane tylko wtedy, gdy UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY jest ustawione na 1 . |
ANDROID_SET_COUNTRY_CODE = 0x1 | Służy do ustawiania aktualnego, regulacyjnego kodu kraju (określanego przy użyciu karty SIM lub Wi-Fi lub zakodowanego na stałe przez producenta OEM). Kod kraju jest wysyłany jako wartość 2-bajtowa odpowiadająca kodowi kraju ISO-3166. Wartość | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | Używany przez powiadomienie do uzyskania statystyk diagnostycznych zakresu UWB. Obsługiwane tylko wtedy, gdy UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS jest ustawiony na 1 . | |
OEM = 0xE,0xF | 0x00 - 0x3F | Zarezerwowane do użytku OEM. |
Rozszerzenia dostawców do komunikatów zdefiniowanych w specyfikacji UCI
W tej sekcji opisano szczegóły rozszerzeń dostawców do komunikatów zdefiniowanych w specyfikacji UCI.
SESSION_SET_APP_CONFIG_[CMD|RSP] i SESSION_GET_APP_CONFIG_[CMD|RSP]
Poniżej znajdują się wartości długości typu (TLV) zdefiniowane przez stos AOSP w zarezerwowanej przez dostawcę części wartości TLV w APP_CONFIG
:
- GID: 0001b (grupa konfiguracyjna sesji UWB)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD
) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD
)
W poniższej tabeli wymieniono parametry komunikatów konfiguracyjnych sesji UWB.
Nazwa parametru | Długość (oktety) | Etykietka (identyfikatory) | Wersja interfejsu dostawcy | Opis |
---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS | 1 | 0xE3 | 1 | Współczynnik przeplatania, jeśli AOA_RESULT_REQ jest ustawiony na 0xF0 . Obsługiwane tylko wtedy, gdy UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING jest ustawione na 1 . |
NB_OF_AZIMUTH_MEASUREMENTS | 1 | 0xE4 | 1 | |
NB_OF_ELEVATION_MEASUREMENTS | 1 | 0xE5 | 1 | |
ENABLE_DIAGNOSTICS | 1 | 0xE8 | 2 | Wartość 1-bajtowa umożliwiająca włączenie lub wyłączenie raportowania diagnostycznego. Skonfiguruj ten parametr tylko wtedy, gdy Wartości:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 lub 4 | 0xE9 | 2 | 1-bajtowa lub 4-bajtowa maska bitowa do konfiguracji raportowania diagnostycznego. Ta maska bitowa ma 1 bajt w systemie Android 14 lub nowszym i 4 bajty w systemie Android 13 lub starszym. Skonfiguruj ten parametr tylko wtedy, gdy Definicje bitów:
|
CORE_GET_CAPS_INFO_RSP
Poniżej znajdują się wartości TLV zdefiniowane przez stos AOSP w zarezerwowanej przez dostawcę części wartości TLV w CAPS_INFO
:
- GID: 0000b (grupa podstawowa UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP
)
W poniższej tabeli wymieniono parametry komunikatów dotyczących możliwości UWB.
Nazwa parametru | Długość (oktety) | Etykietka (identyfikatory) | Wersja interfejsu dostawcy | Opis |
---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | Wartość 1-bajtowa wskazująca obsługę zapytań o statystyki mocy. Wartości:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Wartość 1-bajtowa wskazująca obsługę funkcji przeplatania anteny. Wartości:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | Wartość 4-bajtowa wskazująca obsługiwany minimalny interwał zakresu w milisekundach. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | 4-bajtowa maska bitowa wskazująca obsługiwane wartości RANGE_DATA_NTF_CONFIG . Maska bitowa, w której każdy bit odpowiada wartościom używanym w RANGE_DATA_NTF_CONFIG w SET_APP_CFG_CMD . |
SUPPORTED_RSSI_REPORTING | 1 | 0xE6 | 2 | Wartość 1-bajtowa wskazująca obsługę raportowania RSSI. Wartości:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Wartość 1-bajtowa wskazująca obsługę raportowania diagnostycznego. Wartości:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | Wartość 4-bajtowa wskazująca obsługiwany minimalny czas trwania szczeliny w RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER | 4 | 0xE9 | 2 | Wartość 4-bajtowa wskazująca obsługiwaną maksymalną liczbę sesji ustalania odległości FiRa. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | 2-bajtowa maska bitowa wskazująca kanały obsługujące AoA. Każda Wartości:
|
Kody stanu
Poniżej znajdują się kody stanu w przestrzeni dostawcy. Są one zwracane w odpowiedziach UCI (takich jak SESSION_START_RSP
) przez podsystem UWB (UWBS).
Kod statusu | Wartość | Opis |
---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x52 | Kod stanu zwracany, gdy nie można rozpocząć bieżącej sesji ustalania odległości z powodu konfliktu z innymi sesjami ustalania odległości CCC lub FiRa. |
STATUS_REGULATION_UWB_OFF | 0x53 | Kod stanu zwracany, gdy nie można rozpocząć bieżącej sesji ustalania zakresu ze względów prawnych UWB. |
Kod przyczyny zmiany stanu w SESSION_STATUS_NTF
Poniżej znajdują się kody przyczyny zmiany stanu zdefiniowane w przestrzeni dostawcy dla pola stanu zwróconego przez UWBS w SESSION_STATUS_NTF
. To powiadomienie jest wysyłane przez UWBS, gdy zmienia się stan sesji ustalającej zakres (na przykład z ACTIVE
na IDLE
).
Kod przyczyny zmiany stanu | Wartość | Opis |
---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA | 0x80 | Stan sesji uległ zmianie, ponieważ skonfigurowany kanał nie obsługuje zakresu AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x81 | Stan sesji zmieniony z powodu konfliktu z innymi sesjami CCC lub FiRa. |
REASON_REGULATION_UWB_OFF | 0x82 | Stan sesji uległ zmianie, ponieważ UWB musi zostać wyłączone ze względów prawnych. |