Android 16 (API düzeyi 36), cihazlar arasında hassas mesafe ölçümü için birleştirilmiş ve standartlaştırılmış bir arayüz sağlayan Ranging modülünü kullanıma sunar. Bu API yüzeyini kullanarak her bir mesafe ölçüm teknolojisini ayrı ayrı ele almanıza gerek kalmadan eş cihazların mesafesini ve konumunu ölçebilirsiniz.
Mesafe ölçümü modülü aşağıdaki teknolojileri destekler:
- Ultra geniş bant
- Bluetooth kanal seslendirme
- Kablosuz NAN RTT
- Bluetooth RSSI ölçümü
- Android 17 (API düzeyi 37) ve sonraki sürümlerde Kablosuz Yakınlık Algılama
Mesafe ölçme özellikleri ve kullanılabilirlik
RangingManager sınıfı, uygulamalara yerel cihaz tarafından desteklenen mesafe ölçüm teknolojileri, her bir teknolojinin kullanılabilirliği ve özellikleri hakkında bilgi sağlar. Uygulamalar, desteklenen teknolojilerin kullanılabilirliği veya özelliklerindeki değişikliklerle ilgili güncellemeleri almak için bir RangingCapabilitiesCallback arayüzü kaydedebilir.
Cihaz rolleri
Mesafe ölçümü oturumuna katılan bir cihaz; Android 17 (API düzeyi 37) ve sonraki sürümlerdeki UWB Downlink-TDoA oturumları için başlatıcı, yanıtlayıcı veya Downlink-TDoA Etiketi (DT-Tag) olmalıdır. Başlatıcı cihaz, bir veya daha fazla yanıtlayıcı cihazla mesafe ölçümü oturumunu başlatır. Yanıtlayıcı cihaz, aynı anda yalnızca bir başlatıcının mesafe ölçümü isteklerine yanıt verir. UWB Downlink Time Difference of Arrival (DL-TDoA) oturumunda cihaz, birden fazla UWB bağlantı noktasından sinyal almak için DEVICE_ROLE_DT_TAG rolünü kullanır.
RangingPreference sınıfıyla bir mesafe belirleme oturumunda belirli bir cihazın rolünü belirtebilirsiniz.
Mesafe ölçüm oturumu türleri
Cihazlar arasında mesafe ölçümü oturumu başlatırken genellikle oturum için parametre alışverişi yapmak üzere bant dışı (OOB) veri aktarımı oluşturmak gerekir.
Sıralama modülü, OOB pazarlıklarını sizin için gerçekleştirebilir ancak özel OOB uygulamalarını da destekler.
Varsayılan OOB uygulaması
Bu oturum türünde (RANGING_SESSION_OOB), mesafe ölçümü modülü, mesafe ölçümü oturumu başlatmak için OOB anlaşmalarını yönetir. Uygulama tarafından sağlanan mesafe ölçümü tercihlerine göre uygun parametreleri seçer ve her iki cihazın desteklediği teknolojileri kullanır. Bu oturum türü, standartlaştırılmış bir OOB spesifikasyonu kullanır. Android 16 QPR2 (API düzeyi 36.1) ve sonraki sürümlerde başlatıcılar, OobInitiatorRangingConfig.Builder üzerinde setRangingTechnologyFilter yöntemini çağırarak hangi teknolojilerin kullanılacağını kısıtlayabilir.
Mesafe ölçümü modülü, yalnızca eş cihazla etkileşim kurmak için kullanılacak OOB veri biçimini ve sırasını tanımlar. Eş cihaz keşfi veya bağlantı oluşturma işlemlerini gerçekleştirmez.
Özel OOB uygulaması
Bu oturum türünde (RANGING_SESSION_RAW) uygulama, Mesafe Ölçümü modülünün OOB akışını atlar ve kendi OOB anlaşmasını ve parametrelerini yönetir. Yani uygulamanın, eş cihazın hangi teknolojileri desteklediğini belirlemesi, mesafe ölçümü parametrelerini belirlemesi ve mesafe ölçümü oturumunu başlatması gerekir.
Mesafe ölçümü tercihleri
Mesafe ölçümü oturumu için seçilen parametreleri belirtmek üzere RangingPreference nesnesi kullanın. Bu alanlar/yollar aşağıdakileri içerir:
- Cihaz rolü. Bu, cihazın Android 17 (API düzeyi 37) ve sonraki sürümlerde başlatıcı, yanıtlayıcı veya DT etiketi olup olmadığını gösterir.
- Mesafe ölçümü yapılandırması.
RangingConfignesnesi, mesafe ölçüm oturumu türünü ve mesafe ölçüm oturumu başlatmak için gereken diğer parametreleri belirtir. - Oturum yapılandırması:
SessionConfignesnesi, mesafe ölçüm oturumunda zorunlu kılınacak parametreleri (ör. ölçüm sınırı, sensör füzyonu, coğrafi sınır yapılandırması ve daha fazlası) belirtir. Android 17 (API düzeyi 37) ve sonraki sürümlerde,UwbRangingCapabilitiesüzerindegetSupportedAntennaModesile desteklenen modları kontrol ettikten sonraSessionConfig.BuilderüzerindesetAntennaModeile anten modunu (ANTENNA_MODE_DIRECTIONALveyaANTENNA_MODE_OMNI) da yapılandırabilirsiniz.
Mesafe ölçme izni
Mesafe ölçümü modülü, eşler arası mesafe ölçümü teknolojileri için birleştirilmiş bir izin (android.permission.RANGING) kullanır. Bu izin, NEARBY_DEVICES_PERMISSIONS listesinde yer alır.
<uses-permission android:name="android.permission.RANGING" />
Kısıtlamalar ve sınırlamalar
Mesafe bulma modülü, aşağıdakiler de dahil olmak üzere çeşitli nedenlerle mesafe bulmayı kısıtlayabilir:
- Üçüncü taraf uygulamalarının yalnızca ultra geniş bant ile ve yalnızca desteklenen cihazlarda arka planda mesafe ölçümü yapmasına izin verilir. Diğer teknolojilerle arka planda mesafe ölçümüne izin verilmez.
- Cihaz başına maksimum eşzamanlı mesafe belirleme oturumu sayısına ulaşıldığında mesafe belirlemeye izin verilmez.
- Mesafe ölçümü; pil, performans veya bellek gibi sistem sağlığıyla ilgili endişeler nedeniyle kısıtlanabilir.
Mesafe Ölçme modülünde aşağıdaki bilinen sınırlamalar da vardır:
- Mesafe ölçümü modülü, yalnızca ultra geniş bant için mesafe ölçümü verilerinin eş cihazlara gönderilmesini destekler. Diğer teknolojilerde ise mesafe ölçümü modülü, mesafe ölçümü verilerini yalnızca başlatıcı cihaza gönderir.
- Mesafe ölçümü modülü, cihazların dinamik olarak eklenmesini yalnızca ham mesafe ölçümü modunda ve yalnızca ultra geniş bant için destekler.
- Mesafe ölçümü modülü, varsayılan OOB uygulamaları için bire çok ultra geniş bant oturumlarını desteklemez. Birden fazla cihaz tanıtıcısı iletirseniz modül, ultra geniş bandı destekleyen her eş cihaz için bire bir oturum oluşturur.
Mesafe ölçümü oturumu gerçekleştirme
Mesafe ölçümü modülünü kullanarak mesafe ölçümü oturumu gerçekleştirmek için aşağıdaki adımları uygulayın:
- Tüm cihazların Android 16 (API düzeyi 36) ve sonraki sürümleri çalıştırdığını doğrulayın.
- Uygulama manifestinde
android.permission.RANGINGiznini isteyin. - Mesafe ölçüm teknolojilerinin özelliklerini ve kullanılabilirliğini değerlendirme
- Mesafe ölçme işlemleri için eş cihaz keşfetme
- Mesafe ölçümü oturum türleri bölümünde açıklanan oturum türlerinden birini kullanarak bant dışı değişim için bağlantı kurun.
- Mesafe ölçümünü başlatma ve mesafe ölçümü verilerini sürekli olarak alma
- Mesafe ölçümü oturumunu sonlandırın.
Aşağıdaki kod örneğinde, hem başlatıcı rolü hem de yanıtlayıcı rolü için bu adımlar gösterilmektedir.
class RangingApp { // Starts a ranging session on the initiator side. fun startRangingInitiator( context: Context, deviceHandle: DeviceHandle, executor: Executor, callback: RangingSession.Callback ): RangingSession? { // Get the RangingManager which is the entry point for ranging module. val manager = context.getSystemService(RangingManager::class.java) // Create a new RangingSession using the provided executor and callback. val session = manager.createRangingSession(executor, callback) ?: return null // Create an OobInitiatorRangingConfig, which specifies the ranging parameters for // the initiator role. val config = OobInitiatorRangingConfig.Builder() .setFastestRangingInterval(Duration.ofMillis(100)) .setSlowestRangingInterval(Duration.ofMillis(5000)) .setRangingMode(RANGING_MODE_AUTO) .setSecurityLevel(SECURITY_LEVEL_BASIC) .addDeviceHandle(deviceHandle) .build() // Create a RangingPreference, which specifies the role (initiator) and // configuration for the ranging session. val preference = RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build() // Start ranging session. Ranging data is delivered asynchronously through // callback.onResults; call stopRanging(session) when ranging is no longer needed. session.start(preference) return session } // Starts a ranging session on the responder side. fun startRangingResponder( context: Context, deviceHandle: DeviceHandle, executor: Executor, callback: RangingSession.Callback ): RangingSession? { // Get the RangingManager which is the entry point for ranging module. val manager = context.getSystemService(RangingManager::class.java) // Create a new RangingSession using the provided executor and callback. val session = manager.createRangingSession(executor, callback) ?: return null // Create an OobResponderRangingConfig, which specifies the ranging parameters for // the responder role. val config = OobResponderRangingConfig.Builder(deviceHandle).build() // Create a RangingPreference, which specifies the role (responder) and // configuration for the ranging session. val preference = RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build() // Start the ranging session. Call stopRanging(session) when finished. session.start(preference) return session } // Stops an active ranging session. fun stopRanging(session: RangingSession) { session.stop() } }
Mesafe ölçümü sonuçlarını ve eşlerin hareketini işleme
Bir oturum etkin olduğunda RangingSession.Callback, onResults aracılığıyla RangingData nesnelerinde mesafe ve varış açısı ölçümleri sunar:
- Mesafe belirsizliği. Android 16 QPR2 (API düzeyi 36.1) ve sonraki sürümlerde, mesafe ölçümlerinin standart sapmasını incelemek için
RangingDataüzerindehasDistanceStandardDeviationvegetDistanceStandardDeviationMetersyöntemlerini çağırın. - Teknolojiye özel ekstralar. Android 17 (API düzeyi 37) ve sonraki sürümlerde,
BleSpecificData,UwbSpecificDataveyaWifiRttSpecificDatagibi teknolojiye özel meta veriler içeren birRangingDataExtrasnesnesi almak içinRangingDataüzerindegetRangingDataExtrasyöntemini çağırın. - Benzer hareket durumu. Android 17 (API düzeyi 37) ve sonraki sürümlerde, eş cihazın hareketi değiştiğinde
MotionStategüncellemelerini (MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATEveyaMOTION_LARGE) almak içinRangingSession.CallbackiçindekionMotionReceivedyöntemini geçersiz kılın.
iOS cihazlarla UWB birlikte çalışabilirliği
Mesafe ölçümü modülü, ultra geniş bant (UWB) kullanan iOS cihazlarla birlikte çalışabilirliği destekler. iOS cihazla mesafe ölçümü yapmak için özel bir OOB uygulaması kullanmanız ve mesafe ölçümü oturumunu Apple Yakındaki Etkileşim Aksesuar Protokolü ile eşleşen belirli parametrelerle yapılandırmanız gerekir. Örnek için örnek uygulamaya bakın.
RangingPreference oluştururken yapılandırmayı belirtmek için RawRangingDevice ve UwbRangingParams kullanın. Aşağıdaki parametreler, iOS ile birlikte çalışabilirlik için çok önemlidir:
- Yapılandırma kimliği.
UwbRangingParams.CONFIG_UNICAST_DS_TWRkullanın. - Oturum Anahtarı Bilgileri: Tedarikçi Kimliği ve Statik STS IV'yi içeren bir bayt dizisi sağlayın.
- Karmaşık kanal. Kanal numarasını ve ön talimatlar dizinini iOS cihazın yapılandırmasıyla eşleşecek şekilde ayarlayın.
Aşağıdaki kod snippet'inde, iOS yanıtlayıcı ile ölçüm yapan bir başlatıcı cihaz için RangingPreference oluşturma işlemi gösterilmektedir:
// Create UwbRangingParams with iOS-specific configuration. val uwbRangingParams = UwbRangingParams.Builder( sessionId, UwbRangingParams.CONFIG_UNICAST_DS_TWR, sourceAddress, destinationAddress ) .setComplexChannel( UwbComplexChannel.Builder() .setChannel(channelNumber) .setPreambleIndex(preambleIndex) .build() ) .setRangingUpdateRate(updateRate) .setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV .setSlotDuration(slotDuration) .build() // Create RawRangingDevice. val rawRangingDevice = RawRangingDevice.Builder() .setRangingDevice(RangingDevice.Builder().build()) .setUwbRangingParams(uwbRangingParams) .build() // Create SessionConfig. val sessionConfig = SessionConfig.Builder() .setAngleOfArrivalNeeded(true) .setDataNotificationConfig( DataNotificationConfig.Builder() .setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE) .build() ) .build() // Create RangingPreference for the initiator. val preference = RangingPreference.Builder( RangingPreference.DEVICE_ROLE_INITIATOR, RawInitiatorRangingConfig.Builder() .addRawRangingDevice(rawRangingDevice) .build() ) .setSessionConfig(sessionConfig) .build()
UWB Downlink-TDoA API
Android 17 (API düzeyi 37) ve sonraki sürümlerde, Downlink Time Difference of Arrival (DL-TDoA) ölçümü, bir cihazın sinyallerin göreceli varış sürelerini ölçerek birden fazla UWB bağlantı noktasına göre konumunu belirlemesine olanak tanır.
Aşağıdaki snippet'te, DL-TDoA desteğini doğrulamak için RangingManager'nin nasıl kullanılacağı, oturum başlatmak için DlTdoaRangingParams ve RawDtTagRangingConfig'nin nasıl yapılandırılacağı ve DlTdoaMeasurement sonuçlarının nasıl alınacağı gösterilmektedir:
class RangingApp { fun initDlTdoa(context: Context) { // Initialize the Ranging Manager. val rangingManager = context.getSystemService(RangingManager::class.java) // Register for device capabilities. val capabilitiesCallback = object : RangingManager.RangingCapabilitiesCallback { override fun onRangingCapabilities(capabilities: RangingCapabilities) { // Make sure DL-TDoA is supported before starting the session. if (capabilities.uwbCapabilities?.isDlTdoaSupported == true) { startDlTDoASession(context) } } } rangingManager.registerCapabilitiesCallback(Executors.newSingleThreadExecutor(), capabilitiesCallback) } fun startDlTDoASession(context: Context) { // Initialize the Ranging Manager. val rangingManager = context.getSystemService(RangingManager::class.java) // Create session and configure parameters. val executor = Executors.newSingleThreadExecutor() val rangingSession = rangingManager.createRangingSession(executor, RangingSessionCallback()) val rangingRoundIndexes = byteArrayOf(0) val config: ByteArray = byteArrayOf() // OOB config data val params = DlTdoaRangingParams.createFromFiraConfigPacket(config, rangingRoundIndexes) val rangingDevice = RangingDevice.Builder().build() val rawTagDevice = RawRangingDevice.Builder() .setRangingDevice(rangingDevice) .setDlTdoaRangingParams(params) .build() val dtTagConfig = RawDtTagRangingConfig.Builder(rawTagDevice).build() val preference = RangingPreference.Builder(DEVICE_ROLE_DT_TAG, dtTagConfig) .setSessionConfig(SessionConfig.Builder().build()) .build() // Start the ranging session. rangingSession?.start(preference) } } private class RangingSessionCallback : RangingSession.Callback { override fun onDlTdoaResults(peer: RangingDevice, measurement: DlTdoaMeasurement) { // Process measurement results here. } override fun onOpened() { // ... } override fun onOpenFailed(reason: Int) { // ... } override fun onStarted(peer: RangingDevice, technology: Int) { // ... } override fun onStopped(peer: RangingDevice, technology: Int) { // ... } override fun onResults(peer: RangingDevice, data: RangingData) { // ... } override fun onClosed(reason: Int) { // ... } }
Bant dışı (OOB) yapılandırmalar
Aşağıdaki snippet'te, kablosuz ve BLE için DL-TDoA OOB yapılandırma verilerine dair bir örnek verilmiştir:
// Wi-Fi Configuration (Vendor-Specific IE, FiRa CID 0x5A18FF, Config 0) val wifiConfig = byteArrayOf( 0xDD.toByte(), 0x30, 0x5A, 0x18, 0xFF.toByte(), // Wi-Fi VSE Header 0x5F, 0x1C, // UWB Configuration Sub-Element 0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0 0x06, 0x02, 0x20, 0x08, // Device MAC Address 0x14, 0x01, 0x0A, // Preamble Code Index (10) 0x27, 0x02, 0x08, 0x07, // Vendor ID 0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV 0x08, 0x02, 0x60, 0x09, // Slot Duration (2400 RSTU = 2 ms) 0x1B, 0x01, 0x0A, // Slots per Ranging Round (10) 0x09, 0x04, 0xFA.toByte(), 0x00, 0x00, 0x00, // Ranging Duration (250 ms) 0x52, 0x01, 0x00, // Initiator DT-Anchor Round Index (0) 0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA) ) // BLE Configuration (ADV_NONCONN_IND Service Data UUID 0xFFF3, Config 0) val bleConfig = byteArrayOf( 0x1E, 0x16, 0xF3.toByte(), 0xFF.toByte(), // BLE Service Data Header 0xF0.toByte(), // Fragment Indication Sub-Element (unfragmented) 0x5F, 0x09, // UWB Configuration Sub-Element 0x02, 0x00, // Profile ID (Untracked Navigation), Config ID 0 0x06, 0x02, 0x20, 0x08, // Device MAC Address 0x27, 0x02, 0x08, 0x07, // Vendor ID 0x28, 0x06, 0xA1.toByte(), 0xB2.toByte(), 0xC3.toByte(), 0xD4.toByte(), 0xE5.toByte(), 0xF6.toByte(), // Static STS IV 0x9F.toByte(), 0x04, 0xAA.toByte(), 0xBB.toByte(), 0xCC.toByte(), 0xDD.toByte() // Session ID (0xDDCCBBAA) )
OOB yapılandırması eksik olduğu için kullanılamıyorsa veya OOB yapılandırmasında bulunmayan varsayılan değerleri değiştirmeniz gerekiyorsa DlTdoaRangingParams.createFromFiraConfigPacket yerine DlTdoaRangingParams.Builder ile parametreler oluşturabilirsiniz:
val dlTdoaParams = DlTdoaRangingParams.Builder(1) .setComplexChannel( UwbComplexChannel.Builder() .setChannel(9).setPreambleIndex(10).build() ) .setDeviceAddress(deviceAddress) .setSessionKeyInfo(byteArrayOf(0x01, 0x02, 0x03, 0x04)) .setRangingIntervalMillis(240) .setSlotDuration(UwbRangingParams.DURATION_2_MS) .setSlotsPerRangingRound(20) .setRangingRoundIndexes(byteArrayOf(0x01, 0x05)) .build()
Örnek uygulama
Mesafe ölçümü modülünün nasıl kullanılacağına dair uçtan uca bir örnek için AOSP'deki örnek uygulamaya bakın. Bu örnek uygulama, Mesafe Ölçümü modülü tarafından desteklenen tüm mesafe ölçümü teknolojilerini kapsar ve desteklenen her iki oturum türü için akışlar içerir.
iOS cihazlarla UWB birlikte çalışabilirliği
Android örnek uygulaması, iOS örnek uygulaması ile UWB ölçüm oturumu başlatmayı destekler.