Thêm thiết bị Matter mới vào nhà

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

API Home cho iOS sử dụng một trung tâm Matter để uỷ quyền cho một thiết bị trên một fabric. Trong quá trình uỷ quyền, ứng dụng sẽ gửi một lệnh đến SDK rồi đến trung tâm.

Cách uỷ quyền thiết bị Matter:

1. Thông báo cho Home APIs iOS SDK để chuẩn bị cho các yêu cầu uỷ quyền Matter bằng structure.prepareForMatterCommissioning(). Lệnh này sẽ thực hiện những việc sau:

   • Xác minh rằng quyền đã được cấp.
   • Đảm bảo trung tâm đang kết nối mạng và có thể truy cập được.
   • Đảm bảo không có phiên uỷ quyền nào khác đang diễn ra.

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

2. Tạo một yêu cầu bằng MatterAddDeviceRequest() để bắt đầu quy trình hỗ trợ Matter của Apple.

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

3. Thực hiện yêu cầu bằng perform(). Nếu xảy ra lỗi, hãy huỷ yêu cầu uỷ quyền bằng 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. Tạo App Group ID trong Apple Developer Console để cho phép ứng dụng giao tiếp với tiện ích MatterAddDevice khi đưa thiết bị vào hoạt động.

   Bạn cũng cần cập nhật giá trị nhận dạng gói ứng dụng và hồ sơ cấp phép để sử dụng mã nhận dạng nhóm này.

5. Khi khởi tạo, hãy định cấu hình thực thể Home để sử dụng giá trị nhận dạng nhóm.

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

6. Triển khai Tiện ích ứng dụng Matter của iOS từ Apple.

   Mã mẫu cho thấy ví dụ về cách triển khai một lớp con của API MatterAddDeviceExtensionRequestHandler của Apple.

   Tối thiểu, hãy thêm Khung GoogleHomeMatterCommissionerSDK vào mục tiêu tiện ích và ghi đè 3 phương thức để gọi 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).")
       }
     }
   }