אפשר לגשת לממשקי ה-API של המכשיר דרך ממשקי ה-API של Home ל-Android. מייבאים את החבילות הבאות לאפליקציה:
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id
כדי להשתמש בסוגי מכשירים או במאפיינים ספציפיים עם ממשקי Device API, צריך לייבא אותם בנפרד.
לדוגמה, כדי להשתמש במאפיין Matter On/Off ובסוג המכשיר On/Off Plugin Unit, צריך לייבא את החבילות הבאות לאפליקציה:
import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice
מידע נוסף זמין במאמר מודל נתונים ב-Android.
טיפול בשגיאות
כל שיטה ב-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
מהמאפיין'מופעל/מושבת' של המכשיר. באמצעות מודל נתוני המאפיינים של ממשקי ה-API לבית, שבו המאפיין הזה מזוהה בתור 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
מופיעה רשימה מלאה של סוגי המכשירים שזמינים ב-Home APIs.
אחזור של מזהה הספק או מזהה המוצר של מכשיר
המאפיין 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
.
מטא-נתונים של מכשיר ומאפיינים
למכשירים ולמאפיינים בממשקי ה-API של Home יש מטא-נתונים משויכים, שיכולים לעזור בניהול חוויית המשתמש באפליקציה.
כל מאפיין ב-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 הבאים של המכשיר:
API | תיאור |
---|---|
devices() |
הצגת כל המכשירים בכל המבנים בחשבון Google. הפונקציה מחזירה HomeObjectsFlow שמספק אפשרויות אחזור וסינון נוספות. |
אחרי שתקבלו HomeDevice
, תוכלו לגשת דרכו לממשקי ה-API הבאים:
API | תיאור |
---|---|
allCandidates() |
הפונקציה מחזירה את כל האפשרויות לאוטומציה של המכשיר ושל הצאצאים שלו. |
candidates() |
הפונקציה מחזירה את כל האפשרויות לאוטומציה במכשיר. |
connectivityStateChanged |
הפעם האחרונה שבה המצב של המכשיר השתנה. |
events(event) |
אחזור של תהליך של אירוע ספציפי. |
events(trait) |
הפונקציה מקבלת את הזרימה של כל האירועים לפי המאפיין הזה. |
events(traits) |
הפונקציה מקבלת את כל האירועים לפי המאפיינים האלה. |
getSourceConnectivity(trait) |
אחזור מטא-נתונים של מאפיין מסוים. הפונקציה מחזירה SourceConnectivity . |
has(trait) |
בודקים אם המכשיר תומך במאפיין הנוכחי המבוקש. |
has(type) |
אם המכשיר תומך בסוג שצוין. |
id |
מזהה המערכת הייחודי של המכשיר. |
isInRoom |
אם המכשיר נמצא בחדר. |
isInStructure |
אם המכשיר נמצא במבנה. |
isMatterDevice |
אם המכשיר מגובה על ידי Matter. |
name |
השם של המכשיר שסיפק המשתמש. |
room() |
החדר שאליו המכשיר הוקצה. הפונקציה מחזירה Room . |
roomId |
המזהה של החדר שאליו המכשיר הוקצה. הפונקציה מחזירה Id . |
sourceConnectivity |
קישוריות המקור של המכשיר, שמייצגת מצבי קישוריות מצטברים ואת המיקום ברשת של המאפיינים של המכשיר. |
structure() |
המבנה שאליו המכשיר מוקצה. הפונקציה מחזירה Structure . |
structureId |
המזהה של המבנה שאליו המכשיר מוקצה. הפונקציה מחזירה Id . |
type(type) |
כדי לקבל גישה ישירה, מקבלים את הגדרת הסוג עם המאפיינים מאוכלסים (אם הם זמינים). תמיד מחזירה קובץ snapshot עדכני של המאפיינים. |
types() |
הצגת רשימה של כל הסוגים הזמינים במכשיר. |