Phạm vi giữa các thiết bị

Android 16 giới thiệu mô-đun Phạm vi, cung cấp giao diện hợp nhất và chuẩn hoá để đo phạm vi chính xác giữa các thiết bị. Bạn có thể sử dụng giao diện API này để đo khoảng cách và vị trí của các thiết bị đồng cấp mà không cần xử lý từng công nghệ đo khoảng cách riêng lẻ.

Mô-đun Đo khoảng cách hỗ trợ các công nghệ sau:

Phạm vi tính năng và phạm vi cung cấp

Lớp RangingManager cung cấp cho ứng dụng thông tin về các công nghệ đo khoảng cách mà thiết bị cục bộ hỗ trợ, cũng như khả năng sử dụng và chức năng của từng công nghệ. Các ứng dụng có thể đăng ký Callback để nhận thông tin cập nhật về mọi thay đổi đối với phạm vi cung cấp hoặc chức năng của mọi công nghệ được hỗ trợ.

Vai trò của thiết bị

Thiết bị tham gia một phiên đo khoảng cách phải là thiết bị khởi tạo hoặc thiết bị phản hồi. Thiết bị khởi tạo bắt đầu phiên đo khoảng cách với một hoặc nhiều thiết bị phản hồi. Mỗi lần, thiết bị phản hồi chỉ phản hồi các yêu cầu đo khoảng cách từ một thiết bị khởi tạo. Bạn có thể chỉ định vai trò cho một thiết bị nhất định trong một phiên đo khoảng cách bằng lớp RangingPreference.

Các loại phiên hoạt động

Khi bắt đầu một phiên đo khoảng cách giữa các thiết bị, thường cần thiết lập một phương thức truyền dữ liệu ngoài băng tần (OOB) để trao đổi các thông số cho phiên đó.

Mô-đun Phạm vi có thể xử lý các cuộc đàm phán OOB cho bạn, nhưng cũng hỗ trợ triển khai OOB tuỳ chỉnh.

Hình 1. Quy trình OOB cho các loại phiên.

Triển khai OOB mặc định

Trong loại phiên này (RANGING_SESSION_OOB), mô-đun Đo khoảng cách xử lý các cuộc đàm phán OOB để bắt đầu một phiên đo khoảng cách. Công cụ này chọn các tham số phù hợp dựa trên các lựa chọn ưu tiên về phạm vi do ứng dụng cung cấp và sử dụng các công nghệ thích hợp dựa trên những gì cả hai thiết bị hỗ trợ. Loại phiên này sử dụng OOB specification đã chuẩn hoá.

Mô-đun Đo khoảng cách chỉ xác định định dạng và trình tự dữ liệu OOB được dùng để tương tác với thiết bị ngang hàng. Lớp này không xử lý việc phát hiện thiết bị ngang hàng hoặc thiết lập kết nối.

Triển khai OOB tuỳ chỉnh

Trong loại phiên này (RANGING_SESSION_RAW), ứng dụng sẽ bỏ qua luồng OOB của mô-đun Phạm vi và xử lý các tham số và quy trình đàm phán OOB của riêng ứng dụng. Điều đó có nghĩa là ứng dụng phải xác định những công nghệ mà thiết bị đồng cấp hỗ trợ, đàm phán các tham số đo khoảng cách và bắt đầu phiên đo khoảng cách.

Lựa chọn ưu tiên về phạm vi

Sử dụng đối tượng RangingPreference để chỉ định các tham số mong muốn cho một phiên đo khoảng cách. Trong đó có:

  • Vai trò của thiết bị. Giá trị này cho biết thiết bị sẽ là thiết bị khởi tạo hay thiết bị phản hồi.
  • Cấu hình đo khoảng cách. Đối tượng RangingConfig chỉ định loại phiên đo khoảng cách và các tham số khác cần thiết để bắt đầu một phiên đo khoảng cách.
  • Cấu hình phiên. Đối tượng SessionConfig chỉ định các thông số sẽ được thực thi trên phiên đo khoảng cách, chẳng hạn như giới hạn đo lường, hợp nhất cảm biến, cấu hình khoanh vùng địa lý, v.v.

Quyền đo khoảng cách

Mô-đun Đo khoảng cách yêu cầu một quyền hợp nhất mới (android.permission.RANGING) để truy cập vào tất cả các công nghệ đo khoảng cách hiện tại và trong tương lai. Quyền này nằm trong danh sách NEARBY_DEVICES_PERMISSIONS.

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

Quy định hạn chế và giới hạn

Mô-đun Đo khoảng cách có thể hạn chế việc đo khoảng cách do một số lý do, bao gồm cả những lý do sau:

  • Ứng dụng bên thứ ba chỉ được phép thực hiện tính năng đo khoảng cách ở chế độ nền bằng băng tần siêu rộng và chỉ trên các thiết bị được hỗ trợ. Không được phép đo khoảng cách ở chế độ nền bằng các công nghệ khác.
  • Không được phép đo khoảng cách khi đã đạt đến số lượng phiên đo khoảng cách đồng thời tối đa theo thiết bị.
  • Phạm vi có thể bị hạn chế do các vấn đề về tình trạng hệ thống, chẳng hạn như pin, hiệu suất hoặc bộ nhớ.

Mô-đun Đo khoảng cách cũng có các hạn chế đã biết sau:

  • Mô-đun Đo khoảng cách chỉ hỗ trợ việc phân phối dữ liệu đo khoảng cách đến các thiết bị ngang hàng cho băng tần siêu rộng. Đối với các công nghệ khác, mô-đun Đo khoảng cách chỉ phân phối dữ liệu đo khoảng cách đến thiết bị khởi tạo.
  • Mô-đun Đo khoảng cách chỉ hỗ trợ việc thêm thiết bị một cách linh động ở chế độ đo khoảng cách thô và chỉ dành cho băng tần siêu rộng.
  • Mô-đun Đo khoảng cách không hỗ trợ các phiên băng tần siêu rộng một với nhiều cho các hoạt động triển khai OOB mặc định. Nếu bạn truyền nhiều tay điều khiển thiết bị, mô-đun sẽ tạo một phiên một với một cho mỗi thiết bị ngang hàng hỗ trợ băng tần siêu rộng.

Thực hiện một phiên đo khoảng cách

Để tiến hành một phiên đo khoảng cách bằng mô-đun Đo khoảng cách, hãy làm theo các bước sau:

  1. Xác minh rằng tất cả thiết bị đều đang chạy Android 16 trở lên.
  2. Yêu cầu quyền android.permission.RANGING trong tệp kê khai ứng dụng.
  3. Đánh giá khả năng và phạm vi cung cấp của các công nghệ đo khoảng cách.
  4. Khám phá thiết bị ngang hàng để thực hiện các thao tác đo khoảng cách.
  5. Thiết lập kết nối cho một giao dịch trao đổi ngoài băng thông, bằng cách sử dụng một trong các loại phiên được mô tả trong phần Các loại phiên đo khoảng cách.
  6. Bắt đầu đo khoảng cách và liên tục thu thập dữ liệu đo khoảng cách.
  7. Chấm dứt phiên đo khoảng cách.

Mã mẫu sau đây minh hoạ các bước này cho cả vai trò người khởi tạo và vai trò người phản hồi.

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

Ứng dụng mẫu

Để biết ví dụ toàn diện về cách sử dụng mô-đun Đo khoảng cách, hãy xem ứng dụng mẫu trong AOSP. Ứng dụng mẫu này bao gồm tất cả các công nghệ đo khoảng cách được mô-đun Đo khoảng cách hỗ trợ và bao gồm các luồng cho cả hai loại phiên được hỗ trợ.