AOSP ultra geniş bant (UWB) yığını, HAL yüzeyi olarak FiRa tanımlı UCI arayüzünü kullanır. HAL arayüzü, UWB komut arayüzü (UCI) komutlarını, yanıtlarını ve bildirimlerini göndermek ve almak için opak bir kanal ( IUwbChip::sendUciMessage()
ve IUwbClientCallback::onUciMessage()
) kullanır. Tüm Android UWB satıcıları, FiRa spesifikasyonuyla tanımlanan tüm mesajları desteklemelidir. UWB çerçevesi geriye dönük olarak uyumludur ve UWB satıcısı tarafından cihaza uygulanan herhangi bir UCI sürümüyle çalışır. AOSP UWB çerçevesi bir modül olduğundan, önemli FiRa standart sürümleri için hedeflenen taslak UCI spesifikasyonlarından onaylanmış değişiklik istekleri (CR'ler) için seçici olarak destek de ekleyebilir. Uygulanan bu tür taslak CR'ler değişikliğe tabidir.
Arayüz tanımı
UWB HAL arayüzü kararlı AIDL kullanılarak tanımlanır. Ana arayüz android.hardware.uwb
paketini kullanır.
android.hardware.uwb
paketindeki iki ana arayüz aşağıdadır.
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);
}
UWB çerçevesinden HAL çağrı akışı
Aşağıdaki resimlerde UWB yığın başlatma, UWB yığın başlatmama ve UWB oturumu başlatma ve durdurma işlemleri için UWB çerçevesinden gelen çağrı akışı gösterilmektedir.
Şekil 1. UWB yığını başlatma çağrısı akışı (UWB düğmesi açık)
Şekil 2. UWB yığınını başlatmama çağrısı akışı (UWB kapalı)
Şekil 3. UWB oturumu başlatma/durdurma akışı
UWB ülke kodu yapılandırması
Şekil 1'de gösterildiği gibi, UWB çerçevesi, satıcı alanı UCI komutunu ANDROID_SET_COUNTRY_CODE
(GID= 0xC
, OID= 0x1
) kullanarak UWB yığını başlatma sırasında UWB ülke kodunu yapılandırır. UWB çerçevesi, aşağıdaki kaynakları (öncelik sırasına göre listelenmiştir) kullanarak UWB ülke kodunu belirlemeye çalışır. UWB çerçevesi, ülke kodunun belirlendiği ilk kaynakta durur.
- Ülke kodunu geçersiz kıl: Bir adb kabuk komutu aracılığıyla zorlanan ülke kodu (yerel veya otomatik test).
- Telefon ülke kodu: Cep telefonundan alınan ülke kodu. Farklı kodlar döndüren birden fazla SIM varsa seçilen ülke kodu belirleyici değildir.
- Wi-Fi ülke kodu: Wi-Fi (80211.ad) aracılığıyla alınan ülke kodu.
- Bilinen son telefon ülke kodu: Cep telefonundan alınan bilinen son ülke kodu. Farklı kodlar döndüren birden fazla SIM varsa seçilen ülke kodu belirleyici değildir.
- Konum ülke kodu:
LocationManager
ile birleştirilmiş konum sağlayıcısından alınan ülke kodu. - OEM varsayılan ülke kodu: Cihaz üreticisi tarafından belirlenen ülke kodu.
UWB çerçevesi bir UWB ülke kodunu belirleyemezse, DEFAULT_COUNTRY_CODE ("00")
değeriyle ANDROID_SET_COUNTRY_CODE
UCI komutunu çağırır ve UWB uygulamalarına UWB yığın durumunun DISABLED
olduğunu bildirir. Daha sonra UWB çerçevesi geçerli bir ülke kodu belirleyebildiğinde, ANDROID_SET_COUNTRY_CODE
komutunu kullanarak yeni ülke kodunu yapılandırır ve UWB uygulamalarına UWB yığınının READY
olduğunu bildirir.
Bir ülkedeki yerel düzenlemeler nedeniyle UWB kullanılamıyorsa, UWB denetleyicisi STATUS_CODE_ANDROID_REGULATION_UWB_OFF
durum kodunu döndürür. UWB çerçevesi daha sonra UWB uygulamalarına UWB yığın durumunun DISABLED
olduğunu bildirir.
Bir kullanıcı farklı bir ülkeye seyahat ettiğinde UWB çerçevesi, ANDROID_SET_COUNTRY_CODE
UCI komutunu kullanarak yeni bir ülke kodu yapılandırır. UWB denetleyicisi tarafından döndürülen durum koduna bağlı olarak (yeni ülkedeki UWB düzenlemelerine göre), bu durum UWB yığın durumunda bir değişikliğe yol açabilir.
FIRA UCI spesifikasyonu tanımlı komut formatı
UCI kontrol paketlerinin formatı için UCI spesifikasyonunun 4.4.2 bölümüne bakın.
Arayüz versiyonlama
UCI spesifikasyonu, UWB satıcılarının, UCI_GET_DEVICE_INFO_RSP
ve UCI_GET_CAPS_INFO_RSP
komutlarını kullanarak cihaz tarafından uygulanan UCI yığınının sürümünü açığa çıkarmasına olanak tanır. Çerçeve, cihazın UCI sürümünü getirmek ve davranışını buna göre değiştirmek için bu komutları kullanır.
UWB modülü tarafından desteklenen taslak CR'lerin listesi
FiRa 2.0 için aşağıdaki taslak CR'ler, UWB modülü sürüm #330810000 tarafından desteklenir:
Android UCI arayüzü (FiRa satıcı kısmı)
UCI spesifikasyonu, spesifikasyonla tanımlanan tüm mesajlar için bir dizi grup tanımlayıcıyı (GID'ler) ve işlem kodu tanımlayıcılarını (OID'ler) tanımlar. Spesifikasyon ayrıca yalnızca satıcının kullanımına ayrılmış bir dizi GID'yi de saklı tutar. AOSP UWB yığını, spesifikasyonda tanımlanmayan Android'e özgü komutlar için bu satıcı GID'lerinden ve OID'lerden bazılarını kullanır. Ayrıntılar için UCI spesifikasyonunun 8.4 bölümüne bakın.
Android tarafından kullanılan bu satıcı mesajları android.hardware.uwb.fira_android
HAL paketinde tanımlanmıştır.
Satıcı arayüzü sürümü oluşturma
UWB satıcıları, IUwbChip.getSupportedAndroidUciVersion()
aracılığıyla cihazda desteklenen android.hardware.uwb.fira_android
HAL paketinin sürümünü sunmalıdır. Çerçeve, geriye dönük uyumluluğu yönetmek için bu sürüm bilgilerini kullanır.
Android GID'lerin ve OID'lerin listesi
Aşağıdaki tabloda Android için GID'ler ve OID'ler listelenmektedir. 0xE
ve 0xF
GID'leri Android OEM'lerin kullanımına ayrılmıştır.
GID | OID | Tanım |
---|---|---|
ANDROID = 0xC | ANDROID_GET_POWER_STATS = 0x0 | UWB gücüyle ilgili istatistikleri almak için komut ve yanıt tarafından kullanılır. Yalnızca UwbVendorCapabilityTlvTypes.SUPPORTED_POWER_STATS_QUERY 1 olarak ayarlandığında desteklenir. |
ANDROID_SET_COUNTRY_CODE = 0x1 | Geçerli düzenleyici ülke kodunu ayarlamak için kullanılır (SIM veya Wi-Fi kullanılarak belirlenir veya OEM tarafından sabit kodlanır). Ülke kodu, ISO-3166 ülke koduna karşılık gelen 2 baytlık bir değer olarak gönderilir. Ülke kodunun bilinmediğini belirtmek için | |
ANDROID_RANGE_DIAGNOSTICS = 0x2 | UWB aralıklı tanılama istatistiklerini almak için bildirim tarafından kullanılır. Yalnızca UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS 1 olarak ayarlandığında desteklenir. | |
OEM = 0xE,0xF | 0x00 - 0x3F | OEM kullanımı için ayrılmıştır. |
UCI spesifikasyonu tanımlı mesajlara yönelik satıcı uzantıları
Bu bölümde, UCI spesifikasyonuyla tanımlanan mesajlara yönelik satıcı uzantılarının ayrıntıları açıklanmaktadır.
SESSION_SET_APP_CONFIG_[CMD|RSP] ve SESSION_GET_APP_CONFIG_[CMD|RSP]
Aşağıda, APP_CONFIG
TLV'lerin satıcıya ayrılmış kısmında AOSP yığını tarafından tanımlanan tür uzunluğu değerleri (TLV'ler) verilmiştir:
- GID: 0001b (UWB oturum yapılandırma grubu)
- OID: 000011b (
SESSION_SET_APP_CONFIG_CMD
) - OID: 000100b (
SESSION_GET_APP_CONFIG_CMD
)
Aşağıdaki tabloda UWB oturum yapılandırma mesajlarına ilişkin parametreler listelenmektedir.
Parametre adı | Uzunluk (sekizli) | Etiket (Kimlikler) | Satıcı arayüzü sürümü | Tanım |
---|---|---|---|---|
NB_OF_RANGE_MEASUREMENTS | 1 | 0xE3 | 1 | AOA_RESULT_REQ 0xF0 olarak ayarlanırsa serpiştirme oranı. Yalnızca UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 olarak ayarlandığında desteklenir. |
NB_OF_AZIMUTH_MEASUREMENTS | 1 | 0xE4 | 1 | |
NB_OF_ELEVATION_MEASUREMENTS | 1 | 0xE5 | 1 | |
ENABLE_DIAGNOSTICS | 1 | 0xE8 | 2 | Tanılama raporlamasını etkinleştirmek veya devre dışı bırakmak için 1 baytlık değer. Bu parametreyi yalnızca Değerler:
|
DIAGRAMS_FRAME_REPORTS_FIELDS | 1 veya 4 | 0xE9 | 2 | Tanılama raporlamasını yapılandırmak için 1 baytlık veya 4 baytlık bit maskesi. Bu bit maskesi Android 14 veya üzeri sürümlerde 1 bayt, Android 13 veya altı sürümlerde ise 4 bayttır. Bu parametreyi yalnızca Bit tanımları:
|
CORE_GET_CAPS_INFO_RSP
CAPS_INFO
TLV'lerin satıcıya ayrılmış kısmında AOSP yığını tarafından tanımlanan TLV'ler aşağıdadır:
- GID: 0000b (UWB çekirdek grubu)
- OID: 000011b (
CORE_GET_CAPS_INFO_RSP
)
Aşağıdaki tabloda UWB özelliği mesajlarının parametreleri listelenmektedir.
Parametre adı | Uzunluk (sekizli) | Etiket (Kimlikler) | Satıcı arayüzü sürümü | Tanım |
---|---|---|---|---|
SUPPORTED_POWER_STATS_QUERY | 1 | 0xC0 | 1 | Güç istatistikleri sorgusu desteğini gösteren 1 baytlık değer. Değerler:
|
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING | 1 | 0xE3 | 1 | Anten serpiştirme özelliğinin desteğini gösteren 1 baytlık değer. Değerler:
|
SUPPORTED_MIN_RANGING_INTERVAL_MS | 4 | 0xE4 | 2 | Desteklenen minimum aralık aralığını milisaniye cinsinden belirten 4 baytlık değer. |
SUPPORTED_RANGE_DATA_NTF_CONFIG | 4 | 0xE5 | 2 | Desteklenen RANGE_DATA_NTF_CONFIG değerlerini gösteren 4 baytlık bit maskesi. Her bitin SET_APP_CFG_CMD içindeki RANGE_DATA_NTF_CONFIG içinde kullanılan değerlere karşılık geldiği bit maskesi. |
SUPPORTED_RSSI_REPORTING | 1 | 0xE6 | 2 | RSSI raporlama desteğini gösteren 1 baytlık değer. Değerler:
|
SUPPORTED_DIAGNOSTICS | 1 | 0xE7 | 2 | Tanılama raporlamasının desteğini gösteren 1 baytlık değer. Değerler:
|
SUPPORTED_MIN_SLOT_DURATION_RSTU | 4 | 0xE8 | 2 | RSTU'da desteklenen minimum yuva süresini gösteren 4 baytlık değer. |
SUPPORTED_MAX_RANGING_SESSION_NUMBER | 4 | 0xE9 | 2 | FiRa aralık oturumlarının desteklenen maksimum sayısını gösteren 4 baytlık değer. |
SUPPORTED_CHANNELS_AOA | 2 | 0xEA | 2 | AoA'yı destekleyen kanalları belirtmek için 2 baytlık bit maskesi. Bit maskesindeki her Değerler:
|
Durum kodları
Satıcı alanındaki durum kodları aşağıdadır. Bunlar, UWB alt sistemi (UWBS) tarafından UCI yanıtlarında ( SESSION_START_RSP
gibi) döndürülür.
Durum kodu | Değer | Tanım |
---|---|---|
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x52 | Geçerli aralık oturumu diğer CCC veya FiRa aralık oturumlarıyla çakışma nedeniyle başlatılamadığında döndürülen durum kodu. |
STATUS_REGULATION_UWB_OFF | 0x53 | Geçerli aralık oturumu UWB düzenleme nedenlerinden dolayı başlatılamadığında döndürülen durum kodu. |
SESSION_STATUS_NTF'deki durum değişikliği nedeni kodu
Aşağıda, SESSION_STATUS_NTF
bir UWBS tarafından döndürülen durum alanı için satıcı alanında tanımlanan durum değişikliği nedeni kodları yer almaktadır. Bu bildirim, değişen bir oturumun durumu değiştiğinde (örneğin, ACTIVE
IDLE
) UWBS tarafından gönderilir.
Durum değişikliği nedeni kodu | Değer | Tanım |
---|---|---|
REASON_ERROR_INVALID_CHANNEL_WITH_AOA | 0x80 | Yapılandırılmış kanal AoA aralığını desteklemediğinden oturum durumu değiştirildi. |
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT | 0x81 | Diğer CCC veya FiRa aralık oturumlarıyla çakışma nedeniyle oturum durumu değişti. |
REASON_REGULATION_UWB_OFF | 0x82 | Düzenleyici bir nedenden dolayı UWB'nin devre dışı bırakılması gerektiğinden oturum durumu değişti. |