Instrument Cluster API

गाड़ी में दूसरी स्क्रीन पर नेविगेशन ऐप्लिकेशन दिखाने के लिए, इंस्ट्रुमेंट क्लस्टर एपीआई (Android एपीआई) का इस्तेमाल करें. जैसे, इंस्ट्रुमेंट पैनल पर स्टीयरिंग व्हील के पीछे Google Maps दिखाना. इस पेज पर, दूसरी स्क्रीन को कंट्रोल करने के लिए सेवा बनाने और उस सेवा को CarService के साथ इंटिग्रेट करने का तरीका बताया गया है, ताकि नेविगेशन ऐप्लिकेशन, यूज़र इंटरफ़ेस दिखा सकें.

शब्दावली

इस पेज पर, इन शब्दों का इस्तेमाल किया गया है.

ज़रूरी शर्तें

आगे बढ़ने से पहले, पक्का करें कि आपके पास ये चीज़ें हों:

• Android डेवलपमेंट एनवायरमेंट. Android डेवलपमेंट एनवायरमेंट सेट अप करने के लिए, बिल्ड की ज़रूरी शर्तें देखें.
• Android सोर्स कोड डाउनलोड करें. Android सोर्स कोड का नया वर्शन, https://android.googlesource.com पर pi-car-release ब्रांच (या इसके बाद वाले वर्शन) से पाएं.
• मुख्य यूनिट (एचयू). Android 9 (या इसके बाद वाले वर्शन) पर काम करने वाला Android डिवाइस. इस डिवाइस का अपना डिसप्ले होना चाहिए और इसमें डिसप्ले पर Android के नए बिल्ड फ़्लैश किए जा सकते हों.
• इंस्ट्रुमेंट क्लस्टर इनमें से कोई एक हो सकता है:
  • एचयू से जुड़ा, दूसरा फ़िज़िकल डिसप्ले. अगर डिवाइस का हार्डवेयर और कर्नल, एक से ज़्यादा डिसप्ले को मैनेज करने की सुविधा देते हैं.
  • इंडिपेंडेंट यूनिट. कोई भी कंप्यूटिंग यूनिट, जो नेटवर्क कनेक्शन के ज़रिए एचयू से कनेक्ट हो और अपने डिसप्ले पर वीडियो स्ट्रीम पाने और दिखाने की सुविधा देती हो.
  • इम्युलेटेड डिसप्ले. डेवलपमेंट के दौरान, इम्युलेट किए गए इन एनवायरमेंट में से किसी एक का इस्तेमाल किया जा सकता है:
    • इम्युलेट किए गए दूसरे डिसप्ले. AOSP के किसी भी Android डिस्ट्रिब्यूशन पर, इम्युलेट किए गए दूसरे डिसप्ले को चालू करने के लिए, सेटिंग सिस्टम ऐप्लिकेशन में डेवलपर के लिए सेटिंग और टूल पर जाएं. इसके बाद, इम्युलेट किए गए दूसरे डिसप्ले को चुनें. यह कॉन्फ़िगरेशन, दूसरे फ़िज़िकल डिसप्ले को अटैच करने के बराबर है. हालांकि, इसमें यह पाबंदी है कि यह डिसप्ले, मुख्य डिसप्ले के ऊपर दिखता है.
    • इम्युलेट किया गया इंस्ट्रुमेंट क्लस्टर. AAOS के साथ शामिल Android एम्युलेटर, ClusterRenderingService के साथ इंस्ट्रुमेंट क्लस्टर दिखाने का विकल्प देता है.

इंटिग्रेशन आर्किटेक्चर

इंटिग्रेशन के कॉम्पोनेंट

इंस्ट्रुमेंट क्लस्टर एपीआई के किसी भी इंटिग्रेशन में ये तीन कॉम्पोनेंट शामिल होते हैं:

• CarService
• नेविगेशन ऐप्लिकेशन
• ओईएम इंस्ट्रुमेंट क्लस्टर सेवा

CarService

CarService, नेविगेशन ऐप्लिकेशन और गाड़ी के बीच मीडिएशन करता है. इससे यह पक्का होता है कि किसी भी समय सिर्फ़ एक नेविगेशन ऐप्लिकेशन चालू हो और सिर्फ़ android.car.permission.CAR_INSTRUMENT_CLUSTER_CONTROL अनुमति वाले ऐप्लिकेशन ही गाड़ी को डेटा भेज सकें.

CarService , गाड़ी से जुड़ी सभी सेवाओं को बूटस्ट्रैप करता है और मैनेजर की सीरीज़ के ज़रिए इन सेवाओं का ऐक्सेस देता है. गाड़ी में चलने वाले ऐप्लिकेशन, सेवाओं के साथ इंटरैक्ट करने के लिए इन मैनेजर को ऐक्सेस कर सकते हैं.

इंस्ट्रुमेंट क्लस्टर को लागू करने के लिए, ऑटोमोटिव ओईएम को InstrumentClusterRendererService का कस्टम वर्शन बनाना होगा और ClusterRenderingServiceको अपडेट करना होगा.

इंस्ट्रुमेंट क्लस्टर को रेंडर करते समय, बूट प्रोसेस के दौरान CarService ClusterRenderingService की InstrumentClusterRendererService कुंजी को पढ़कर, InstrumentClusterService के वर्शन का पता लगाता है. AOSP में, यह एंट्री, नेविगेशन स्टेट एपीआई के सैंपल क्लस्टर को लागू करने वाली रेंडर सेवा की ओर इशारा करती है:

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

इस एंट्री में बताई गई सेवा को शुरू किया जाता है और CarService से बाइंड किया जाता है. जब Google Maps जैसे नेविगेशन ऐप्लिकेशन, CarInstrumentClusterManager का अनुरोध करते हैं, तो CarService एक ऐसा मैनेजर उपलब्ध कराता है जो बाइंड किए गए InstrumentClusterRenderingService से इंस्ट्रुमेंट क्लस्टर की स्थिति को अपडेट करता है. (इस मामले में, बाइंड का मतलब Android सेवाओं से है.)

इंस्ट्रुमेंट क्लस्टर सेवा

ओईएम को एक Android पैकेज (एपीके) बनाना होगा, जिसमें ClusterRenderingService की सबक्लास शामिल हो .

इस क्लास के दो मकसद होते हैं:

• Android और इंस्ट्रुमेंट क्लस्टर रेंडर करने वाले डिवाइस के लिए इंटरफ़ेस उपलब्ध कराता है (इस पेज का मकसद).
• नेविगेशन की स्थिति के अपडेट पाता है और उन्हें रेंडर करता है. जैसे, रास्ते के लिए दिशा-निर्देश .

पहले मकसद के लिए, InstrumentClusterRendererService को, गाड़ी के केबिन में स्क्रीन पर जानकारी रेंडर करने के लिए इस्तेमाल किए जाने वाले दूसरे डिसप्ले को शुरू करना होगा. साथ ही, CarService तक इस जानकारी को पहुंचाने के लिए, InstrumentClusterRendererService.setClusterActivityOptions() और InstrumentClusterRendererService.setClusterActivityState() तरीकों को कॉल करना होगा.

दूसरे फ़ंक्शन के लिए, इंस्ट्रुमेंट क्लस्टर सेवा को ClusterRenderingService इंटरफ़ेस का एक वर्शन उपलब्ध कराना होगा, जो नेविगेशन की स्थिति के अपडेट इवेंट पाता है. इन्हें eventType और बंडल में कोड में बदले गए इवेंट डेटा के तौर पर कोड में बदला जाता है.

इंटिग्रेशन का क्रम

नीचे दिया गया डायग्राम, नेविगेशन की स्थिति को लागू करने का तरीका दिखाता है, जो अपडेट रेंडर करता है:

इस इमेज में, रंगों का मतलब यहां दिया गया है:

• पीला. CarService और CarNavigationStatusManager , जो Android प्लैटफ़ॉर्म उपलब्ध कराता है. ज़्यादा जानने के लिए, Car और CAR_NAVIGATION_SERVICE देखें.
• सियान. InstrumentClusterRendererService लागू किया गया है ओईएम द्वारा.
• बैंगनी. नेविगेशन ऐप्लिकेशन, जिसे Google और तीसरे पक्ष के डेवलपर ने लागू किया है.
• हरा. CarAppFocusManager. ज़्यादा जानने के लिए, नीचे CarAppFocusManager API का इस्तेमाल करना और CarAppFocusManager देखें.

नेविगेशन की स्थिति की जानकारी का फ़्लो इस क्रम में होता है:

1. CarService, InstrumentClusterRenderingService को शुरू करता है.
2. शुरुआत के दौरान, InstrumentClusterRenderingService अपडेट करता है CarService के साथ:
   1. इंस्ट्रुमेंट क्लस्टर डिसप्ले की प्रॉपर्टी, जैसे कि अनऑब्स्क्योर बाउंड्री (अनऑब्स्क्योर बाउंड्री के बारे में ज़्यादा जानकारी बाद में दी जाएगी).
   2. इंस्ट्रुमेंट क्लस्टर डिसप्ले में ऐक्टिविटी लॉन्च करने के लिए ज़रूरी ऐक्टिविटी के विकल्प. ज़्यादा जानने के लिए, ActivityOptions देखें.
3. कोई नेविगेशन ऐप्लिकेशन (जैसे, Android Automotive के लिए Google Maps या ज़रूरी अनुमतियों वाला कोई भी मैप ऐप्लिकेशन जिसमें ज़रूरी अनुमतियां हों):
   1. कार-lib से Car क्लास का इस्तेमाल करके, CarAppFocusManager हासिल करता है.
   2. मोड़-दर-मोड़ दिशा-निर्देश शुरू होने से पहले, CarAppFocusManager.requestFocus() को CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION को appType पैरामीटर के तौर पर पास करने के लिए कॉल करता है.
4. CarAppFocusManager, इस अनुरोध को CarService तक पहुंचाता है. अगर अनुमति मिलती है, तो CarService, नेविगेशन ऐप्लिकेशन के पैकेज की जांच करता है और android.car.cluster.NAVIGATION कैटगरी के तौर पर मार्क की गई कोई गतिविधि ढूंढता है.
5. अगर गतिविधि मिलती है, तो नेविगेशन ऐप्लिकेशन, गतिविधि लॉन्च करने के लिए ActivityOptions से मिली InstrumentClusterRenderingService का इस्तेमाल करता है. साथ ही, इंटेंट में इंस्ट्रुमेंट क्लस्टर डिसप्ले की प्रॉपर्टी को एक्स्ट्रा के तौर पर शामिल करता है.

एपीआई इंटिग्रेट करना

InstrumentClusterRenderingService को लागू करने के लिए, यह ज़रूरी है कि:

• AndroidManifest.xml में यह वैल्यू जोड़कर, इसे सिंगलटन सेवा के तौर पर तय किया जाए. यह पक्का करने के लिए ज़रूरी है कि इंस्ट्रुमेंट क्लस्टर सेवा की सिर्फ़ एक कॉपी चले. भले ही, शुरुआत के दौरान और उपयोगकर्ता स्विच करने के दौरान भी:
  android:singleUser="true"
• BIND_INSTRUMENT_CLUSTER_RENDERER_SERVICE सिस्टम की अनुमति हो. इससे यह पक्का होता है कि सिर्फ़ इंस्ट्रुमेंट क्लस्टर रेंडर करने वाली सेवा को बाइंड करे. यह सेवा, Android सिस्टम इमेज के हिस्से के तौर पर शामिल होती है: CarService

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

InstrumentClusterRenderingService लागू करना

सेवा बनाने के लिए:

1. ClusterRenderingService से एक्सटेंड होने वाली कोई क्लास लिखें. इसके बाद, अपनी AndroidManifest.xml फ़ाइल में उससे जुड़ी एंट्री जोड़ें. यह क्लास इंस्ट्रुमेंट क्लस्टर डिसप्ले को कंट्रोल करती है और (ज़रूरी नहीं) नेविगेशन स्टेट एपीआई का डेटा रेंडर कर सकती है.
2. onCreate() के दौरान, रेंडरिंग हार्डवेयर के साथ कम्यूनिकेशन शुरू करने के लिए इस सेवा का इस्तेमाल करें. विकल्पों में ये शामिल हैं:
   • इंस्ट्रुमेंट क्लस्टर के लिए इस्तेमाल किया जाने वाला दूसरा डिसप्ले तय करना.
   • एक वर्चुअल डिसप्ले बनाना, ताकि इंस्ट्रुमेंट क्लस्टर ऐप्लिकेशन, रेंडर की गई इमेज को रेंडर और ट्रांसमिट कर सके. इसके लिए, वीडियो स्ट्रीमिंग फ़ॉर्मैट (जैसे, H.264) का इस्तेमाल किया जा सकता है.
3. जब ऊपर बताया गया डिसप्ले तैयार हो जाए, तो इस सेवा को InstrumentClusterRenderingService#setClusterActivityLaunchOptions() को कॉल करना होगा, ताकि सही ActivityOptions को तय किया जा सके. इसका इस्तेमाल, इंस्ट्रुमेंट क्लस्टर पर कोई ऐक्टिविटी दिखाने के लिए किया जाना चाहिए. इन पैरामीटर का इस्तेमाल करें:
   • category. ClusterRenderingService.
   • ActivityOptions. एक ActivityOptions इंस्टेंस, जिसका इस्तेमाल इंस्ट्रुमेंट क्लस्टर में कोई ऐक्टिविटी लॉन्च करने के लिए किया जा सकता है. उदाहरण के लिए, AOSP पर इंस्ट्रूमेंट क्लस्टर को लागू करने के सैंपल से:

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

4. जब इंस्ट्रुमेंट क्लस्टर, गतिविधियां दिखाने के लिए तैयार हो जाए, तो इस सेवा को लागू करना होगा InstrumentClusterRenderingService#setClusterActivityState(). इन पैरामीटर का इस्तेमाल करें:
   • category ClusterRenderingService.
   • state ClusterRenderingService से जनरेट किया गया बंडल. यह डेटा ज़रूर दें:
     • visible इंस्ट्रुमेंट क्लस्टर को दिखने वाला और कॉन्टेंट दिखाने के लिए तैयार के तौर पर तय करता है कॉन्टेंट दिखाता है.
     • unobscuredBounds एक ऐसा रेक्टैंगल जो इंस्ट्रुमेंट क्लस्टर डिसप्ले में उस जगह को तय करता है जहां कॉन्टेंट को सुरक्षित तरीके से दिखाया जा सकता है. उदाहरण के लिए, डायल और गेज से कवर की गई जगहें.
5. Service#dump() तरीके को बदलें और डीबग करने के लिए काम की स्थिति की जानकारी दें. ज़्यादा जानकारी के लिए, dumpsys देखें.

InstrumentClusterRenderingService को लागू करने का सैंपल

यहां दिए गए उदाहरण में, InstrumentClusterRenderingService को लागू करने का तरीका बताया गया है. इसमें, रिमोट फ़िज़िकल डिसप्ले पर इंस्ट्रुमेंट क्लस्टर का कॉन्टेंट दिखाने के लिए, VirtualDisplay बनाया जाता है.

इसके अलावा, अगर एचयू से कनेक्ट किया गया कोई दूसरा फ़िज़िकल डिसप्ले उपलब्ध है, तो यह कोड उसका displayId पास कर सकता है.

/**
* 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 का इस्तेमाल करना

CarAppFocusManager API, getAppTypeOwner() नाम का एक तरीका उपलब्ध कराता है. इससे ओईएम की ओर से लिखी गई क्लस्टर सेवा को यह पता चलता है कि किसी भी समय, किस नेविगेशन ऐप्लिकेशन पर फ़ोकस है. ओईएम, मौजूदा CarAppFocusManager#addFocusListener() तरीके का इस्तेमाल कर सकते हैं. इसके बाद, यह जानने के लिए getAppTypeOwner() का इस्तेमाल कर सकते हैं कि किस ऐप्लिकेशन पर फ़ोकस है. इस जानकारी की मदद से, ओईएम ये काम कर सकते हैं:

• क्लस्टर में दिखाई जाने वाली गतिविधि को, फ़ोकस में मौजूद नेविगेशन ऐप्लिकेशन की ओर से उपलब्ध कराई गई क्लस्टर गतिविधि पर स्विच करना.
• यह पता लगाना कि फ़ोकस में मौजूद नेविगेशन ऐप्लिकेशन में क्लस्टर गतिविधि है या नहीं. अगर फ़ोकस में मौजूद नेविगेशन ऐप्लिकेशन में क्लस्टर गतिविधि नहीं है (या अगर ऐसी गतिविधि बंद है), तो ओईएम इस सिग्नल को कार DIM को भेज सकते हैं, ताकि क्लस्टर के नेविगेशन फ़ैसेट को पूरी तरह से स्किप किया जा सके.

मौजूदा ऐप्लिकेशन के फ़ोकस को सेट करने और उसकी जानकारी पाने के लिए, CarAppFocusManager का इस्तेमाल करें. जैसे, चालू नेविगेशन या बोलकर दिया गया कोई निर्देश. आम तौर पर, सिस्टम में ऐसे ऐप्लिकेशन का सिर्फ़ एक इंस्टेंस चालू होता है (या फ़ोकस में होता है).

ऐप्लिकेशन के फ़ोकस में होने वाले बदलावों की जानकारी पाने के लिए, CarAppFocusManager#addFocusListener(..) तरीके का इस्तेमाल करें:

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
}

फ़ोकस में मौजूद किसी दिए गए ऐप्लिकेशन टाइप के मौजूदा मालिक के पैकेज के नाम पाने के लिए, CarAppFocusManager#getAppTypeOwner(..) तरीके का इस्तेमाल करें. अगर मौजूदा मालिक, 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 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
}

...

टेंप्लेट ऐप्लिकेशन की पहचान करना

Car App लाइब्रेरी का इस्तेमाल करने वाले, टेंप्लेट पर आधारित नेविगेशन ऐप्लिकेशन के लिए, CarAppFocusManager#getAppTypeOwner(), होस्ट का पैकेज नाम दिखाता है. जैसे, com.google.android.apps.automotive.templates.host. ऐसा इसलिए, क्योंकि होस्ट, क्लाइंट ऐप्लिकेशन की ओर से सिस्टम फ़ोकस रखता है.

नेविगेट करने वाले क्लाइंट ऐप्लिकेशन की पहचान करने के लिए, ओईएम, CarNavigationStatusManager के साथ भेजे गए नेविगेशन स्टेट बंडल से पैकेज का नाम निकाल सकते हैं. पैकेज का नाम, NavigationRenderer#onNavigationStateChanged(Bundle) से मिले बंडल में, active_app_package_name कुंजी के तहत सेव होता है:

// In your NavigationRenderer implementation
@Override
public void onNavigationStateChanged(Bundle bundle) {
    if (bundle.containsKey("active_app_package_name")) {
        String activeAppPackage = bundle.getString("active_app_package_name");
        // Use the package name to identify the navigating app (e.g., com.waze)
    }
}

अपेंडिक्स: सैंपल के तौर पर मिले ऐप्लिकेशन का इस्तेमाल करना

AOSP, नेविगेशन स्टेट एपीआई को लागू करने वाला एक सैंपल ऐप्लिकेशन उपलब्ध कराता है.

इस सैंपल ऐप्लिकेशन को चलाने के लिए:

1. Android Auto को, काम करने वाले एचयू पर बनाएं और फ़्लैश करें. अपने डिवाइस के लिए, Android बनाने और फ़्लैश करने के निर्देशों का इस्तेमाल करें. निर्देशों के लिए, रेफ़रंस बोर्ड का इस्तेमाल करना देखें.
2. एचयू से दूसरा फ़िज़िकल डिसप्ले कनेक्ट करें (अगर यह सुविधा उपलब्ध है) या दूसरा वर्चुअल दूसरा एचयू चालू करें:
   1. सेटिंग ऐप्लिकेशन में डेवलपर मोड चुनें.
   2. सेटिंग > सिस्टम > बेहतर सेटिंग > डेवलपर के लिए सेटिंग और टूल > इम्युलेट किए गए दूसरे डिसप्ले पर जाएं.
3. एचयू को फिर से चालू करें
4. KitchenSink ऐप्लिकेशन लॉन्च करने के लिए:
   1. ड्रॉर खोलें.
   2. इंस्ट्रुमेंट क्लस्टर पर जाएं.
   3. मेटाडेटा शुरू करें पर क्लिक करें.

KitchenSink, नेविगेशन फ़ोकस का अनुरोध करता है. इससे DirectRenderingCluster सेवा को इंस्ट्रुमेंट क्लस्टर पर मॉक-अप यूज़र इंटरफ़ेस दिखाने का निर्देश मिलता है.