Gugus Instrumen

Gunakan Instrument Cluster API (API Android) untuk menampilkan aplikasi navigasi, termasuk Google Maps, pada tampilan sekunder di dalam mobil, seperti di belakang kemudi pada panel instrumen. Halaman ini menjelaskan cara membuat layanan untuk mengontrol tampilan sekunder tersebut dan kemudian mengintegrasikan layanan dengan CarService sehingga aplikasi navigasi dapat menampilkan antarmuka pengguna.

Terminologi

Istilah berikut digunakan di halaman ini:

Prasyarat

Untuk mengembangkan integrasi, pastikan untuk memiliki elemen-elemen ini:

• lingkungan pengembangan Android. Untuk menyiapkan lingkungan pengembangan Android, lihat Persyaratan build .
• Unduh kode sumber Android. Dapatkan kode sumber Android versi terbaru dari cabang pi-car-release (atau lebih baru) di https://android.googlesource.com .
• Kepala Unit (HU). Perangkat Android yang mampu menjalankan Android 9 (atau lebih baru). Perangkat ini harus memiliki tampilan sendiri dan mampu mem-flash tampilan dengan Android versi baru.
• Kluster Instrumen adalah salah satu dari berikut ini:
  • Tampilan sekunder fisik terpasang pada HU. Jika perangkat keras dan kernel mendukung pengelolaan beberapa tampilan.
  • Satuan mandiri. Setiap unit komputasi yang terhubung ke HU melalui koneksi jaringan, mampu menerima dan menampilkan aliran video di layarnya sendiri.
  • Tampilan yang ditiru. Selama pengembangan, Anda dapat menggunakan salah satu lingkungan yang ditiru ini:
    • Tampilan sekunder yang disimulasikan. Untuk mengaktifkan tampilan sekunder yang disimulasikan pada distribusi Android AOSP apa pun, buka pengaturan Opsi Pengembang di aplikasi sistem Pengaturan lalu pilih Simulasikan tampilan sekunder. Konfigurasi ini setara dengan memasang layar sekunder fisik, dengan batasan bahwa layar ini ditumpangkan di atas layar utama.
    • Kluster instrumen yang ditiru. Emulator Android yang disertakan dengan Android Automotive menyediakan opsi untuk menampilkan kluster instrumen dengan emulator Android _qemu-pipes . Gunakan implementasi kluster instrumen referensi DirectRenderingCluster untuk menyambungkan ke tampilan eksternal yang diemulasi ini.

Arsitektur integrasi

komponen integrasi

Setiap integrasi dari Instrument Cluster API terdiri dari tiga komponen berikut:

• CarService
• Aplikasi navigasi
• Layanan Cluster Instrumen OEM

Layanan Mobil

CarService menengahi antara aplikasi navigasi dan mobil, memastikan bahwa hanya satu aplikasi navigasi yang aktif pada waktu tertentu dan hanya aplikasi dengan izin android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL yang dapat mengirim data ke mobil.

CarService -bootstrap semua layanan khusus mobil dan menyediakan akses ke layanan ini melalui serangkaian manajer. Untuk berinteraksi dengan layanan, aplikasi yang berjalan di mobil dapat mengakses pengelola ini.

Untuk implementasi kluster instrumen, OEM otomotif harus membuat implementasi kustom InstrumentClusterRendererService dan memperbarui file config.xml untuk menunjuk ke implementasi kustom tersebut.

Saat merender Cluster Instrumen, selama proses boot, CarService membaca kunci InstrumentClusterRendererService dari config.xml untuk menemukan implementasi InstrumentClusterService . Di AOSP, entri ini menunjuk ke layanan render implementasi cluster sampel Navigation State API:

<string name="instrumentClusterRendererService">
android.car.cluster/.ClusterRenderingService
</string>

Layanan yang dirujuk dalam entri ini diinisialisasi dan terikat ke CarService . Saat aplikasi navigasi, seperti Google Maps, meminta CarInstrumentClusterManager , CarService menyediakan pengelola yang memperbarui status Instrument Cluster dari InstrumentClusterRenderingService terikat. (Dalam hal ini, terikat mengacu pada Layanan Android .)

Layanan Kluster Instrumen

OEM harus membuat Android Package (APK) yang berisi subkelas InstrumentClusterRendererService . Lihat ClusterRenderingService untuk contoh.

Kelas ini memiliki dua tujuan:

• Menyediakan antarmuka Android dan perangkat rendering Instrument Cluster (tujuan halaman ini).
• Menerima dan merender pembaruan status navigasi, seperti panduan navigasi belokan demi belokan.

Untuk tujuan pertama, implementasi OEM InstrumentClusterRendererService harus menginisialisasi tampilan sekunder yang digunakan untuk merender informasi pada layar di kabin mobil dan mengomunikasikan informasi ini ke CarService dengan memanggil metode InstrumentClusterRendererService.setClusterActivityOptions() dan InstrumentClusterRendererService.setClusterActivityState() .

Untuk fungsi kedua, layanan Instrument Cluster harus menyediakan implementasi antarmuka NavigationRenderer yang menerima peristiwa pembaruan status navigasi , yang dikodekan sebagai eventType dan data peristiwa yang dikodekan dalam bundel.

Urutan integrasi

Diagram berikut mengilustrasikan penerapan status navigasi yang membuat pembaruan:

Dalam ilustrasi ini, warna menunjukkan hal berikut:

• Kuning. CarService dan CarNavigationStatusManager disediakan oleh platform Android.
• Sian. InstrumentClusterRendererService diimplementasikan oleh OEM.
• Ungu. Aplikasi Navigasi yang diterapkan oleh Google dan pengembang pihak ketiga.
• Hijau. CarAppFocusManager .

Alur informasi Status Navigasi mengikuti urutan ini:

1. CarService menginisialisasi InstrumentClusterRenderingService .
2. Selama inisialisasi, InstrumentClusterRenderingService memperbarui CarService dengan:
   1. Properti tampilan Kluster Instrumen, seperti batas yang tidak jelas (lihat detail selengkapnya tentang batas yang tidak jelas nanti).
   2. Opsi aktivitas diperlukan untuk meluncurkan aktivitas di dalam tampilan Kluster Instrumen (lihat detail selengkapnya di ActivityOptions .
3. Aplikasi navigasi (seperti Google Maps untuk Android Automotive atau aplikasi peta apa pun dengan izin yang diperlukan):
   1. Memperoleh CarAppFocusManager menggunakan kelas Car dari car-lib.
   2. Sebelum petunjuk arah belokan demi belokan dimulai, panggil CarAppFocusManager.requestFocus() untuk meneruskan CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION sebagai parameter appType .
4. CarAppFocusManager mengomunikasikan permintaan ini ke CarService . Jika diberikan, CarService memeriksa paket aplikasi navigasi dan menemukan aktivitas yang ditandai dengan kategori android.car.cluster.NAVIGATION .
5. Jika ditemukan, aplikasi navigasi menggunakan ActivityOptions yang dilaporkan oleh InstrumentClusterRenderingService untuk meluncurkan aktivitas dan menyertakan properti tampilan Cluster Instrumen sebagai tambahan dalam maksud.

Mengintegrasikan API

Implementasi InstrumentClusterRenderingService harus:

• Ditetapkan sebagai layanan tunggal dengan menambahkan nilai berikut ke AndroidManifest.xml. Ini diperlukan untuk memastikan bahwa satu salinan layanan Instrument Cluster akan berjalan, bahkan selama inisialisasi dan peralihan pengguna:
  android:singleUser="true"
• Tahan izin sistem BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE . Ini menjamin bahwa hanya layanan rendering Cluster Instrumen yang disertakan sebagai bagian dari citra sistem Android yang pernah terikat oleh CarService : l10n

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

Menerapkan InstrumentClusterRenderingService

Untuk membangun layanan:

1. Tulis kelas yang diperluas dari InstrumentClusterRenderingService lalu tambahkan entri yang sesuai ke file AndroidManifest.xml Anda. Kelas ini mengontrol tampilan Kluster Instrumen dan dapat ( secara opsional ) merender data API Status Navigasi.
2. Selama onCreate() , gunakan layanan ini untuk menginisialisasi komunikasi dengan perangkat keras rendering. Pilihan meliputi:
   • Tentukan tampilan sekunder yang akan digunakan untuk Instrument Cluster.
   • Buat tampilan virtual sehingga aplikasi Instrument Cluster merender dan mentransmisikan gambar yang dirender ke unit eksternal (menggunakan format streaming video, seperti H.264).
3. Saat tampilan yang ditunjukkan di atas sudah siap, layanan ini harus memanggil InstrumentClusterRenderingService#setClusterActivityLaunchOptions() untuk menentukan ActivityOptions yang tepat yang harus digunakan untuk menampilkan Aktivitas di Kluster Instrumen. Gunakan parameter ini:
   • kategori. CarInstrumentClusterManager#CATEGORY_NAVIGATION
   • ActivityOptions. Instance ActivityOptions yang dapat digunakan untuk meluncurkan Aktivitas di Kluster Instrumen. Misalnya, dari contoh implementasi Instrument Cluster di AOSP:

     getService().setClusterActivityLaunchOptions(
        CATEGORY_NAVIGATION,
        ActivityOptions.makeBasic()
           .setLaunchDisplayId(displayId));
     

4. Saat Kluster Instrumen siap menampilkan aktivitas, layanan ini harus memanggil InstrumentClusterRenderingService#setClusterActivityState() . Gunakan parameter ini:
   • category CarInstrumentClusterManager#CATEGORY_NAVIGATION
   • state Bundle dihasilkan dengan ClusterActivityState . Pastikan untuk memberikan data berikut:
     • visible Menentukan Cluster Instrumen sebagai konten yang terlihat dan siap untuk ditampilkan.
     • unobscuredBounds Sebuah persegi panjang yang mendefinisikan area dalam tampilan Instrument Cluster yang aman untuk menampilkan konten. Misalnya, area yang dicakup oleh dial dan pengukur.
5. Ganti metode Service#dump() dan laporkan informasi status yang berguna untuk debugging (lihat dumpsys untuk informasi lebih lanjut).

Contoh implementasi InstrumentClusterRenderingService

Contoh berikut menguraikan implementasi InstrumentClusterRenderingService , yang membuat VirtualDisplay untuk menyajikan konten Instrument Cluster pada tampilan fisik jarak jauh.

Sebagai alternatif, kode ini dapat melewati displayId dari tampilan sekunder fisik yang terhubung ke HU, jika diketahui tersedia.

/**
* Sample {@link InstrumentClusterRenderingService} implementation
*/
public class SampleClusterServiceImpl extends InstrumentClusterRenderingService {
   // Used to retrieve or create displays
   private final DisplayManager mDisplayManager;
   // Unique identifier for the display that will be used for instrument
   // cluster
   private final String mUniqueId = UUID.randomUUID().toString();
   // Format of the instrument cluster display
   private static final int DISPLAY_WIDTH = 1280;
   private static final int DISPLAY_HEIGHT = 720;
   private static final int DISPLAY_DPI = 320;
   // Area not covered by instruments
   private static final int DISPLAY_UNOBSCURED_LEFT = 40;
   private static final int DISPLAY_UNOBSCURED_TOP = 0;
   private static final int DISPLAY_UNOBSCURED_RIGHT = 1200;
   private static final int DISPLAY_UNOBSCURED_BOTTOM = 680;
   @Override
   public void onCreate() {
      super.onCreate();
      // Create a virtual display to render instrument cluster activities on
      mDisplayManager = getSystemService(DisplayManager.class);
      VirtualDisplay display = mDisplayManager.createVirtualDisplay(
          mUniqueId, DISPLAY_WIDTH, DISPLAY_HEIGHT, DISPLAY_DPI, null,
          0 /* flags */, null, null);
      // Do any additional initialization (e.g.: start a video stream
      // based on this virtual display to present activities on a remote
      // display).
      onDisplayReady(display.getDisplay());
}
private void onDisplayReady(Display display) {
    // Report activity options that should be used to launch activities on
    // the instrument cluster.
    String category = CarInstrumentClusterManager.CATEGORY_NAVIGATION;
    ActionOptions options = ActivityOptions.makeBasic()
        .setLaunchDisplayId(display.getDisplayId());
    setClusterActivityOptions(category, options);
    // Report instrument cluster state.
    Rect unobscuredBounds = new Rect(DISPLAY_UNOBSCURED_LEFT,
        DISPLAY_UNOBSCURED_TOP, DISPLAY_UNOBSCURED_RIGHT,
        DISPLAY_UNOBSCURED_BOTTOM);
    boolean visible = true;
    ClusterActivityState state = ClusterActivityState.create(visible,
       unobscuredBounds);
    setClusterActivityState(category, options);
  }
}

Menggunakan CarAppFocusManager

CarAppFocusManager API menyediakan metode bernama getAppTypeOwner() , yang memungkinkan layanan klaster yang ditulis oleh OEM untuk mengetahui aplikasi navigasi mana yang memiliki fokus navigasi pada waktu tertentu. OEM dapat menggunakan metode CarAppFocusManager#addFocusListener() yang ada, lalu menggunakan getAppTypeOwner() untuk mempelajari aplikasi mana yang memiliki fokus. Dengan informasi ini, OEM dapat:

• Alihkan aktivitas yang ditampilkan di kluster ke aktivitas kluster yang disediakan oleh aplikasi navigasi yang memegang fokus.
• Dapat mendeteksi apakah aplikasi navigasi terfokus memiliki aktivitas cluster atau tidak. Jika aplikasi navigasi terfokus tidak memiliki aktivitas cluster (atau jika aktivitas tersebut dinonaktifkan), OEM dapat mengirim sinyal ini ke DIM mobil sehingga aspek navigasi cluster dilewati sama sekali.

Gunakan CarAppFocusManager untuk mengatur dan mendengarkan fokus aplikasi saat ini, seperti navigasi aktif atau perintah suara. Biasanya hanya satu contoh dari aplikasi tersebut yang aktif berjalan (atau terfokus) dalam sistem.

Gunakan metode CarAppFocusManager#addFocusListener(..) untuk mendengarkan perubahan fokus aplikasi:

import android.car.CarAppFocusManager;

...

Car car = Car.createCar(this);
mAppFocusManager = (CarAppFocusManager)car.getCarManager(Car.APP_FOCUS_SERVICE);
mAppFocusManager.addFocusListener(this, CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION);

...

public void onAppFocusChanged(int appType, boolean active) {
    // Use the CarAppFocusManager#getAppTypeOwner(appType) method call
    // to retrieve a list of active package names
}

Gunakan metode CarAppFocusManager#getAppTypeOwner(..) untuk mengambil nama paket pemilik saat ini dari jenis aplikasi tertentu yang ada dalam fokus. Metode ini dapat mengembalikan lebih dari satu nama paket jika pemilik saat ini menggunakan fitur android:sharedUserId .

import android.car.CarAppFocusManager;

...

Car car = Car.createCar(this);
mAppFocusManager = (CarAppFocusManager)car.getCarManager(Car.APP_FOCUS_SERVICE);
List<String> focusOwnerPackageNames = mAppFocusManager.getAppTypeOwner(
              CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION);

if (focusOwnerPackageNames == null || focusOwnerPackageNames.isEmpty()) {
        // No Navigation application has focus
        // OEM may choose to show their default cluster view
} else {
       // focusOwnerPackageNames
       // Use the PackageManager to retrieve the cluster activity for the package(s)
       // returned in focusOwnerPackageNames
}

...

Lampiran: Menggunakan contoh aplikasi

AOSP menyediakan contoh aplikasi yang mengimplementasikan Navigation State API.

Untuk menjalankan aplikasi contoh ini:

1. Bangun dan flash Android Auto pada HU yang didukung. Gunakan instruksi pembuatan dan flashing Android khusus untuk perangkat Anda. Untuk instruksi, lihat Menggunakan Papan Referensi .
2. Hubungkan layar sekunder fisik ke HU (jika didukung) atau nyalakan HU sekunder virtual:
   1. Pilih Mode Pengembang di aplikasi Pengaturan.
   2. Buka Pengaturan > Sistem > Lanjutan > Opsi pengembang > Simulasikan tampilan sekunder .
3. Nyalakan ulang HU. Layanan ClusterRenderingService terhubung ke layar sekunder.
4. Untuk meluncurkan aplikasi KitchenSink:
   1. Buka laci.
   2. Pergi ke Inst. Gugus .
   3. Klik MULAI METADATA .

KitchenSink meminta fokus NAVIGASI, yang menginstruksikan layanan DirectRenderingCluster untuk menampilkan antarmuka pengguna tiruan pada Instrument Cluster.