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

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

การกำหนดค่าโปรเจ็กต์ 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 Add Device Extension สื่อสารกันได้ (เช่น group.com.yourdomain.appgroupname) ตัวระบุนี้สร้างและลงทะเบียนโดยนักพัฒนาแอปใน Apple Developer Console และต้องตรงกับกลุ่มแอปที่กำหนดค่าไว้ในความสามารถของเป้าหมายใน 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 Developer Console เพื่ออนุญาตให้แอปสื่อสารกับส่วนขยาย 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

   โค้ดตัวอย่างแสดงตัวอย่างการติดตั้งใช้งานคลาสย่อยของ 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
       }
     }
   }