یک برنامه اندروید برای Matter بسازید

1. خوش آمدید

Matter که با هدف یکسان سازی استانداردهای اینترنت اشیا ساخته شده است، دستگاه های خانه هوشمند را در اکوسیستم های مختلف مانند Google Home، Zigbee، Bluetooth Mesh، Z-Wave و غیره متصل می کند.

دستگاه های تلفن همراه یک نقطه تعامل مرکزی با دستگاه های خانه هوشمند هستند. اگر می‌خواهید برنامه‌های Android خود را برای پشتیبانی از دستگاه‌های Matter بسازید، ما می‌توانیم به شما کمک کنیم تا سریع شروع کنید.

Google Home Sample App for Matter (GHSA for Matter) API های Home Mobile SDK را به نمایش می گذارد و به کاربران امکان می دهد دستگاه ها را سفارش دهند و به اشتراک بگذارند. همچنین می توانید از برنامه نمونه به عنوان یک ابزار یادگیری برای درک بهتر مفاهیم کلیدی Matter و همچنین ابزاری برای اشکال زدایی و عیب یابی تعامل با دستگاه های Matter استفاده کنید.

کاری که خواهی کرد

در این Codelab، کد منبع برنامه نمونه را دانلود خواهید کرد و نحوه استفاده از Home Mobile SDK برای راه اندازی و اشتراک گذاری دستگاه ها را یاد خواهید گرفت. همچنین نحوه استفاده از کتابخانه های راه اندازی و کلاستر را از مخزن Matter ( connectedhomeip ) یاد خواهید گرفت.

پس از دانلود نمونه برنامه، کد منبع را در Android Studio بررسی کرده و API های Home Mobile SDK زیر را پیاده سازی می کنیم:

• راه اندازی
• ShareDevice

همچنین درباره مفاهیم راه اندازی، پارچه های Matter و نحوه کنترل دستگاه های Matter بیشتر خواهید آموخت.

آنچه شما نیاز دارید

قبل از شروع، مطمئن شوید که مراحل زیر را کامل کرده اید:

• راهنمای Google Home Sample App for Matter را مرور کنید.
• اندروید استودیو را دانلود کنید .
• یک Android O (8.1، API سطح 27) یا دستگاه جدیدتر برای آزمایش در دسترس داشته باشید. برای اطمینان از اینکه دستگاه شما آخرین پشتیبانی Matter را دارد، راهنمای Verify Matter Modules & Services را مرور کنید.
• یک دستگاه Matter با قابلیت روشن/خاموش بسازید. این نمونه برنامه با یک دستگاه مجازی و یک ESP32 کار می کند.
  • با برنامه rootnode_dimmablelight_bCwGYSDpoe یک دستگاه مجازی Matter بسازید . هنگامی که یک Matter یکپارچه سازی را در Home Developer Console ایجاد می کنید، از 0xFFF1 به عنوان شناسه فروشنده و 0x8000 به عنوان شناسه محصول خود استفاده کنید.
  • یک دستگاه Espressif با all-clusters-app بسازید. هنگامی که یک Matter یکپارچه سازی در Home Developer Console ایجاد می کنید، از 0xFFF1 به عنوان شناسه فروشنده و 0x8001 به عنوان شناسه محصول خود استفاده کنید.
• نحوه راه‌اندازی سرویس‌های Google Play را مرور کنید.

برای راه اندازی و کنترل دستگاه ها با برنامه نمونه، به هاب، به عنوان مثال Google Nest Hub (نسل دوم) نیاز ندارید.

2. راه اندازی شوید

مخزن برنامه نمونه GitHub شامل کتابخانه های شخص ثالث از مخزن Matter ( connectedhomeip ) است. این کتابخانه های بومی بیش از 50 مگابایت هستند و نیاز به استفاده از Git Large File Storage (LFS) دارند.

برنامه شروع کد لبه در شعبه codelab قرار دارد. برای شروع کار با کد منبع کد، می توانید فایل ZIP را دانلود کنید. این ZIP شامل کتابخانه های بومی Matter SDK بدون نیاز به Git LFS است:

file_download دانلود ZIP

شما از این فایل ZIP codelab برای ساختن یک نمونه کار استفاده خواهید کرد.

نسخه های Codelab

شاخه codelab با نسخه 1.2.2 برنامه نمونه برچسب گذاری شده است. برای مقایسه به‌روزرسانی‌های خود در طول هر مرحله، می‌توانید کد منبع تکمیل‌شده این نسخه را دانلود کنید.

file_download دانلود ZIP کامل شد

اگر می‌خواهید مخزن GitHub را شبیه‌سازی کنید، دستورالعمل‌های موجود در برنامه Sample README را دنبال کنید.

وابستگی ها

ما شما را از طریق کد منبع مورد نیاز برای اشتراک‌گذاری و راه‌اندازی دستگاه‌ها راهنمایی می‌کنیم، اما ممکن است قبل از شروع به آگاهی از وابستگی‌های زیر کمک کند:

• خانه موبایل SDK .

  implementation 'com.google.android.gms:play-services-home:16.0.0'
  

• کتابخانه های Matter SDK.

  // Native libs
  implementation fileTree(dir: "third_party/connectedhomeip/libs", include: ["*.jar", "*.so"])
  

• طراحی متریال. برای کسب اطلاعات بیشتر به MDC-103 Android: Material Theming with Color, Elevation and Type (Kotlin) و Material Theme Builder مراجعه کنید.

  implementation 'com.google.android.material:material:1.5.0'
  

• Proto DataStore، برای تداوم داده های برنامه استفاده می شود. مخازن Datastore و Serializers در java/data ذخیره می شوند، از جمله طرحواره ها برای دستگاه ها و تنظیمات برگزیده کاربر. برای کسب اطلاعات بیشتر در مورد DataStore، به کار با Proto DataStore مراجعه کنید.

  implementation "androidx.datastore:datastore:$dataStoreVersion"
  implementation 'androidx.datastore:datastore-core:1.0.0'
  implementation 'com.google.protobuf:protobuf-javalite:3.18.0'
  

• برای تداوم داده ها و پشتیبانی از تزریق وابستگی انتخاب کنید .

  kapt 'com.google.dagger:hilt-compiler:2.41'
  implementation 'com.google.dagger:hilt-android:2.41'
  

کد منبع

رابط کاربری و بسیاری از قابلیت ها قبلا برای شما ایجاد شده است.

برای این کد لبه، ما قابلیت Matter را به فایل‌های زیر اضافه می‌کنیم:

• java/commissioning/AppCommissioningService : به شما امکان می دهد دستگاه ها را به پارچه توسعه سفارش دهید
• java/screens/HomeFragment و java/screens/HomeViewModel.kt : شامل قابلیت راه اندازی Home Mobile SDK
• java/screens/DeviceViewModel : شامل تماس‌های اشتراک‌گذاری API دستگاه است

هر فایل با بلوک کدی که شما در حال تغییر آن هستید، نظر داده می شود، به عنوان مثال:

// CODELAB: add commissioningFunction()

این به شما این امکان را می دهد که به سرعت بخش مربوطه را در Codelab پیدا کنید.

3. کمیسیون به گوگل

قبل از اینکه بتوانید دستگاه‌ها را کنترل کنید و به آن‌ها اجازه دهید در یک پارچه با یکدیگر ارتباط برقرار کنند، باید توسط کمیسیونر سفارش داده شوند، که در این مورد این نمونه برنامه، Google Home Sample App for Matter است.

درک مفاهیم زیر در مورد راه اندازی Matter مهم است:

• پارچه ها به دستگاه ها اجازه می دهند با یکدیگر ارتباط برقرار کنند.
• پارچه ها مجموعه ای مشترک از اعتبار منحصر به فرد را حفظ می کنند.
• اکوسیستم ها مسئول صدور گواهی های ریشه قابل اعتماد، تخصیص شناسه های فابریک و تخصیص شناسه های گره منحصر به فرد هستند. یک اکوسیستم سرویس پشتیبان یک کمیسیون است، برای مثال Home Graph برای اکوسیستم Google Home.
• دستگاه ها را می توان به بیش از یک پارچه راه اندازی کرد (ویژگی چند مدیر).

برای راه اندازی یک دستگاه، باید از CommissioningClient API استفاده کنید. تماس با .commissionDevice() یک IntentSender را برمی گرداند که فعالیت مناسب را در خدمات Google Play راه اندازی می کند:

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

در بخش‌های بعدی، حداقل کدهای مورد نیاز برای سفارش دستگاه‌ها را به فابریک Google بررسی خواهیم کرد.

مرحله 1: راه‌انداز فعالیت

برای مدیریت IntentSender از CommissioningClient ، می توانید از ActivityResultLauncher استفاده کنید:

private lateinit var commissioningLauncher: ActivityResultLauncher<IntentSenderRequest>

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

مرحله 2: عملکرد راه اندازی

در اینجا یک مثال اساسی است که از CommissioningClient API برای سفارش دستگاه به فابریک گوگل استفاده می کند.

1. فرآیند راه اندازی با تابع commissionDevice() شروع می شود. ابتدا یک CommissioningRequest تعریف می شود. با این پیکربندی پیش‌فرض، دستگاه‌ها فقط به فابریک Local Android راه‌اندازی می‌شوند.
2. Matter نقطه ورود برای Home Mobile SDK است. در تماس بعدی، .getCommissioningClient با this (Activity) یک CommissioningClient دریافت می کند.
3. .commissionDevice() CommissioningRequest می پذیرد.
4. و در نهایت، .addOnSuccessListener فراخوانی می شود تا CommissioningResult را پردازش کند و فعالیت دستگاه کمیسیون خدمات Google Play (GPS) را راه اندازی کند.

private fun commissionDevice() {
    val request: CommissioningRequest = CommissioningRequest.builder().build()
    Matter.getCommissioningClient(this)
        .commissionDevice(request)
        .addOnSuccessListener { result ->
            commissioningLauncher.launch(IntentSenderRequest.Builder(result).build())
        }
}

Local Android Fabric را می‌توان از طریق تنظیمات Android برای ساده‌سازی فرآیند راه‌اندازی دستگاه‌های خود به پارچه‌های دیگر استفاده کرد.

در مرحله بعد، شما یاد خواهید گرفت که چگونه یک دستگاه را به یک پارچه توسعه سفارش دهید.

برای مرور کلی رابط کاربری در طول فرآیند راه اندازی، به راهنمای Google Home Sample App for Matter مراجعه کنید.

4. کمیسیون به یک بافت توسعه

دستگاه ها را می توان به بیش از یک پارچه راه اندازی کرد. برای مدیریت جفت‌های قابل اعتماد، دستگاه‌ها یک FabricTable حاوی اعضای مختلف FabricInfo را ذخیره می‌کنند، به عنوان مثال:

• شناسایی پارچه
• شناسه گره که توسط پارچه به دستگاه اختصاص داده شده است
• شناسه فروشنده
• شناسه پارچه
• اعتبار عملیاتی دستگاه

مدیر دامنه اداری (ADM) اعتبار فابریک را تعریف می کند. در سناریوی قبلی، Google Play Services اکوسیستمی است که به عنوان یک مرجع معتبر گواهی ریشه (CA) عمل می کند. هنگامی که دستگاه‌ها را به فابریک Android محلی سفارش می‌دهید، هر دستگاه دارای مجموعه‌ای از اعتبارنامه‌های فابریک و همان مجموعه CA است.

خدمات راه اندازی سفارشی

برای سفارش به فابریک Local Android، از پارامترهای پیش‌فرض برای ساخت CommissioningRequest در CommissioningClient API استفاده کردیم:

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

اگر می خواهید دستگاه های جدید را از برنامه خود کنترل و مدیریت کنید، باید یک بافت توسعه محلی ایجاد کنید و اعتبار عملیاتی را برای راه اندازی دستگاه ها به دست آورید. در این سناریو، برنامه شما به یک اکوسیستم منحصر به فرد و مستقل تبدیل می شود که اعتبار گره مناسب را به دستگاه ها اختصاص می دهد.

می‌توانید با ارائه یک سرویس سفارشی به CommissioningRequest، به Home Mobile SDK اطلاع دهید که می‌خواهید دستگاه‌ها را به پارچه خودتان سفارش دهید:

class CommissioningRequest {
  static CommissioningRequest.Builder builder();

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

    CommissioningRequest build();
  }
}

در مراحل بعدی، تابع commissionDevice() را برای استفاده از یک سرویس سفارشی تغییر می دهیم. همچنین یک Activity Launcher به بخش Home اضافه می کنیم و از اشیاء LiveData برای مدیریت جریان API استفاده می کنیم.

مرحله 1: یک راه‌انداز فعالیت GPS ایجاد کنید

ابتدا، اجازه دهید یک Activity Launcher برای مدیریت IntentSender از API CommissioningClient ایجاد کنیم.

1. HomeFragment در پوشه java/screens/home/ باز کنید.
2. نظر // CODELAB: commissionDeviceLauncher declaration با اعلان زیر جایگزین کنید:

   // The ActivityResult launcher that launches the "commissionDevice" activity in Google Play
   // Services.
   private lateinit var commissionDeviceLauncher: ActivityResultLauncher<IntentSenderRequest>
   

3. // CODELAB: commissionDeviceLauncher definition را با کد زیر جایگزین کنید تا نتیجه فعالیت راه اندازی را ثبت و مدیریت کنید:

   commissionDeviceLauncher =
       registerForActivityResult(ActivityResultContracts.StartIntentSenderForResult()) { result ->
         // Commission Device Step 5.
         // The Commission Device activity in GPS has completed.
         val resultCode = result.resultCode
         if (resultCode == Activity.RESULT_OK) {
           Timber.d("CommissionDevice: Success")
           // We now need to capture the device information for the app's fabric.
           // Once this completes, a call is made to the viewModel to persist the information
           // about that device in the app.
           showNewDeviceAlertDialog(result)
         } else {
           viewModel.commissionDeviceFailed(resultCode)
         }
       }    ```
   
   

مرحله 2: اشیاء LiveData را ایجاد کنید

پاسخ تماس موفقیت آمیز API .commissionDevice() IntentSender را فراهم می کند تا از آن برای راه اندازی فعالیت دستگاه کمیسیون در خدمات Google Play استفاده شود. در HomeViewModel ، دو شی LiveData ایجاد می‌کنیم تا نتایج این فراخوانی API را گزارش کنیم:

• commissionDeviceStatus برای ردیابی TaskStatus .
• commissionDeviceIntentSender برای رسیدگی به نتیجه فراخوانی .commissionDevice() . این LiveData Object ActivityLauncher را که به تازگی ایجاد کرده ایم راه اندازی می کند و فعالیت دستگاه کمیسیون GPS را به کاربر نمایش می دهد.

1. در private fun setupObservers() ، نظر // CODELAB: commissionDeviceStatus را با ناظر زیر جایگزین کنید:

   // The current status of the share device action.
   viewModel.commissionDeviceStatus.observe(viewLifecycleOwner) { status ->
     Timber.d("commissionDeviceStatus.observe: status [${status}]")
   }
   

2. سپس، نظر // CODELAB: commissionDeviceIntentSender را با ناظر زیر جایگزین کنید:

   viewModel.commissionDeviceIntentSender.observe(viewLifecycleOwner) { sender ->
     Timber.d(
         "commissionDeviceIntentSender.observe is called with [${intentSenderToString(sender)}]")
     if (sender != null) {
       // Commission Device Step 4: Launch the activity described in the IntentSender that
       // was returned in Step 3 (where the viewModel calls the GPS API to commission
       // the device).
       Timber.d("CommissionDevice: Launch GPS activity to commission device")
       commissionDeviceLauncher.launch(IntentSenderRequest.Builder(sender).build())
       viewModel.consumeCommissionDeviceIntentSender()
     }
   }
   

مرحله 3: با API تماس بگیرید

اکنون که کدی را برای مدیریت جریان API نوشتیم، زمان آن فرا رسیده است که API را فراخوانی کنیم، یک سرویس سفارشی را ارسال کنیم (که در مرحله بعد تعریف خواهیم کرد)، و به اشیاء LiveData خود پست کنیم.

1. HomeViewModel.kt در پوشه java/screens/home/ باز کنید.
2. // CODELAB: commissionDevice commentDevice را با commissionDeviceRequest زیر جایگزین کنید. setCommissioningService AppCommissioningService به یک نمونه CommissioningService متصل می کند که در یک تابع callback برگردانده می شود. وقتی یک سرویس سفارشی را ارسال می‌کنید، Home Mobile SDK ابتدا دستگاه‌ها را به فابریک Google سفارش می‌دهد، سپس بار ورودی را به AppCommissioningService بازگرداند.

   fun commissionDevice(context: Context) {
     _commissionDeviceStatus.postValue(TaskStatus.InProgress)
   
     val commissionDeviceRequest =
         CommissioningRequest.builder()
             .setCommissioningService(ComponentName(context, AppCommissioningService::class.java))
             .build()
   

3. با .getCommissioningClient() و سپس .commissionDevice() تماس بگیرید.

   Matter.getCommissioningClient(context)
       .commissionDevice(commissionDeviceRequest)
   

برای تکمیل عملکرد commissionDevice ما، یک addOnSuccessListener و addOnFailureListener اضافه کنید و به اشیاء LiveData پست کنید:

      .addOnSuccessListener { result ->
        // Communication with fragment is via livedata
        _commissionDeviceIntentSender.postValue(result)
      }
      .addOnFailureListener { error ->
        Timber.e(error)
        _commissionDeviceStatus.postValue(
          TaskStatus.Failed("Failed to to get the IntentSender.", error)
      }
}

پس از استفاده از فرستنده، consumeCommissionDeviceIntentSender() باید فراخوانی شود تا از دریافت مجدد فرستنده پس از تغییر پیکربندی جلوگیری شود.

  /**
   * Consumes the value in [_commissionDeviceIntentSender] and sets it back to null. Needs to be
   * called to avoid re-processing the IntentSender after a configuration change (where the LiveData
   * is re-posted).
   */
  fun consumeCommissionDeviceIntentSender() {
    _commissionDeviceIntentSender.postValue(null)
  }

5. یک CommissioningService ایجاد کنید

در تابع commissionDevice() درخواست کردیم که یک CommissioningService از API CommissioningClient دریافت کنیم. در این جریان، CommissioningClient API ابتدا دستگاه‌ها را به فابریک Android محلی سفارش می‌دهد، سپس یک callback شامل شی 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())
   }
 }

مرحله 1: AppCommissioningService سفارشی را کاوش کنید

برای کمک به شما برای شروع، ما قبلا ساختار کلاس پایه را برای CommissioningService سفارشی خود تعریف کرده ایم. در اینجا یک نمای کلی از عملکرد سرویس ارائه شده است. برای پیگیری، AppCommissioningService در java/commissioning باز کنید.

ما موارد وارداتی زیر را برای APIهای Home Mobile SDK اضافه کرده‌ایم:

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 ( connectedhomeip ) می شود:

import com.google.home_sample_app_for_matter.chip.ChipClient

در نهایت، این سرویس شامل واردات برای پشتیبانی از کوروتین های Hilt و Kotlin است.

در مرحله بعد، سازنده را ایجاد می‌کنیم و چند چیز را تنظیم می‌کنیم، از جمله commissioningServiceDelegate ، که از آن استفاده می‌کنیم تا به سرویس‌های Google Play اطلاع دهیم که راه‌اندازی کامل شد.

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

اکنون زمان اضافه کردن توابع راه اندازی است.

مرحله 2: روی CommissioningRequested لغو شود

برای سفارش دستگاه به بافت توسعه برنامه، مراحل زیر را انجام دهید:

1. AppCommissioningService در java/commissioning باز کنید.
2. تابع onCommissioningRequested() را پیدا کنید. ما یک پیام گزارش ارائه کرده‌ایم که CommissioningRequestMetadata را چاپ می‌کند. کامنت // CODELAB: onCommissioningRequested() جایگزین کنید تا سرفصل serviceScope را شروع کنید و deviceId دریافت کنید.

   // Perform commissioning on custom fabric for the sample app.
   serviceScope.launch {
     val deviceId = devicesRepository.incrementAndReturnLastDeviceId()
   

3. راه اندازی را انجام دهید. برای این مرحله، می‌توانیم اطلاعات دستگاه را که در شی CommissioningRequestMetadata بازگردانده شده است، ارسال کنیم. ChipClient از این اطلاعات فراداده برای ایجاد یک کانال امن بین برنامه GHSA for Matter و دستگاه شما استفاده می کند.

   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)
   

4. از commissioningServiceDelegate استفاده کنید تا به خدمات Google Play اطلاع دهید که راه اندازی کامل شده است. در .sendCommissioningComplete() CommissioningCompleteMetadata را ارسال کنید.

     Timber.d("Commissioning: Calling commissioningServiceDelegate.sendCommissioningComplete()")
     commissioningServiceDelegate
         .sendCommissioningComplete(
             CommissioningCompleteMetadata.builder().setToken(deviceId.toString()).build())
         .addOnSuccessListener {
             Timber.d("Commissioning: OnSuccess for commissioningServiceDelegate.sendCommissioningComplete()")
         }
         .addOnFailureListener { ex -> 
           Timber.e(ex, "Commissioning: Failed to send commissioning complete.", ex)
         }
   }
   

برنامه را اجرا کنید

اکنون که همه کدهای مورد نیاز برای راه اندازی بافت محلی ما در دسترس هستند، زمان آزمایش آن فرا رسیده است. دستگاه اندروید خود را انتخاب کنید و برنامه را اجرا کنید. از صفحه اصلی، روی Add Device ضربه بزنید و مراحل راه اندازی دستگاه خود را تکمیل کنید.

وقتی راه اندازی کامل شد، دستگاه شما اکنون در دو فابریک شرکت می کند: فابریک Local Android و پارچه توسعه محلی شما. هر پارچه دارای مجموعه ای از اعتبارنامه ها و یک شناسه پارچه 64 بیتی منحصر به فرد است.

6. دستگاه ها را کنترل کنید

راه اندازی یک پارچه توسعه به شما امکان می دهد از کتابخانه های موجود در مخزن Matter ( connectedhomeip ) برای کنترل دستگاه ها از برنامه نمونه استفاده کنید.

ما چند کلاس کمکی ایجاد کرده‌ایم تا دسترسی به خوشه‌های دستگاه و ارسال دستورات را آسان‌تر کنیم. برای کسب اطلاعات بیشتر، ClustersHelper در java/clusters باز کنید. این کمک کننده Singleton کتابخانه های زیر را برای دسترسی به اطلاعات دستگاه وارد می کند:

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 مقداردهی اولیه می شود، سرویس های Cluster به پیام های دریافتی گوش می دهند. هنگامی که یک دستگاه راه اندازی می شود، مشتریان 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")
       }
   

این تابع از DeviceFragment فراخوانی می شود:

// Change the on/off state of the device
binding.onoffSwitch.setOnClickListener {
  val isOn = binding.onoffSwitch.isChecked
  viewModel.updateDeviceStateOn(selectedDeviceViewModel.selectedDeviceLiveData.value!!, isOn)
}

برنامه را اجرا کنید

برای بارگیری مجدد به‌روزرسانی‌ها، برنامه را اجرا کنید. از صفحه اصلی، دستگاه خود را روشن و خاموش کنید.

7. دستگاه ها را با اکوسیستم های دیگر به اشتراک بگذارید

به اشتراک گذاری یک دستگاه در مشخصات Matter به عنوان جریان چند مدیره گفته می شود.

در مراحل قبلی متوجه شدیم که Home Mobile SDK این امکان را فراهم می‌کند که دستگاه‌ها را به Fabric Android Local و همچنین به یک پارچه توسعه برای برنامه نمونه سفارش دهید. این نمونه‌ای از جریان چند مدیر است که در آن دستگاه‌ها می‌توانند به بیش از یک پارچه راه‌اندازی شوند.

اکنون، ممکن است بخواهید دستگاه‌ها را با پارچه‌های بیشتری به اشتراک بگذارید، به‌خصوص اگر این خانواده‌ای است که در آن افراد ترجیحات خاص خود را در مورد برنامه‌ها و پلتفرم‌ها دارند.

Home Mobile SDK این قابلیت را در ShareDeviceRequest API فراهم می کند و به شما امکان می دهد:

1. یک پنجره راه اندازی موقت برای دستگاه ها باز کنید.
2. وضعیت دستگاه های خود را تغییر دهید و آنها را به پارچه دیگری راه اندازی کنید.
3. دستگاه های خود را از برنامه ها و اکوسیستم های دیگر کنترل کنید.

در مراحل بعدی، از Home Mobile SDK برای اشتراک‌گذاری دستگاه‌ها استفاده خواهید کرد.

مرحله 1: یک راه‌انداز فعالیت GPS ایجاد کنید

مشابه راه‌اندازی فعالیت راه‌اندازی که هنگام سفارش‌دادن به یک بافت توسعه ایجاد کردیم، یک راه‌انداز فعالیت اشتراک دستگاه برای مدیریت IntentSender از API CommissioningClient ایجاد کرده‌ایم.

1. DeviceFragment در پوشه java/screens/device/ باز کنید.
2. // CODELAB: shareDeviceLauncher definition با کد زیر جایگزین کنید تا نتیجه فعالیت .shareDevice() ثبت و مدیریت شود:

   shareDeviceLauncher =
       registerForActivityResult(ActivityResultContracts.StartIntentSenderForResult()) { result ->
         // Share Device Step 5.
         // The Share Device activity in GPS (step 4) has completed.
         val resultCode = result.resultCode
         if (resultCode == RESULT_OK) {
           Timber.d("ShareDevice: Success")
           viewModel.shareDeviceSucceeded(selectedDeviceViewModel.selectedDeviceLiveData.value!!)
         } else {
           viewModel.shareDeviceFailed(
               selectedDeviceViewModel.selectedDeviceLiveData.value!!, resultCode)
         }
       }
   

مرحله 2: اشیاء LiveData را بررسی کنید

پاسخ به تماس موفقیت آمیز .shareDevice() API IntentSender را فراهم می کند تا از آن برای راه اندازی Share Device Activity در خدمات Google Play استفاده شود. در DeviceViewModel ، دو شی LiveData ایجاد کرده‌ایم تا نتایج این فراخوانی API را گزارش کنیم:

• _shareDeviceStatus برای ردیابی وضعیت TaskStatus .

  // The current status of the share device action.
  viewModel.shareDeviceStatus.observe(viewLifecycleOwner) { status ->
    val isButtonEnabled = status !is InProgress
    updateShareDeviceButton(isButtonEnabled)
    if (status is TaskStatus.Failed) {
      showAlertDialog(errorAlertDialog, status.message, status.cause!!.toString())
    }
  }
  

• _shareDeviceIntentSender برای رسیدگی به نتیجه فراخوانی .sharedevice() .

viewModel.shareDeviceIntentSender.observe(viewLifecycleOwner) { sender -> Timber.d("shareDeviceIntentSender.observe با [${intentSenderToString(sender)}] فراخوانی می شود") if (فرستنده != null) { // اشتراک گذاری دستگاه مرحله 4: راه اندازی فعالیتی که در IntentSender توضیح داده شده است که // در مرحله 3 بازگردانده شد (جایی که viewModel API GPS را برای راه اندازی // دستگاه فراخوانی می کند). Timber.d("ShareDevice: راه اندازی فعالیت GPS برای اشتراک گذاری دستگاه") shareDeviceLauncher.launch(IntentSenderRequest.Builder(sender).build()) viewModel.consumeShareDeviceIntentSender() } } ```

در مراحل بعدی، از این اشیاء LiveData در فراخوانی API .shareDevice() خود استفاده خواهیم کرد.

مرحله 3: با API تماس بگیرید

اکنون زمان شروع یک کار اشتراک گذاری دستگاه است.

1. DeviceViewModel.kt در پوشه java/screens/device/ باز کنید.
2. تابع shareDevice() را پیدا کنید. // CODELAB: shareDevice را با ShareDeviceRequest جایگزین کنید. DeviceDescriptor اطلاعات خاصی در مورد دستگاه مانند شناسه فروشنده، شناسه محصول و نوع دستگاه ارائه می دهد. در این مثال، ما مقادیر را سخت کد می کنیم.

     Timber.d("ShareDevice: Setting up the IntentSender")
     val shareDeviceRequest =
         ShareDeviceRequest.builder()
             .setDeviceDescriptor(DeviceDescriptor.builder().build())
             .setDeviceName("temp device name")
   

3. CommissioningWindow و پارامترها را تنظیم کنید. در این مرحله پنجره راه اندازی موقت روی دستگاه باز می شود.

             .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() تماس بگیرید، فقط این بار از API .shareDevice() استفاده کنید. پاسخ تماس موفقیت آمیز API commissioningClient.shareDevice() IntentSender را فراهم می کند تا از آن برای راه اندازی Share Device Activity در خدمات Google Play استفاده شود.

   Matter.getCommissioningClient(activity)
       .shareDevice(shareDeviceRequest)
   

5. برای تکمیل عملکرد shareDevice ، یک addOnSuccessListener و addOnFailureListener اضافه کنید و به اشیاء LiveData پست کنید:

         .addOnSuccessListener { result ->
           Timber.d("ShareDevice: Success getting the IntentSender: result [${result}]")
           // Communication with fragment is via livedata
           _backgroundWorkAlertDialogAction.postValue(BackgroundWorkAlertDialogAction.Hide)
           _shareDeviceIntentSender.postValue(result)
         }
         .addOnFailureListener { error ->
           Timber.e(error)
           _backgroundWorkAlertDialogAction.postValue(BackgroundWorkAlertDialogAction.Hide)
           _shareDeviceStatus.postValue(
               TaskStatus.Failed("Setting up the IntentSender failed", error))
         }
   

پس از استفاده از فرستنده، consumeShareDeviceIntentSender باید فراخوانی شود تا پس از تغییر پیکربندی، دوباره فرستنده دریافت نشود.

  /**
   * Consumes the value in [_shareDeviceIntentSender] and sets it back to null. Needs to be called
   * to avoid re-processing an IntentSender after a configuration change where the LiveData is
   * re-posted.
   */
  fun consumeShareDeviceIntentSender() {
    _shareDeviceIntentSender.postValue(null)
  }

برنامه را اجرا کنید

برای به اشتراک گذاشتن دستگاه Matter خود با سایر اکوسیستم ها، باید پلتفرم دیگری را روی دستگاه اندروید خود نصب کنید. ما نمونه دیگری از برنامه نمونه ایجاد کرده‌ایم که می‌توانید از آن به‌عنوان مأمور هدف استفاده کنید.

file_download دانلود اپلیکیشن Target Commissioner

هنگامی که کمیسیونر هدف را روی دستگاه Android خود نصب کردید، بررسی کنید که می توانید دستگاه Matter خود را به اشتراک بگذارید. برنامه کمیسیونر هدف دارای برچسب GHSAFM-TC است.

دستگاه های شما اکنون می توانند در سه پارچه شرکت کنند:

1. پارچه اندروید محلی.
2. پارچه توسعه شما (این برنامه).
3. این پارچه سوم که شما به تازگی دستگاه را با آن به اشتراک گذاشته اید.

8. مراحل بعدی

تبریک می گویم

تبریک می گوییم، شما این Codelab را با موفقیت به پایان رساندید و یاد گرفتید که چگونه دستگاه ها را با استفاده از Home Mobile SDK راه اندازی و به اشتراک بگذارید.

اگر با برنامه نمونه مشکل دارید، مراحل را برای تأیید محیط خود تکمیل کنید:

• ماژول‌ها و خدمات موضوع را تأیید کنید

اگر در مورد استفاده از برنامه نمونه یا کشف یک اشکال کد سؤالی دارید، می‌توانید مشکلات را به ردیاب مشکل در مخزن GitHub ارسال کنید:

• نمونه-برنامه-برای-ماتر-اندروید/مسائل

برای دریافت راهنمایی رسمی از Google در مورد سؤالات فنی، از تالار گفتمان توسعه دهندگان خانه هوشمند استفاده کنید:

• انجمن توسعه دهندگان خانه هوشمند

برای دریافت پشتیبانی فنی از انجمن، از برچسب google-smart-home در Stack Overflow استفاده کنید:

• Stack Overflow: google-smart-home