בניית אפליקציה ל-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 כדי להפעיל ולשתף מכשירים. בנוסף, תלמדו איך להשתמש בספריות של הזמנות ושל אשכולות מתוך מאגר Matter (‏connectedhomeip).

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

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

הדרישות

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

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

2. להגדרה

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

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

גרסאות של Codelab

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

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

תלויות

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

קוד מקור

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

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

  • ‫java/com/google/homesampleapp/commissioning/AppCommissioningService: מאפשר להפעיל מכשירים ב-Development Fabric
  • ‫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

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

חשוב להבין את המושגים הבאים לגבי הפעלת מכשירי Matter:

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

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

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

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

שלב 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 כדי להפעיל מכשיר ב-Google Fabric.

  1. תהליך ההפעלה מתחיל בפונקציה commissionDevice(). קודם כול, מוגדר CommissioningRequest. בתצורת ברירת המחדל הזו, המכשירים מוקצים רק לרשת המקומית של Android.
  2. ‫Matter היא נקודת הכניסה ל-Home Mobile SDK. בשיחה הבאה, .getCommissioningClient מקבל CommissioningClient על ידי this (Activity).
  3. ‫.commissionDevice() מקבל את CommissioningRequest.
  4. לבסוף, מתבצעת קריאה ל-.addOnSuccessListener כדי לעבד את CommissioningResult ולהפעיל את הפעילות Commission Device (הפעלת המכשיר) של 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 כדי לפשט את תהליך ההפעלה של המכשירים שלו ב-Fabrics אחרים.

בשלב הבא נסביר איך להפעיל מכשיר ברשת פיתוח.

סקירה כללית של ממשק המשתמש במהלך תהליך ההפעלה מופיעה במדריך לאפליקציית הדוגמה של Google Home ל-Matter.

4. העברה של קוד למאגר פיתוח

אפשר להוסיף מכשירים ליותר מ-Fabric אחד. כדי לנהל את ההתאמות המהימנות, המכשירים מאחסנים FabricTable שמכיל חברים שונים ב-FabricInfo, לדוגמה:

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

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

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

כדי להפעיל את המכשיר באמצעות Local Android fabric, השתמשנו בפרמטרים שמוגדרים כברירת מחדל כדי ליצור את 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() כדי להשתמש בשירות מותאם אישית. בנוסף, נוסיף Activity Launcher לקטע Home ונשתמש באובייקטים של LiveData כדי לנהל את זרימת ה-API.

שלב 1: יוצרים משגר פעילות GPS

קודם כל, ניצור Activity Launcher כדי לטפל ב-IntentSender מ-CommissioningClient API.

  1. פותחים את HomeScreen בתיקייה java/com/google/homesampleapp/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/com/google/homesampleapp/screens/home.
  2. מחליפים את התגובה // CODELAB: commissionDevice בתגובה הבאה commissionDeviceRequest. הפונקציה setCommissioningService קושרת את AppCommissioningService למופע CommissioningService שמוחזר בפונקציית קריאה חוזרת. כשמעבירים שירות בהתאמה אישית, Home Mobile SDK מקצה קודם מכשירים ל-Android local fabric, ואז שולח את מטען הייעוד של ההצטרפות בחזרה אל 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 מ-CommissioningClient API. בתהליך הזה, CommissioningClient API מפעיל מכשירים ב-Local Android fabric קודם, ואז מחזיר קריאה חוזרת שכוללת את האובייקט 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 coroutines.

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

הוספה לרשת פיתוח מאפשרת לכם להשתמש בספריות ממאגר Matter (connectedhomeip) כדי לשלוט במכשירים מאפליקציית הדוגמה.

יצרנו כמה מחלקות עזר כדי להקל על הגישה לקלאסטרים של מכשירים ועל שליחת פקודות. מידע נוסף זמין במאמר ClustersHelper בjava/clusters. ה-Singleton helper הזה מייבא את הספריות הבאות כדי לגשת לפרטי המכשיר:

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

אפשר להשתמש במחלקה הזו כדי לקבל את האשכול On/Off של מכשיר, ואז לקרוא ל-.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 מאפשרת להוסיף מכשירים ל-Local Android fabric וגם ל-development fabric באפליקציית הדוגמה. זהו דוגמה לזרימת נתונים עם כמה אדמינים, שבה אפשר להוסיף מכשירים ליותר מ-fabric אחד.

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

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

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

בשלבים הבאים נסביר איך לשתף מכשירים באמצעות Home Mobile SDK.

שלב 1: יוצרים משגר פעילות GPS

בדומה ל-Commissioning Activity Launcher שיצרנו כשביצענו הקצאת הרשאות ל-Development Fabric, יצרנו את Share Device Activity Launcher כדי לטפל ב-IntentSender מ-CommissioningClient API.

  1. פותחים את DeviceScreen בתיקייה java/com/google/homesampleapp/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 = remember {
 {
   deviceViewModel.openPairingWindow(deviceUiModel!!.device.deviceId)
 }
}

אחרי שחלון ההתאמה נפתח, deviceViewModel מעביר את המידע הזה לממשק המשתמש. התקשורת בין ViewModel לממשק המשתמש מתבצעת באמצעות אובייקטים של StateFlow.

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

כשרואים את השינוי באובייקט StateFlow, ‏ DeviceScreen מבצע את הקריאה הבאה:

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

שלב 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)

הקריאה החוזרת (callback) של commissioningClient.shareDevice() API מספקת את IntentSender שמשמש להפעלת 'שיתוף פעילות במכשיר' בשירותי 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. יצרנו מופע נוסף של אפליקציית הדוגמה שבו אפשר להשתמש כגורם המוסמך לביצוע פעולות.

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

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

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

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

מזל טוב

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

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

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

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

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