دستگاه های جدید Matter را به خانه اضافه کنید

API های Home برای iOS از یک Matter Hub برای راه اندازی دستگاه روی پارچه استفاده می کنند. در طول راه اندازی، برنامه دستوری را به 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() برای شروع جریان پشتیبانی 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 در کنسول برنامه نویس اپل ایجاد کنید تا به برنامه اجازه دهید هنگام راه اندازی دستگاه با افزونه 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. افزونه برنامه iOS Matter را از اپل پیاده سازی کنید.

   کد نمونه نمونه ای از پیاده سازی یک زیر کلاس از MatterAddDeviceExtensionRequestHandler API اپل را نشان می دهد.

   حداقل، GoogleHomeMatterCommissionerSDK Framework را به هدف برنامه افزودنی اضافه کنید و سه روش را برای فراخوانی APIهای HomeMatterCommissioner Google Home platform لغو کنید.

   • 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).")
       }
     }
   }