Android 16, cihazlar arasında hassas mesafe ölçümü için birleşik ve standartlaştırılmış bir arayüz sağlayan Mesafe Ölçümü modülünü sunar. Bu API yüzeyini kullanarak, her bir mesafe ölçme teknolojisini ayrı ayrı ele almanıza gerek kalmadan yakındaki cihazların mesafesini ve konumunu ölçebilirsiniz.
Mesafe ölçme modülü aşağıdaki teknolojileri destekler:
- Ultra geniş bant
- Bluetooth kanal seslendirmesi
- Wi-Fi NAN RTT
- Bluetooth RSSI aralığı
Mesafe ölçme özellikleri ve kullanılabilirlik
RangingManager sınıfı, uygulamalara yerel cihaz tarafından desteklenen mesafe ölçme teknolojileri, her teknolojinin kullanılabilirliği ve özellikleri hakkında bilgi sağlar. Uygulamalar, desteklenen teknolojilerin kullanılabilirliğinde veya özelliklerinde yapılan değişikliklerle ilgili güncellemeler almak için Callback kaydı oluşturabilir.
Cihaz rolleri
Mesafe ölçme oturumuna katılan bir cihaz başlatıcı veya yanıtlayıcı olmalıdır. Başlatıcı cihaz, bir veya daha fazla yanıtlayıcı cihazla aralık belirleme oturumunu başlatır. Yanıtlayıcı cihaz, aralık belirleme isteklerine tek seferde yalnızca bir başlatıcıdan gelen istekleri yanıtlar. RangingPreference sınıfıyla bir mesafe ölçme oturumunda belirli bir cihazın rolünü belirtebilirsiniz.
Ranging oturum türleri
Cihazlar arasında bir mesafe ölçme oturumu başlatırken genellikle oturum parametrelerini değiştirmek için bant dışı (OOB) veri aktarımı oluşturmak gerekir.
Kapsam modülü, sizin için OOB pazarlıklarını yönetebilir ancak özel OOB uygulamalarını da destekler.
Varsayılan OOB uygulaması
Bu oturum türünde (RANGING_SESSION_OOB), Ranging modülü, bir mesafe ölçme oturumu başlatmak için bant dışı görüşmeleri yönetir. Uygulama tarafından sağlanan aralık tercihlerine göre uygun parametreleri seçer ve her iki cihazın da desteklediği teknolojileri kullanır. Bu oturum türünde standart bir OOB specification kullanılır.
Aralık 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, Ranging modülünün OOB akışını atlar ve kendi OOB görüşmesini ve parametrelerini işler. Bu nedenle, uygulamanın eş cihazın hangi teknolojileri desteklediğini belirlemesi, mesafe ölçümü parametrelerini görüşmesi ve mesafe ölçümü oturumunu başlatması gerekir.
Aralık tercihleri
Belirli bir oturum için seçilen parametreleri belirtmek üzere RangingPreference nesnesini kullanın. Bu destek, şunları içerir:
- Cihaz rolü. Bu, cihazın başlatıcı mı yoksa yanıtlayıcı mı olacağını gösterir.
- Mesafe yapılandırması. Bir
RangingConfignesnesi, mesafe ölçme oturumu türünü ve mesafe ölçme oturumu başlatmak için gereken diğer parametreleri belirtir. - Oturum yapılandırması. Bir
SessionConfignesnesi, ölçüm sınırı, sensör füzyonu, coğrafi çit yapılandırması gibi aralık belirleme oturumunda uygulanacak parametreleri belirtir.
Aralık izni
Mesafe ölçme modülü, mevcut ve gelecekteki tüm mesafe ölçme teknolojilerine erişmek için yeni bir birleştirilmiş izin (android.permission.RANGING) gerektirir. Bu izin, NEARBY_DEVICES_PERMISSIONS listesinde yer alıyor.
<uses-permission android:name="android.permission.RANGING" />
Kısıtlamalar ve sınırlamalar
Mesafe ölçme modülü, aşağıdakiler de dahil olmak üzere çeşitli nedenlerle mesafe ölçmeyi 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 aralık belirlemeye izin verilmez.
- Cihaz başına maksimum eşzamanlı aralık belirleme oturumu sayısına ulaşıldığında aralık belirlemeye izin verilmez.
- Mesafe ölçme, pil, performans veya bellek gibi sistem sağlığıyla ilgili sorunlar nedeniyle kısıtlanabilir.
Mesafe ölçme modülünün bilinen sınırlamaları da şunlardır:
- Mesafe ölçme modülü yalnızca ultra geniş bant için mesafe ölçme verilerinin yakındaki cihazlara iletilmesini destekler. Diğer teknolojilerde, mesafe ölçme modülü yalnızca başlatıcı cihaza mesafe ölçme verileri sağlar.
- Mesafe ölçme modülü, yalnızca ham mesafe ölçme modunda ve yalnızca ultra geniş bant için cihazların dinamik olarak eklenmesini destekler.
- Mesafe ölçme 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çme oturumu gerçekleştirme
Mesafe ölçme modülünü kullanarak mesafe ölçme oturumu gerçekleştirmek için aşağıdaki adımları uygulayın:
- Tüm cihazların Android 16 veya sonraki bir sürümde çalıştığını doğrulayın.
- Uygulama manifestinde
android.permission.RANGINGiznini isteyin. - Mesafe ölçme teknolojilerinin özelliklerini ve kullanılabilirliğini değerlendirin.
- Mesafe ölçme işlemleri için bir benzer cihaz keşfedin.
- Mesafe ölçme oturumu türleri bölümünde açıklanan oturum türlerinden birini kullanarak bant dışı değişim için bağlantı oluşturun.
- Mesafe ölçümünü başlatın ve sürekli olarak mesafe ölçümü verileri alın.
- Mesafe ölçme oturumunu sonlandırın.
Aşağıdaki kod örneğinde, bu adımlar hem başlatıcı hem de yanıtlayıcı rolü için gösterilmektedir.
Kotlin
class RangingApp {
// Starts a ranging session on the initiator side.
fun startRangingInitiator(
context: Context,
deviceHandle: DeviceHandle,
executor: Executor,
callback: RangingSessionCallback
) {
// 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)
// 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.
session.start(preference)
// If successful, the ranging data will be sent through callback#onResults
// Stop ranging session
session.stop()
}
// Starts a ranging session on the responder side.
fun startRangingResponder(
context: Context,
deviceHandle: DeviceHandle,
executor: Executor,
callback: RangingSessionCallback
) {
// 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)
// 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.
session.start(preference)
// Stop the ranging session
session.stop()
}
}
Java
public class RangingApp {
// Starts a ranging session on the initiator side.
void startRangingInitiator(Context context, DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {
// Get the RangingManager which is the entry point for ranging module.
RangingManager manager = context.getSystemService(RangingManager.class);
// Create a new RangingSession using the provided executor and callback.
RangingSession session = manager.createRangingSession(executor, callback);
// Create an OobInitiatorRangingConfig, which specifies the ranging parameters for
// the initiator role.
OobInitiatorRangingConfig config = new 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.
RangingPreference preference =
new RangingPreference.Builder(DEVICE_ROLE_INITIATOR, config).build();
// Start ranging session.
session.start(preference);
// If successful, the ranging data will be sent through callback#onResults
// Stop ranging session
session.stop();
}
// Starts a ranging session on the responder side.
void startRangingResponder(Context context, DeviceHandle deviceHandle, Executor executor, RangingSessionCallback callback) {
// Get the RangingManager which is the entry point for ranging module.
RangingManager manager = context.getSystemService(RangingManager.class);
// Create a new RangingSession using the provided executor and callback.
RangingSession session = manager.createRangingSession(executor, callback);
// Create an OobResponderRangingConfig, which specifies the ranging parameters for
// the responder role.
OobResponderRangingConfig config = new OobResponderRangingConfig.Builder( deviceHandle).build();
// Create a RangingPreference, which specifies the role (responder) and
// configuration for the ranging session.
RangingPreference preference =
new RangingPreference.Builder(DEVICE_ROLE_RESPONDER, config).build();
// Start the ranging session.
session.start(preference);
// Stop the ranging session
session.stop();
}
}
iOS cihazlarla ultra geniş bant birlikte çalışabilirliği
Mesafe ölçme modülü, ultra geniş bant (UWB) kullanan iOS cihazlarla birlikte çalışmayı destekler. iOS cihazla mesafe ölçümü yapmak için özel bir OOB uygulaması kullanmanız ve mesafe ölçümü oturumunu Apple Nearby Interaction Accessory Protocol ile eşleşen belirli parametrelerle yapılandırmanız gerekir. Referans 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 birlikte çalışabilirliği için çok önemlidir:
- Yapılandırma kimliği:
UwbRangingParams.CONFIG_UNICAST_DS_TWRkullanın. - Oturum Anahtarı Bilgileri: Satıcı kimliğini ve statik STS IV'yi içeren bir bayt dizisi sağlayın.
- Karmaşık Kanal: Kanal numarasını ve önsöz 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 aralık belirleyen bir başlatıcı cihaz için RangingPreference nasıl oluşturulacağı gösterilmektedir:
Kotlin
// 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()
Java
// Create UwbRangingParams with iOS-specific configuration
UwbRangingParams uwbRangingParams = new UwbRangingParams.Builder(
sessionId,
UwbRangingParams.CONFIG_UNICAST_DS_TWR,
sourceAddress,
destinationAddress)
.setComplexChannel(new UwbComplexChannel.Builder()
.setChannel(channelNumber)
.setPreambleIndex(preambleIndex)
.build())
.setRangingUpdateRate(updateRate)
.setSessionKeyInfo(sessionKeyInfo) // Vendor ID + STS IV
.setSlotDuration(slotDuration)
.build();
// Create RawRangingDevice
RawRangingDevice rawRangingDevice = new RawRangingDevice.Builder()
.setRangingDevice(new RangingDevice.Builder().build())
.setUwbRangingParams(uwbRangingParams)
.build();
// Create SessionConfig
SessionConfig sessionConfig = new SessionConfig.Builder()
.setAngleOfArrivalNeeded(true)
.setDataNotificationConfig(new DataNotificationConfig.Builder()
.setNotificationConfigType(DataNotificationConfig.NOTIFICATION_CONFIG_ENABLE)
.build())
.build();
// Create RangingPreference for the initiator
RangingPreference preference = new RangingPreference.Builder(
RangingPreference.DEVICE_ROLE_INITIATOR,
new RawInitiatorRangingConfig.Builder()
.addRawRangingDevice(rawRangingDevice)
.build())
.setSessionConfig(sessionConfig)
.build();
Örnek uygulama
Mesafe ölçme 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, Ranging modülü tarafından desteklenen tüm mesafe ölçme teknolojilerini kapsar ve desteklenen her iki oturum türü için de akışlar içerir.
iOS cihazlarla ultra geniş bant birlikte çalışabilirliği
Android örnek uygulaması, iOS örnek uygulaması ile UWB mesafe ölçümü oturumu başlatmayı destekler.