Ultra Geniş Bant HAL arayüzü

AOSP ultra geniş bant (UWB) yığını, HAL yüzeyi olarak FiRa tarafından tanımlanan 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 boru (IUwbChip::sendUciMessage() ve IUwbClientCallback::onUciMessage()) kullanır. Tüm Android ultra geniş bant tedarikçileri, FiRa spesifikasyonunda tanımlanan tüm mesajları desteklemelidir. Ultra geniş bant çerçevesi geriye dönük uyumludur ve cihazda ultra geniş bant tedarikçisi tarafından uygulanan tüm UCI sürümleriyle çalışır. AOSP UWB çerçevesi bir modül olduğundan, ana FiRa standartları sürümlerini hedefleyen taslak UCI spesifikasyonlarından onaylanmış değişiklik istekleri (CR'ler) için seçmeli olarak destek ekleyebilir. Uygulanan bu tür taslak inceleme raporları değiştirilebilir.

Arayüz tanımı

UWB HAL arayüzü, sağlam AIDL kullanılarak tanımlanır. Ana arayüz android.hardware.uwb paketini kullanır.

Aşağıda, android.hardware.uwb paketindeki iki ana arayüz gösterilmektedir.

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, ultra geniş bant yığını başlatma, ultra geniş bant yığınını başlatma ve ultra geniş bant oturumu başlatma ve durdurma işlemleri için ultra geniş bant çerçevesinden gelen çağrı akışı gösterilmektedir.

Ultra geniş bant yığını başlatma

Şekil 1. UWB yığınını ilk kullanıma hazırlama çağrı akışı (UWB açma/kapatma düğmesi)

Ultra geniş bant yığınının devre dışı bırakılması

Şekil 2. UWB yığınının ilk durumuna döndürme çağrı akışı (UWB açma/kapatma düğmesi)

Ultra geniş bant oturumu başlatma ve durdurma

Şekil 3. Ultra geniş bant oturumu başlatma/durdurma akışı

Ultra geniş bant ülke kodu yapılandırması

Şekil 1'de gösterildiği gibi, ultra geniş bant çerçevesi, ultra geniş bant yığınının başlatılması sırasında tedarikçi alanı UCI komutunu ANDROID_SET_COUNTRY_CODE (GID=0xC, OID=0x1) kullanarak ultra geniş bant ülke kodunu yapılandırır. Ultra geniş bant çerçevesi, aşağıdaki kaynakları (öncelik sırasına göre listelenmiştir) kullanarak ultra geniş bant ülke kodunu belirlemeye çalışır. Ultra Geniş Bant çerçevesi, ülke kodunun belirlendiği ilk kaynakta durur.

  1. Ülke kodunu geçersiz kılma: Ülke kodu, adb kabuk komutu aracılığıyla zorunlu kılınmıştır (yerel veya otomatik test).
  2. Telefon ülke kodu: Cep telefonu üzerinden alınan ülke kodu. Farklı kodlar döndüren birden fazla SIM varsa seçilen ülke kodu kesin değildir.
  3. Kablosuz ağ ülke kodu: Kablosuz ağ üzerinden alınan ülke kodu (80211.ad).
  4. Bilinen son telefon ülke kodu: Cep telefonu üzerinden alınan bilinen son ülke kodu. Farklı kodlar döndüren birden fazla SIM varsa seçilen ülke kodu rastgeledir.
  5. Konum ülke kodu: Birleştirilmiş konum sağlayıcıdan alınan ülke kodu.LocationManager
  6. OEM varsayılan ülke kodu: Cihaz üreticisi tarafından ayarlanan ülke kodu.

Ultra Geniş Bant çerçevesi bir ultra geniş bant ülke kodu belirleyemiyorsa ANDROID_SET_COUNTRY_CODE UCI komutunu DEFAULT_COUNTRY_CODE ("00") değeriyle çağırır ve ultra geniş bant uygulamalarına ultra geniş bant yığınının DISABLED olduğunu bildirir. Daha sonra, ultra geniş bant çerçevesi geçerli bir ülke kodu belirleyebildiğinde ANDROID_SET_COUNTRY_CODE komutunu kullanarak yeni ülke kodunu yapılandırır ve ultra geniş bant uygulamalarını ultra geniş bant yığınının READY olduğunu bildirir.

Bir ülkedeki yerel düzenlemeler nedeniyle ultra geniş bant kullanılamıyorsa ultra geniş bant denetleyicisi STATUS_CODE_ANDROID_REGULATION_UWB_OFF durum kodunu döndürür. Ardından ultra geniş bant çerçevesi, ultra geniş bant uygulamalarını ultra geniş bant yığın durumunun DISABLED olduğunu bildirir.

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. Bu durum, ultra geniş bant denetleyicisi tarafından döndürülen durum koduna (yeni ülkedeki ultra geniş bant düzenlemelerine bağlı olarak) bağlı olarak ultra geniş bant yığın durumunda bir değişikliğe neden olabilir.

FIRA UCI spesifikasyonu tarafından tanımlanan komut biçimi

UCI kontrol paketlerinin biçimi için UCI spesifikasyonunun 4.4.2 bölümüne bakın.

Arayüz sürümü oluşturma

UCI spesifikasyonu, ultra geniş bant tedarikçi firmalarının UCI_GET_DEVICE_INFO_RSP ve UCI_GET_CAPS_INFO_RSP komutlarını kullanarak cihaz tarafından uygulanan UCI yığını sürümünü sunabilmesini sağlar. Çerçeve, cihazın UCI sürümünü almak 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, spesifikasyonda tanımlanan tüm mesajlar için bir grup tanımlayıcı (GID) ve kod işlemi tanımlayıcı (OID) grubu tanımlar. Bu spesifikasyon, yalnızca satıcı kullanımı için ayrılmış bir GID grubu da ayırır. AOSP ultra geniş bant yığını, spesifikasyonda tanımlanmayan Android'e özgü komutlar için bu tedarikçi GID'lerinden ve OID'lerinden bazılarını kullanır. Ayrıntılar için UCI spesifikasyonunun 8.4 numaralı bölümüne bakın.

Android tarafından kullanılan bu tedarikçi firma mesajları, android.hardware.uwb.fira_android HAL paketinde tanımlanmıştır.

Tedarikçi firma arayüzü sürüm oluşturma

Ultra geniş bant tedarikçileri, cihazda desteklenen android.hardware.uwb.fira_androidHAL paketinin sürümünü IUwbChip.getSupportedAndroidUciVersion() tarihine kadar göstermelidir. Çerçeve, geriye dönük uyumluluğu yönetmek için bu sürüm bilgilerini kullanır.

Android GID'lerinin ve OID'lerinin listesi

Aşağıdaki tabloda Android için GID'ler ve OID'ler listelenmiştir. 0xE ve 0xF GID'leri Android OEM'lerin kullanması için ayrılmıştır.

GID OID Tanım
ANDROID = 0xC ANDROID_GET_POWER_STATS = 0x0 Ultra geniş bant 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 ayarlanmışsa desteklenir.
ANDROID_SET_COUNTRY_CODE = 0x1

Mevcut yasal ülke kodunu (SIM veya kablosuz ağ kullanılarak belirlenir ya da OEM tarafından kodlanır) ayarlamak için kullanılır. Ülke kodu, ISO-3166 ülke koduna karşılık gelen 2 baytlık bir değer olarak gönderilir. 00 değeri, ülke kodunun bilinmediğini belirtmek için kullanılır.
ANDROID_RANGE_DIAGNOSTICS = 0x2 Ultra Geniş Bant aralığı teşhis istatistiklerini almak için bildirim tarafından kullanılır. Yalnızca UwbVendorCapabilityTlvTypes.SUPPORTED_DIAGNOSTICS, 1 olarak ayarlanmışsa desteklenir.
OEM = 0xE,0xF 0x00 - 0x3F OEM kullanımı için ayrılmıştır.

UCI spesifikasyonu tarafından tanımlanan mesajlara yönelik tedarikçi uzantıları

Bu bölümde, UCI spesifikasyonu tarafından tanımlanan mesajlara yönelik tedarikçi 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 bölgesindeki TLV'lerin tedarikçi tarafından ayrılmış bölümünde AOSP yığını tarafından tanımlanan tür uzunluğu değerleri (TLV'ler) verilmiştir:

  • GID: 0001b (UWB oturumu yapılandırma grubu)
  • OID: 000011b (SESSION_SET_APP_CONFIG_CMD)
  • OID: 000100b (SESSION_GET_APP_CONFIG_CMD)

Aşağıdaki tabloda, ultra geniş bant oturum yapılandırma mesajlarının parametreleri listelenmiştir.

Parametre adı Uzunluk
(oktet)		 Etiket
(Kimlikler)		 Tedarikçi firma arayüzü sürümü Açıklama
NB_OF_RANGE_MEASUREMENTS 1 0xE3 1 AOA_RESULT_REQ 0xF0 olarak ayarlandıysa ara sarma oranı. Yalnızca UwbVendorCapabilityTlvTypes.SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING, 1 olarak ayarlanmışsa desteklenir.
NB_OF_AZIMUTH_MEASUREMENTS 1 0xE4 1
NB_OF_ELEVATION_MEASUREMENTS 1 0xE5 1
ENABLE_DIAGNOSTICS 1 0xE8 2

Teşhis 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, teşhis raporlama özelliğinin desteklendiğini belirten 1 değerine sahip SUPPORTED_DIAGNOSTICS döndürdüğünde yapılandırın.

Değerler:

  • 1: Özellik etkin
  • 0: Özellik devre dışı bırakıldı
DIAGRAMS_FRAME_REPORTS_FIELDS 1 veya 4 0xE9 2

Teşhis raporlamasını yapılandırmak için 1 bayt veya 4 baytlık bit maskesi. Bu bit maskesi, Android 14 veya sonraki sürümlerde 1 bayt, Android 13 veya önceki sürümlerde ise 4 bayttır.

Bu parametreyi yalnızca CORE_GET_CAPS_INFO_RSP, SUPPORTED_DIAGNOSTICS değerini 1 olarak döndürdüğünde yapılandırın. Bu değer, teşhis raporlama özelliğinin desteklendiğini gösterir.

Bit tanımları:

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

CORE_GET_CAPS_INFO_RSP

Aşağıda, CAPS_INFO içindeki TLV'lerin tedarikçi firma tarafından ayrılmış bölümünde AOSP yığını tarafından tanımlanan TLV'ler verilmiştir:

  • GID: 0000b (ultra geniş bant çekirdek grubu)
  • OID: 000011b (CORE_GET_CAPS_INFO_RSP)

Aşağıdaki tabloda, ultra geniş bant özellik mesajlarının parametreleri listelenmiştir.

Parametre adı Uzunluk
(oktet)		 Etiket
(Kimlikler)		 Tedarikçi firma arayüzü sürümü Açıklama
SUPPORTED_POWER_STATS_QUERY 1 0xC0 1

Güç istatistikleri sorgusu desteğini gösteren 1 bayt değeri.

Değerler:

  • 1: Özellik destekleniyor
  • 0: Özellik desteklenmiyor
SUPPORTED_AOA_RESULT_REQ_ANTENNA_INTERLEAVING 1 0xE3 1

Anten ara ekleme özelliğinin desteklendiğini belirten 1 baytlık değer.

Değerler:

  • 1: Özellik destekleniyor
  • 0: Özellik desteklenmiyor
SUPPORTED_MIN_RANGING_INTERVAL_MS 4 0xE4 2 Milisaniye cinsinden desteklenen minimum menzil aralığını gösteren 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 bir bitin SET_APP_CFG_CMD içindeki RANGE_DATA_NTF_CONFIG alanında kullanılan değerlere karşılık geldiği bit maskesi.
SUPPORTED_RSSI_REPORTING 1 0xE6 2

RSSI raporlamasının desteklendiğini belirten 1 baytlık değer.

Değerler:

  • 1: Özellik destekleniyor
  • 0: Özellik desteklenmiyor
SUPPORTED_DIAGNOSTICS 1 0xE7 2

Teşhis raporlamasının desteklendiğini belirten 1 baytlık değer.

Değerler:

  • 1: Özellik destekleniyor
  • 0: Özellik desteklenmiyor
SUPPORTED_MIN_SLOT_DURATION_RSTU 4 0xE8 2 RSTU'da desteklenen minimum slot süresini gösteren 4 baytlık değer.
SUPPORTED_MAX_RANGING_SESSION_NUMBER 4 0xE9 2 Desteklenen maksimum FiRa menzil belirleme oturumu sayısını belirten 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 ultra geniş bant kanalına karşılık gelir.

Değerler:

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

Durum kodları

Aşağıda, tedarikçi firma alanındaki durum kodları verilmiştir. Bunlar, UWB alt sistemi (UWBS) tarafından UCI yanıtlarında (SESSION_START_RSP gibi) döndürülür.

Durum kodu Değer Açıklama
STATUS_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x52

Mevcut menzil belirleme oturumu, diğer CCC veya FiRa menzil belirleme oturumlarıyla çakıştığı için başlatılamadığında döndürülen durum kodu.
STATUS_REGULATION_UWB_OFF 0x53

Ultra Geniş Bantla ilgili yönetmelik nedeniyle mevcut aralık oturumu 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 içinde bir UWBS tarafından döndürülen durum alanı için tedarikçi alanında tanımlanan durum değişikliği nedeni kodları verilmiştir. Bu bildirim, bir menzil belirleme oturumunun durumu değiştiğinde (örneğin, ACTIVE yerine IDLE) UWBS tarafından gönderilir.

Durum değişikliği nedeni kodu Değer Açıklama
REASON_ERROR_INVALID_CHANNEL_WITH_AOA 0x80

Yapılandırılmış kanal AoA aralığını desteklemediğinden oturum durumu değişti.
REASON_ERROR_STOPPED_DUE_TO_OTHER_SESSION_CONFLICT 0x81

Diğer CCC veya FiRa aralığı oturumlarıyla çakıştığı için oturum durumu değişti.
REASON_REGULATION_UWB_OFF 0x82

Ultra geniş bant, yasal nedenlerle devre dışı bırakılması gerektiği için oturum durumu değişti.