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:
- Łącze ultraszerokopasmowe
- Sondowanie kanału Bluetooth
- Wi-Fi NAN RTT
- Zakres RSSI Bluetooth
- Wykrywanie urządzeń w pobliżu przez Wi-Fi na Androidzie 17 (poziom interfejsu API 37) i nowszym
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.
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
RangingConfigokreśla typ sesji pomiaru odległości i inne parametry potrzebne do rozpoczęcia sesji pomiaru odległości. - Konfiguracja sesji. Obiekt
SessionConfigokreś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_DIRECTIONALlubANTENNA_MODE_OMNI) za pomocąsetAntennaModenaSessionConfig.Builderpo sprawdzeniu obsługiwanych trybów za pomocągetSupportedAntennaModesnaUwbRangingCapabilities.
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:
- Sprawdź, czy wszystkie urządzenia mają Androida 16 (API na poziomie 36) lub nowszego.
- Poproś o uprawnienie
android.permission.RANGINGw pliku manifestu aplikacji. - ocenić możliwości i dostępność technologii pomiaru odległości;
- wykrywanie urządzenia równorzędnego na potrzeby operacji określania odległości;
- 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.
- rozpoczynanie pomiaru odległości i ciągłe pozyskiwanie danych dotyczących odległości;
- 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
hasDistanceStandardDeviationigetDistanceStandardDeviationMetersnaRangingData, 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
getRangingDataExtrasnaRangingData, aby pobrać obiektRangingDataExtraszawierający metadane dotyczące technologii, takie jakBleSpecificData,UwbSpecificDatalubWifiRttSpecificData. - Stan ruchu partnera. Na Androidzie 17 (poziom API 37) i nowszych zastąp
onMotionReceivedwRangingSession.Callback, aby otrzymywać aktualizacjeMotionState(MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATElubMOTION_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.