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 solchen ausgestellten 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 sind die beiden Hauptschnittstellen im Paket android.hardware.uwb aufgeführt.
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 gezeigt, 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). Das UWB-Framework versucht, den UWB-Ländercode anhand der folgenden Quellen zu ermitteln (nach Priorität aufgelistet). Das UWB-Framework stoppt an der ersten Quelle, in der der Ländercode bestimmt wird.
- Ländercode überschreiben: Der Ländercode wird über einen adb-Shell-Befehl erzwungen (lokale oder automatisierte Tests).
- 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.
- WLAN-Ländercode: Über WLAN (80211.ad) abgerufener Ländercode.
- Letzter bekannter Ländercode der Telefonie: Letzter bekannter Ländercode, der über das Mobilfunknetz abgerufen wurde. Wenn mehrere SIM-Karten unterschiedliche Codes zurückgeben, ist der ausgewählte Ländercode nicht deterministisch.
- Standort – Ländercode: Der Ländercode, der vom
LocationManager-Dienstleister für den kombinierten Standort abgerufen wurde. - 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. 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-Anwendungen, 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 verreist, 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 (gemäß den UWB-Bestimmungen im neuen Land) kann dies zu einer Änderung des UWB-Stackstatus führen.
Befehlsformat gemäß FIRA UCI-Spezifikation
Das Format von UCI-Kontrollpaketen findest du im 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 das 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-Spezifikation – Unterstützung für die Anforderungen der CCC Digital Key-Schnittstelle
Android-UCI-Oberfläche (FiRa-Anbieterbereich)
Die UCI-Spezifikation definiert einen Satz von Gruppenkennungen (GIDs) und Opcode-Identifikatoren (OIDs) für alle durch die 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 nicht in der Spezifikation 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 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() offenlegen. 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 Android-OEMs reserviert.
| GID | OID | Definition |
|---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Wird vom Befehl und der Antwort verwendet, um UWB-bezogene Statistiken zur Stromversorgung abzurufen.
Wird nur unterstützt, wenn UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY auf 1 gesetzt ist. |
ANDROID_SET_COUNTRY_CODE = 0x1 |
Wird verwendet, um den aktuellen länderspezifischen Code festzulegen (wird über die SIM oder das WLAN ermittelt oder vom OEM hartcodiert). Der Ländercode wird als 2-Byte-Wert gesendet, der dem ISO-3166-Ländercode entspricht. Der Wert |
|
ANDROID_RANGE_DIAGNOSTICS = 0x2 |
Wird von der Benachrichtigung verwendet, um UWB-Diagnosestatistiken für die Entfernungsmessung abzurufen.
Wird nur unterstützt, wenn UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS auf 1 gesetzt ist.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Für die Verwendung durch 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 Konfigurationsnachrichten für UWB-Sitzungen aufgeführt.
| Parametername | Länge (Oktette) |
Tag (IDs) |
Version der Anbieterschnittstelle | Beschreibung |
|---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS |
1 | 0xE3 |
1 | Interleaving-Verhältnis, wenn AOA_RESULT_REQ auf 0xF0 gesetzt ist. Wird nur unterstützt, wenn UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING auf 1 gesetzt ist. |
NB_OF_AZIMUTH_MEASUREMENTS |
1 | 0xE4 |
1 | |
NB_OF_ELEVATION_MEASUREMENTS |
1 | 0xE5 |
1 | |
ENABLE_DIAGNOSTICS |
1 | 0xE8 |
2 | Ein Byte-Wert, mit dem Diagnoseberichte aktiviert oder deaktiviert werden.
Konfigurieren Sie diesen Parameter nur, wenn Werte:
|
DIAGRAMS_FRAME_REPORTS_FIELDS |
1 oder 4 | 0xE9 |
2 | 1-Byte- oder 4-Byte-Bitmaske zum Konfigurieren der Diagnoseberichte. Diese Bitmaske ist 1 Byte unter Android 14 oder höher und 4 Byte unter Android 13 oder niedriger. Konfigurieren Sie diesen Parameter nur, wenn Bitdefinitionen:
|
CORE_GET_CAPS_INFO_RSP
Im Folgenden sind die vom AOSP-Stack im vom Anbieter reservierten Teil der TLVs in CAPS_INFO definierten TLVs aufgeführt:
- GID: 0000b (UWB-Kerngruppe)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP)
In der folgenden Tabelle sind die Parameter für UWB-Funktionsnachrichten aufgeführt.
| Parametername | Länge (Oktette) |
Tag (IDs) |
Version der Anbieterschnittstelle | Beschreibung |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY |
1 | 0xC0 |
1 | 1-Byte-Wert, der angibt, dass die Abfrage für Leistungsstatistiken unterstützt wird. Werte:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | 1 Byte-Wert, der die Unterstützung der Antennenverschränkungsfunktion angibt. Werte:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | Ein 4-Byte-Wert, der das unterstützte minimale Intervall für die Reichweitenmessung in Millisekunden angibt. |
SUPPORTED_RANGE_DATA_NTF_CONFIG |
4 | 0xE5 |
2 | 4-Byte-Bitmaske, die die unterstützten RANGE_DATA_NTF_CONFIG-Werte angibt.
Bitmaske, bei der jedes Bit den Werten in RANGE_DATA_NTF_CONFIG in SET_APP_CFG_CMD entspricht. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | 1-Byte-Wert, der die Unterstützung von RSSI-Berichten angibt. Werte:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | Ein Byte-Wert, der die Unterstützung von Diagnoseberichten angibt. Werte:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU |
4 | 0xE8 |
2 | Ein 4-Byte-Wert, der die unterstützte Mindestdauer des Slots in RSTU angibt. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | Ein 4-Byte-Wert, der die maximal unterstützte Anzahl von FiRa-Messsitzungen angibt. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | 2‑Byte-Bitmaske, die die Kanäle angibt, die AoA unterstützen. Jede Werte:
|
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.
| Status code | Wert | Beschreibung |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x52 |
Statuscode, der zurückgegeben wird, wenn die aktuelle Rangierungssitzung aufgrund eines Konflikts mit anderen CCC- oder FiRa-Rangierungssitzungen nicht gestartet werden kann. |
STATUS_REGULATION_UWB_OFF |
0x53 |
Statuscode, der zurückgegeben wird, wenn die aktuelle Messsitzung aus UWB-rechtlichen Gründen nicht gestartet werden kann. |
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).
| Code für den Grund der Statusänderung | Wert | Beschreibung |
|---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
Der Sitzungsstatus hat sich geändert, da der konfigurierte Kanal die AoA-Messung nicht unterstützt. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
Der Sitzungsstatus hat sich aufgrund eines Konflikts mit anderen CCC- oder FiRa-Bereichssitzungen geändert. |
REASON_REGULATION_UWB_OFF |
0x82 |
Der Sitzungsstatus hat sich geändert, da UWB aus rechtlichen Gründen deaktiviert werden muss. |