เพิ่มอุปกรณ์ Matter ใหม่ในบ้าน

Home API สำหรับ 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 Framework ไปยังเป้าหมายของส่วนขยายและลบล้าง 3 เมธอดเพื่อเรียกใช้ 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).")
       }
     }
   }