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

رابط‌های برنامه‌نویسی کاربردی (API) هوم برای iOS از یک هاب Matter برای راه‌اندازی یک دستگاه روی پارچه استفاده می‌کنند. در طول راه‌اندازی، برنامه یک دستور را به SDK و سپس به هاب ارسال می‌کند.

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

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

حقوق و مزایا

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

• مدیریت اعتبارنامه‌های شبکه Thread:

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

  برای استفاده از این مجوز در یک ساختار توزیع‌شده، باید فرم درخواست مجوز را به اپل ارسال کنید. اپل از شما می‌خواهد که عضویت خود را در گروه Thread اثبات کنید و تأیید کنید که روتر Thread Border شما توسط گروه Thread تأیید شده است.

• اطلاعات وای فای:

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

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

اشتراک‌گذاری جاکلیدی (اختیاری)

اگر افزونه‌ی برنامه‌ی شما نیاز به بازیابی اعتبارنامه‌ها یا دسترسی به توکن‌های ذخیره‌شده توسط برنامه‌ی اصلی با استفاده از UserInfo.authorizationToken() دارد، باید یک گروه دسترسی keychain مشترک را برای هر دو هدف برنامه‌ی اصلی و افزونه‌ی برنامه در لیست مجوزهای آنها پیکربندی کنید:

<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 را قرار دهید:

  <key>NSBonjourServices</key>
  <array>
      <string>_matter._tcp</string>
      <string>_matterc._udp</string>
      <string>_matterd._udp</string>
      <string>_meshcop._udp</string>
  </array>
  

• شرح استفاده از شبکه محلی: کلید NSLocalNetworkUsageDescription را به همراه پیامی که مجوزهای کشف شبکه محلی را توضیح می‌دهد، وارد کنید.

سفارش ساخت دستگاه

برای راه‌اندازی دستگاه Matter :

1. با استفاده از structure.prepareForMatterCommissioning() به Home APIs iOS SDK اطلاع دهید تا برای درخواست‌های راه‌اندازی Matter آماده شود. این دستور موارد زیر را انجام می‌دهد:

   • تأیید کنید که مجوز اعطا شده است.
   • مطمئن شوید که هاب آنلاین و قابل دسترس است.
   • مطمئن شوید که هیچ جلسه راه‌اندازی فعال دیگری در حال انجام نیست.

   do {
     try await structure.prepareForMatterCommissioning()
   } catch {
     // Failed to prepare for Matter Commissioning
     return
   }
   

2. برای شروع جریان پشتیبانی Matter اپل، یک درخواست با 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 در کنسول توسعه‌دهندگان اپل ایجاد کنید تا برنامه بتواند هنگام راه‌اندازی دستگاه با افزونه 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 App از اپل را پیاده‌سازی کنید.

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

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

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