UWB HAL Arayüzü

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.

UWB yığını başlatma

Şekil 1. UWB yığını başlatma çağrısı akışı (UWB düğmesi açık)

UWB yığınını başlatmama

Şekil 2. UWB yığınını başlatmama çağrısı akışı (UWB kapalı)

UWB oturumu başlatma ve durdurma

Ş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.

  1. Ülke kodunu geçersiz kıl: Bir adb kabuk komutu aracılığıyla zorlanan ülke kodu (yerel veya otomatik test).
  2. 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.
  3. Wi-Fi ülke kodu: Wi-Fi (80211.ad) aracılığıyla alınan ülke kodu.
  4. 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.
  5. Konum ülke kodu: LocationManager ile birleştirilmiş konum sağlayıcısından alınan ülke kodu.
  6. 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 00 değeri kullanılır.

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 CORE_GET_CAPS_INFO_RSP tanılama raporlama özelliğinin desteklendiğini belirten 1 değeriyle SUPPORTED_DIAGNOSTICS değerini döndürdüğünde yapılandırın.

Değerler:

  • 1 : Özellik etkin
  • 0 : Özellik devre dışı

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 CORE_GET_CAPS_INFO_RSP , tanılama raporlama özelliğinin desteklendiğini belirten 1 değeriyle SUPPORTED_DIAGNOSTICS değerini döndürdüğünde yapılandırın.

Bit tanımları:

  • b0 (0x01) : RSSI alanlarını etkinleştir
  • b1 (0x02) : AoA alanlarını etkinleştir
  • b2 (0x04) : CIR alanlarını etkinleştir

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:

  • 1 : Desteklenen özellik
  • 0 : Özellik desteklenmiyor
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:

  • 1 : Desteklenen özellik
  • 0 : Özellik desteklenmiyor
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:

  • 1 : Desteklenen özellik
  • 0 : Özellik desteklenmiyor
SUPPORTED_DIAGNOSTICS 1 0xE7 2

Tanılama raporlamasının desteğini gösteren 1 baytlık değer.

Değerler:

  • 1 : Desteklenen özellik
  • 0 : Özellik desteklenmiyor
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 1 belirli bir UWB kanalına karşılık gelir.

Değerler:

  • 0x01 : Kanal 5 destekleniyor
  • 0x02 : Kanal 6 destekleniyor
  • 0x04 : Kanal 8 destekleniyor
  • 0x08 : Kanal 9 destekleniyor
  • 0x10 : Kanal 10 desteklenir
  • 0x20 : Kanal 12 desteklenir
  • 0x40 : Kanal 13 desteklenir
  • 0x80 : Kanal 14 desteklenir

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.