שליטה במכשירים ב-iOS

המדריך הזה הוא המשך של גישה למכשירים ולמטא-נתונים של מכשירים ב-iOS, ומופיעות בו דוגמאות נוספות לשליטה במכשירים ולגישה אליהם.

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

import GoogleHomeSDK
import GoogleHomeTypes

איך בודקים אם מאפיין תומך בפקודה

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

לדוגמה, כדי לבדוק אם מכשיר תומך בפקודה toggle של מאפיין ההפעלה וההשבתה:

// Check if the OnOff trait supports the toggle command.
if onOffTraitTest.supportsToggleCommand {
  print("onOffTrait supports toggle command")
} else {
  print("onOffTrait does not support stateful toggle command")
}

שליחת פקודה למכשיר

שליחת פקודה דומה לקריאת מאפיין מצב מתכונה. כדי להפעיל או להשבית את המכשיר, משתמשים בפקודה Toggle ‏(החלפה), שמוגדרת במודל הנתונים של הסביבה העסקית של Google Home כ-toggle().OnOffTrait השיטה הזו משנה את onOff ל-false אם הערך הוא true, או ל-true אם הערך הוא false:

// Calling a command on a trait.
do {
  try await onOffTraitTest.toggle()
} catch let error as HomeError {
  // Code for handling the exception
}

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

לחלופין, אפשר להשתמש בפקודות off() או on() כדי להגדיר במפורש את המצב:

do {
  try await onOffTraitTest.off()
  try await onOffTraitTest.on()
} catch let error as HomeError {
  // Code for handling the exception
}

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

שליחת פקודה עם פרמטרים

חלק מהפקודות עשויות להשתמש בפרמטרים, כמו אלה שמופיעים בOnOffTrait או בLevelControlTrait:

// Turn off the light using the DyingLight effect.
do {
  try await onOffTraitTest.offWithEffect(
    effectIdentifier: Matter.OnOffTrait.EffectIdentifierEnum.dyingLight,
    effectVariant: 0
  )
} catch let error as HomeError {
  // Code for handling the exception
}

// Change the brightness of the light to 50%
do {
  try await levelControlTraitTest.moveToLevel(
    level: UInt8(127),
    transitionTime: 0,
    optionsMask: Matter.LevelControlTrait.OptionsBitmap(),
    optionsOverride: Matter.LevelControlTrait.OptionsBitmap()
  )
} catch let error as HomeError {
  // Code for handling the exception
}

איך בודקים אם מאפיין תומך במאפיין

יכול להיות שמכשירים מסוימים תומכים בתכונה Matter, אבל לא בתכונה ספציפית. לדוגמה, יכול להיות שמכשיר Cloud-to-cloud שמופה ל-Matter לא תומך בכל מאפיין של Matter. כדי לטפל במקרים כאלה, משתמשים במאפיין isSupported ברמת המאפיין כדי לבדוק אם המאפיין נתמך במכשיר מסוים.

לדוגמה, כדי לבדוק אם מכשיר תומך במאפיין onOff של תכונת ההפעלה וההשבתה:

// Check if the OnOff trait supports the onOff attribute.
if onOffTrait.attributes.$onOff.isSupported {
  print("onOffTrait supports onOff state")
} else {
  print("onOffTrait is for a command only device!")
}

חלק מהמאפיינים יכולים להיות ריקים במפרט Matter או בסכמה Cloud-to-cloud smart home. במאפיינים האלה, אפשר לקבוע אם הערך nil שמוחזר על ידי המאפיין נובע מכך שהמכשיר לא מדווח על הערך הזה, או אם הערך של המאפיין הוא למעשה nil. כדי לעשות זאת, משתמשים ב-isNullable בנוסף ל-isSupported:

// Check if a nullable attribute is set or is not supported.
if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
  if let onOffTrait = deviceType.traits[Matter.OnOffTrait.self] {
    if onOffTrait.attributes.startUpOnOff == nil {
      if onOffTrait.attributes.$startUpOnOff.isSupported {
        print(
          "onOffTrait supports startUpOnOff and it is nil. Check the spec for the contextual meaning."
        )
      } else {
        print("onOffTrait does not support startUpOnOff!")
      }
    } else {
      print(
        "onOffTrait supports startUpOnOff and it is set to \(onOffTrait.attributes.startUpOnOff)"
      )
    }
  }
}

עדכון מאפייני התכונות

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

האפשרות לשנות את הערך של מאפיין תלויה בשני גורמים:

• האם אפשר לכתוב למאפיין?
• האם הערך של המאפיין יכול להשתנות כתוצאה משליחת פקודת מאפיין?

המידע הזה מופיע במסמכי העזר בנושא מאפיינים והמאפיינים שלהם.

לכן, השילובים של מאפיינים שמכתיבים איך אפשר לשנות את הערך של מאפיין הם:

• לקריאה בלבד ולא מושפע מפונקציות אחרות. כלומר, הערך של המאפיין לא משתנה. לדוגמה, המאפיין currentPosition של SwitchTrait.

• לקריאה בלבד ומושפע מפקודות אחרות. המשמעות היא שהדרך היחידה שבה הערך של המאפיין יכול להשתנות היא כתוצאה משליחת פקודה. לדוגמה, המאפיין currentLevel של LevelControlTrait הוא לקריאה בלבד, אבל אפשר לשנות את הערך שלו באמצעות פקודות כמו moveToLevel.

• ניתן לכתיבה ולא מושפע מפקודות אחרות. כלומר, אפשר לשנות ישירות את הערך של המאפיין באמצעות הפונקציה update של התכונה, אבל אין פקודות שישפיעו על הערך של המאפיין. לדוגמה, המאפיין WrongCodeEntryLimit של DoorLockTrait.

• ניתן לכתיבה ומושפע מפקודות אחרות. המשמעות היא שאפשר לשנות ישירות את הערך של המאפיין באמצעות הפונקציה update של המאפיין, והערך של המאפיין יכול להשתנות כתוצאה משליחת פקודה. לדוגמה, אפשר לכתוב למאפיין occupiedCoolingSetpoint של ThermostatTrait, אבל אפשר גם לעדכן אותו באמצעות הפקודה setpointRaiseLower.

דוגמה לשימוש בפונקציית העדכון כדי לשנות את הערך של מאפיין

בדוגמה הזו מוצג איך להגדיר באופן מפורש את הערך של המאפיין DoorLockTrait.wrongCodeEntryLimit.

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

לדוגמה:

if doorLockTraitTest.attributes.$wrongCodeEntryLimit.isSupported {
  let _ = try await doorLockTraitTest.update {
    $0.setWrongCodeEntryLimit(3)
  }
}