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

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

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

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

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

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

   do {
     try await structure.prepareForMatterCommissioning()
   } catch {
     Logger.error("Failed to prepare for Matter Commissioning: \(error).")
     return
   }
   

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

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

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

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

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 מ-Apple.

   הקוד לדוגמה מציג דוגמה להטמעה של תת-סוג של MatterAddDeviceExtensionRequestHandler API של Apple.

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

   • commissionDevice
   • rooms
   • configureDevice

   import MatterSupport
   import GoogleHomeMatterCommissionerSDK
   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 {
       Logger.info("Commission Matter device with payload: '\(onboardingPayload)'.")
   
       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()
         Logger.info("Returning \(fetchedRooms.count) fetched rooms.")
         return fetchedRooms
       } catch {
         Logger.info("Failed to fetch rooms with error: \(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 {
       Logger.info("Configure Device name: '\(name)', room: \(room?.displayName ?? "").")
       do {
         let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
         await homeMatterCommissioner.configureMatterDevice(
           deviceName: name, roomName: room?.displayName)
       } catch {
         Logger.info("Configure Device failed with error: \(error).")
       }
     }
   }