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

1. היי!

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

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

באפליקציה לדוגמה של Google Home for 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/com/google/homesampleapp/commissioning/AppCommissioningService: מאפשר לשייך מכשירים למארג הפיתוח
  • java/com/google/homesampleapp/screens/home/HomeScreen ו-java/com/google/homesampleapp/screens/home/HomeViewModel.kt: כולל את פונקציונליות הזמנת ה-SDK לניידים לבית
  • java/com/google/homesampleapp/screens/device/DeviceScreen ו-java/com/google/homesampleapp/screens/device/DeviceViewModel: כולל את הקריאות ל-Share Device API

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

// CODELAB: add commissioningFunction()

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

3. עמלה ל-Google

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

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

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

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

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

בקטעים הבאים נעבור על הקוד המינימלי שנדרש כדי לשייך מכשירים למארג של Google.

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

כדי לטפל ב-IntentSender מה-CommissioningClient, אפשר להשתמש ב-ActivityתוצאהLauncher:

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 בנושא עניינים.

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/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, ואז ישלח את המטען הייעודי (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. יצירת שירות עמלה

בפונקציה commissionDevice() ביקשנו לקבל CommissioningService מ-CommissioningClient API. בתהליך הזה, ה-API של CommissioningClient API משריין קודם על המכשירים לפי המארג של 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 כולל גם ספריות ממאגר המשאבים (connectedhomeip):

import com.google.homesampleapp.chip.ChipClient

לבסוף, השירות כולל ייבוא כדי לתמוך במחרוזות Hilt וקוטלין.

בשלב הבא אנחנו יוצרים את ה-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() כדי להפעיל את התיקוף של serviceScope ולקבל את deviceId.
    // Perform commissioning on custom fabric for the sample app.
serviceScope.launch {
  val deviceId = devicesRepository.incrementAndReturnLastDeviceId()
  3. מבצעים עמלה. בשלב הזה, אנחנו יכולים להעביר את פרטי המכשיר שמוחזרים באובייקט CommissioningRequestMetadata. ChipClient משתמש בפרטי המטא-נתונים האלה כדי ליצור ערוץ מאובטח בין אפליקציית GHSA של תקן 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)
              }
            })
  }
}

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

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

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

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

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

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

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

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

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

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

  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 מעביר את העובדה הזו לממשק המשתמש. התקשורת בין 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) המוצלחת של ה-API של commissioningClient.shareDevice() מאפשרת להשתמש ב-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.

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

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

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

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