Cihazlar arasındaki mesafe

Android 16, cihazlar arasında hassas mesafeyi ölçmek için birleşik ve standartlaştırılmış bir arayüz sağlayan Ranging modülünü sunar. Bu API yüzeyini kullanarak her bir mesafe ölçme teknolojisini ayrı ayrı ele almanıza gerek kalmadan eş 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 durumu

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ı yaptırabilir.

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 mesafe ölçme oturumunu başlatır. Yanıtlayıcı cihaz, tek seferde yalnızca bir başlatıcıdan gelen mesafe ölçme isteklerine yanıt verir. RangingPreference sınıfıyla bir mesafe ölçme oturumunda belirli bir cihazın rolünü belirtebilirsiniz.

Ranging oturum türleri

Cihazlar arasında mesafe ölçme oturumu başlatırken oturum parametrelerini değiştirmek için genellikle bant dışı (OOB) veri aktarımı oluşturmak gerekir.

Ranging modülü, sizin için OOB pazarlıklarını yönetebilir ancak özel OOB uygulamalarını da destekler.

Şekil 1. Oturum türleri için OOB akışı.

Varsayılan OOB uygulaması

Bu oturum türünde (RANGING_SESSION_OOB), mesafe ölçme oturumu başlatmak için mesafe ölçme modülü OOB görüşmelerini 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 standartlaştırılmış bir OOB specification kullanılır.

Ranging 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 alanlar/yollar aşağıdakileri içerir:

• Cihaz rolü. Bu, cihazın başlatıcı mı yoksa yanıtlayıcı mı olacağını gösterir.
• Mesafe ölçme yapılandırması. Bir RangingConfig nesnesi, 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 SessionConfig nesnesi, ölçüm sınırı, sensör füzyonu ve 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, arka planda ultra geniş bant ile mesafe ölçümü yapmasına yalnızca desteklenen cihazlarda izin verilir. Diğer teknolojilerle arka planda mesafe ölçümüne izin verilmez.
• Cihaz başına maksimum eşzamanlı mesafe ölçme oturumu sayısına ulaşıldığında mesafe ölçmeye izin verilmez.
• Mesafe ölçümü, 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, Ranging modülü yalnızca başlatıcı cihaza mesafe verileri sağlar.
• Mesafe ölçme modülü yalnızca ham mesafe ölçme modunda cihazların dinamik olarak eklenmesini ve yalnızca ultra geniş bant için destekler.
• Mesafe ölçme modülü, varsayılan OOB uygulamaları için bire çok ultra geniş bant oturumlarını desteklemez. Birden fazla cihaz tutma yeri 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:

1. Tüm cihazların Android 16 veya sonraki bir sürümde çalıştığını doğrulayın.
2. Uygulama manifestinde android.permission.RANGING iznini isteyin.
3. Mesafe ölçme teknolojilerinin özelliklerini ve kullanılabilirliğini değerlendirin.
4. Mesafe ölçme işlemleri için bir benzer cihaz keşfedin.
5. 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ı kurun.
6. Mesafe ölçümünü başlatın ve sürekli olarak mesafe ölçümü verileri alın.
7. 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_TWR kullanı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();

UWB Downlink-TDoA API

UWB DL-TDoA API için Android 17'deki yeni özellikler başlıklı makaleyi inceleyin.

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

Şekil 2. Android ve iOS'te UWB kullanımı.