גישה למכשירים ולמטא-נתונים של המכשירים

אפשר לגשת לממשקי ה-API של המכשיר דרך ממשקי ה-API של Home. מייבאים את החבילות האלה לאפליקציה:

import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id

כדי להשתמש בסוגי מכשירים או במאפיינים ספציפיים עם ממשקי ה-API של המכשירים, צריך לייבא אותם בנפרד.

לדוגמה, כדי להשתמש במאפיין Matter On/Off ובסוג המכשיר On/Off Plugin Unit, צריך לייבא את החבילות הבאות לאפליקציה:

import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice

מידע נוסף זמין במאמר מודל נתונים.

טיפול בשגיאות

כל שיטה ב-Home APIs יכולה להוביל ליצירה של HomeException, לכן מומלץ להשתמש בבלוק try-catch כדי לתפוס את HomeException בכל הקריאות.

כשעובדים עם HomeException, כדאי לבדוק את השדות code ו-message כדי להבין מה השתבש.

חריגות שלא מטופלות יגרמו לקריסה של האפליקציה.

מידע נוסף זמין במאמר טיפול בשגיאות.

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

שיחות לדוגמה

הצגת רשימת מכשירים

כשהמבנה זמין, קריאה ל-devices() מחזירה זרימה של מכשירים שיש לכם גישה אליהם מהמבנה הזה:

// Get a flow of all devices accessible to the user
val allDevicesFlow: HomeObjectsFlow<HomeDevice> = home.devices()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allDevices: Set<HomeDevice> = allDevicesFlow.list()

משם אפשר לגשת למצבים של כל מכשיר ולשלוח למכשיר פקודות נתמכות.

קריאת מצב של מכשיר

נבחן דוגמה לבדיקה של המאפיין OnOff מהמאפיין'מופעל/מושבת' של המכשיר. באמצעות מודל נתוני המאפיינים של Home APIs, שבו המאפיין הזה מזוהה בתור OnOff, אפשר לאחזר נתוני מאפיינים דרך הכיתה standardTraits של סוג המכשיר:

// Assuming we have a device.
val deviceFlow = home.devices().itemFlow(myDeviceId)

val device = deviceFlow.first()

// Get a flow of a standard trait on the type. distinctUntilChanged() is needed to only trigger
// on the specific trait changes and not the whole type.
val onOffTraitFlow: Flow<OnOff?> =
  device.type(DimmableLightDevice).map { it.standardTraits.onOff }.distinctUntilChanged()

val onOffTrait: OnOff = onOffTraitFlow.first()!!

למידע נוסף על פונקציית הזרימה ב-Kotlin, אפשר לעיין במאמר distinctUntilChanged.

ביטול התוקף של מצב במינוי למאפיין

ממשק TraitStateInvalidation מאפשר לבטל את התוקף של מצב שאוחזר דרך מינויים למכשיר היעד במקרים שבהם המצב לא מדווח בצורה נכונה. דוגמאות למקרים שבהם יכול להיות שהמצב לא ידווח בצורה נכונה: שימוש במאפיינים במאפייני Matter עם איכות 'C', או בגלל הטמעה של מכשיר שגורמת לבעיה באופן בלתי צפוי.

ה-API הזה מבצע קריאה מאולצת של מצב המאפיין הנוכחי ומחזיר את התוצאה באמצעות תהליכי המאפיינים הקיימים.

מקבלים את המאפיין ומריצים forceRead על המאפיין:

val generalDiagnosticsTrait = device.trait(GeneralDiagnostics).first()
generalDiagnosticsTrait.forceRead()

הצגת רשימה של מאפייני סוג המכשיר

מומלץ להשתמש בסוגי המכשירים כנקודת כניסה לקריאת המאפיינים, כי הם מפרקים את המכשיר לחלקים הפונקציונליים שלו (כמו נקודות קצה ב-Matter).

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

כדי לקבל את רשימת המאפיינים הזמינים לסוג המכשיר 'תאורה ניתנת לעמעום':

// Get all types available on this device. Requires the types to be part of the registry during
// SDK initialization.
val typesFlow: Flow<Set<DeviceType>> = device.types()

// Get a snapshot of all types.
val types: Set<DeviceType> = typesFlow.first()

// Get the DimmableLightDevice instance from the set of types.
val dimmableLightDevice = types.filterIsInstance<DimmableLightDevice>().firstOrNull()

// Get all traits in the type + traits registered
val allTraits: Set<Trait> = dimmableLightDevice!!.traits()

סוג אחר של התנגשות מאפיינים יכולה להתרחש כשלמכשיר יש שני מאפיינים עם אותו שם. לדוגמה, הערך onOff יכול להתייחס למופעים של המאפיין הסטנדרטי OnOff, או למופעים של המאפיין OnOff שהוגדר על ידי היצרן. כדי למנוע אי-בהירות לגבי המאפיין הרצוי, צריך להוסיף למכונה שמפנה למאפיין Trait שמות תחום מתאימים. למאפיינים רגילים, כלומר למאפיינים שדומים לאשכולות הרגילים של Matter, משתמשים ב-standardTraits. למאפיינים של Google, משתמשים ב-googleTraits:

// Accessing standard traits on the type.
val onOffTrait: OnOff? = dimmableLightDevice.standardTraits.onOff
val levelControlTrait: LevelControl? = dimmableLightDevice.standardTraits.levelControl

כדי לגשת למאפיין ספציפי ליצרן, צריך להפנות אליו ישירות:

// Accessing a custom trait on the type.
val customTrait = dimmableLightDevice.trait(MyCustomTrait)

הצגת רשימה של מכשירים עם מאפיין ספציפי

אפשר להשתמש בפונקציה filter ב-Kotlin כדי לשפר את הקריאות ל-API. לדוגמה, כדי לקבל רשימה של כל המכשירים בבית שיש להם את המאפיין 'הפעלה/כיבוי':

// Get all devices that support OnOff
val onOffDevices: Flow<List<HomeDevice>> =
  home.devices().map { devices -> devices.filter { it.has(OnOff) } }

בממשק Trait מופיעה רשימה מלאה של המאפיינים שזמינים ב-Home APIs.

הצגת רשימה של מכשירים עם סוגי מכשירים דומים

כדי לקבל רשימה של מכשירים שמייצגים את כל הנורות בבית:

// Get a list of devices with similar device types (lights)
val lightDevices =
  home.devices().map { devices ->
    devices.filter {
      it.has(DimmableLightDevice) ||
        it.has(OnOffLightDevice) ||
        it.has(ColorTemperatureLightDevice) ||
        it.has(ExtendedColorLightDevice)
    }
  }

יש כמה סוגים של מכשירים בממשקי ה-API של Home שיכולים לייצג סוג מכשיר ליבה. לדוגמה, אין סוג מכשיר בשם 'תאורה'. במקום זאת, יש ארבעה סוגים שונים של מכשירים שיכולים לייצג תאורה, כפי שמוצג בדוגמה הקודמת. לכן, כדי לקבל תצוגה מקיפה של סוגים ברמה גבוהה יותר של מכשירי בית, צריך לכלול כמה סוגים של מכשירים בתהליכים המסוננים.

בממשק DeviceType מפורטת רשימה מלאה של סוגי המכשירים שזמינים בממשקי ה-API של Home.

אחזור של מזהה הספק או מזהה המוצר של מכשיר

המאפיין BasicInformation כולל מידע כמו מזהה הספק, מזהה המוצר, שם המוצר והמספר הסידורי של המכשיר:

// Get device basic information. All general information traits are on the RootNodeDevice type.
val basicInformation = device.type(RootNodeDevice).first().standardTraits.basicInformation!!
println("vendorName ${basicInformation.vendorName}")
println("vendorId ${basicInformation.vendorId}")
println("productId ${basicInformation.productId}")

זיהוי מכשירים מסוג Cloud-to-cloud

אם אתם יצרני מכשירים ומפתחים מכשירי Cloud-to-cloud, כדי לזהות את מכשירי Cloud-to-cloud באמצעות המאפיין BasicInformation, תוכלו לכלול את שדות המחרוזות הבאים בתשובה SYNC שלהם:

• מזהה הספק שהונפק על ידי Connectivity Standards Alliance‏ (CSA): "matterOriginalVendorId": "0xfff1",

• מזהה מוצר שמזהה באופן ייחודי מוצר של ספק: "matterOriginalProductId": "0x1234",

• מזהה ייחודי של המכשיר, שנוצר באופן ספציפי ליצרן: "matterUniqueId": "matter-device-id",

כשמוסיפים את שדות המחרוזות האלה, צריך להשתמש במזהי המוצרים והספקים של Matter, אם יש לכם אותם. אם אתם לא חברים בתוכנית CSA ולא הוקצו לכם המזהים האלה, תוכלו להשאיר את השדות matterOriginalVendorId ו-matterOriginalProductId ריקים ולספק את matterUniqueId כמזהה.

בתגובת ה-SYNC לדוגמה מוצג השימוש בשדות האלה:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting",
        ],
        "willReportState": true,
        "deviceInfo": { ... },
        "matterOriginalVendorId": "0xfff1",
        "matterOriginalProductId": "0x1234",
        "matterUniqueId": "matter-device-id",
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id",
          }
        ]
      }
    ]
  }
}

למידע נוסף, ראו מסמכי העזרה של Cloud-to-cloud SYNC.

מטא-נתונים של מכשיר ומאפיינים

למכשירים ולמאפיינים ב-Home APIs יש מטא-נתונים משויכים, שיכולים לעזור בניהול חוויית המשתמש באפליקציה.

כל מאפיין ב-Home APIs מכיל את המאפיין sourceConnectivity, שמכיל מידע על הסטטוס באינטרנט ועל המיקום של המאפיין (ניתוב מקומי או מרוחק).

אחזור הסוג הראשי של מכשיר

במכשירים מסוימים עשויים להופיע כמה סוגים של מכשירים דרך ממשקי ה-API של Home. כדי לוודא שהמשתמשים יקבלו באפליקציה את האפשרויות המתאימות למכשירים שלהם (כמו בקרת מכשיר והצעות לאוטומציה), כדאי לבדוק מהו סוג המכשיר הראשי של המכשיר.

קודם מקבלים את סוגי המכשיר באמצעות type(), ואז קובעים מהו הסוג הראשי:

val types = device.types().first()
val primaryType = types.first { it.metadata.isPrimaryType }

איך בודקים אם מאפיין מסוים זמין באינטרנט

משתמשים בשיטה connectivityState() כדי לבדוק את קישוריות המאפיין:

val onOffConnectivity = onOffTrait?.metadata?.sourceConnectivity?.connectivityState

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

בדיקת הקישוריות של מכשיר

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

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

המצב PARTIALLY_ONLINE עשוי להופיע במקרה של מכשירי תערובת כשאין חיבור לאינטרנט. יכול להיות שתכונות רגילות של Matter עדיין יהיו באינטרנט בגלל ניתוב מקומי, אבל תכונות מבוססות-ענן יהיו במצב אופליין.

בדיקת הניתוב ברשת של מאפיין

המיקום של מאפיין זמין גם בממשקי ה-API של Home. השדה dataSourceLocality מציין אם המאפיין מנותב מרחוק (דרך הענן), באופן מקומי (דרך צומת מקומי) או בצורה peer-to-peer (ישירות ממכשיר למכשיר, ללא צומת).

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

val onOffLocality = onOffTrait?.metadata?.sourceConnectivity?.dataSourceLocality

בדיקת ניתוב הרשת של מכשיר

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

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

המצב MIXED עשוי להתרחש בתרחיש דומה לזה של קישוריות PARTIALLY_ONLINE: חלק מהמאפיינים מבוססי ענן וחלקם מקומיים.

רשימת ממשקי ה-API

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

אחרי שתקבלו HomeDevice, תוכלו לגשת דרכו לממשקי ה-API הבאים: