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

Home API สำหรับ iOS ใช้ฮับ Matter เพื่อตั้งค่าอุปกรณ์ ใน Fabric โดยระหว่างการตั้งค่า แอปจะส่งคำสั่งไปยัง SDK แล้วจึงส่งไปยังฮับ

การกำหนดค่าโปรเจ็กต์ Xcode

ก่อนที่จะติดตั้งใช้งาน 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 ของคุณได้รับการรับรองจาก Thread Group

• ข้อมูล Wi-Fi

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

• กลุ่มแอป: เพิ่มกลุ่มแอปที่แชร์เพื่อให้แอปหลักและ Matter Add Device Extension สื่อสารกันได้ (เช่น group.com.yourdomain.appgroupname) นักพัฒนาแอปเป็นผู้สร้างและลงทะเบียนตัวระบุนี้ในคอนโซลของนักพัฒนาแอป Apple และต้องตรงกับกลุ่มแอปที่กำหนดค่าไว้ในความสามารถของเป้าหมายใน Xcode Google Home SDK ใช้ตัวระบุนี้ในทั้ง 2 เป้าหมายเพื่อซิงค์สถานะการตั้งค่า ข้อมูลเข้าสู่ระบบของ Fabric และรายการห้องโดยอัตโนมัติโดยใช้คอนเทนเนอร์ UserDefaults ที่แชร์

การแชร์พวงกุญแจ (ไม่บังคับ)

หากส่วนขยายแอปต้องดึงข้อมูลเข้าสู่ระบบหรือโทเค็นเพื่อเข้าถึงที่แอปหลักจัดเก็บไว้โดยใช้ 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 ในเครือข่ายท้องถิ่น

  <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. สร้างคำขอด้วย MatterAddDeviceRequest() เพื่อเริ่มขั้นตอนการรองรับ Matter ของ Apple

   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 ได้เมื่อ ตั้งค่าอุปกรณ์

   นอกจากนี้ คุณจะต้องอัปเดตตัวระบุ App Bundle และโปรไฟล์การจัดสรรเพื่อใช้รหัสกลุ่มนี้

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

   โค้ดตัวอย่างแสดงตัวอย่างการติดตั้งใช้งานคลาสย่อยของ API MatterAddDeviceExtensionRequestHandler ของ Apple

   เพิ่มเฟรมเวิร์ก GoogleHomeMatterCommissionerSDK ลงในเป้าหมายส่วนขยายและลบล้าง 3 เมธอดเพื่อเรียก Google Home platformHomeMatterCommissioner API อย่างน้อย

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