בניית אפליקציה ל-Android

1. היי!

תקן Matter פותח במטרה לאחד את תקני IoT, והוא מחבר מכשירים לבית חכם במגוון סביבות עסקיות, כמו Google Home, Zigbee, Bluetooth Mesh, Z-Wave ועוד.

המכשירים הניידים הם נקודת אינטראקציה מרכזית עם מכשירים לבית חכם. רוצה ליצור אפליקציות משלך ל-Android שיתמכו במכשירים בתקן Matter? אנחנו יכולים לעזור לך להתחיל במהירות.

באפליקציה לדוגמה של Google Home לתקן Matter (GHSA for Matter) מוצגים ממשקי ה-API של Home Mobile SDK, שמאפשרים למשתמשים להזמין מכשירים ולשתף אותם. אתם יכולים גם להשתמש באפליקציה לדוגמה ככלי למידה שעוזר לכם להבין טוב יותר מושגים מרכזיים בתקן Matter, וגם ככלי לניפוי באגים ולפתרון בעיות באינטראקציות עם מכשירים בתקן Matter.

הפעולות שתבצעו:

בשיעור ה-Codelab הזה תוכלו להוריד את קוד המקור של האפליקציה לדוגמה וללמוד איך להשתמש ב-Home Mobile SDK כדי להזמין מכשירים ולשתף אותם. בנוסף, נלמד איך להשתמש בספריות הזמנה ואשכולות ממאגר התוכן (connectedhomeip).

אחרי שתורידו את האפליקציה לדוגמה, נבדוק את קוד המקור ב-Android Studio ונטמיע את ממשקי ה-API של Home Mobile SDK:

בנוסף, נסביר על הזמנת מושגים, על בדים בתקן Matter, ואיך לשלוט במכשירים בתקן Matter.

מה הדרישות כדי להצטרף לתוכנית?

לפני שמתחילים, חשוב לבצע את השלבים הבאים:

אין צורך ב-Hub, למשל Google Nest Hub (דור שני), כדי להזמין מכשירים ולשלוט בהם באמצעות האפליקציה לדוגמה.

2. להגדרה

האפליקציה לתחילת העבודה ב-Codelab ממוקמת בהסתעפות codelab. כדי להתחיל לעבוד עם קוד המקור של Codelab, אפשר להוריד את קובץ ה-ZIP.

אפשר להשתמש בקובץ ה-ZIP הזה בגודל codelab כדי ליצור דוגמה תקינה.

גרסאות Codelab

ההסתעפות codelab מתויגת בגרסה 2.0.0 של האפליקציה לדוגמה. כדי להשוות בין העדכונים בזמן העבודה על כל שלב, אפשר להוריד את קוד המקור שמוכן לגרסה הזו.

אם רוצים לשכפל את מאגר GitHub, פועלים לפי ההוראות בקובץ README לדוגמה.

יחסי תלות

נדריך אותך לגבי קוד המקור הנדרש לשיתוף מכשירים ולביצוע רכישות שלהם, אבל כדאי להיות מודעים ליחסי התלות הבאים לפני שמתחילים. שימו לב שיחסי התלות האלה מוצהרים בקובץ libs.versions.toml ומשתמשים בהם שצוינו בקובץ build.gradle.kts

קוד מקור

ממשק המשתמש ורוב הפונקציונליות כבר נוצרו עבורכם.

במסגרת ה-Codelab הזה, נוסיף את הפונקציונליות של Matter לקבצים הבאים:

  • java/commissioning/AppCommissioningService: מאפשרת להזמין מכשירים למארג הפיתוח
  • java/screens/home/HomeScreen ו-java/screens/home/HomeViewModel.kt: כולל את פונקציונליות ההזמנה של Home Mobile SDK
  • java/screens/device/DeviceScreen ו-java/screens/device/DeviceViewModel: כולל קריאות ל-Share Device API

כל קובץ מקבל תגובה עם בלוק הקוד שתשנה. לדוגמה:

// CODELAB: add commissioningFunction()

כך תוכלו לאתר במהירות את הקטע התואם ב-Codelab.

3. עמלה ל-Google

כדי לשלוט במכשירים ולאפשר להם לתקשר זה עם זה באותו המרקם, צריך להזמין את הנציב. במקרה הזה, האפליקציה לדוגמה הזו – אפליקציית Google Home לדוגמה ל-Matter.

חשוב להבין את המושגים הבאים לגבי הזמנת עניינים:

  • בדים מאפשרים למכשירים לתקשר זה עם זה.
  • למוצרי בדים יש קבוצה משותפת של פרטי כניסה ייחודיים.
  • מערכות אקולוגיות אחראיות להנפקת אישורי בסיס מהימנים, הקצאת מזהי בד והקצאת מזהי צמתים ייחודיים. מערכת אקולוגית היא השירות העורפי של עמלה. לדוגמה, תרשים הבית של הסביבה העסקית של Google Home.
  • ניתן להזמין מכשירים ליותר מיחידה אחת (תכונה של אדמינים מרובים).

כדי להזמין מכשיר, צריך להשתמש ב-CommissioningClient API. קריאה אל .commissionDevice() מחזירה IntentSender, שמפעיל את הפעילות הנכונה ב-Google Play Services:

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

בקטעים הבאים נפרט את הקוד המינימלי שנדרש כדי להזמין מכשירים לפורמט של Google.

שלב 1: מרכז האפליקציות

כדי לטפל ב-IntentSender מ-CommissioningClient, אפשר להשתמש ב-ActivityActivityLauncher

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 כדי להזמין מכשיר למרקם של Google.

  1. תהליך הביצוע מתחיל בפונקציה commissionDevice(). קודם כול, מוגדר CommissioningRequest. עם תצורת ברירת המחדל הזו, המכשירים מחויבים רק למרקם המקומי של Android.
  2. Matter היא נקודת הכניסה ל-Home Mobile SDK. בשיחה הבאה, .getCommissioningClient יקבל 'עמלה' מאת this (פעילות).
  3. .commissionDevice() מקבל את CommissioningRequest.
  4. ולסיום, .addOnSuccessListener נקרא כדי לעבד את CommissioningResult ולהשיק את פעילות מכשיר העמלה של Google Play Services (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 בתקן Matter.

4. עמלה למארג פיתוח

ניתן להזמין מכשירים ליותר מבד אחד. כדי לנהל התאמות מהימנות, במכשירים נשמרים FabricTable עם חברים שונים ב-FabricInfo, לדוגמה:

  • זיהוי בד
  • מזהה הצומת הוקצה למכשיר על ידי הבד
  • מזהה הספק
  • מזהה בד
  • פרטי כניסה תפעוליים של המכשיר

מנהל הדומיין המנהלי (ADM) מגדיר פרטי כניסה מבד. בתרחיש הקודם, Google Play Services היא הסביבה העסקית שפועלת כרשות אישורים מהימנה ברמה הבסיסית (CA). כאשר מקצים מכשירים למרקם של Android המקומי, כל מכשיר כולל את אותה קבוצה של פרטי כניסה מבד, ואותם קבוצות של רשויות אישורים.

שירותי עמלות בהתאמה אישית

כדי לבצע הזמנה עבור המארג של Android המקומי, השתמשנו בפרמטרים שמוגדרים כברירת מחדל כדי ליצור את CommissioningRequest ב- CommissioningClient API:

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 כדי לנהל את זרימת ה-API.

שלב 1: יצירת מרכז אפליקציות לפעילות GPS

קודם כול ניצור מרכז אפליקציות שיטפל ב-IntentSender מ- CommissioningClient API.

  1. פותחים את HomeScreen בתיקייה java/screens/home/.
  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)
    }
  }

שלב 2: הפעלת פעולת העמלה על המכשיר

בשלב הזה, המשתמש מפעיל את הפעולה 'מכשיר העמלה' על ידי לחיצה על הלחצן '+' בפינה השמאלית התחתונה של מסך הבית. לאחר מכן תבוצע שיחה אל commissionDevice().

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

שלב 3: קוראים ל-API

  1. עדיין נמצאים ב-HomeScreen.kt בתיקייה java/screens/home/.
  2. החליפו את התגובה // CODELAB: commissionDevice בcommissionDeviceRequest הבאה. הפונקציה setCommissioningService מחייבת את AppCommissioningService למופע של CommissioningService, שמוחזר בפונקציית קריאה חוזרת. אחרי שמעבירים שירות מותאם אישית, Home Mobile SDK יקצה קודם מכשירים למרקם המקומי של Android, ולאחר מכן ישלח את המטען הייעודי (payload) שנשלח בחזרה אל 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. יצירת CommissioningService

בפונקציה commissionDevice() ביקשנו לקבל CommissioningService מ-CommissioningClient API. בתהליך הזה, ה-API של CommissioningClient מזמין תחילה מכשירים למרקם המקומי של 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())
   }
 }

שלב 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 כולל גם ספריות ממאגר Mater (connectedhomeip):

import com.google.home_sample_app_for_matter.chip.ChipClient

לבסוף, השירות כולל ייבוא תמיכה ב-Hilt ובקורוטינים של Kotlin.

בשלב הבא ניצור את ה-builder ונגדיר כמה דברים, כולל commissioningServiceDelegate, שבו נשתמש כדי להודיע ל-Google Play Services כשההזמנה תושלם.

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

זה הזמן להוסיף את פונקציות הביצוע.

שלב 2: ביטול onCommissioningRequested

כדי להזמין מכשירים למארג הפיתוח של האפליקציה, יש להשלים את השלבים הבאים:

  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 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. שליטה במכשירים

הזמנה למארג פיתוח מאפשרת לכם להשתמש בספריות ממאגר החומר (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)
              }
            })
  }
}

החלפת מצב במכשיר

אחרי שמזמינים מכשיר, המטען הייעודי (payload) שהוחזר ב-CommissioningResult מתווסף ל-DataStore. כך האפליקציה שלנו יכולה לגשת למידע מהמכשיר שיכול לשמש לשליחת פקודות.

אפליקציות בתקן Matter מבוססות על אירועים. כשהמקבץ של תקן Matter מופעל, שירותי האשכול מאזינים להודעות נכנסות. לאחר הזמנת המכשיר, לקוחות בתקן Matter שולחים פקודות בערוץ התפעול המאובטח שנוצר במהלך הזמנת המכשיר.

החבילות במכשיר מאומתות, מפוענחות ונשלחות באמצעות קריאה חוזרת (callback). פונקציות הקריאה החוזרות (callback) כוללות את ערכי 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 מאפשר לבצע הזמנה של מכשירים לבד של Android המקומי וגם למארג פיתוח של האפליקציה לדוגמה. זו דוגמה לתהליך של אדמינים מרובים, שבו ניתן להזמין מכשירים ליותר מבד אחד.

עכשיו יכול להיות שתרצו לשתף מכשירים עם מספר גדול יותר של בדים, במיוחד אם מדובר בבית שבו יש לאנשים העדפות משלהם בכל מה שקשור לאפליקציות ולפלטפורמות.

ה-Home Mobile SDK מספק את הפונקציונליות הזו ב-ShareDeviceRequest API ומאפשר לך:

  1. פתיחת חלון זמני להזמנה עבור מכשירים.
  2. אפשר לשנות את המצב של המכשירים כדי שאפשר יהיה להזמין אותם למרקם אחר.
  3. שליטה במכשירים מאפליקציות אחרות ומסביבות עסקיות אחרות.

בשלבים הבאים צריך להשתמש ב-Home Mobile SDK כדי לשתף מכשירים.

שלב 1: יצירת מרכז אפליקציות לפעילות GPS

בדומה ל-Commiting Activity Launcher שיצרנו כשהזמננו למארג פיתוח, יצרנו מרכז אפליקציות לשיתוף מכשירים כדי לטפל ב-IntentSender מ- CommissioningClient API.

  1. פותחים את DeviceScreen בתיקייה java/screens/device/.
  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)
  }
}

שלב 2: מפעילים את פעולת שיתוף המכשיר

בשלב הזה, המשתמש מפעיל את הפעולה 'שיתוף מכשיר' על ידי לחיצה על הלחצן 'שיתוף' במסך המכשיר. לאחר מכן תתבצע שיחה אל deviceViewModel כדי לפתוח חלון התאמה לצורך שיתוף המכשיר.

// Share Device button click.
val onShareDevice: () -> Unit = {
 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)

שלב 3: קוראים ל-API

עכשיו אפשר להתחיל במשימה של שיתוף מכשיר.

  1. פותחים את DeviceScreen.kt בתיקייה java/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)

הקריאה החוזרת (callback) שמסתיימת בהצלחה ב-API commissioningClient.shareDevice() מספקת את IntentSender לשימוש כדי להפעיל את שיתוף פעילות המכשיר ב-Google Play Services.

  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. יצרנו מופע נוסף של האפליקציה לדוגמה, שבה אפשר להשתמש בתור נציב היעד.

אחרי שמתקינים את ה-Target Commissioner במכשיר Android, צריך לוודא שיש לכם אפשרות לשתף את מכשיר Matter. אפליקציית היעד של העמלה מסומנת בתווית GHSAFM-TC.

המכשירים שלך יכולים עכשיו להשתתף בשלושה בדים:

  1. בד של Android המקומי.
  2. בד הפיתוח שלך (האפליקציה הזו).
  3. הבד השלישי הזה ששיתפת איתו את המכשיר.

8. השלבים הבאים

מזל טוב

כל הכבוד! השלמת את ה-Codelab הזה ולמדת איך להזמין מכשירים ולשתף אותם באמצעות Home Mobile SDK.

אם אתם נתקלים בבעיות באפליקציה לדוגמה, נסו להשלים את השלבים לאימות הסביבה:

אם יש לכם שאלות לגבי השימוש באפליקציה לדוגמה או אם גיליתם באג בקוד, תוכלו לדווח על בעיות ב'מעקב אחר בעיות' במאגר של GitHub:

כדי לקבל הדרכה רשמית מ-Google לגבי שאלות טכניות, תוכלו להשתמש בפורום למפתחים של בית חכם:

כדי לקבל תמיכה טכנית מהקהילה, אפשר להשתמש בתג google-smart-home ב-Stack Overflow: