הוספת מכשירים חדשים של Matter לבית

ממשקי ה-Home API ל-iOS משתמשים ברכזת Matter כדי להוסיף מכשיר למארג. במהלך ההפעלה, האפליקציה שולחת פקודה ל-SDK ואז לרכזת.

הגדרת פרויקט Xcode

   הטמעה באפליקציה לדוגמה ל-iOS   

לפני שמטמיעים את Commissioning API, חשוב להוסיף את היכולות, ההרשאות והמאפיינים של Info.plist הנדרשים ליעדי Xcode:

הרשאות

מוסיפים את הרשומות הבאות לקובצי .entitlements של יעד האפליקציה הראשי ושל התוסף:

• ניהול פרטי הכניסה לרשת של פרוטוקול Thread:

  <key>com.apple.developer.networking.manage-thread-network-credentials</key>
  <true/>
  

  כדי להשתמש בהרשאה הזו ב-distributed build, צריך לשלוח ל-Apple טופס בקשה להרשאה. חברת Apple דורשת הוכחה לחברות ב-Thread Group ואימות של Thread Border Router (TBR) על ידי Thread Group.

• מידע על ה-Wi-Fi:

  <key>com.apple.developer.networking.wifi-info</key>
  <true/>
  

• קבוצות אפליקציות: מוסיפים קבוצת אפליקציות משותפת כדי לאפשר לאפליקציה הראשית ולתוסף Matter Add Device לתקשר ביניהן (לדוגמה, group.com.yourdomain.appgroupname). המזהה הזה נוצר ונרשם על ידי המפתח ב-Apple Developer Console, והוא חייב להתאים לקבוצת האפליקציות שהוגדרה ביכולות היעד ב-Xcode. ערכת ה-SDK של Google Home משתמשת במזהה הזה בשני היעדים כדי לסנכרן באופן אוטומטי את מצב ההפעלה, את פרטי הכניסה של המארג ואת רשימות החדרים באמצעות מאגר UserDefaults משותף.

שיתוף Keychain (אופציונלי)

אם תוסף האפליקציה צריך לאחזר הסמכות או טוקני גישה שמאוחסנים באפליקציה הראשית באמצעות UserInfo.authorizationToken(), צריך להגדיר קבוצת גישה משותפת ל-Keychain גם לאפליקציה הראשית וגם לתוסף האפליקציה בקובץ ה-plist של ההרשאות שלהם:

<key>keychain-access-groups</key>
<array>
    <string>$(AppIdentifierPrefix)your.shared.keychain.group</string>
</array>

מאפייני Info.plist

צריך לכלול את מפתחות התיאור הבאים ב-Info.plist של יעד האפליקציה הראשי:

• תיאור השימוש במיקום:

  <key>NSLocationWhenInUseUsageDescription</key>
  <string>Your custom message explaining why location access is needed to read the current Wi-Fi SSID</string>
  

• שירותי Bonjour: בקטע NSBonjourServices, כוללים את השירותים שנדרשים לגילוי מקומי של Matter ו-Thread:

  <key>NSBonjourServices</key>
  <array>
      <string>_matter._tcp</string>
      <string>_matterc._udp</string>
      <string>_matterd._udp</string>
      <string>_meshcop._udp</string>
  </array>
  

• תיאור השימוש ברשת המקומית: צריך לכלול את המפתח NSLocalNetworkUsageDescription עם הודעה שמסבירה את הרשאות הגילוי ברשת המקומית.

איך מחברים מכשיר

כדי להגדיר מכשיר Matter:

1. צריך להודיע ל-Home APIs iOS SDK כדי להתכונן לבקשות להפעלה של Matter באמצעות structure.prepareForMatterCommissioning(). הפקודה הזו תבצע את הפעולות הבאות:

   • מוודאים שההרשאה ניתנה.
   • מוודאים שהרכזת מחוברת לאינטרנט ושאפשר לגשת אליה.
   • מוודאים שאין סשן פעיל אחר של הגדרת מכשיר.

   do {
     try await structure.prepareForMatterCommissioning()
   } catch {
     // Failed to prepare for Matter Commissioning
     return
   }
   

2. כדי להתחיל את תהליך התמיכה של אפל ב-Matter, צריך ליצור בקשה באמצעות MatterAddDeviceRequest().

   let topology = MatterAddDeviceRequest.Topology(
     ecosystemName: "Google Home",
     homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
   )
   
   let request = MatterAddDeviceRequest(topology: topology)
   

3. מבצעים את הבקשה באמצעות perform(). אם מתרחשת שגיאה, מבטלים את בקשת ההפעלה באמצעות structure.cancelMatterCommissioning().

   do {
     // Starting MatterAddDeviceRequest.
     try await request.perform()
     // Successfully completed MatterAddDeviceRequest.
     let commissionedDeviceIDs = try structure.completeMatterCommissioning()
     // Commissioned device IDs.
   } catch let error {
     structure.cancelMatterCommissioning()
     // Failed to complete MatterAddDeviceRequest.
   }
   

4. יוצרים App Group ID ב-Apple Developer Console כדי לאפשר לאפליקציה לתקשר עם התוסף של MatterAddDevice בזמן הפעלת המכשיר.

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

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

   func application(_ application: UIApplication, didFinishLaunchingWithOptions
   launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
     Home.configure {
       $0.sharedAppGroup = "group.com.sample.app.commissioning"
     }
   
     return true
   }
   

6. מטמיעים את תוסף האפליקציה Matter ל-iOS של אפל.

   הקוד לדוגמה מראה איך להטמיע מחלקת משנה של MatterAddDeviceExtensionRequestHandler API של אפל.

   לכל הפחות, צריך להוסיף את ה-Framework של GoogleHomeMatterCommissionerSDK ליעד של התוסף ולבטל שלוש שיטות כדי לשלוח קריאה לממשקי ה-API של Google Home platformHomeMatterCommissioner.

   • commissionDevice
   • rooms
   • configureDevice

   import MatterSupport
   import GoogleHomeSDK
   import OSLog
   
   final class RequestHandler: MatterAddDeviceExtensionRequestHandler {
     // The App Group ID defined by the application to share information between the extension and main app.
     private static var appGroup = "group.com.sample.app.commissioning"
   
     ...
   
     // MARK: - Home API commissioning handlers
   
     /// Commissions a device to the Google Home ecosystem.
     /// - Parameters:
     ///   - home: The home that the device will be added to
     ///   - onboardingPayload: The payload to be sent to the Matter Commissioning SDK to commission the device.
     ///   - commissioningID: An identifier not used by the Home API SDK.
     override func commissionDevice(in home: MatterAddDeviceRequest.Home?, onboardingPayload: String, commissioningID: UUID) async throws {
       // Commission Matter device with payload.
   
       var onboardingPayloadForHub = onboardingPayload
       let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
       try await homeMatterCommissioner.commissionMatterDevice(
       onboardingPayload: onboardingPayloadForHub)
     }
   
     /// Obtains rooms from the Home Ecosystem to present to the user during the commissioning flow.
     /// - Parameter home: The home that the device will be added to.
     /// - Returns: A list of rooms if obtained from the Google Home ecosystem or an empty list if there was an error in getting them.
     override func rooms(in home: MatterAddDeviceRequest.Home?) async -> [MatterAddDeviceRequest.Room] {
       do {
         let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
         let fetchedRooms = try homeMatterCommissioner.fetchRooms()
         // Returning fetched rooms.
         return fetchedRooms
       } catch {
         // Failed to fetch rooms with error
         return []
       }
     }
   
     /// Pushes the device's configurations to the Google Home Ecosystem.
     /// - Parameters:
     ///   - name: The friendly name the user chose to set on the device.
     ///   - room: The room identifier that the user chose to put the device in.
     override func configureDevice(named name: String, in room: MatterAddDeviceRequest.Room?) async {
       // Configure Device name: room
       do {
         let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
         await homeMatterCommissioner.configureMatterDevice(
           deviceName: name, roomName: room?.displayName)
       } catch {
         // Configure Device failed with error
       }
     }
   }