Gösterge Kümesi API'si

Google Haritalar da dahil olmak üzere navigasyon uygulamalarını arabadaki ikinci bir ekranda (örneğin, direksiyon simidinin arkası) gösterge panelinde görüntülemek için Instrument Cluster API'yi (bir Android API) kullanın. Bu sayfada, ikincil ekranı kontrol etmek için bir hizmetin nasıl oluşturulacağı ve daha sonra navigasyon uygulamalarının bir kullanıcı arayüzünü görüntüleyebilmesi için hizmetin CarService ile nasıl entegre edileceği açıklanmaktadır.

Terminoloji

Bu sayfada aşağıdaki terimler kullanılmaktadır:

Terim Tanım
CarInstrumentClusterManager Harici uygulamaların Gösterge Kümesi üzerinde bir etkinlik başlatmasına ve Gösterge Kümesi etkinlikleri görüntülemeye hazır olduğunda geri aramalar almasına olanak tanıyan bir CarManager örneği.
CarManager CarService tarafından uygulanan araca özel hizmetlerle etkileşimde bulunmak için harici uygulamalar tarafından kullanılan tüm yöneticilerin temel sınıfı.
CarService Harici uygulamalar (Google Haritalar dahil) ile Gösterge Kümesi erişimi gibi araca özgü özellikler arasında iletişim sağlayan Android Platformu hizmeti.
Varış noktası Aracın gideceği son varış noktası.
ETA Hedefe tahmini varış zamanı.
Ana ünite (HU) Bir arabaya yerleştirilmiş birincil hesaplama birimi. HU tüm Android kodlarını çalıştırır ve arabadaki merkezi ekrana bağlanır.
Gösterge Grubu Direksiyon simidinin arkasında ve araç göstergelerinin arasında bulunan ikincil ekran. Bu, aracın dahili ağı (CAN veri yolu) aracılığıyla HU'ya bağlanan bağımsız bir hesaplama birimi veya HU'ya bağlı ikincil bir ekran olabilir.
InstrumentClusterRenderingService Gösterge Paneli ekranıyla arayüz oluşturmak için kullanılan hizmetin temel sınıfı. OEM'ler, bu sınıfın OEM'e özgü donanımla etkileşim kuran bir uzantısını sağlamalıdır.
KitchenSink uygulaması Android Automotive'e dahil olan test uygulaması.
Rota Bir aracın bir varış noktasına varmak için izlediği belirli bir yol.
Tekil hizmet android:singleUser özelliğine sahip bir Android hizmeti. Herhangi bir zamanda, hizmetin en fazla bir örneği Android sisteminde çalışır.

Önkoşullar

Entegrasyonu geliştirmek için şu öğelere sahip olduğunuzdan emin olun:

  • Android geliştirme ortamı. Android geliştirme ortamını ayarlamak için bkz. Derleme gereksinimleri .
  • Android kaynak kodunu indirin. Android kaynak kodunun en son sürümünü https://android.googlesource.com adresindeki pi-car-release şubesinden (veya üzeri) edinin.
  • Ana ünite (HU). Android 9'u (veya üstünü) çalıştırabilen bir Android cihazı. Bu cihazın kendi ekranı olmalı ve ekranı Android'in yeni sürümleriyle birlikte gösterebilmelidir.
  • Gösterge Grubu aşağıdakilerden biridir:
    • HU'ya bağlı fiziksel ikincil ekran. Cihaz donanımı ve çekirdeği birden fazla ekranın yönetimini destekliyorsa.
    • Bağımsız birim. Bir ağ bağlantısı yoluyla HU'ya bağlanan, video akışını alabilen ve kendi ekranında görüntüleyebilen herhangi bir hesaplama birimi.
    • Öykünülmüş ekran. Geliştirme sırasında aşağıdaki öykünülmüş ortamlardan birini kullanabilirsiniz:
      • Simüle edilmiş ikincil ekranlar. Herhangi bir AOSP Android dağıtımında simüle edilmiş bir ikincil ekranı etkinleştirmek için Ayarlar sistem uygulamasında Geliştirici Seçenekleri ayarlarına gidin ve ardından İkincil ekranları simüle et seçeneğini seçin. Bu yapılandırma, fiziksel bir ikincil ekranın eklenmesine eşdeğerdir; ancak bu ekranın birincil ekranın üzerine yerleştirilmesi sınırlaması vardır.
      • Benzetilmiş gösterge paneli. Android Automotive'de bulunan Android emülatörü, ClusterRenderingService hizmetinin ikincil ekrana bağlı olduğu bir gösterge kümesini görüntüleme seçeneği sunar.
      • emülatör _qemu boruları . ClusterRenderingService hizmeti ikincil ekrana bağlanır. Bu taklit edilmiş harici ekrana bağlanmak için gösterge paneli uygulamasına bakın.

Entegrasyon mimarisi

Entegrasyon bileşenleri

Instrument Cluster API'nin herhangi bir entegrasyonu şu üç bileşenden oluşur:

  • CarService
  • Navigasyon uygulamaları
  • OEM Gösterge Grubu Hizmeti

Entegrasyon bileşenleri

Araba servisi

CarService , navigasyon uygulamaları ile araç arasında aracılık yaparak herhangi bir zamanda yalnızca bir navigasyon uygulamasının etkin olmasını ve yalnızca android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL iznine sahip uygulamaların araca veri gönderebilmesini sağlar.

CarService araca özel tüm hizmetleri önyükler ve bir dizi yönetici aracılığıyla bu hizmetlere erişim sağlar. Araçta çalışan uygulamalar, hizmetlerle etkileşim kurmak için bu yöneticilere erişebilir.

Gösterge kümesi uygulaması için otomotiv OEM'lerinin, InstrumentClusterRendererService'in özel bir uygulamasını oluşturması ve ikincil ekrana bağlı olan ClusterRenderingService hizmetini güncellemesi gerekir.

Bir Instrument Cluster oluşturulurken, önyükleme işlemi sırasında CarService , ikincil ekrana bağlanan ClusterRenderingService hizmetinin InstrumentClusterRendererService anahtarını okur. InstrumentClusterService uygulamasını bulmak için. AOSP'de bu giriş, Gezinme Durumu API'si örnek küme uygulama oluşturma hizmetine işaret eder:

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

Bu girişte adı geçen hizmet başlatıldı ve CarService bağlandı. Google Haritalar gibi navigasyon uygulamaları bir CarInstrumentClusterManager isteğinde bulunduğunda CarService , Instrument Cluster durumunu bağlı InstrumentClusterRenderingService öğesinden güncelleyen bir yönetici sağlar. (Bu durumda bağlı , Android Hizmetlerini ifade eder.)

Gösterge Grubu hizmeti

OEM'lerin, ikincil ekrana bağlı ClusterRenderingService hizmetinin bir alt sınıfını içeren bir Android Paketi (APK) oluşturması gerekir. ClusterRenderingService hizmeti ikincil ekrana bağlanır. bir örnek için.

Bu sınıf iki amaca hizmet eder:

  • Android ve Instrument Cluster işleme cihazı için bir arayüz sağlar (bu sayfanın amacı).
  • Adım adım navigasyon rehberliği gibi navigasyon durumu güncellemelerini alır ve işler.

İlk amaç için, InstrumentClusterRendererService OEM uygulamaları, araba kabinindeki ekranlardaki bilgileri işlemek için kullanılan ikincil ekranı başlatmalı ve bu bilgiyi InstrumentClusterRendererService.setClusterActivityOptions() ve InstrumentClusterRendererService.setClusterActivityState() yöntemlerini çağırarak CarService iletmelidir.

İkinci işlev için, Instrument Cluster hizmetinin, ikincil ekrana bağlanan ClusterRenderingService hizmetinin bir uygulamasını sağlaması gerekir. eventType olarak kodlanmış navigasyon durumu güncelleme olaylarını ve bir pakette kodlanmış olay verilerini alan arayüz.

Entegrasyon sırası

Aşağıdaki diyagramda güncellemeleri işleyen bir gezinme durumunun uygulanması gösterilmektedir:

Entegrasyon sırası

Bu çizimde renkler aşağıdakileri ifade eder:

  • Sarı. Android platformu tarafından sağlanan CarService ve CarNavigationStatusManager . Daha fazla bilgi edinmek için Araba ve CAR_NAVIGATION_SERVICE bölümüne bakın.
  • Camgöbeği. OEM tarafından uygulanan InstrumentClusterRendererService .
  • Mor. Google ve üçüncü taraf geliştiriciler tarafından uygulanan Navigasyon uygulaması.
  • Yeşil. CarAppFocusManager . Daha fazla bilgi edinmek için aşağıdaki CarAppFocusManager API'sini kullanma ve CarAppFocusManager bölümlerine bakın.

Navigasyon Durumu bilgi akışı şu sırayı takip eder:

  1. CarService InstrumentClusterRenderingService öğesini başlatır.
  2. Başlatma sırasında InstrumentClusterRenderingService , CarService aşağıdakilerle günceller:
    1. Gösterge Grubu, belirsiz olmayan sınırlar gibi görüntüleme özelliklerini gösterir (daha sonra belirsiz olmayan sınırlar hakkında daha fazla ayrıntıya bakın).
    2. Gösterge Grubu ekranı içindeki etkinlikleri başlatmak için gereken etkinlik seçenekleri (daha fazla ayrıntıya ActivityOptions adresinden bakın.
  3. Bir navigasyon uygulaması (Android Automotive için Google Haritalar veya gerekli izinlere sahip herhangi bir harita uygulaması gibi):
    1. Car-lib'den Car sınıfını kullanarak bir CarAppFocusManager alır.
    2. Adım adım yol tarifleri başlamadan önce, CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION appType parametresi olarak iletmek için CarAppFocusManager.requestFocus() 'a çağrı yapılır.
  4. CarAppFocusManager bu isteği CarService iletir. Onaylanırsa, CarService navigasyon uygulaması paketini inceler ve android.car.cluster.NAVIGATION kategorisiyle işaretlenmiş bir etkinliği bulur.
  5. Bulunursa navigasyon uygulaması, etkinliği başlatmak için InstrumentClusterRenderingService tarafından bildirilen ActivityOptions kullanır ve amaca ekstralar olarak Instrument Cluster görüntüleme özelliklerini ekler.

API'yi entegre edin

InstrumentClusterRenderingService uygulamasının şunları yapması gerekir:

  • AndroidManifest.xml dosyasına aşağıdaki değer eklenerek tekil hizmet olarak belirlenebilir. Bu, başlatma ve kullanıcı değiştirme sırasında bile Gösterge Kümesi hizmetinin tek bir kopyasının çalışmasını sağlamak için gereklidir:
    android:singleUser="true"
  • BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE sistem iznine sahip olun. Bu, yalnızca Android sistem görüntüsünün bir parçası olarak dahil edilen Gösterge Grubu oluşturma hizmetinin CarService bağlı olacağını garanti eder:
    <uses-permission android:name="android.car.permission.BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE"/>
    

InstrumentClusterRenderingService'i uygulayın

Hizmeti oluşturmak için:

  1. İkincil ekrana bağlı ClusterRenderingService hizmetinden uzanan bir sınıf yazın.
  2. ve ardından AndroidManifest.xml dosyanıza karşılık gelen girişi ekleyin. Bu sınıf, Gösterge Grubu ekranını kontrol eder ve ( isteğe bağlı olarak ) Navigasyon Durumu API verilerini işleyebilir.
  3. onCreate() sırasında, işleme donanımıyla iletişimi başlatmak için bu hizmeti kullanın. Seçenekler şunları içerir:
    • Gösterge Paneli için kullanılacak ikincil ekranı belirleyin.
    • Instrument Cluster uygulamasının işlenen görüntüyü harici bir birime (H.264 gibi bir video akış formatı kullanarak) aktarabilmesi için sanal bir ekran oluşturun.
  4. Yukarıda belirtilen ekran hazır olduğunda, bu hizmetin InstrumentClusterRenderingService#setClusterActivityLaunchOptions() öğesini çağırarak Gösterge Kümesi üzerinde bir Aktivite görüntülemek için kullanılması gereken ActivityOptions tam olarak tanımlaması gerekir. Bu parametreleri kullanın:
    • kategori. ClusterRenderingService hizmeti ikincil ekrana bağlanır.
    • ActivityOptions. Instrument Cluster'da bir Activity başlatmak için kullanılabilecek bir ActivityOptions örneği. Örneğin, AOSP'deki örnek Enstrüman Kümesi uygulamasından:
      getService().setClusterActivityLaunchOptions(
         CATEGORY_NAVIGATION,
         ActivityOptions.makeBasic()
            .setLaunchDisplayId(displayId));
      
  5. Instrument Cluster etkinlikleri görüntülemeye hazır olduğunda, bu hizmetin InstrumentClusterRenderingService#setClusterActivityState() çağırması gerekir. Bu parametreleri kullanın:
    • category ClusterRenderingService hizmeti ikincil ekrana bağlanır.
    • ClusterRenderingService hizmetiyle oluşturulan state paketi ikincil ekrana bağlanır.
    • Aşağıdaki verileri sağladığınızdan emin olun:
      • visible Gösterge Panelinin görünür ve içeriği görüntülemeye hazır olduğunu belirtir.
      • unobscuredBounds Gösterge Grubu ekranında içeriğin güvenli bir şekilde görüntülendiği alanı tanımlayan bir dikdörtgen. Örneğin kadranların ve göstergelerin kapsadığı alanlar.
  6. Service#dump() yöntemini geçersiz kılın ve hata ayıklama için yararlı olan durum bilgilerini rapor edin (daha fazla bilgi için dumpsys'e bakın).

Örnek InstrumentClusterRenderingService uygulaması

Aşağıdaki örnek, Instrument Cluster içeriğini uzak bir fiziksel ekranda sunmak için bir VirtualDisplay oluşturan InstrumentClusterRenderingService uygulamasını özetlemektedir.

Alternatif olarak bu kod, eğer mevcut olduğu biliniyorsa, HU'ya bağlı bir fiziksel ikincil ekranın displayId geçebilir.

/**
* Sample {@link InstrumentClusterRenderingService} implementation
*/
public class SampleClusterServiceImpl extends InstrumentClusterRenderingService {
   // Used to retrieve or create displays
   private final DisplayManager mDisplayManager;
   // Unique identifier for the display to 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);
  }
}

CarAppFocusManager API'sini kullanın

CarAppFocusManager API, OEM'ler tarafından yazılan küme hizmetinin herhangi bir zamanda hangi navigasyon uygulamasının navigasyon odağına sahip olduğunu bilmesine olanak tanıyan getAppTypeOwner() adlı bir yöntem sağlar. OEM'ler mevcut CarAppFocusManager#addFocusListener() yöntemini kullanabilir ve ardından hangi uygulamanın odaklandığını öğrenmek için getAppTypeOwner() kullanabilir. Bu bilgilerle OEM'ler şunları yapabilir:

  • Kümede gösterilen etkinliği, odağı tutan navigasyon uygulaması tarafından sağlanan küme etkinliğine değiştirin.
  • Odaklanmış navigasyon uygulamasının bir küme etkinliğine sahip olup olmadığını tespit edebilir. Odaklanmış navigasyon uygulamasının bir küme etkinliği yoksa (veya bu tür bir etkinlik devre dışı bırakılırsa), OEM'ler bu sinyali arabanın DIM'sine gönderebilir, böylece kümenin gezinme özelliği tamamen atlanır.

Aktif navigasyon veya sesli komut gibi mevcut uygulama odağını ayarlamak ve dinlemek için CarAppFocusManager kullanın. Genellikle böyle bir uygulamanın yalnızca bir örneği sistemde aktif olarak çalışır (veya odaklanır).

Uygulama odak değişikliklerini dinlemek için CarAppFocusManager#addFocusListener(..) yöntemini kullanın:

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
}

Odaktaki belirli bir uygulama türünün geçerli sahibinin paket adlarını almak için CarAppFocusManager#getAppTypeOwner(..) yöntemini kullanın. Geçerli sahibi android:sharedUserId özelliğini kullanıyorsa bu yöntem birden fazla paket adı döndürebilir.

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 app 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
}

...

Ek: Örnek uygulamayı kullanın

AOSP, Gezinme Durumu API'sini uygulayan örnek bir uygulama sağlar.

Bu örnek uygulamayı çalıştırmak için:

  1. Desteklenen bir HU'da Android Auto'yu oluşturun ve flashlayın. Cihazınıza özel Android oluşturma ve yanıp sönme talimatlarını kullanın. Talimatlar için bkz. Referans Kartlarını Kullanma .
  2. HU'ya (destekleniyorsa) fiziksel bir ikincil ekran bağlayın veya sanal ikincil HU'yu açın:
    1. Ayarlar uygulamasında Geliştirici Modunu seçin.
    2. Ayarlar > Sistem > Gelişmiş > Geliştirici seçenekleri > İkincil ekranları simüle et seçeneğine gidin.
  3. HU'yu yeniden başlatın. ClusterRenderingService hizmeti ikincil ekrana bağlanır.
  4. KitchenSink uygulamasını başlatmak için:
    1. Çekmeceyi açın.
    2. Enstitü'ye git. Küme .
    3. META VERİLERİ BAŞLAT'ı tıklayın.

KitchenSink, DirectRenderingCluster hizmetine Gösterge Kümesi üzerinde modellenmiş bir kullanıcı arayüzü görüntülemesi talimatını veren NAVIGATION odağını talep eder.