افزودن دستگاه‌های Matter جدید به خانه

‫Home APIs برای iOS از یک هاب Matter برای راه‌اندازی دستگاه در یک فابریک استفاده می‌کند. درطول راه‌اندازی، برنامه فرمانی به کیت توسعه نرم‌افزار و سپس به هاب ارسال می‌کند.

پیکربندی پروژه Xcode

   در برنامه نمونه برای iOS پیاده‌سازی شده است   

قبل‌از پیاده‌سازی Commissioning API، حتماً قابلیت‌ها، حقوق، و ویژگی‌های Info.plist موردنیاز را به هدف‌های Xcode خود اضافه کنید:

حقوق استفاده

ورودی‌های زیر را در فایل‌های .entitlements هدف برنامه اصلی و افزونه‌تان قرار دهید:

• مدیریت اطلاعات کاربری شبکه Thread:

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

  برای استفاده از این حق در ساخت توزیع‌شده، باید فرم درخواست حق را به Apple ارسال کنید. Apple از شما می‌خواهد که عضویت در Thread Group را اثبات کنید و تأیید کنید که Thread Border Router (TBR) شما توسط Thread Group گواهی شده است.

• اطلاعات Wi-Fi:

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

• گروه‌های برنامه: گروه برنامه هم‌رسانی‌شده‌ای اضافه کنید تا به برنامه اصلی و Matter «افزونه افزودن دستگاه» اجازه دهید باهم ارتباط برقرار کنند (برای مثال، group.com.yourdomain.appgroupname). این شناسه توسط توسعه‌دهنده در Apple Developer Console او ایجاد و ثبت می‌شود و باید با «گروه برنامه» پیکربندی‌شده در قابلیت‌های هدف در Xcode مطابقت داشته باشد. «کیت توسعه نرم‌افزار Google Home» از این شناسه در هر دو هدف استفاده می‌کند تا به‌طور خودکار وضعیت راه‌اندازی، اعتبارنامه‌های ساختار، و فهرست اتاق‌ها را بااستفاده از محفظه مشترک UserDefaults همگام‌سازی کند.

هم‌رسانی Keychain (اختیاری)

اگر افزونه برنامه شما نیاز به بازیابی اطلاعات کاربری یا کد دسترسی ذخیره‌شده توسط برنامه اصلی بااستفاده از UserInfo.authorizationToken() دارد، باید یک گروه دسترسی به دسته کلید مشترک برای هر دو هدف برنامه اصلی و افزونه برنامه در 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 discovery را اضافه کنید:

  <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 Apple، درخواستی با 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 ایجاد کنید تا به برنامه اجازه دهید هنگام راه‌اندازی دستگاه با افزونه 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 را به هدف افزونه اضافه کنید و سه روش را برای فراخوانی Google Home platform (GHP)HomeMatterCommissioner APIs لغو کنید.

   • 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
       }
     }
   }