Zasięg między urządzeniami

Android 16 (poziom API 36) wprowadza moduł pomiaru odległości, który zapewnia ujednolicony i ujednolicony interfejs do precyzyjnego pomiaru odległości między urządzeniami. Możesz używać tego interfejsu API do pomiaru odległości i pozycji urządzeń równorzędnych bez konieczności obsługi każdej technologii pomiaru odległości osobno.

Moduł pomiaru odległości obsługuje te technologie:

Możliwości i dostępność funkcji pomiaru odległości

Klasa RangingManager dostarcza aplikacjom informacje o technologiach pomiaru odległości obsługiwanych przez urządzenie lokalne, a także o dostępności i możliwościach każdej z nich. Aplikacje mogą zarejestrować interfejs RangingCapabilitiesCallback, aby otrzymywać aktualizacje dotyczące zmian w dostępności lub możliwościach obsługiwanych technologii.

Role urządzeń

Urządzenie uczestniczące w sesji pomiaru odległości musi być inicjatorem, odpowiadającym lub tagiem Downlink-TDoA (DT-Tag) w przypadku sesji UWB Downlink-TDoA na Androidzie 17 (poziom API 37) lub nowszym. Urządzenie inicjujące rozpoczyna sesję pomiaru odległości z co najmniej 1 urządzeniem odpowiadającym. Urządzenie odpowiadające odpowiada na żądania pomiaru odległości tylko od jednego inicjatora naraz. W sesji UWB Downlink Time Difference of Arrival (DL-TDoA) urządzenie używa roli DEVICE_ROLE_DT_TAG do odbierania sygnałów z wielu kotwic UWB. Rolę danego urządzenia w sesji określania odległości możesz określić za pomocą klasy RangingPreference.

Typy sesji pomiaru odległości

Podczas rozpoczynania sesji pomiaru odległości między urządzeniami często konieczne jest ustanowienie transportu danych poza pasmem (OOB) w celu wymiany parametrów sesji.

Moduł określania odległości może obsługiwać negocjacje OOB, ale obsługuje też niestandardowe implementacje OOB.

Rysunek 1. Przepływ OOB dla typów sesji.

Domyślna implementacja OOB

W tym typie sesji (RANGING_SESSION_OOB) moduł pomiaru odległości obsługuje negocjacje OOB, aby rozpocząć sesję pomiaru odległości. Wybiera odpowiednie parametry na podstawie preferencji dotyczących zakresu podanych przez aplikację i używa odpowiednich technologii na podstawie tego, co obsługują oba urządzenia. Ten typ sesji korzysta ze standardowej specyfikacji OOB. Na Androidzie 16 QPR2 (poziom API 36.1) i nowszych inicjatorzy mogą ograniczyć technologie, które są negocjowane, wywołując setRangingTechnologyFilter w OobInitiatorRangingConfig.Builder.

Moduł pomiaru odległości definiuje tylko format i sekwencję danych OOB, które mają być używane do interakcji z urządzeniem równorzędnym. Nie obsługuje wykrywania urządzeń równorzędnych ani nawiązywania połączeń.

Niestandardowa implementacja OOB

W tym typie sesji (RANGING_SESSION_RAW) aplikacja pomija proces OOB modułu Ranging i obsługuje własne negocjacje i parametry OOB. Oznacza to, że aplikacja musi określić, które technologie obsługuje urządzenie równorzędne, wynegocjować parametry pomiaru odległości i rozpocząć sesję pomiaru odległości.

Ustawienia zakresu

Użyj obiektu RangingPreference, aby określić wybrane parametry sesji pomiaru odległości. między innymi na następujące działania:

  • Rola urządzenia. Wskazuje, czy urządzenie jest inicjatorem, odpowiadającym czy tagiem DT na Androidzie 17 (interfejs API na poziomie 37) lub nowszym.
  • Konfiguracja pomiaru odległości. Obiekt RangingConfig określa typ sesji pomiaru odległości i inne parametry potrzebne do rozpoczęcia sesji pomiaru odległości.
  • Konfiguracja sesji. Obiekt SessionConfig określa parametry, które mają być wymuszane podczas sesji pomiaru odległości, takie jak limit pomiaru, fuzja czujników, konfiguracja geofence i inne. Na Androidzie 17 (poziom interfejsu API 37) i nowszym możesz też skonfigurować tryb anteny (ANTENNA_MODE_DIRECTIONAL lub ANTENNA_MODE_OMNI) za pomocą setAntennaMode na SessionConfig.Builder po sprawdzeniu obsługiwanych trybów za pomocą getSupportedAntennaModes na UwbRangingCapabilities.

Uprawnienia do określania odległości

Moduł Ranging używa ujednoliconego uprawnienia (android.permission.RANGING) do technologii pomiaru odległości peer-to-peer. To uprawnienie znajduje się na liście NEARBY_DEVICES_PERMISSIONS.

<uses-permission android:name="android.permission.RANGING" />

Ograniczenia

Moduł Ranging może ograniczać pomiar odległości z kilku powodów, takich jak:

  • Aplikacje innych firm mogą wykonywać pomiary odległości w tle tylko za pomocą łącza ultraszerokopasmowego i tylko na obsługiwanych urządzeniach. Określanie odległości w tle za pomocą innych technologii jest niedozwolone.
  • Określanie odległości jest niedozwolone, gdy zostanie osiągnięta maksymalna liczba jednoczesnych sesji określania odległości na urządzeniu.
  • Określanie odległości może być ograniczone ze względu na stan systemu, np. baterię, wydajność lub pamięć.

Moduł Ranging ma też te znane ograniczenia:

  • Moduł zakresu obsługuje tylko dostarczanie danych o zakresie do urządzeń peer-to-peer w przypadku łącza ultraszerokopasmowego. W przypadku innych technologii moduł pomiaru odległości dostarcza dane dotyczące odległości tylko do urządzenia inicjującego.
  • Moduł pomiaru odległości obsługuje dynamiczne dodawanie urządzeń tylko w trybie nieprzetworzonego pomiaru odległości i tylko w przypadku łącza ultraszerokopasmowego.
  • Moduł pomiaru odległości nie obsługuje sesji łącza ultraszerokopasmowego typu jeden do wielu w przypadku domyślnych implementacji OOB. Jeśli przekażesz kilka uchwytów urządzeń, moduł utworzy sesję 1:1 dla każdego urządzenia równorzędnego, które obsługuje ultraszerokopasmowość.

Przeprowadzanie sesji pomiaru odległości

Aby przeprowadzić sesję pomiaru odległości za pomocą modułu pomiaru odległości, wykonaj te czynności:

  1. Sprawdź, czy wszystkie urządzenia mają Androida 16 (API na poziomie 36) lub nowszego.
  2. Poproś o uprawnienie android.permission.RANGING w pliku manifestu aplikacji.
  3. ocenić możliwości i dostępność technologii pomiaru odległości;
  4. wykrywanie urządzenia równorzędnego na potrzeby operacji określania odległości;
  5. Nawiąż połączenie na potrzeby wymiany poza pasmem, używając jednego z typów sesji opisanych w sekcji Typy sesji pomiaru odległości.
  6. rozpoczynanie pomiaru odległości i ciągłe pozyskiwanie danych dotyczących odległości;
  7. Zakończ sesję pomiaru odległości.

Poniższy przykładowy kod pokazuje te kroki zarówno w przypadku roli inicjatora, jak i roli odpowiadającego.

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()
    }
}

Obsługa wyników pomiaru odległości i ruchu urządzenia równorzędnego

Gdy sesja jest aktywna, RangingSession.Callback dostarcza pomiary odległości i kąta nadejścia w obiektach RangingData za pomocą onResults:

  • Niepewność odległości. Na Androidzie 16 QPR2 (poziom API 36.1) i nowszych wywołaj hasDistanceStandardDeviation i getDistanceStandardDeviationMeters na RangingData, aby sprawdzić odchylenie standardowe pomiarów odległości, gdy jest dostępne.
  • Dodatki związane z technologią. Na Androidzie 17 (poziom API 37) i nowszych wywołaj getRangingDataExtras na RangingData, aby pobrać obiekt RangingDataExtras zawierający metadane dotyczące technologii, takie jak BleSpecificData, UwbSpecificData lub WifiRttSpecificData.
  • Stan ruchu partnera. Na Androidzie 17 (poziom API 37) i nowszych zastąp onMotionReceived w RangingSession.Callback, aby otrzymywać aktualizacje MotionState (MOTION_NOT_DETECTED, MOTION_SLIGHT, MOTION_MODERATE lub MOTION_LARGE), gdy zmienia się ruch urządzenia równorzędnego.

Interoperacyjność UWB z urządzeniami z iOS

Moduł pomiaru odległości obsługuje interoperacyjność z urządzeniami z iOS za pomocą łącza ultraszerokopasmowego (UWB). Aby określić odległość za pomocą urządzenia z iOS, musisz użyć niestandardowej implementacji OOB i skonfigurować sesję określania odległości z określonymi parametrami, które pasują do protokołu Apple Nearby Interaction Accessory Protocol. Przykład znajdziesz w przykładowej aplikacji.

Podczas tworzenia RangingPreference użyj RawRangingDevice i UwbRangingParams, aby określić konfigurację. Te parametry są kluczowe dla interoperacyjności z iOS:

  • Identyfikator konfiguracji. Użyj formatu UwbRangingParams.CONFIG_UNICAST_DS_TWR.
  • Informacje o kluczu sesji. Podaj tablicę bajtów zawierającą identyfikator dostawcy i statyczny wektor inicjujący STS.
  • Kanał złożony Ustaw numer kanału i indeks wprowadzenia, aby dopasować je do konfiguracji urządzenia z iOS.

Poniższy fragment kodu pokazuje, jak utworzyć RangingPreference dla urządzenia inicjującego, które mierzy odległość od urządzenia odpowiadającego z iOS:

// 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

Na Androidzie 17 (poziom interfejsu API 37) i nowszych funkcja określania odległości na podstawie różnicy czasu nadejścia sygnału (DL-TDoA) umożliwia urządzeniu określenie jego pozycji względem wielu punktów odniesienia UWB przez pomiar względnego czasu nadejścia sygnałów.

Poniższy fragment kodu pokazuje, jak używać RangingManager do weryfikacji obsługi DL-TDoA, konfigurować DlTdoaRangingParams i RawDtTagRangingConfig, aby rozpocząć sesję, oraz otrzymywać wyniki DlTdoaMeasurement:

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) {
        // ...
    }
}

Konfiguracje poza pasmem (OOB)

Poniższy fragment kodu przedstawia przykładowe dane konfiguracji DL-TDoA OOB dla Wi-Fi i BLE:

// 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)
)

Jeśli nie możesz użyć konfiguracji OOB, ponieważ jej brakuje, lub jeśli chcesz zmienić wartości domyślne, których nie ma w konfiguracji OOB, możesz utworzyć parametry za pomocą DlTdoaRangingParams.Builder zamiast wywoływać DlTdoaRangingParams.createFromFiraConfigPacket:

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()

Przykładowa aplikacja

Kompleksowy przykład użycia modułu pomiaru odległości znajdziesz w przykładowej aplikacji w AOSP. Ta przykładowa aplikacja obejmuje wszystkie technologie określania odległości obsługiwane przez moduł określania odległości i zawiera przepływy dla obu obsługiwanych typów sesji.

Interoperacyjność UWB z urządzeniami z iOS

Przykładowa aplikacja na Androida obsługuje rozpoczynanie sesji pomiaru odległości UWB z przykładową aplikacją na iOS.

Rysunek 2. korzystanie z UWB na Androidzie i iOS.