Ultraszerokopasmowa (UWB) warstwa AOSP używa interfejsu UCI zdefiniowanego przez FiRa jako interfejs HAL. Interfejs HAL używa nieprzezroczystego kanału (IUwbChip::sendUciMessage() i IUwbClientCallback::onUciMessage()) do wysyłania i odbierania poleceń, odpowiedzi i powiadomień interfejsu poleceń UWB (UCI).
Wszyscy dostawcy technologii UWB na Androida muszą obsługiwać wszystkie wiadomości zdefiniowane w specyfikacji FiRa. Platforma UWB jest zgodna wstecz i działa z dowolną wersją interfejsu użytkownika UCI implementowaną przez dostawcę UWB na urządzeniu. Framework AOSP UWB jest modułem, więc może też selektywnie dodawać obsługę zatwierdzonych żądań zmiany z projektu specyfikacji UCI przeznaczonego do głównych wersji standardów FiRa. Wszelkie wdrożone wersje robocze CR mogą ulec zmianie.
Definicja interfejsu
Interfejs HAL UWB jest definiowany za pomocą stabilnego AIDL.
Główny interfejs korzysta z pakietu android.hardware.uwb.
Poniżej przedstawiliśmy 2 główne interfejsy w pakiecie 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łania HAL z platformy UWB
Na ilustracjach poniżej przedstawiono przepływ wywołań z ramy UWB na potrzeby inicjowania i wyłączania modułu UWB oraz uruchamiania i zatrzymywania sesji UWB.
Rysunek 1. Przebieg wywołania inicjowania stosu UWB (przełącznik UWB włączony)
Rysunek 2. Przebieg rozmowy dotyczącego deinicjalizacji modułu UWB (przełącznik UWB wyłączony)
Rysunek 3. Proces rozpoczynanie/zatrzymywanie sesji UWB
Konfiguracja kodu kraju UWB
Jak widać na ilustracji 1, platforma UWB konfiguruje kod kraju UWB podczas inicjowania stosu UWB za pomocą polecenia UCI ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1) w ramach pola dostawcy w przestrzeni UWB. Platforma UWB próbuje określić kod kraju UWB przy użyciu poniższych źródeł (wymienionych w kolejności priorytetu). Ramy UWB przestają działać po pierwszym źródle, w którym określony jest kod kraju.
- Zastąpienie kodu kraju: kod kraju wymuszony za pomocą polecenia adb shell (testy lokalne lub zautomatyzowane).
- Kod kraju telefonicznego: kod kraju pobrany z komórki. Jeśli wiele kart SIM zwraca różne kody, wybrany kod kraju nie jest deterministyczny.
- Kod kraju Wi-Fi: kod kraju pobrany przez Wi-Fi (80211.ad).
- Ostatni znany kod kraju usług telefonicznych: ostatni znany kod kraju pobrany przez sieć komórkową. Jeśli masz kilka kart SIM, które zwracają różne kody, wybrany kod kraju jest niedeterministyczny.
- Kod kraju lokalizacji: kod kraju pobrany z usługodawcy lokalizacji z użyciem funkcji z ujednoliconym interfejsem.
LocationManager - Domyślny kod kraju OEM: kod kraju ustawiony przez producenta urządzenia.
Jeśli framework UWB nie może określić kodu kraju UWB, wywołuje polecenie UCI ANDROID_SET_COUNTRY_CODE o wartości DEFAULT_COUNTRY_CODE ("00") i powiadamia aplikacje UWB, że stan stosu UWB to DISABLED. Gdy usługa UWB wykryje prawidłowy kod kraju, skonfiguruje nowy kod kraju za pomocą polecenia ANDROID_SET_COUNTRY_CODE i powiadomi aplikacje UWB, że pakiet usług UWB jest READY.
Jeśli ze względu na lokalne przepisy obowiązujące w danym kraju nie można użyć UWB, kontroler UWB zwraca kod stanu STATUS_CODE_ANDROID_REGULATION_UWB_OFF. Następnie framework UWB powiadamia aplikacje UWB, że stan stosu UWB to 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 (na podstawie przepisów dotyczących UWB w nowym kraju) może to spowodować zmianę stanu modułu UWB.
Zdefiniowany w specyfikacji FIRA UCI format polecenia
Format pakietów sterujących UCI znajdziesz w sekcji 4.4.2 specyfikacji UCI.
Obsługa wersji interfejsu
Specyfikacja UCI pozwala dostawcom UWB ujawniać wersję stosu UCI zaimplementowaną przez urządzenie za pomocą poleceń UCI_GET_DEVICE_INFO_RSP i UCI_GET_CAPS_INFO_RSP. Platforma używa tych poleceń, aby pobrać wersję UCI urządzenia i odpowiednio zmienić jego działanie.
Lista projektów CR obsługiwanych przez moduł UWB
Te wersje robocze szablonów odpowiedzi dotyczących FiRa 2.0 są obsługiwane przez moduł UWB w wersji 330810000:
- CR 287
- Obsługa interfejsu SUS API i specyfikacji UCI w zakresie wymagań interfejsu cyfrowego klucza CCC
Interfejs UCI Androida (część dotycząca dostawcy FiRa)
Specyfikacja UCI definiuje zestaw identyfikatorów grup (GID) i identyfikatorów kodu operacji (OID) dla wszystkich komunikatów zdefiniowanych w specyfikacji. Specyfikacja rezerwuje też zestaw identyfikatorów GID do użytku wyłącznie przez dostawców. Stosunek AOSP UWB używa niektórych z tych identyfikatorów GID i OID dostawcy do poleceń specyficznych dla Androida, które nie są zdefiniowane w specyfikacji. Szczegółowe informacje znajdziesz w sekcji 8.4 specyfikacji UCI.
Te komunikaty dostawców używane przez Androida są zdefiniowane w pakiecie HAL android.hardware.uwb.fira_android.
Obsługa wersji interfejsu dostawcy
Dostawcy technologii UWB muszą udostępnić wersję pakietu android.hardware.uwb.fira_android
HAL obsługiwanego na urządzeniu za pomocą IUwbChip.getSupportedAndroidUciVersion(). Platforma wykorzystuje te informacje o wersji do obsługi zgodności wstecznej.
Lista identyfikatorów GID i OID na Androida
W tabeli poniżej znajdziesz identyfikatory GID i OID do Androida. Identyfikatory GID 0xE i 0xF są zarezerwowane dla producentów urządzeń na Androida.
| GID | OID | Definicja |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Służy do uzyskiwania statystyk dotyczących zasilania UWB.
Obsługiwane tylko wtedy, gdy UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY ma wartość 1. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Służy do ustawienia bieżącego kodu kraju (określanego za pomocą karty SIM lub Wi-Fi lub zakodowanego na stałe przez producenta OEM). Kod kraju jest wysyłany w postaci 2-bajtowej wartości odpowiadającej kodowi kraju ISO-3166. Wartość |
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
Używane przez powiadomienie do pobierania statystyk diagnostycznych zakresu UWB.
Obsługiwane tylko wtedy, gdy UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS ma wartość 1.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Zarezerwowane do użycia przez producentów OEM. |
Rozszerzenia dostawców do wiadomości zdefiniowanych w specyfikacji UCI
W tej sekcji opisano szczegóły rozszerzeń dostawców do wiadomości 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 zdefiniowane przez pakiet AOSP w części zarezerwowanej przez dostawcę w elementach TLV w APP_CONFIG:
- Identyfikator GID: 0001b (grupa konfiguracji sesji UWB)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD)
W tabeli poniżej znajdziesz parametry wiadomości konfiguracji sesji UWB.
| Nazwa parametru | Długość (oktety) |
Tag (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 element UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING ma wartość 1. |
NB_OF_AZIMUTH_MEASUREMENTS |
1 | 0xE4 |
1 | |
NB_OF_ELEVATION_MEASUREMENTS |
1 | 0xE5 |
1 | |
ENABLE_DIAGNOSTICS |
1 | 0xE8 |
2 | Wartość 1-bajtowa do włączania i wyłączania raportowania diagnostyki.
Skonfiguruj ten parametr tylko wtedy, gdy funkcja Wartości:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 lub 4 | 0xE9 |
2 | maska bitowa 1- lub 4-bajtowa do konfigurowania raportowania danych diagnostycznych. Ta maska bitowa ma rozmiar 1 bajt na Androidzie 14 lub nowszym i 4 bajty na Androidzie 13 lub starszym. Skonfiguruj ten parametr tylko wtedy, gdy funkcja Definicje bitów:
|
CORE_GET_CAPS_INFO_RSP
Oto listy TLV zdefiniowane przez pakiet AOSP w części TLV przeznaczonej dla dostawcy w pliku CAPS_INFO:
- GID: 0000b (grupa podstawowa UWB)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
W tabeli poniżej znajdziesz parametry wiadomości o możliwościach UWB.
| Nazwa parametru | Długość (oktety) |
Tag (identyfikatory) |
Wersja interfejsu dostawcy | Opis |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY |
1 | 0xC0 |
1 | Wartość 1 bajt wskazująca obsługę zapytania dotyczącego statystyk zasilania. Wartości:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | 1 bajtowa wartość wskazująca obsługę funkcji przeplatania anten. Wartości:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | Wartość 4-bajtowa wskazująca obsługiwany minimalny interwał pomiaru 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 | 1-bajtowa wartość wskazująca na 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 bajtów wskazująca obsługiwany minimalny czas trwania slotu w RSTU. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | Wartość 4 bajtów wskazująca obsługiwaną maksymalną liczbę sesji pomiarowych FiRa. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | 2-bajtowa maska bitowa wskazująca kanały obsługujące AoA. Każdy obiekt Wartości:
|
Kody stanu
Poniżej znajdują się kody stanu w obszarze dostawcy. Są one zwracane w odpowiedziach UCI (np. SESSION_START_RSP) przez podsystem UWB (UWBS).
| Kod stanu | Wartość | Opis |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x52 |
Kod stanu zwracany, gdy nie można rozpocząć bieżącej sesji pomiaru zasięgu z powodu konfliktu z innymi sesjami pomiaru zasięgu CCC lub FiRa. |
STATUS_REGULATION_UWB_OFF |
0x53 |
Kod stanu zwracany, gdy nie można rozpocząć bieżącej sesji pomiaru odległości z powodu ograniczeń dotyczących UWB. |
Kod powodu zmiany stanu w SESSION_STATUS_NTF
Poniżej znajdują się kody przyczyny zmiany stanu zdefiniowane w przestrzeni dostawcy dla pola stanu zwracanego przez UWBS w SESSION_STATUS_NTF. To powiadomienie jest wysyłane przez UWBS, gdy stan sesji pomiaru zasięgu ulegnie zmianie (np. z ACTIVE na IDLE).
| Kod przyczyny zmiany stanu | Wartość | Opis |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
Stan sesji zmienił się, ponieważ skonfigurowany kanał nie obsługuje zakresu AoA. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
Stan sesji zmienił się z powodu konfliktu z innymi sesjami CCC lub FiRa. |
REASON_REGULATION_UWB_OFF |
0x82 |
Stan sesji zmienił się, ponieważ UWB musi być wyłączony ze względów regulacyjnych. |