Der AOSP Ultra-Wideband (UWB)-Stack verwendet die von FiRa definierte UCI-Schnittstelle als HAL-Oberfläche. Die HAL-Schnittstelle verwendet eine undurchsichtige Pipe ( IUwbChip::sendUciMessage() und IUwbClientCallback::onUciMessage() ), um Befehle, Antworten und Benachrichtigungen der UWB-Befehlsschnittstelle (UCI) 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 vom UWB-Anbieter auf dem Gerät implementierten UCI-Version. Da es sich beim AOSP-UWB-Framework um ein Modul handelt, kann es auch selektiv Unterstützung für genehmigte Änderungsanfragen (CRs) aus UCI-Spezifikationsentwürfen hinzufügen, die für wichtige FiRa-Standardversionen vorgesehen sind. Alle derart umgesetzten CR-Entwürfe können sich ändern.
Schnittstellendefinition
Die UWB-HAL-Schnittstelle wird mit stabilem AIDL definiert. Die Hauptschnittstelle 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-Anruffluss vom UWB-Framework
Die folgenden Bilder veranschaulichen den Aufrufablauf vom UWB-Framework für die Initialisierung des UWB-Stacks, die Deinitialisierung des UWB-Stacks sowie die Start- und Stoppprozesse der UWB-Sitzung.
Abbildung 1. Aufrufablauf für die UWB-Stack-Initialisierung (UWB einschalten)
Abbildung 2. Aufrufablauf für die Deinitialisierung des UWB-Stacks (UWB ausschalten)
Abbildung 3. Start-/Stopp-Ablauf der UWB-Sitzung
Konfiguration des UWB-Ländercodes
Wie in Abbildung 1 dargestellt, konfiguriert das UWB-Framework den UWB-Ländercode während der UWB-Stack-Initialisierung mithilfe des Hersteller-Space-UCI-Befehls ANDROID_SET_COUNTRY_CODE (GID= 0xC , OID= 0x1 ). Das UWB-Framework versucht, den UWB-Ländercode anhand der folgenden Quellen zu ermitteln (in der Reihenfolge der Priorität aufgeführt). Das UWB-Framework stoppt bei der ersten Quelle, in der der Ländercode ermittelt wird.
- Ländercode überschreiben: Ländercode, der durch einen ADB-Shell-Befehl erzwungen wird (lokaler oder automatisierter Test).
- Telefon-Ländercode: Ländercode, der über das Mobilfunknetz abgerufen wird. Wenn es mehrere SIMs gibt, die unterschiedliche Codes zurückgeben, ist der gewählte Ländercode nicht deterministisch.
- Wi-Fi-Ländercode: Über Wi-Fi abgerufener Ländercode (80211.ad).
- Letzter bekannter Telefon-Ländercode: Letzter bekannter Ländercode, der über das Mobilfunknetz abgerufen wurde. Wenn es mehrere SIMs gibt, die unterschiedliche Codes zurückgeben, ist der gewählte Ländercode nicht deterministisch.
- Standort-Ländercode: Ländercode, der vom
LocationManagerAnbieter für zusammengeführte Standorte abgerufen wird. - OEM-Standard-Ländercode: Vom Gerätehersteller festgelegter 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 Vorschriften 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 Benutzer in ein anderes Land reist, konfiguriert das UWB-Framework mithilfe des UCI-Befehls ANDROID_SET_COUNTRY_CODE einen neuen Ländercode. Abhängig vom vom UWB-Controller zurückgegebenen Statuscode (basierend auf den UWB-Vorschriften im neuen Land) kann dies zu einer Änderung des UWB-Stack-Status führen.
Durch die FIRA UCI-Spezifikation definiertes Befehlsformat
Informationen zum Format von UCI-Kontrollpaketen finden Sie in Abschnitt 4.4.2 der UCI-Spezifikation .
Schnittstellenversionierung
Mit der UCI-Spezifikation können UWB-Anbieter die vom Gerät implementierte Version des UCI-Stacks mithilfe der Befehle UCI_GET_DEVICE_INFO_RSP und UCI_GET_CAPS_INFO_RSP offenlegen. 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 CR-Entwürfe
Die folgenden CR-Entwürfe für FiRa 2.0 werden von der UWB- Modulversion Nr. 330810000 unterstützt:
Android UCI-Schnittstelle (FiRa-Anbieterteil)
Die UCI-Spezifikation definiert eine Reihe von Gruppenkennungen (GIDs) und Opcode-Kennungen (OIDs) für alle in der Spezifikation definierten Nachrichten. Die Spezifikation reserviert außerdem eine Reihe von GIDs, die ausschließlich der Verwendung durch Anbieter vorbehalten sind. Der AOSP-UWB-Stack verwendet einige dieser Hersteller-GIDs und OIDs für Android-spezifische Befehle, die nicht in der Spezifikation definiert sind. Einzelheiten finden Sie in Abschnitt 8.4 der UCI-Spezifikation .
Diese von Android verwendeten Herstellermeldungen sind im HAL-Paket android.hardware.uwb.fira_android definiert.
Versionierung der Anbieterschnittstelle
UWB-Anbieter müssen die Version des auf dem Gerät unterstützten HAL-Pakets android.hardware.uwb.fira_android über IUwbChip.getSupportedAndroidUciVersion() offenlegen. Das Framework verwendet diese Versionsinformationen, um die Abwärtskompatibilität zu handhaben.
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 Statistiken zur UWB-Leistung 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 gesetzlichen Ländercode festzulegen (ermittelt über SIM oder Wi-Fi oder vom OEM fest codiert). 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-Bereichsdiagnosestatistiken abzurufen. Wird nur unterstützt, wenn UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS auf 1 festgelegt ist. | |
OEM = 0xE,0xF | 0x00 - 0x3F | Reserviert für OEM-Nutzung. |
Herstellererweiterungen für in der UCI-Spezifikation definierte Nachrichten
In diesem Abschnitt werden Einzelheiten zu Herstellererweiterungen für in der UCI-Spezifikation definierte Nachrichten beschrieben.
SESSION_SET_APP_CONFIG_[CMD|RSP] und SESSION_GET_APP_CONFIG_[CMD|RSP]
Im Folgenden sind die Typlängenwerte (TLVs) aufgeführt, die vom AOSP-Stack im vom Anbieter reservierten Teil der TLVs in APP_CONFIG definiert werden:
- 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) | Etikett (IDs) | Version der Herstellerschnittstelle | 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 Diagnoseberichterstattung. 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 in Android 14 oder höher und 4 Bytes in Android 13 oder niedriger. Konfigurieren Sie diesen Parameter nur, wenn Bitdefinitionen:
|
CORE_GET_CAPS_INFO_RSP
Im Folgenden sind die TLVs aufgeführt, die vom AOSP-Stack im vom Anbieter reservierten 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-Fähigkeitsmeldungen aufgeführt.
| Parametername | Länge (Oktette) | Etikett (IDs) | Version der Herstellerschnittstelle | Beschreibung |
|---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | 1-Byte-Wert, der die Unterstützung für die Abfrage von Leistungsstatistiken angibt. Werte:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | 1-Byte-Wert, der die Unterstützung für die Antennen-Interleaving-Funktion angibt. Werte:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | 4-Byte-Wert, der das unterstützte Mindestbereichsintervall 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, wobei jedes Bit den in RANGE_DATA_NTF_CONFIG in SET_APP_CFG_CMD verwendeten Werten entspricht. |
SUPPORTED_RSSI_REPORTING | 1 | 0xE6 | 2 | 1-Byte-Wert, der die Unterstützung der RSSI-Berichterstellung angibt. Werte:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | 1-Byte-Wert, der die Unterstützung der Diagnoseberichterstattung angibt. Werte:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | 4-Byte-Wert, der die unterstützte minimale Slotdauer in RSTU angibt. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER | 4 | 0xE9 | 2 | 4-Byte-Wert, der die unterstützte maximale Anzahl von FiRa-Ranging-Sitzungen angibt. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | 2-Byte-Bitmaske zur Angabe der Kanäle, die AoA unterstützen. Jede Werte:
|
Statuscodes
Im Folgenden sind die Statuscodes im Anbieterbereich aufgeführt. Diese werden in UCI-Antworten (z. B. SESSION_START_RSP ) vom UWB-Subsystem (UWBS) zurückgegeben.
| Statuscode | Wert | Beschreibung |
|---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x52 | Der Statuscode wird zurückgegeben, wenn die aktuelle Ranging-Sitzung aufgrund eines Konflikts mit anderen CCC- oder FiRa-Ranging-Sitzungen nicht gestartet werden kann. |
STATUS_REGULATION_UWB_OFF | 0x53 | Der Statuscode wird zurückgegeben, wenn die aktuelle Ranging-Sitzung aus regulatorischen Gründen für UWB nicht gestartet werden kann. |
Code für den Statusänderungsgrund in SESSION_STATUS_NTF
Im Folgenden sind die Statusänderungs-Ursachencodes aufgeführt, die im Anbieterbereich für das von einem UWBS in SESSION_STATUS_NTF zurückgegebene Statusfeld definiert sind. Diese Benachrichtigung wird vom UWBS gesendet, wenn sich der Status einer Ranging-Sitzung ä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 das AoA-Ranging 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 hat sich geändert, da die UWB aus regulatorischen Gründen deaktiviert werden muss. |