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.
- Ländercode überschreiben: Ländercode, der durch einen adb-Shell-Befehl erzwungen wird (lokale oder automatisierte Tests).
- Landesvorwahl für Telefonie: Über Mobilfunk abgerufene Landesvorwahl. Wenn mehrere SIMs unterschiedliche Codes zurückgeben, ist der ausgewählte Ländercode nicht deterministisch.
- WLAN-Ländercode: Ländercode, der über WLAN (80211.ad) abgerufen wird.
- 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.
- Standort – Ländercode: Ländercode, der vom
LocationManager
-Anbieter für zusammengeführte Standorte abgerufen wurde. - 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.
GID | OID | Definition |
---|---|---|
ANDROID = 0xC |
ANDROID_GET_POWER_STATS = 0x0 |
Wird vom Befehl und der Antwort verwendet, um UWB-Leistungsstatistiken 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ändercode für die behördliche Genehmigung festzulegen (wird über die SIM-Karte, WLAN oder vom OEM fest codiert bestimmt). 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 Statistiken zur UWB-Entfernungsmessung abzurufen.
Wird nur unterstützt, wenn UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS auf 1 gesetzt ist.
|
|
OEM = 0xE,0xF |
0x00 - 0x3F |
Für die OEM-Verwendung 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.
Parametername | Länge (Oktette) |
Tag (IDs) |
Version der Anbieterschnittstelle | Beschreibung |
---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS |
1 | 0xE3 |
1 | Verschachtelungsverhä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 | 1‑Byte-Wert zum Aktivieren oder Deaktivieren der Diagnoseberichterstellung.
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 Diagnoseberichterstellung. Diese Bitmaske ist in Android 14 oder höher 1 Byte und in Android 13 oder niedriger 4 Byte groß. Konfigurieren Sie diesen Parameter nur, wenn Bitdefinitionen:
|
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.
Parametername | Länge (Oktette) |
Tag (IDs) |
Version der Anbieterschnittstelle | Beschreibung |
---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY |
1 | 0xC0 |
1 | 1 Byte-Wert, der angibt, ob die Abfrage von Leistungsstatistiken unterstützt wird. Werte:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING |
1 | 0xE3 |
1 | 1-Byte-Wert, der die Unterstützung für das Feature „Antenna Interleaving“ angibt. Werte:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS |
4 | 0xE4 |
2 | 4‑Byte-Wert, der das unterstützte minimale Intervall für die Entfernungsmessung 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, in der jedes Bit den Werten entspricht, die in RANGE_DATA_NTF_CONFIG in SET_APP_CFG_CMD verwendet werden. |
SUPPORTED_RSSI_REPORTING |
1 | 0xE6 |
2 | 1-Byte-Wert, der angibt, ob RSSI-Berichte unterstützt werden. Werte:
|
SUPPORTED_DIAGNOSTICS |
1 | 0xE7 |
2 | 1-Byte-Wert, der angibt, ob die Berichterstellung für Diagnosen unterstützt wird. Werte:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU |
4 | 0xE8 |
2 | 4-Byte-Wert, der die unterstützte Mindestdauer des Slots in RSTU angibt. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER |
4 | 0xE9 |
2 | 4-Byte-Wert, der die maximal unterstützte Anzahl von FiRa-Ranging-Sitzungen angibt. |
SUPPORTED_CHANNELS_AOA |
2 | 0xEA |
2 | 2-Byte-Bitmaske zur Angabe der Kanäle, die AoA unterstützen. Jedes Werte:
|
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.
Status code | Wert | Beschreibung |
---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x52 |
Statuscode, der zurückgegeben wird, wenn die aktuelle Ranging-Sitzung aufgrund eines Konflikts mit anderen CCC- oder FiRa-Ranging-Sitzungen nicht gestartet werden kann. |
STATUS_REGULATION_UWB_OFF |
0x53 |
Statuscode, der zurückgegeben wird, wenn die aktuelle Ranging-Sitzung aus UWB-rechtlichen Gründen nicht gestartet werden kann. |
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
).
Grundcode für Statusänderung | Wert | Beschreibung |
---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA |
0x80 |
Der Sitzungsstatus hat sich geändert, da der konfigurierte Channel die AoA-Entfernungsmessung nicht unterstützt. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT |
0x81 |
Der Sitzungsstatus hat sich aufgrund eines Konflikts mit anderen CCC- oder FiRa-Ranging-Sitzungen geändert. |
REASON_REGULATION_UWB_OFF |
0x82 |
Der Sitzungsstatus wurde geändert, da UWB aus rechtlichen Gründen deaktiviert werden muss. |