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 undurchsichtige Pipe (IUwbChip::sendUciMessage() und IUwbClientCallback::onUciMessage()), um UCI-Befehle (UWB Command Interface), 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-Spezifikationen im Entwurf hinzufügen, die auf wichtige FiRa-Standardversionen ausgerichtet sind. Alle so implementierten CR-Entwürfe können sich ändern.

Schnittstellendefinition

Die UWB-HAL-Schnittstelle wird mit stabiler AIDL definiert. Die Hauptschnittstelle verwendet das Paket android.hardware.uwb.

Im Folgenden werden die beiden wichtigsten Schnittstellen 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 über das UWB-Framework

Die folgenden Bilder veranschaulichen den Aufrufablauf vom UWB-Framework für die Initialisierung und Deinitialisierung des UWB-Stacks sowie für das Starten und Beenden von UWB-Sitzungen.

Abbildung 1: UWB-Stack-Initialisierungsablauf (UWB-Schalter aktiviert)

Abbildung 2: Ablauf des Deinitialisierungsaufrufs des UWB-Stacks (UWB-Schalter aus)

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-Ländercode während der Initialisierung des UWB-Stacks mit dem UCI-Befehl ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1) im Vendor-Bereich. Das UWB-Framework versucht, den UWB-Ländercode anhand der folgenden Quellen zu ermitteln (in Prioritätsreihenfolge aufgeführt). Das UWB-Framework wird bei der ersten Quelle beendet, in der der Ländercode ermittelt wird.

1. Ländercode überschreiben: Ländercode, der durch einen adb-Shell-Befehl erzwungen wird (lokale oder automatisierte Tests).
2. Landesvorwahl für Telefonie: Über Mobilfunk abgerufene Landesvorwahl. Wenn mehrere SIMs unterschiedliche Codes zurückgeben, ist der ausgewählte Ländercode nicht deterministisch.
3. WLAN-Ländercode: Ländercode, der über WLAN (80211.ad) abgerufen wird.
4. Letzte bekannte Landesvorwahl: Die letzte bekannte Landesvorwahl, die über das Mobilfunknetz abgerufen wurde. Wenn mehrere SIMs unterschiedliche Codes zurückgeben, ist der ausgewählte Ländercode nicht deterministisch.
5. Standort – Ländercode: Ländercode, der vom LocationManager-Anbieter für zusammengeführte Standorte abgerufen wurde.
6. Standardländercode des Erstausrüsters: Der vom Gerätehersteller festgelegte Ländercode.

Wenn das UWB-Framework keinen UWB-Ländercode 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. Wenn das UWB-Framework später 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. Abhängig vom Statuscode, der vom UWB-Controller zurückgegeben wird (basierend auf den UWB-Bestimmungen im neuen Land), kann dies zu einer Änderung des UWB-Stack-Status führen.

Befehlsformat gemäß FIRA UCI-Spezifikation

Informationen zum Format von UCI-Steuerpaketen finden Sie im Abschnitt 4.4.2 der UCI-Spezifikation.

Versionsverwaltung für Schnittstellen

Mit der UCI-Spezifikation können UWB-Anbieter die Version des UCI-Stacks, der vom Gerät implementiert wird, über die Befehle UCI_GET_DEVICE_INFO_RSP und UCI_GET_CAPS_INFO_RSP verfügbar machen. Das Framework verwendet diese Befehle, um die UCI-Version des Geräts abzurufen und das Verhalten entsprechend zu ändern.

Liste der vom UWB-Modul unterstützten CR-Entwürfe

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

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

Android-UCI-Schnittstelle (FiRa-Anbieterteil)

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

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

Versionsverwaltung der Anbieterschnittstelle

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() verfügbar machen. Das Framework verwendet diese Versionsinformationen, um die Abwärtskompatibilität zu gewährleisten.

Liste der Android-GIDs und ‑OIDs

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

Anbietererweiterungen für Nachrichten, die in der UCI-Spezifikation definiert sind

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

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

Die folgenden Typ-Längen-Werte (Type-Length-Values, TLVs) werden vom AOSP-Stack im für den Anbieter reservierten Teil der TLVs in APP_CONFIG definiert:

• 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 sind die TLVs aufgeführt, die vom AOSP-Stack im anbieterreservierten Teil der TLVs in CAPS_INFO definiert werden:

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

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

Status codes

Im Anbieterbereich sind die folgenden Statuscodes verfügbar. Diese werden in UCI-Antworten (z. B. SESSION_START_RSP) vom UWB-Subsystem (UWBS) zurückgegeben.

Grundcode für Statusänderung in SESSION_STATUS_NTF

Im Anbieterbereich sind die folgenden Grundcodes für Statusänderungen 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 Ranging-Sitzung ändert (z. B. von ACTIVE zu IDLE).