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 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 است:
شما از این فایل ZIP codelab
برای ساختن یک نمونه کار استفاده خواهید کرد.
نسخه های Codelab
شاخه codelab
با نسخه 1.2.2 برنامه نمونه برچسب گذاری شده است. برای مقایسه بهروزرسانیهای خود در طول هر مرحله، میتوانید کد منبع تکمیلشده این نسخه را دانلود کنید.
اگر میخواهید مخزن 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 برای سفارش دستگاه به فابریک گوگل استفاده می کند.
- فرآیند راه اندازی با تابع
commissionDevice()
شروع می شود. ابتدا یکCommissioningRequest
تعریف می شود. با این پیکربندی پیشفرض، دستگاهها فقط به فابریک Local Android راهاندازی میشوند. -
Matter
نقطه ورود برای Home Mobile SDK است. در تماس بعدی،.getCommissioningClient
باthis
(Activity) یک CommissioningClient دریافت می کند. -
.commissionDevice()
CommissioningRequest
می پذیرد. - و در نهایت،
.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 ایجاد کنیم.
-
HomeFragment
در پوشهjava/screens/home/
باز کنید. - نظر
// CODELAB: commissionDeviceLauncher declaration
با اعلان زیر جایگزین کنید:// The ActivityResult launcher that launches the "commissionDevice" activity in Google Play // Services. private lateinit var commissionDeviceLauncher: ActivityResultLauncher<IntentSenderRequest>
-
// 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 ObjectActivityLauncher
را که به تازگی ایجاد کرده ایم راه اندازی می کند و فعالیت دستگاه کمیسیون GPS را به کاربر نمایش می دهد.
- در
private fun setupObservers()
، نظر// CODELAB: commissionDeviceStatus
را با ناظر زیر جایگزین کنید:// The current status of the share device action. viewModel.commissionDeviceStatus.observe(viewLifecycleOwner) { status -> Timber.d("commissionDeviceStatus.observe: status [${status}]") }
- سپس، نظر
// 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 خود پست کنیم.
-
HomeViewModel.kt
در پوشهjava/screens/home/
باز کنید. -
// 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()
- با
.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 لغو شود
برای سفارش دستگاه به بافت توسعه برنامه، مراحل زیر را انجام دهید:
-
AppCommissioningService
درjava/commissioning
باز کنید. - تابع
onCommissioningRequested()
را پیدا کنید. ما یک پیام گزارش ارائه کردهایم کهCommissioningRequestMetadata
را چاپ میکند. کامنت// CODELAB: onCommissioningRequested()
جایگزین کنید تا سرفصلserviceScope
را شروع کنید وdeviceId
دریافت کنید.// Perform commissioning on custom fabric for the sample app. serviceScope.launch { val deviceId = devicesRepository.incrementAndReturnLastDeviceId()
- راه اندازی را انجام دهید. برای این مرحله، میتوانیم اطلاعات دستگاه را که در شی 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)
- از
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
برای جابجایی یک دستگاه استفاده خواهید کرد.
- در
java/screens/device
بهDeviceViewModel
بروید. - تابع
updateDeviceStateOn
را پیدا کنید. -
// 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 فراهم می کند و به شما امکان می دهد:
- یک پنجره راه اندازی موقت برای دستگاه ها باز کنید.
- وضعیت دستگاه های خود را تغییر دهید و آنها را به پارچه دیگری راه اندازی کنید.
- دستگاه های خود را از برنامه ها و اکوسیستم های دیگر کنترل کنید.
در مراحل بعدی، از Home Mobile SDK برای اشتراکگذاری دستگاهها استفاده خواهید کرد.
مرحله 1: یک راهانداز فعالیت GPS ایجاد کنید
مشابه راهاندازی فعالیت راهاندازی که هنگام سفارشدادن به یک بافت توسعه ایجاد کردیم، یک راهانداز فعالیت اشتراک دستگاه برای مدیریت IntentSender
از API CommissioningClient ایجاد کردهایم.
-
DeviceFragment
در پوشهjava/screens/device/
باز کنید. -
// 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 تماس بگیرید
اکنون زمان شروع یک کار اشتراک گذاری دستگاه است.
-
DeviceViewModel.kt
در پوشهjava/screens/device/
باز کنید. - تابع
shareDevice()
را پیدا کنید.// CODELAB: shareDevice
را با ShareDeviceRequest جایگزین کنید.DeviceDescriptor
اطلاعات خاصی در مورد دستگاه مانند شناسه فروشنده، شناسه محصول و نوع دستگاه ارائه می دهد. در این مثال، ما مقادیر را سخت کد می کنیم.Timber.d("ShareDevice: Setting up the IntentSender") val shareDeviceRequest = ShareDeviceRequest.builder() .setDeviceDescriptor(DeviceDescriptor.builder().build()) .setDeviceName("temp device name")
- CommissioningWindow و پارامترها را تنظیم کنید. در این مرحله پنجره راه اندازی موقت روی دستگاه باز می شود.
.setCommissioningWindow( CommissioningWindow.builder() .setDiscriminator(Discriminator.forLongValue(DISCRIMINATOR)) .setPasscode(SETUP_PIN_CODE) .setWindowOpenMillis(SystemClock.elapsedRealtime()) .setDurationSeconds(OPEN_COMMISSIONING_WINDOW_DURATION_SECONDS.toLong()) .build()) .build()
- با
.getCommissioningClient()
تماس بگیرید، فقط این بار از API.shareDevice()
استفاده کنید. پاسخ تماس موفقیت آمیز APIcommissioningClient.shareDevice()
IntentSender را فراهم می کند تا از آن برای راه اندازی Share Device Activity در خدمات Google Play استفاده شود.Matter.getCommissioningClient(activity) .shareDevice(shareDeviceRequest)
- برای تکمیل عملکرد
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 خود با سایر اکوسیستم ها، باید پلتفرم دیگری را روی دستگاه اندروید خود نصب کنید. ما نمونه دیگری از برنامه نمونه ایجاد کردهایم که میتوانید از آن بهعنوان مأمور هدف استفاده کنید.
هنگامی که کمیسیونر هدف را روی دستگاه Android خود نصب کردید، بررسی کنید که می توانید دستگاه Matter خود را به اشتراک بگذارید. برنامه کمیسیونر هدف دارای برچسب GHSAFM-TC است.
دستگاه های شما اکنون می توانند در سه پارچه شرکت کنند:
- پارچه اندروید محلی.
- پارچه توسعه شما (این برنامه).
- این پارچه سوم که شما به تازگی دستگاه را با آن به اشتراک گذاشته اید.
8. مراحل بعدی
تبریک می گویم
تبریک می گوییم، شما این Codelab را با موفقیت به پایان رساندید و یاد گرفتید که چگونه دستگاه ها را با استفاده از Home Mobile SDK راه اندازی و به اشتراک بگذارید.
اگر با برنامه نمونه مشکل دارید، مراحل را برای تأیید محیط خود تکمیل کنید:
اگر در مورد استفاده از برنامه نمونه یا کشف یک اشکال کد سؤالی دارید، میتوانید مشکلات را به ردیاب مشکل در مخزن GitHub ارسال کنید:
برای دریافت راهنمایی رسمی از Google در مورد سؤالات فنی، از تالار گفتمان توسعه دهندگان خانه هوشمند استفاده کنید:
برای دریافت پشتیبانی فنی از انجمن، از برچسب google-smart-home
در Stack Overflow استفاده کنید: