Interfejs UWB HAL

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.

Inicjalizacja stosu UWB

Rysunek 1. Przepływ wywołań inicjujących stos UWB (włączony przełącznik UWB)

Deinicjalizacja stosu UWB

Rysunek 2. Przepływ wywołań deinicjalizacji stosu UWB (przełącznik UWB wyłączony)

Rozpoczynanie i zatrzymywanie sesji UWB

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.

  1. Zastąp kod kraju: kod kraju wymuszony za pomocą polecenia powłoki adb (testowanie lokalne lub automatyczne).
  2. 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.
  3. Kod kraju Wi-Fi: Kod kraju pobrany przez Wi-Fi (80211.ad).
  4. 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.
  5. Kod kraju lokalizacji: Kod kraju pobrany od dostawcy połączonej lokalizacji LocationManager .
  6. 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ść 00 oznacza, że ​​kod kraju jest nieznany.

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 CORE_GET_CAPS_INFO_RSP zwraca SUPPORTED_DIAGNOSTICS z wartością 1 wskazującą, że obsługiwana jest funkcja raportowania diagnostycznego.

Wartości:

  • 1 : Funkcja włączona
  • 0 : Funkcja wyłączona

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 CORE_GET_CAPS_INFO_RSP zwraca SUPPORTED_DIAGNOSTICS z wartością 1 wskazującą, że obsługiwana jest funkcja raportowania diagnostycznego.

Definicje bitów:

  • b0 (0x01) : Aktywuj pola RSSI
  • b1 (0x02) : Aktywuj pola AoA
  • b2 (0x04) : Aktywuj pola CIR

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:

  • 1 : Obsługiwana funkcja
  • 0 : Funkcja nieobsługiwana
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

Wartość 1-bajtowa wskazująca obsługę funkcji przeplatania anteny.

Wartości:

  • 1 : Obsługiwana funkcja
  • 0 : Funkcja nieobsługiwana
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:

  • 1 : Obsługiwana funkcja
  • 0 : Funkcja nieobsługiwana
SUPPORTED_DIAGNOSTICS 1 0xE7 2

Wartość 1-bajtowa wskazująca obsługę raportowania diagnostycznego.

Wartości:

  • 1 : Obsługiwana funkcja
  • 0 : Funkcja nieobsługiwana
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 1 w masce bitowej odpowiada konkretnemu kanałowi UWB.

Wartości:

  • 0x01 : Obsługiwany kanał 5
  • 0x02 : Obsługiwany kanał 6
  • 0x04 : Obsługiwany kanał 8
  • 0x08 : Obsługiwany kanał 9
  • 0x10 : Obsługiwany kanał 10
  • 0x20 : Obsługiwany kanał 12
  • 0x40 : Obsługiwany kanał 13
  • 0x80 : Obsługiwany kanał 14

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.