Instrument Cluster API

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

शब्दावली

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

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

आगे बढ़ने से पहले, पक्का करें कि आपके पास ये एलिमेंट हों:

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

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

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

Instrument Cluster API के किसी भी इंटिग्रेशन में, ये तीन कॉम्पोनेंट शामिल होते हैं:

• CarService
• नेविगेशन ऐप्लिकेशन
• OEM इंस्ट्रूमेंट क्लस्टर सर्विस

CarService

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

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

इंस्ट्रुमेंट क्लस्टर को लागू करने के लिए, वाहन संबंधित OEM को InstrumentClusterRendererService का कस्टम वर्शन बनाना होगा. साथ ही, ClusterRenderingService को अपडेट करना होगा.

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

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

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

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

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

इस क्लास का इस्तेमाल दो कामों के लिए किया जाता है:

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

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

दूसरे फ़ंक्शन के लिए, Instrument Cluster सेवा को 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. car-lib से Car क्लास का इस्तेमाल करके, CarAppFocusManager को हासिल करता है.
   2. मोड़-दर-मोड़ दिशा-निर्देश शुरू होने से पहले, appType पैरामीटर के तौर पर CarAppFocusManager.APP_FOCUS_TYPE_NAVIGATION को पास करने के लिए, CarAppFocusManager.requestFocus() को कॉल करें.
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 फ़ाइल में इससे जुड़ी एंट्री जोड़ें. यह क्लास, इंस्ट्रूमेंट क्लस्टर के डिसप्ले को कंट्रोल करती है. साथ ही, यह ज़रूरत के मुताबिक Navigation State API का डेटा रेंडर कर सकती है.
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() का इस्तेमाल करके यह जान सकते हैं कि फ़ोकस में कौन-सा ऐप्लिकेशन है. इस जानकारी की मदद से, ओईएम ये काम कर सकते हैं:

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

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
}

...

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

कार ऐप्लिकेशन लाइब्रेरी का इस्तेमाल करने वाले, टेंप्लेट पर आधारित नेविगेशन ऐप्लिकेशन के लिए, 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, Navigation State API को लागू करने वाला एक सैंपल ऐप्लिकेशन उपलब्ध कराता है.

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

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

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