یک برنامه اندروید برای 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 زیر را پیاده سازی می کنیم:

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

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

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

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

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

برنامه شروع کد لبه در شعبه codelab قرار دارد. برای شروع کار با کد منبع کد، می توانید فایل ZIP را دانلود کنید.

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

نسخه های Codelab

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

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

وابستگی ها

ما شما را از طریق کد منبع مورد نیاز برای اشتراک‌گذاری و راه‌اندازی دستگاه‌ها راهنمایی می‌کنیم، اما ممکن است قبل از شروع، آگاهی از وابستگی‌های زیر مفید باشد. توجه داشته باشید که این وابستگی ها در فایل libs.versions.toml اعلام شده و کاربرد آنها در فایل build.gradle.kts مشخص شده است.

کد منبع

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

برای این کد لبه، ما قابلیت 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 : شامل تماس‌های اشتراک‌گذاری 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 استفاده کنید:

val 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. HomeScreen در پوشه java/com/google/homesampleapp/screens/home/ باز کنید.
  2. نظر // CODELAB: commissionDeviceLauncher definition با کد زیر جایگزین کنید تا نتیجه Activity راه اندازی را ثبت و مدیریت کنید: 
    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)
    }
  }

مرحله 2: اقدام دستگاه کمیسیون را فعال کنید

در این مرحله، کاربر با کلیک بر روی دکمه "+" در سمت راست پایین صفحه اصلی، اقدام "Commission Device" را آغاز می کند. سپس یک تماس با commissionDevice() برقرار می شود.

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

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

  1. هنوز در HomeScreen.kt در پوشه java/com/google/homesampleapp/screens/home .
  2. // CODELAB: commissionDevice با commissionDeviceRequest زیر جایگزین کنید. setCommissioningService AppCommissioningService به یک نمونه CommissioningService متصل می کند که در یک تابع callback برگردانده می شود. وقتی یک سرویس سفارشی را ارائه می‌کنید، 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() درخواست کردیم که یک 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.homesampleapp.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 و دستگاه شما استفاده می کند. 
    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 اطلاع دهید که راه اندازی کامل شده است. در .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")
    }
}

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

اکنون که همه کدهای مورد نیاز برای راه اندازی بافت محلی ما در دسترس هستند، زمان آزمایش آن فرا رسیده است. دستگاه اندروید خود را انتخاب کنید و برنامه را اجرا کنید. از صفحه اصلی، روی 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. به DeviceViewModel در java/screens/device بروید.
  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 این امکان را فراهم می‌کند که دستگاه‌ها را به Fabric Android Local و همچنین به یک پارچه توسعه برای برنامه نمونه سفارش دهید. این نمونه‌ای از جریان چند مدیر است که در آن دستگاه‌ها می‌توانند به بیش از یک پارچه راه‌اندازی شوند.

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

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

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

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

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

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

  1. DeviceScreen در پوشه java/com/google/homesampleapp/screens/device/ باز کنید.
  2. برای ثبت و مدیریت نتیجه فعالیت .shareDevice() کامنت // CODELAB: shareDeviceLauncher definition با کد زیر جایگزین کنید: 
    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)
  }
}

مرحله 2: اقدام اشتراک دستگاه را فعال کنید

در این مرحله، کاربر با کلیک بر روی دکمه «اشتراک‌گذاری» در صفحه دستگاه، اقدام «اشتراک‌گذاری دستگاه» را راه‌اندازی می‌کند. سپس با deviceViewModel تماس گرفته می شود تا پنجره جفت سازی برای اشتراک گذاری دستگاه باز شود. 

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

پس از باز کردن موفقیت آمیز پنجره جداسازی، deviceViewModel این واقعیت را به UI منتقل می کند. ارتباط بین ViewModel و UI از طریق اشیاء 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)

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

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

  1. DeviceScreen.kt را در پوشه java/com/google/homesampleapp/screens/device/ باز کنید.
  2. تابع shareDevice() را پیدا کنید. // CODELAB: shareDevice با ShareDeviceRequest جایگزین کنید. DeviceDescriptor اطلاعات خاصی در مورد دستگاه مانند شناسه فروشنده، شناسه محصول و نوع دستگاه ارائه می دهد. در این مثال، ما مقادیر را سخت کد می کنیم. 
    val shareDeviceRequest =
  ShareDeviceRequest.builder()
    .setDeviceDescriptor(DeviceDescriptor.builder().build())
    .setDeviceName("GHSAFM 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() استفاده کنید. 
    Matter.getCommissioningClient(context)
    .shareDevice(shareDeviceRequest)

پاسخ تماس موفقیت آمیز API commissioningClient.shareDevice() IntentSender را فراهم می کند تا از آن برای راه اندازی Share Device Activity در خدمات Google Play استفاده شود.

  1. برای تکمیل عملکرد shareDevice ، یک addOnSuccessListener و addOnFailureListener اضافه کنید. در صورت موفقیت، launch در shareDeviceLauncher فراخوانی می شود تا فعالیت GPS را برای اشتراک گذاری دستگاه راه اندازی کند. 
        .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 خود نصب کردید، بررسی کنید که می توانید دستگاه Matter خود را به اشتراک بگذارید. برنامه کمیسیونر هدف دارای برچسب GHSAFM-TC است.

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

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

8. مراحل بعدی

تبریک میگم

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

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

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

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

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