Android 16 (ระดับ API 36) เปิดตัวโมดูลการวัดระยะ ซึ่งมีอินเทอร์เฟซที่เป็นมาตรฐานและเป็นหนึ่งเดียวสำหรับการวัดระยะที่แม่นยำระหว่างอุปกรณ์ คุณสามารถใช้แพลตฟอร์ม API นี้เพื่อวัดระยะทางและตำแหน่งของอุปกรณ์ที่เทียบเท่ากันโดยไม่ต้องจัดการเทคโนโลยีการวัดระยะแต่ละรายการแยกกัน
โมดูลการวัดระยะรองรับเทคโนโลยีต่อไปนี้
- แถบความถี่กว้างยิ่งยวด
- การวัดช่องสัญญาณบลูทูธ
- Wi-Fi NAN RTT
- การกำหนดช่วง RSSI ของบลูทูธ
- การตรวจหาฮาร์ดแวร์ใกล้เคียงผ่าน Wi-Fi ใน Android 17 (ระดับ API 37) ขึ้นไป
ความสามารถและความพร้อมใช้งานของ Ranging
คลาส RangingManager จะให้ข้อมูลเกี่ยวกับเทคโนโลยีการวัดระยะที่อุปกรณ์ในพื้นที่รองรับ รวมถึงความพร้อมใช้งานและความสามารถของแต่ละเทคโนโลยีแก่แอป แอปสามารถลงทะเบียนอินเทอร์เฟซ RangingCapabilitiesCallback เพื่อรับข้อมูลอัปเดตเกี่ยวกับการเปลี่ยนแปลงความพร้อมใช้งานหรือความสามารถของเทคโนโลยีที่รองรับ
บทบาทของอุปกรณ์
อุปกรณ์ที่เข้าร่วมเซสชันการวัดระยะต้องเป็นผู้เริ่มต้น ผู้ตอบสนอง หรือแท็ก Downlink-TDoA (DT-Tag) สำหรับเซสชัน UWB Downlink-TDoA ใน Android 17 (ระดับ API 37) ขึ้นไป อุปกรณ์เริ่มต้นจะเริ่มเซสชันการวัดระยะกับอุปกรณ์ตอบสนองอย่างน้อย 1 เครื่อง อุปกรณ์ที่ตอบสนองจะตอบสนองต่อคำขอการวัดระยะจากอุปกรณ์ที่เริ่มต้นเพียงครั้งละ 1 เครื่องเท่านั้น ในเซสชัน Downlink Time Difference of Arrival (DL-TDoA) ของ UWB อุปกรณ์จะใช้บทบาท DEVICE_ROLE_DT_TAG เพื่อรับสัญญาณจาก Anchor ของ UWB หลายรายการ
คุณสามารถระบุบทบาทของอุปกรณ์หนึ่งๆ ในเซสชันการกำหนดระยะได้ด้วยคลาส RangingPreference
ประเภทเซสชันการวัดระยะ
เมื่อเริ่มเซสชันการวัดระยะระหว่างอุปกรณ์ต่างๆ มักจำเป็นต้องสร้างการรับส่งข้อมูลนอกย่านความถี่ (OOB) เพื่อแลกเปลี่ยนพารามิเตอร์สำหรับเซสชัน
โมดูลการกำหนดระยะสามารถจัดการการเจรจาต่อรอง OOB ให้คุณได้ แต่ก็รองรับการใช้งาน OOB ที่กำหนดเองด้วย
การติดตั้งใช้งาน OOB เริ่มต้น
ในเซสชันประเภทนี้ (RANGING_SESSION_OOB) โมดูลการวัดระยะจะจัดการการเจรจา OOB เพื่อเริ่มเซสชันการวัดระยะ โดยจะเลือกพารามิเตอร์ที่เหมาะสมตามค่ากำหนดการวัดระยะที่แอปให้ไว้ และใช้เทคโนโลยีที่เหมาะสมตามที่อุปกรณ์ทั้ง 2 เครื่องรองรับ เซสชันประเภทนี้ใช้ข้อกำหนด OOB ที่ได้มาตรฐาน ใน Android 16 QPR2 (ระดับ API 36.1) ขึ้นไป ผู้เริ่มต้นสามารถจำกัดเทคโนโลยีที่เจรจาได้โดยเรียกใช้ setRangingTechnologyFilter ใน OobInitiatorRangingConfig.Builder
โมดูลการกำหนดระยะจะกำหนดเฉพาะรูปแบบข้อมูล OOB และลำดับที่จะใช้เพื่อโต้ตอบกับอุปกรณ์เพียร์ แต่จะไม่จัดการการค้นหาอุปกรณ์ที่เทียบเท่าหรือการสร้างการเชื่อมต่อ
การติดตั้งใช้งาน OOB ที่กำหนดเอง
ในเซสชันประเภทนี้ (RANGING_SESSION_RAW) แอปจะข้ามขั้นตอน OOB ของโมดูลการวัดระยะและจัดการการเจรจาต่อรองและพารามิเตอร์ OOB ของตนเอง ซึ่งหมายความว่าแอปต้องระบุเทคโนโลยีที่อุปกรณ์เพียร์รองรับ เจรจาต่อรองพารามิเตอร์การวัดระยะ และเริ่มเซสชันการวัดระยะ
ค่ากำหนดการวัดระยะ
ใช้ออบเจ็กต์ RangingPreference เพื่อระบุพารามิเตอร์ที่เลือกสำหรับเซสชันการกำหนดระยะ ซึ่งรวมถึงสิ่งต่อไปนี้
- บทบาทของอุปกรณ์ ซึ่งจะระบุว่าอุปกรณ์เป็นผู้เริ่มต้น ผู้ตอบสนอง หรือ DT-Tag ใน Android 17 (ระดับ API 37) ขึ้นไป
- การกำหนดค่าการวัดระยะทาง ออบเจ็กต์
RangingConfigจะระบุประเภทเซสชันการวัดระยะและพารามิเตอร์อื่นๆ ที่จำเป็นในการเริ่มเซสชันการวัดระยะ - การกำหนดค่าเซสชัน ออบเจ็กต์
SessionConfigจะระบุพารามิเตอร์ที่จะบังคับใช้ในเซสชันการวัดระยะ เช่น ขีดจำกัดการวัด, การรวมเซ็นเซอร์, การกำหนดค่าเขตพื้นที่เสมือน และอื่นๆ ใน Android 17 (ระดับ API 37) ขึ้นไป คุณยังกำหนดค่าโหมดเสาอากาศ (ANTENNA_MODE_DIRECTIONALหรือANTENNA_MODE_OMNI) ด้วยsetAntennaModeในSessionConfig.Builderได้หลังจากตรวจสอบโหมดที่รองรับด้วยgetSupportedAntennaModesในUwbRangingCapabilities
สิทธิ์ในการวัดระยะ
โมดูลการกำหนดระยะใช้สิทธิ์แบบรวม (android.permission.RANGING) สำหรับเทคโนโลยีการกำหนดระยะแบบเพียร์ทูเพียร์ สิทธิ์นี้อยู่ในรายการ NEARBY_DEVICES_PERMISSIONS
<uses-permission android:name="android.permission.RANGING" />
ข้อจำกัด
โมดูลการวัดระยะอาจจำกัดการวัดระยะด้วยเหตุผลหลายประการ เช่น
- แอปของบุคคลที่สามจะได้รับอนุญาตให้ทำการวัดระยะในเบื้องหลังด้วยแถบความถี่กว้างยิ่งยวดเท่านั้น และเฉพาะในอุปกรณ์ที่รองรับ ไม่อนุญาตให้ใช้เทคโนโลยีอื่นๆ ในการวัดระยะในเบื้องหลัง
- ไม่อนุญาตให้ใช้การวัดระยะเมื่ออุปกรณ์มีเซสชันการวัดระยะที่เกิดขึ้นพร้อมกันถึงจำนวนสูงสุดแล้ว
- การกำหนดระยะอาจถูกจำกัดเนื่องจากข้อกังวลด้านประสิทธิภาพของระบบ เช่น แบตเตอรี่ ประสิทธิภาพ หรือหน่วยความจำ
โมดูลการกำหนดระยะยังมีข้อจำกัดที่ทราบดังต่อไปนี้
- โมดูลการกำหนดระยะรองรับเฉพาะการนำส่งข้อมูลการกำหนดระยะไปยังอุปกรณ์ที่เทียบเท่าสำหรับแถบความถี่กว้างยิ่งยวด สำหรับเทคโนโลยีอื่นๆ โมดูลการวัดระยะจะส่งข้อมูลการวัดระยะไปยังอุปกรณ์เริ่มต้นเท่านั้น
- โมดูลการวัดระยะรองรับเฉพาะการเพิ่มอุปกรณ์แบบไดนามิกในโหมดการวัดระยะดิบ และสำหรับแถบความถี่กว้างยิ่งยวดเท่านั้น
- โมดูลการกำหนดระยะไม่รองรับเซสชันแถบความถี่กว้างยิ่งยวดแบบ 1 ต่อหลายรายการสำหรับการติดตั้งใช้งาน OOB เริ่มต้น หากคุณส่งแฮนเดิลอุปกรณ์หลายรายการ โมดูลจะสร้างเซสชันแบบหนึ่งต่อหนึ่งสำหรับอุปกรณ์ที่เชื่อมต่อแต่ละเครื่องที่รองรับแถบความถี่กว้างยิ่งยวด
ดำเนินการเซสชันการวัดระยะ
หากต้องการดำเนินการเซสชันการกำหนดระยะโดยใช้โมดูลการกำหนดระยะ ให้ทำตามขั้นตอนต่อไปนี้
- ตรวจสอบว่าอุปกรณ์ทั้งหมดใช้ Android 16 (ระดับ API 36) ขึ้นไป
- ขอสิทธิ์
android.permission.RANGINGในไฟล์ Manifest ของแอป - ประเมินความสามารถและความพร้อมใช้งานของเทคโนโลยีการวัดระยะ
- ค้นหาอุปกรณ์ที่เทียบเท่าสำหรับการดำเนินการกำหนดระยะ
- สร้างการเชื่อมต่อสำหรับการแลกเปลี่ยนนอกย่านความถี่ โดยใช้เซสชันประเภทใดประเภทหนึ่งที่อธิบายไว้ในประเภทเซสชันการวัดระยะ
- เริ่มการวัดระยะและรับข้อมูลการวัดระยะอย่างต่อเนื่อง
- สิ้นสุดเซสชันการวัดระยะ
ตัวอย่างโค้ดต่อไปนี้แสดงขั้นตอนเหล่านี้สำหรับทั้งบทบาทผู้เริ่มต้นและบทบาทผู้ตอบ
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() } }
จัดการผลลัพธ์การวัดระยะและการเคลื่อนไหวของเพียร์
เมื่อเซสชันทำงานอยู่ RangingSession.Callback จะแสดงการวัดระยะทางและมุมที่มาถึงในออบเจ็กต์ RangingData ผ่าน onResults ดังนี้
- ความไม่แน่นอนของระยะทาง ใน Android 16 QPR2 (ระดับ API 36.1) ขึ้นไป ให้เรียกใช้
hasDistanceStandardDeviationและgetDistanceStandardDeviationMetersในRangingDataเพื่อตรวจสอบค่าเบี่ยงเบนมาตรฐานของการวัดระยะทางเมื่อพร้อมใช้งาน - สิทธิพิเศษเฉพาะเทคโนโลยี ใน Android 17 (ระดับ API 37) ขึ้นไป ให้เรียกใช้
getRangingDataExtrasในRangingDataเพื่อดึงข้อมูลออบเจ็กต์RangingDataExtrasที่มีข้อมูลเมตาเฉพาะเทคโนโลยี เช่นBleSpecificData,UwbSpecificDataหรือWifiRttSpecificData - สถานะการเคลื่อนไหวของแอปเทียบเท่า ใน Android 17 (ระดับ API 37) ขึ้นไป ให้ลบล้าง
onMotionReceivedในRangingSession.Callbackเพื่อรับการอัปเดตMotionState(MOTION_NOT_DETECTED,MOTION_SLIGHT,MOTION_MODERATEหรือMOTION_LARGE) เมื่อการเคลื่อนไหวของอุปกรณ์ที่เชื่อมต่อกันมีการเปลี่ยนแปลง
ความสามารถในการทำงานร่วมกันของ UWB กับอุปกรณ์ iOS
โมดูลการกำหนดระยะรองรับความสามารถในการทำงานร่วมกันกับอุปกรณ์ iOS โดยใช้แถบความถี่กว้างยิ่งยวด (UWB) หากต้องการหาช่วงด้วยอุปกรณ์ iOS คุณต้องใช้การติดตั้งใช้งาน OOB ที่กำหนดเอง และกำหนดค่าเซสชันการหาช่วงด้วยพารามิเตอร์ที่เฉพาะเจาะจงซึ่งตรงกับโปรโตคอลอุปกรณ์เสริมสำหรับการโต้ตอบกับอุปกรณ์ใกล้เคียงของ Apple ดูตัวอย่างได้ที่แอปตัวอย่าง
เมื่อสร้าง RangingPreference ให้ใช้ RawRangingDevice และ UwbRangingParams เพื่อระบุการกำหนดค่า พารามิเตอร์ต่อไปนี้มีความสำคัญต่อความสามารถในการทำงานร่วมกันของ iOS
- รหัสการกำหนดค่า ใช้
UwbRangingParams.CONFIG_UNICAST_DS_TWR - ข้อมูลเซสชันคีย์ ระบุอาร์เรย์ไบต์ที่มีรหัสผู้ให้บริการและ Static STS IV
- Complex Channel ตั้งค่าหมายเลขช่องสัญญาณและดัชนีข้อความนำให้ตรงกับการกำหนดค่าของอุปกรณ์ iOS
ข้อมูลโค้ดต่อไปนี้แสดงวิธีสร้าง RangingPreference สำหรับการกำหนดระยะของอุปกรณ์ผู้เริ่มต้นด้วยอุปกรณ์ 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
ใน Android 17 (ระดับ API 37) ขึ้นไป การกำหนดระยะด้วย Downlink Time Difference of Arrival (DL-TDoA) ช่วยให้อุปกรณ์ระบุตำแหน่งของตนเองโดยสัมพันธ์กับ Anchor ของ UWB หลายตัวได้ด้วยการวัดเวลาที่สัญญาณมาถึงโดยสัมพันธ์กัน
ข้อมูลโค้ดต่อไปนี้แสดงวิธีใช้ RangingManager เพื่อยืนยันการรองรับ DL-TDoA, กำหนดค่า DlTdoaRangingParams และ RawDtTagRangingConfig เพื่อเริ่มเซสชัน และรับผลลัพธ์ 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) { // ... } }
การกำหนดค่า Out-of-Band (OOB)
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างข้อมูลการกำหนดค่า DL-TDoA OOB สำหรับ Wi-Fi และ 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) )
หากใช้การกำหนดค่า OOB ไม่ได้เนื่องจากไม่มี หรือหากต้องการเปลี่ยนค่าเริ่มต้นที่ไม่ได้อยู่ในการกำหนดค่า OOB คุณสามารถสร้างพารามิเตอร์ด้วย DlTdoaRangingParams.Builder แทนการเรียกใช้ 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()
แอปตัวอย่าง
ดูตัวอย่างตั้งแต่ต้นจนจบเกี่ยวกับวิธีใช้โมดูลการกำหนดระยะได้ที่แอปตัวอย่างใน AOSP แอปตัวอย่างนี้ครอบคลุมเทคโนโลยีการวัดระยะทั้งหมดที่โมดูลการวัดระยะรองรับ และรวมถึงขั้นตอนสำหรับเซสชันทั้ง 2 ประเภทที่รองรับ
ความสามารถในการทำงานร่วมกันของ UWB กับอุปกรณ์ iOS
แอปตัวอย่างของ Android รองรับการเริ่มเซสชันการวัดระยะด้วย UWB กับแอปตัวอย่างของ iOS