UWB-HAL-Schnittstelle

Der Ultrabreitband-Stack (UWB) von AOSP verwendet die von FiRa definierte UCI-Schnittstelle als HAL-Oberfläche. Die HAL-Schnittstelle verwendet eine opake Pipe (IUwbChip::sendUciMessage() und IUwbClientCallback::onUciMessage()), um UWB-Befehle, ‑Antworten und ‑Benachrichtigungen zu senden und zu empfangen. Alle Android-UWB-Anbieter müssen alle in der FiRa-Spezifikation definierten Nachrichten unterstützen. Das UWB-Framework ist abwärtskompatibel und funktioniert mit jeder UCI-Version, die vom UWB-Anbieter auf dem Gerät implementiert wurde. Da das AOSP UWB-Framework ein Modul ist, kann es auch selektiv Unterstützung für genehmigte Änderungsanfragen (Change Requests, CRs) aus UCI-Entwurfsspezifikationen hinzufügen, die auf wichtige FiRa-Standardveröffentlichungen ausgerichtet sind. Alle implementierten Entwürfe von Antwortvorlagen können sich ändern.

Schnittstellendefinition

Die UWB HAL-Schnittstelle wird mit stabilem AIDL definiert. Die Hauptoberfläche verwendet das Paket android.hardware.uwb.

Im Folgenden werden die beiden Hauptoberflächen im android.hardware.uwb-Paket beschrieben.

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);

}

HAL-Aufrufablauf vom UWB-Framework

Die folgenden Bilder veranschaulichen den Aufrufablauf vom UWB-Framework für die UWB-Stack-Initialisierung, die UWB-Stack-Deinitialisierung und die UWB-Sitzungsstart- und -Stopp-Prozesse.

Abbildung 1: Aufrufablauf für die UWB-Stack-Initialisierung (UWB-Schalter aktiviert)

Abbildung 2: Aufrufabfolge für die Deinitialisierung des UWB-Stacks (UWB-Schalter deaktiviert)

Abbildung 3: Ablauf zum Starten/Beenden einer UWB-Sitzung

Konfiguration des UWB-Ländercodes

Wie in Abbildung 1 dargestellt, konfiguriert das UWB-Framework den UWB-Landescode während der UWB-Stack-Initialisierung mit dem UCI-Befehl ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1) aus dem Anbieterbereich. Das UWB-Framework versucht, den UWB-Landescode anhand der folgenden Quellen zu ermitteln (in Prioritätsreihenfolge aufgeführt). Das UWB-Framework stoppt bei der ersten Quelle, an der der Ländercode ermittelt wird.

1. Ländercode überschreiben: Der Ländercode wird über einen adb-Shell-Befehl erzwungen (lokale oder automatisierte Tests).
2. Landesvorwahl für Telefonie: Landesvorwahl, die über das Mobilfunknetz abgerufen wird. Wenn mehrere SIM-Karten unterschiedliche Codes zurückgeben, ist der ausgewählte Ländercode nicht deterministisch.
3. WLAN-Ländercode: Über WLAN (80211.ad) abgerufener Ländercode.
4. Letzte bekannte Ländervorwahl für Telefonie: Letzte bekannte Ländervorwahl, die über das Mobilfunknetz abgerufen wurde. Wenn mehrere SIM-Karten unterschiedliche Codes zurückgeben, ist der ausgewählte Ländercode nicht deterministisch.
5. Standort – Ländercode: Der Ländercode, der vom LocationManager-Dienstleister für den kombinierten Standort abgerufen wurde.
6. OEM-Standard-Ländercode: Der vom Gerätehersteller festgelegte Ländercode.

Wenn das UWB-Framework keinen UWB-Landescode ermitteln kann, ruft es den UCI-Befehl ANDROID_SET_COUNTRY_CODE mit dem Wert DEFAULT_COUNTRY_CODE ("00") auf und benachrichtigt UWB-Apps, dass der UWB-Stack-Status DISABLED ist. Später, wenn das UWB-Framework einen gültigen Ländercode ermitteln kann, konfiguriert es den neuen Ländercode mit dem Befehl ANDROID_SET_COUNTRY_CODE und benachrichtigt UWB-Apps, dass der UWB-Stack READY ist.

Wenn UWB aufgrund lokaler Bestimmungen in einem Land nicht verwendet werden kann, gibt der UWB-Controller den Statuscode STATUS_CODE_ANDROID_REGULATION_UWB_OFF zurück. Das UWB-Framework benachrichtigt dann UWB-Apps, dass der UWB-Stack-Status DISABLED ist.

Wenn ein Nutzer in ein anderes Land reist, konfiguriert das UWB-Framework mit dem UCI-Befehl ANDROID_SET_COUNTRY_CODE einen neuen Ländercode. Je nach dem vom UWB-Controller zurückgegebenen Statuscode (basierend auf den UWB-Bestimmungen im neuen Land) kann dies zu einer Änderung des UWB-Stack-Status führen.

Befehlsformat gemäß FIRA UCI-Spezifikation

Das Format von UCI-Kontrollpaketen findest du in Abschnitt 4.4.2 der UCI-Spezifikation.

Versionierung der Benutzeroberfläche

Mit der UCI-Spezifikation können UWB-Anbieter die Version des vom Gerät implementierten UCI-Stacks mit den Befehlen UCI_GET_DEVICE_INFO_RSP und UCI_GET_CAPS_INFO_RSP freigeben. Das Framework verwendet diese Befehle, um die UCI-Version des Geräts abzurufen und sein Verhalten entsprechend zu ändern.

Liste der vom UWB-Modul unterstützten Entwurfs-CRs

Die folgenden CR-Entwürfe für FiRa 2.0 werden vom UWB-Modul Version 330810000 unterstützt:

• CR 287
• SUS API- und UCI-Spezifikationsunterstützung für die Anforderungen der CCC Digital Key-Schnittstelle

Android-UCI-Oberfläche (FiRa-Anbieterbereich)

Die UCI-Spezifikation definiert eine Reihe von Gruppen-IDs (GIDs) und Opcode-IDs (OIDs) für alle in der Spezifikation definierten Nachrichten. Die Spezifikation reserviert auch eine Reihe von GIDs, die ausschließlich für die Nutzung durch Anbieter reserviert sind. Der AOSP-UWB-Stack verwendet einige dieser Anbieter-GIDs und -OIDs für Android-spezifische Befehle, die in der Spezifikation nicht definiert sind. Weitere Informationen finden Sie im Abschnitt 8.4 der UCI-Spezifikation.

Diese von Android verwendeten Anbieternachrichten sind im HAL-Paket android.hardware.uwb.fira_android definiert.

Versionierung der Anbieteroberfläche

UWB-Anbieter müssen die Version des android.hardware.uwb.fira_android-HAL-Pakets, das auf dem Gerät unterstützt wird, über IUwbChip.getSupportedAndroidUciVersion() offenlegen. Das Framework verwendet diese Versionsinformationen, um die Abwärtskompatibilität zu gewährleisten.

Liste der Android-Gruppen-IDs und -Objekt-IDs

In der folgenden Tabelle sind die GIDs und OIDs für Android aufgeführt. Die GIDs 0xE und 0xF sind für Android-OEMs reserviert.

Anbietererweiterungen für in der UCI-Spezifikation definierte Nachrichten

In diesem Abschnitt werden Details zu Anbietererweiterungen für von der UCI-Spezifikation definierte Nachrichten beschrieben.

SESSION_SET_APP_CONFIG_[CMD|RSP] und SESSION_GET_APP_CONFIG_[CMD|RSP]

Im vom AOSP-Stack im vom Anbieter reservierten Teil der TLVs in APP_CONFIG definierten Typlängenwerte (TLVs):

• GID: 0001b (UWB-Sitzungskonfigurationsgruppe)
• OID: 000011b (SESSION_SET_APP_CONFIG_CMD)
• OID: 000100b (SESSION_GET_APP_CONFIG_CMD)

In der folgenden Tabelle sind die Parameter für UWB-Sitzungskonfigurationsnachrichten aufgeführt.

CORE_GET_CAPS_INFO_RSP

Im Folgenden finden Sie die vom AOSP-Stack im vom Anbieter reservierten Teil der TLVs in CAPS_INFO definierten TLVs:

• GID: 0000b (UWB-Kerngruppe)
• OID: 000011b (CORE_GET_CAPS_INFO_RSP)

In der folgenden Tabelle sind die Parameter für UWB-Funktionsnachrichten aufgeführt.

Status codes

Im Folgenden finden Sie die Statuscodes im Anbieterbereich. Diese werden vom UWB-Subsystem (UWBS) in UCI-Antworten (z. B. SESSION_START_RSP) zurückgegeben.

Code für den Grund der Statusänderung in SESSION_STATUS_NTF

Im Anbieterbereich sind die folgenden Statusänderungsgrundcodes für das Statusfeld definiert, das von einem UWBS in SESSION_STATUS_NTF zurückgegeben wird. Diese Benachrichtigung wird vom UWBS gesendet, wenn sich der Status einer Messsitzung ändert (z. B. von ACTIVE zu IDLE).