Matter के लिए एक Android ऐप्लिकेशन बनाएं

1. आपका स्वागत है

Matter को IoT स्टैंडर्ड को एक साथ लाने के मकसद से बनाया गया है. यह Google Home, Zigbee, Bluetooth Mesh, Z-Wave जैसे अलग-अलग इकोसिस्टम में स्मार्ट होम डिवाइसों को कनेक्ट करता है.

स्मार्ट होम डिवाइसों को कंट्रोल करने के लिए, मोबाइल डिवाइसों का इस्तेमाल किया जाता है. अगर आपको Matter डिवाइसों के साथ काम करने वाले Android ऐप्लिकेशन बनाने हैं, तो हम आपकी मदद कर सकते हैं.

Google Home Sample App for Matter (GHSA for Matter), Home Mobile SDK API के बारे में जानकारी देता है. इससे उपयोगकर्ता, डिवाइसों को चालू कर सकते हैं और उन्हें शेयर कर सकते हैं. सैंपल ऐप्लिकेशन को लर्निंग टूल के तौर पर भी इस्तेमाल किया जा सकता है. इससे Matter के मुख्य सिद्धांतों को बेहतर तरीके से समझा जा सकता है. साथ ही, इसे Matter डिवाइसों के साथ इंटरैक्शन की समस्याओं को ठीक करने और डीबग करने के लिए भी इस्तेमाल किया जा सकता है.

आपको क्या करना होगा

इस कोडलैब में, आपको सैंपल ऐप्लिकेशन का सोर्स कोड डाउनलोड करने का तरीका बताया जाएगा. साथ ही, डिवाइसों को चालू करने और उन्हें शेयर करने के लिए, Home Mobile SDK का इस्तेमाल करने का तरीका बताया जाएगा. आपको Matter repo (connectedhomeip) से कमीशनिंग और क्लस्टर लाइब्रेरी इस्तेमाल करने का तरीका भी पता चलेगा.

सेंपल ऐप्लिकेशन डाउनलोड करने के बाद, हम Android Studio में सोर्स कोड की समीक्षा करेंगे. साथ ही, Home Mobile SDK API को लागू करेंगे:

आपको कमीशनिंग के कॉन्सेप्ट, Matter फ़ैब्रिक, और Matter डिवाइसों को कंट्रोल करने के तरीके के बारे में भी ज़्यादा जानकारी मिलेगी.

आपको किन चीज़ों की ज़रूरत होगी

शुरू करने से पहले, पक्का करें कि आपने ये चरण पूरे कर लिए हों:

सैंपल ऐप्लिकेशन की मदद से डिवाइसों को चालू और कंट्रोल करने के लिए, आपको हब की ज़रूरत नहीं है. उदाहरण के लिए, Google Nest Hub (दूसरी जनरेशन).

2. सेट अप करें

कोडलैब का स्टार्टर ऐप्लिकेशन, codelab ब्रांच में मौजूद है. कोड लैब के सोर्स कोड का इस्तेमाल करने के लिए, ZIP फ़ाइल डाउनलोड करें.

इस codelab ZIP फ़ाइल का इस्तेमाल करके, काम करने वाला सैंपल बनाया जाएगा.

कोडलैब के वर्शन

codelab ब्रांच को सैंपल ऐप्लिकेशन के 2.0.0 वर्शन के साथ टैग किया गया है. हर चरण को पूरा करते समय अपने अपडेट की तुलना करने के लिए, इस वर्शन का पूरा सोर्स कोड डाउनलोड किया जा सकता है.

अगर आपको GitHub रिपॉज़िटरी को क्लोन करना है, तो सैंपल ऐप्लिकेशन के README में दिए गए निर्देशों का पालन करें.

डिपेंडेंसी

हम आपको डिवाइसों को शेयर करने और कमीशन करने के लिए ज़रूरी सोर्स कोड के बारे में बताएंगे. हालांकि, शुरू करने से पहले, आपको इन डिपेंडेंसी के बारे में पता होना चाहिए. ध्यान दें कि इन डिपेंडेंसी का एलान, libs.versions.toml फ़ाइल में किया गया है. साथ ही, इनके इस्तेमाल के बारे में build.gradle.kts फ़ाइल में बताया गया है

  • Home Mobile SDK
  • Matter SDK लाइब्रेरी.
  • Jetpack Compose. यूज़र इंटरफ़ेस (यूआई) को पूरी तरह से Compose का इस्तेमाल करके लागू किया गया है.
  • Material Design. ज़्यादा जानने के लिए, MDC-103 Android: Material Theming with Color, Elevation and Type (Kotlin) और Material Theme Builder देखें.
  • Proto DataStore का इस्तेमाल, ऐप्लिकेशन के डेटा को सेव करने के लिए किया जाता है. Datastore Repositories और Serializers को java/data में सेव किया जाता है. इनमें डिवाइसों और उपयोगकर्ता की प्राथमिकताओं के स्कीमा भी शामिल हैं. DataStore के बारे में ज़्यादा जानने के लिए, Proto DataStore के साथ काम करना लेख पढ़ें.
  • डेटा को बनाए रखने और डिपेंडेंसी इंजेक्शन के लिए Hilt.

सोर्स कोड

आपके लिए यूज़र इंटरफ़ेस और ज़्यादातर सुविधाएं पहले से ही बना दी गई हैं.

इस कोडलैब के लिए, हम इन फ़ाइलों में Matter की सुविधा जोड़ेंगे:

  • java/com/google/homesampleapp/commissioning/AppCommissioningService: इसकी मदद से, डिवाइसों को डेवलपमेंट फ़ैब्रिक में कमीशन किया जा सकता है
  • java/com/google/homesampleapp/screens/home/HomeScreen और java/com/google/homesampleapp/screens/home/HomeViewModel.kt: इसमें Home Mobile SDK की कमीशनिंग की सुविधा शामिल है
  • java/com/google/homesampleapp/screens/device/DeviceScreen और java/com/google/homesampleapp/screens/device/DeviceViewModel: इसमें Share Device API कॉल शामिल हैं

हर फ़ाइल में, उस कोड-ब्लॉक के बारे में टिप्पणी की गई है जिसमें आपको बदलाव करना है. उदाहरण के लिए:

// CODELAB: add commissioningFunction()

इससे आपको कोडलैब में, इससे जुड़ा सेक्शन तुरंत ढूंढने में मदद मिलती है.

3. Google को कमीशन

डिवाइसों को कंट्रोल करने और उन्हें एक ही फ़ैब्रिक में एक-दूसरे से कम्यूनिकेट करने की अनुमति देने से पहले, उन्हें कमिश्नर से कमीशन किया जाना चाहिए. इस मामले में, कमिश्नर यह सैंपल ऐप्लिकेशन है, जो कि Matter के लिए Google Home Sample App है.

Matter डिवाइस को चालू करने के बारे में इन कॉन्सेप्ट को समझना ज़रूरी है:

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

किसी डिवाइस को चालू करने के लिए, आपको CommissioningClient API का इस्तेमाल करना होगा. .commissionDevice() को कॉल करने पर, IntentSender मिलता है. इससे Google Play services में सही गतिविधि लॉन्च होती है:

interface CommissioningClient {
  Task<IntentSender> commissionDevice(CommissioningRequest request);
}

अगले सेक्शन में, हम Google फ़ैब्रिक में डिवाइसों को चालू करने के लिए ज़रूरी कम से कम कोड के बारे में जानेंगे.

पहला चरण: Activity Launcher

IntentSender से CommissioningClient को हैंडल करने के लिए, ActivityResultLauncher का इस्तेमाल किया जा सकता है:

val commissioningLauncher = registerForActivityResult(
    StartIntentSenderForResult()
) { result: ActivityResult ->
    if (result.resultCode == RESULT_OK) {
        Timber.d(TAG, "Commissioning succeeded.")
    } else {
        Timber.d(TAG, "Commissioning failed. " + result.resultCode)
    }
}

दूसरा चरण: कमीशनिंग फ़ंक्शन

यहां एक बुनियादी उदाहरण दिया गया है. इसमें CommissioningClient API का इस्तेमाल करके, किसी डिवाइस को Google फ़ैब्रिक से जोड़ने का तरीका बताया गया है.

  1. कमीशनिंग की प्रोसेस, commissionDevice() फ़ंक्शन से शुरू होती है. सबसे पहले, CommissioningRequest तय किया जाता है. इस डिफ़ॉल्ट कॉन्फ़िगरेशन के साथ, डिवाइसों को सिर्फ़ लोकल Android फ़ैब्रिक के लिए चालू किया जाता है.
  2. Matter, Home Mobile SDK के लिए एंट्री पॉइंट है. अगले कॉल में, .getCommissioningClient को this (गतिविधि) के ज़रिए CommissioningClient मिलता है.
  3. .commissionDevice() ने CommissioningRequest स्वीकार कर लिया है.
  4. आखिर में, .addOnSuccessListener को कॉल किया जाता है, ताकि CommissioningResult को प्रोसेस किया जा सके. साथ ही, Google Play services (GPS) की Commission Device Activity लॉन्च की जा सके.
private fun commissionDevice() {
    val request: CommissioningRequest = CommissioningRequest.builder().build()
    Matter.getCommissioningClient(this)
        .commissionDevice(request)
        .addOnSuccessListener { result ->
            commissioningLauncher.launch(IntentSenderRequest.Builder(result).build())
        }
}

Android की सेटिंग के ज़रिए, लोकल Android फ़ैब्रिक का इस्तेमाल किया जा सकता है. इससे, डिवाइसों को अन्य फ़ैब्रिक पर चालू करने की प्रोसेस को आसान बनाया जा सकता है.

इसके बाद, आपको डेवलपमेंट फ़ैब्रिक में डिवाइस को चालू करने का तरीका बताया जाएगा.

कमीशनिंग की प्रोसेस के दौरान यूज़र इंटरफ़ेस की खास जानकारी के लिए, Google Home Sample App for Matter Guide देखें.

4. डेवलपमेंट फ़ैब्रिक के लिए कमीशन

डिवाइसों को एक से ज़्यादा फ़ैब्रिक में कमीशन किया जा सकता है. भरोसेमंद डिवाइसों के साथ पेयरिंग को मैनेज करने के लिए, डिवाइस एक FabricTable सेव करते हैं. इसमें अलग-अलग FabricInfo सदस्य होते हैं. उदाहरण के लिए:

  • कपड़े की पहचान करने की सुविधा
  • फ़ैब्रिक की ओर से डिवाइस को असाइन किया गया नोड आईडी
  • वेंडर आईडी
  • कपड़े का आईडी
  • डिवाइस के ऑपरेशनल क्रेडेंशियल

एडमिनिस्ट्रेटिव डोमेन मैनेजर (एडीएम), फ़ैब्रिक क्रेडेंशियल तय करता है. पिछले उदाहरण में, Google Play Services एक ऐसा ईकोसिस्टम है जो भरोसेमंद रूट सर्टिफ़िकेट देने वाली संस्था (CA) के तौर पर काम करता है. डिवाइसों को लोकल Android फ़ैब्रिक में शामिल करने पर, हर डिवाइस में फ़ैब्रिक क्रेडेंशियल का एक ही सेट और सीए का एक ही सेट शामिल होता है.

कस्टम कमीशनिंग सेवाएं

Local Android फ़ैब्रिक को चालू करने के लिए, हमने CommissioningClient API में CommissioningRequest बनाने के लिए डिफ़ॉल्ट पैरामीटर का इस्तेमाल किया:

val request: CommissioningRequest = CommissioningRequest.builder().build()

अगर आपको अपने ऐप्लिकेशन से नए डिवाइसों को कंट्रोल और मैनेज करना है, तो आपको लोकल डेवलपमेंट फ़ैब्रिक बनाना होगा. साथ ही, डिवाइसों को चालू करने के लिए, ऑपरेशनल क्रेडेंशियल पाने होंगे. इस स्थिति में, आपका ऐप्लिकेशन एक यूनीक और स्वतंत्र इकोसिस्टम बन जाता है. यह डिवाइसों को नोड के सही क्रेडेंशियल असाइन करता है.

Home Mobile SDK को यह बताया जा सकता है कि आपको अपने फ़ैब्रिक में डिवाइसों को कमीशन करना है. इसके लिए, CommissioningRequest को कस्टम सेवा पास करें:

class CommissioningRequest {
  static CommissioningRequest.Builder builder();

  class Builder {
    Builder setCommissioningService(@Nullable ComponentName commissioningService);

    CommissioningRequest build();
  }
}

अगले चरणों में, हम commissionDevice() फ़ंक्शन में बदलाव करके, कस्टम सेवा का इस्तेमाल करेंगे. हम होम फ़्रैगमेंट में एक गतिविधि लॉन्चर भी जोड़ेंगे. साथ ही, एपीआई फ़्लो को मैनेज करने के लिए LiveData ऑब्जेक्ट का इस्तेमाल करेंगे.

पहला चरण: GPS Activity Launcher बनाना

सबसे पहले, CommissioningClient API से मिले IntentSender को मैनेज करने के लिए, एक Activity Launcher बनाते हैं.

  1. java/com/google/homesampleapp/screens/home/ फ़ोल्डर में HomeScreen खोलें.
  2. कमीशनिंग गतिविधि के नतीजे को रजिस्टर और मैनेज करने के लिए, // CODELAB: commissionDeviceLauncher definition टिप्पणी की जगह यह कोड डालें:
    val commissionDeviceLauncher =
  rememberLauncherForActivityResult(
    contract = ActivityResultContracts.StartIntentSenderForResult()
  ) { result ->
    // Commission Device Step 5.
    // The Commission Device activity in GPS (step 4) has completed.
    val resultCode = result.resultCode
    if (resultCode == Activity.RESULT_OK) {
      Timber.d("CommissionDevice: Success")
      // We let the ViewModel know that GPS commissioning has completed successfully.
      // The ViewModel knows that we still need to capture the device name and will\
      // update UI state to trigger the NewDeviceAlertDialog.
      homeViewModel.gpsCommissioningDeviceSucceeded(result)
    } else {
      homeViewModel.commissionDeviceFailed(resultCode)
    }
  }

दूसरा चरण: कमीशन डिवाइस ऐक्शन को ट्रिगर करना

इस चरण में, उपयोगकर्ता होम स्क्रीन पर सबसे नीचे दाईं ओर मौजूद "+" बटन पर क्लिक करके, "डिवाइस चालू करें" कार्रवाई को ट्रिगर करता है. इसके बाद, commissionDevice() पर कॉल किया जाता है.

val onCommissionDevice = {
  ...
  commissionDevice(activity!!.applicationContext, commissionDeviceLauncher)
}

तीसरा चरण: एपीआई को कॉल करना

  1. यह अब भी java/com/google/homesampleapp/screens/home फ़ोल्डर में HomeScreen.kt में है.
  2. // CODELAB: commissionDevice टिप्पणी की जगह, यहां दी गई commissionDeviceRequest टिप्पणी का इस्तेमाल करें. setCommissioningService, AppCommissioningService को CommissioningService इंस्टेंस से बाइंड करता है. यह इंस्टेंस, कॉलबैक फ़ंक्शन में दिखता है. कस्टम सेवा पास करने पर, Home Mobile SDK पहले डिवाइसों को Android लोकल फ़ैब्रिक पर कमीशन करेगा. इसके बाद, AppCommissioningService को ऑनबोर्डिंग पेलोड वापस भेजेगा.
    val commissionDeviceRequest =
    CommissioningRequest.builder()
        .setCommissioningService(ComponentName(
            context, AppCommissioningService::class.java))
        .build()
  3. .getCommissioningClient() पर कॉल करें. इसके बाद, .commissionDevice() पर कॉल करें.
Matter.getCommissioningClient(context)
    .commissionDevice(commissionDeviceRequest)

हमारे commissionDevice फ़ंक्शन को पूरा करने के लिए, addOnSuccessListener और addOnFailureListener जोड़ें:

    .addOnSuccessListener { result ->
      commissionDeviceLauncher.launch(IntentSenderRequest.Builder(result).build())
    }
    .addOnFailureListener { error ->
      Timber.e(error)
    }

5. कमीशनिंग सेवा बनाना

हमने commissionDevice() फ़ंक्शन में, CommissioningClient API से CommissioningService पाने का अनुरोध किया है. इस फ़्लो में, CommissioningClient API पहले डिवाइसों को लोकल Android फ़ैब्रिक के लिए कमीशन करता है. इसके बाद, एक कॉलबैक दिखाता है, जिसमें CommissioningRequestMetadata ऑब्जेक्ट शामिल होता है:

public interface CommissioningService {
interface Callback {
    void onCommissioningRequested(CommissioningRequestMetadata metadata);
  }
}

अब हमें CommissioningService.Callback को इनहेरिट करना होगा. साथ ही, अपने सैंपल ऐप्लिकेशन में डिवाइसों को चालू करने के लिए ज़रूरी फ़ंक्शनैलिटी देनी होगी. यहां CommissioningService को लागू करने का एक बुनियादी उदाहरण दिया गया है:

class MatterCommissioningService : Service(), CommissioningService.Callback {
   private val commissioningServiceDelegate =
     CommissioningService.Builder(this)
       .setCallback(this)
       .build()

   override fun onBind(intent: Intent) = commissioningServiceDelegate.asBinder()

   override fun onCommissioningRequested(metadata: CommissioningRequestMetadata) {
     // perform commissioning

     commissioningServiceDelegate
       .sendCommissioningComplete(CommissioningCompleteMetadata.builder().build())
   }
 }

पहला चरण: कस्टम AppCommissioningService के बारे में जानें

हमारा कस्टम CommissioningService इस्तेमाल करने के लिए, हमने पहले से ही क्लास का बुनियादी स्ट्रक्चर तय कर दिया है. इस सेवा के काम करने के तरीके के बारे में खास जानकारी यहां दी गई है. साथ-साथ काम करने के लिए, java/commissioning में AppCommissioningService खोलें.

हमने Home Mobile SDK API के लिए, ये इंपोर्ट जोड़े हैं:

import com.google.android.gms.home.matter.commissioning.CommissioningCompleteMetadata
import com.google.android.gms.home.matter.commissioning.CommissioningRequestMetadata
import com.google.android.gms.home.matter.commissioning.CommissioningService

AppCommissioningService में, Matter repo (connectedhomeip) की लाइब्रेरी भी शामिल हैं:

import com.google.homesampleapp.chip.ChipClient

आखिर में, इस सेवा में Hilt और Kotlin coroutines के साथ काम करने के लिए इंपोर्ट शामिल हैं.

इसके बाद, हम कंस्ट्रक्टर बनाते हैं और कुछ चीज़ें सेट अप करते हैं. इनमें commissioningServiceDelegate भी शामिल है. इसका इस्तेमाल, Google Play services को यह बताने के लिए किया जाएगा कि कमीशनिंग कब पूरी हुई.

private lateinit var commissioningServiceDelegate: CommissioningService
...
commissioningServiceDelegate = CommissioningService.Builder(this).setCallback(this).build()

अब कमीशनिंग फ़ंक्शन जोड़ने का समय है.

दूसरा चरण: onCommissioningRequested को बदलें

डिवाइसों को ऐप्लिकेशन के डेवलपमेंट फ़ैब्रिक में कमीशन करने के लिए, यह तरीका अपनाएं:

  1. AppCommissioningService को java/commissioning में खोलें.
  2. onCommissioningRequested() फ़ंक्शन ढूंढें. हमने एक लॉग मैसेज दिया है, जो CommissioningRequestMetadata को प्रिंट करता है. serviceScope को रूटीन शुरू करने और deviceId पाने के लिए, // CODELAB: onCommissioningRequested() टिप्पणी को बदलें.
    // Perform commissioning on custom fabric for the sample app.
serviceScope.launch {
  val deviceId = devicesRepository.incrementAndReturnLastDeviceId()
  3. डिवाइस को चालू करें. इस चरण के लिए, हम CommissioningRequestMetadata ऑब्जेक्ट में मौजूद डिवाइस की जानकारी पास कर सकते हैं. ChipClient इस मेटाडेटा का इस्तेमाल, GHSA for Matter ऐप्लिकेशन और आपके डिवाइस के बीच एक सुरक्षित चैनल बनाने के लिए करता है.
    try {
  Timber.d(
      "Commissioning: App fabric -> ChipClient.establishPaseConnection(): deviceId [${deviceId}]")
  chipClient.awaitEstablishPaseConnection(
      deviceId,
      metadata.networkLocation.ipAddress.hostAddress!!,
      metadata.networkLocation.port,
      metadata.passcode)
  Timber.d(
      "Commissioning: App fabric -> ChipClient.commissionDevice(): deviceId [${deviceId}]")
  chipClient.awaitCommissionDevice(deviceId, null)
} catch (e: Exception) {
  Timber.e(e, "onCommissioningRequested() failed")
  // No way to determine whether this was ATTESTATION_FAILED or DEVICE_UNREACHABLE.
  commissioningServiceDelegate
      .sendCommissioningError(CommissioningError.OTHER)
      .addOnSuccessListener {
        Timber.d(
            "Commissioning: commissioningServiceDelegate.sendCommissioningError() succeeded")
      }
      .addOnFailureListener { e2 ->
        Timber.e(e2, "Commissioning: commissioningServiceDelegate.sendCommissioningError() failed")
      }
  return@launch
}
  4. commissioningServiceDelegate का इस्तेमाल करके, Google Play Services को बताएं कि कमीशनिंग पूरी हो गई है. .sendCommissioningComplete() में, CommissioningCompleteMetadata पास करें.
    commissioningServiceDelegate
    .sendCommissioningComplete(
        CommissioningCompleteMetadata.builder().setToken(deviceId.toString()).build())
    .addOnSuccessListener {
      Timber.d("Commissioning: commissioningServiceDelegate.sendCommissioningComplete() succeeded")
    }
    .addOnFailureListener { e ->
      Timber.e(e, "Commissioning: commissioningServiceDelegate.sendCommissioningComplete() failed")
    }
}

ऐप्लिकेशन चलाएं

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

कमीशनिंग पूरी होने के बाद, आपका डिवाइस अब दो फ़ैब्रिक में शामिल हो जाता है: लोकल Android फ़ैब्रिक और लोकल डेवलपमेंट फ़ैब्रिक. हर फ़ैब्रिक के क्रेडेंशियल का अपना सेट होता है. साथ ही, उसका यूनीक 64-बिट फ़ैब्रिक आईडी होता है.

6. डिवाइसों को कंट्रोल करना

डेवलपमेंट फ़ैब्रिक में कमीशन करने से, आपको Matter repo (connectedhomeip) से लाइब्रेरी इस्तेमाल करने की अनुमति मिलती है. इससे, सैंपल ऐप्लिकेशन से डिवाइसों को कंट्रोल किया जा सकता है.

हमने कुछ हेल्पर क्लास बनाई हैं, ताकि डिवाइस क्लस्टर को आसानी से ऐक्सेस किया जा सके और निर्देश भेजे जा सकें. ज़्यादा जानने के लिए, java/clusters में ClustersHelper खोलें. यह सिंगलटन हेल्पर, डिवाइस की जानकारी ऐक्सेस करने के लिए इन लाइब्रेरी को इंपोर्ट करता है:

import chip.devicecontroller.ChipClusters
import chip.devicecontroller.ChipStructs

हम इस क्लास का इस्तेमाल करके, किसी डिवाइस के लिए चालू/बंद क्लस्टर पा सकते हैं. इसके बाद, .toggle को कॉल कर सकते हैं:

suspend fun toggleDeviceStateOnOffCluster(deviceId: Long, endpoint: Int) {
  Timber.d("toggleDeviceStateOnOffCluster())")
  val connectedDevicePtr =
      try {
        chipClient.getConnectedDevicePointer(deviceId)
      } catch (e: IllegalStateException) {
        Timber.e("Can't get connectedDevicePointer.")
        return
      }
  return suspendCoroutine { continuation ->
    getOnOffClusterForDevice(connectedDevicePtr, endpoint)
        .toggle(
            object : ChipClusters.DefaultClusterCallback {
              override fun onSuccess() {
                continuation.resume(Unit)
              }
              override fun onError(ex: Exception) {
                Timber.e("readOnOffAttribute command failure: $ex")
                continuation.resumeWithException(ex)
              }
            })
  }
}

किसी डिवाइस को टॉगल करना

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

Matter ऐप्लिकेशन, इवेंट पर आधारित होते हैं. Matter स्टैक के शुरू होने पर, क्लस्टर सेवाएं आने वाले मैसेज सुनती हैं. किसी डिवाइस को चालू करने के बाद, Matter क्लाइंट, डिवाइस को चालू करने के दौरान बनाए गए सुरक्षित ऑपरेशनल चैनल पर कमांड भेजते हैं.

डिवाइस पर, पैकेट की पुष्टि की जाती है, उन्हें डिक्रिप्ट किया जाता है, और फिर कॉलबैक के साथ भेजा जाता है. कॉलबैक फ़ंक्शन में EndpointId, ClusterId, और AttributeId शामिल होते हैं. इन्हें attributePath से ऐक्सेस किया जा सकता है. उदाहरण के लिए, इस कोड को Matter डिवाइस पर लागू किया जा सकता है:

void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, uint8_t mask, uint8_t type,
                                       uint16_t size, uint8_t * value)
{
    // handle callback
    ClusterId clusterId     = attributePath.mClusterId;
    AttributeId attributeId = attributePath.mAttributeId;
}

अगले चरणों में, डिवाइस को टॉगल करने के लिए Matter SDK और ClustersHelper का इस्तेमाल किया जाएगा.

  1. java/screens/device में DeviceViewModel पर जाएं.
  2. updateDeviceStateOn फ़ंक्शन ढूंढें.
  3. // CODELAB: toggle टिप्पणी को clustersHelper को कॉल करने वाले कोड से बदलें. इसके बाद, डिवाइस रिपॉज़िटरी को अपडेट करें:
    Timber.d("Handling real device")
    try {
      clustersHelper.setOnOffDeviceStateOnOffCluster(deviceUiModel.device.deviceId, isOn, 1)
      devicesStateRepository.updateDeviceState(deviceUiModel.device.deviceId, true, isOn)
    } catch (e: Throwable) {
      Timber.e("Failed setting on/off state")
    }

इस फ़ंक्शन को DeviceScreen से कॉल किया जाता है:

// On/Off Switch click.
val onOnOffClick: (value: Boolean) -> Unit = { value ->
  deviceViewModel.updateDeviceStateOn(deviceUiModel!!, value)
}

ऐप्लिकेशन चलाएं

अपडेट किए गए डेटा को फिर से लोड करने के लिए, ऐप्लिकेशन चलाएं. होम स्क्रीन पर, अपने डिवाइस को टॉगल करके चालू और बंद करें.

7. डिवाइसों को अन्य इकोसिस्टम के साथ शेयर करना

डिवाइस शेयर करने की सुविधा को Matter स्पेसिफ़िकेशन में एक से ज़्यादा एडमिन वाला फ़्लो कहा जाता है.

पिछले चरणों में, हमने जाना कि Home Mobile SDK की मदद से, डिवाइसों को लोकल Android फ़ैब्रिक और सैंपल ऐप्लिकेशन के लिए डेवलपमेंट फ़ैब्रिक में कमीशन किया जा सकता है. यह मल्टी-एडमिन फ़्लो का एक उदाहरण है. इसमें डिवाइसों को एक से ज़्यादा फ़ैब्रिक में कमीशन किया जा सकता है.

अब आपको डिवाइसों को ज़्यादा से ज़्यादा फ़ैब्रिक के साथ शेयर करना पड़ सकता है. ऐसा तब होता है, जब घर के लोगों की ऐप्लिकेशन और प्लैटफ़ॉर्म के मामले में अपनी-अपनी पसंद होती है.

Home Mobile SDK, ShareDeviceRequest API में यह सुविधा देता है. इससे आपको ये काम करने की अनुमति मिलती है:

  1. डिवाइसों के लिए, कुछ समय के लिए कमीशन करने की विंडो खोलें.
  2. अपने डिवाइसों की स्थिति बदलें, ताकि उन्हें किसी दूसरे फ़ैब्रिक में कमीशन किया जा सके.
  3. अपने डिवाइसों को अन्य ऐप्लिकेशन और इकोसिस्टम से कंट्रोल करें.

अगले चरणों में, डिवाइसों को शेयर करने के लिए Home Mobile SDK का इस्तेमाल किया जाएगा.

पहला चरण: GPS Activity Launcher बनाना

हमने कमीशनिंग ऐक्टिविटी लॉन्चर बनाया था, ताकि डेवलपमेंट फ़ैब्रिक को कमीशन किया जा सके. इसी तरह, हमने शेयर डिवाइस ऐक्टिविटी लॉन्चर बनाया है, ताकि CommissioningClient API से मिले IntentSender को मैनेज किया जा सके.

  1. java/com/google/homesampleapp/screens/device/ फ़ोल्डर में DeviceScreen खोलें.
  2. // CODELAB: shareDeviceLauncher definition टिप्पणी की जगह यह कोड डालें, ताकि .shareDevice() गतिविधि के नतीजे को रजिस्टर और मैनेज किया जा सके:
    val shareDeviceLauncher = rememberLauncherForActivityResult(
  contract = ActivityResultContracts.StartIntentSenderForResult()
) { result ->
  // Commission Device Step 5.
  // The Share Device activity in GPS (step 4) has completed.
  val resultCode = result.resultCode
  if (resultCode == Activity.RESULT_OK) {
    deviceViewModel.shareDeviceSucceeded()
  } else {
    deviceViewModel.shareDeviceFailed(resultCode)
  }
}

दूसरा चरण: डिवाइस शेयर करने की कार्रवाई ट्रिगर करना

इस चरण में, उपयोगकर्ता डिवाइस की स्क्रीन पर मौजूद "शेयर करें" बटन पर क्लिक करके, "डिवाइस शेयर करें" कार्रवाई को ट्रिगर करता है. इसके बाद, deviceViewModel को कॉल किया जाता है, ताकि डिवाइस शेयर करने के लिए पेयरिंग विंडो खोली जा सके.

// Share Device button click.
val onShareDevice: () -> Unit = remember {
 {
   deviceViewModel.openPairingWindow(deviceUiModel!!.device.deviceId)
 }
}

पेयरिंग विंडो के खुलने के बाद, deviceViewModel यूज़र इंटरफ़ेस (यूआई) को इसकी सूचना देता है. ViewModel और यूज़र इंटरफ़ेस (यूआई) के बीच कम्यूनिकेशन, StateFlow ऑब्जेक्ट के ज़रिए होता है.

// Communicate to the UI that the pairing window is open.
// UI can then launch the GPS activity for device sharing.
_pairingWindowOpenForDeviceSharing.value = true

StateFlow ऑब्जेक्ट में हुए बदलाव को देखने के बाद, DeviceScreen यह कॉल करता है:

shareDevice(activity!!.applicationContext, shareDeviceLauncher, deviceViewModel)

तीसरा चरण: एपीआई को कॉल करना

अब डिवाइस शेयर करने का टास्क शुरू करें.

  1. java/com/google/homesampleapp/screens/device/ फ़ोल्डर में DeviceScreen.kt खोलें.
  2. shareDevice() फ़ंक्शन ढूंढें. // CODELAB: shareDevice टिप्पणी को ShareDeviceRequest से बदलें. DeviceDescriptor, डिवाइस के बारे में खास जानकारी देता है. जैसे, वेंडर आईडी, प्रॉडक्ट आईडी, और डिवाइस टाइप. इस उदाहरण में, हमने वैल्यू को हार्ड-कोड किया है.
    val shareDeviceRequest =
  ShareDeviceRequest.builder()
    .setDeviceDescriptor(DeviceDescriptor.builder().build())
    .setDeviceName("GHSAFM temp device name")
  3. CommissioningWindow और parameters सेट करें.
        .setCommissioningWindow(
        CommissioningWindow.builder()
            .setDiscriminator(Discriminator.forLongValue(DISCRIMINATOR))
            .setPasscode(SETUP_PIN_CODE)
            .setWindowOpenMillis(SystemClock.elapsedRealtime())
            .setDurationSeconds(OPEN_COMMISSIONING_WINDOW_DURATION_SECONDS.toLong())
            .build())
    .build()
  4. .getCommissioningClient() को कॉल करें. हालांकि, इस बार सिर्फ़ .shareDevice() एपीआई का इस्तेमाल करें.
    Matter.getCommissioningClient(context)
    .shareDevice(shareDeviceRequest)

commissioningClient.shareDevice() एपीआई का success कॉलबैक, IntentSender उपलब्ध कराता है. इसका इस्तेमाल Google Play services में, डिवाइस पर की गई गतिविधि शेयर करने की सुविधा को लॉन्च करने के लिए किया जाता है.

  1. हमारे shareDevice फ़ंक्शन को पूरा करने के लिए, addOnSuccessListener और addOnFailureListener जोड़ें. सफल होने पर, shareDeviceLauncher पर launch को कॉल किया जाता है, ताकि डिवाइस शेयर करने के लिए जीपीएस गतिविधि लॉन्च की जा सके.
        .addOnSuccessListener { result ->
      Timber.d("ShareDevice: Success getting the IntentSender: result [${result}]")
      shareDeviceLauncher.launch(IntentSenderRequest.Builder(result).build())
    }
    .addOnFailureListener { error ->
      Timber.e(error)
      deviceViewModel.showMsgDialog("Share device failed", error.toString())
    }

ऐप्लिकेशन चलाएं

अपने Matter डिवाइस को अन्य इकोसिस्टम के साथ शेयर करने के लिए, आपको अपने Android डिवाइस पर कोई दूसरा प्लैटफ़ॉर्म इंस्टॉल करना होगा. हमने सैंपल ऐप्लिकेशन का एक और इंस्टेंस बनाया है. इसका इस्तेमाल टारगेट कमिशनर के तौर पर किया जा सकता है.

अपने Android डिवाइस पर टारगेट कमिशनर इंस्टॉल करने के बाद, पुष्टि करें कि आपके पास Matter डिवाइस शेयर करने का विकल्प है. टारगेट कमिश्नर ऐप्लिकेशन को GHSAFM-TC के तौर पर लेबल किया गया है.

अब आपके डिवाइस इन तीन फ़ैब्रिक में हिस्सा ले सकते हैं:

  1. Android के लिए लोकल फ़ैब्रिक.
  2. आपका डेवलपमेंट फ़ैब्रिक (यह ऐप्लिकेशन).
  3. यह तीसरा फ़ैब्रिक है, जिसके साथ आपने अभी-अभी डिवाइस शेयर किया है.

8. अगले चरण

बधाई हो

बधाई हो, आपने इस कोडलैब को पूरा कर लिया है. साथ ही, आपने Home Mobile SDK का इस्तेमाल करके डिवाइसों को चालू करने और उन्हें शेयर करने का तरीका सीख लिया है.

अगर आपको सैंपल ऐप्लिकेशन से जुड़ी समस्याएं आ रही हैं, तो अपने एनवायरमेंट की पुष्टि करने के लिए यह तरीका अपनाएं:

अगर आपको सैंपल ऐप्लिकेशन का इस्तेमाल करने के बारे में कोई सवाल पूछना है या आपको कोड में कोई गड़बड़ी मिली है, तो GitHub रिपॉज़िटरी में मौजूद Issue Tracker में समस्याएं सबमिट करें:

तकनीकी सवालों के बारे में Google से आधिकारिक दिशा-निर्देश पाने के लिए, Smart Home Developer Forum का इस्तेमाल करें:

कम्यूनिटी से तकनीकी सहायता पाने के लिए, Stack Overflow पर google-smart-home टैग का इस्तेमाल करें: