Thêm thiết bị Matter mới vào nhà

các API cho Home cho iOS sử dụng một thiết bị trung tâm Matter để uỷ quyền cho một thiết bị vào một cấu trúc. Trong quá trình uỷ quyền, ứng dụng sẽ gửi lệnh đến SDK rồi đến trung tâm.

Cấu hình dự án Xcode

   Được triển khai trong Ứng dụng mẫu cho iOS   

Trước khi triển khai API uỷ quyền, hãy nhớ thêm các chức năng, quyền và thuộc tính Info.plist bắt buộc vào mục tiêu Xcode:

Quyền

Thêm các mục sau vào tệp .entitlements của mục tiêu ứng dụng chính và tiện ích:

• Quản lý thông tin đăng nhập mạng Thread:

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

  Để sử dụng quyền này trong một bản dựng phân phối, bạn phải gửi biểu mẫu yêu cầu quyền cho Apple. Apple yêu cầu bạn chứng minh tư cách thành viên trong Thread Group và xác minh rằng Thread Border Router (TBR) của bạn được Thread Group chứng nhận.

• Thông tin về mạng Wi-Fi:

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

• Nhóm ứng dụng: Thêm một nhóm ứng dụng dùng chung để cho phép ứng dụng chính và Matter Tiện ích thêm thiết bị giao tiếp với nhau (ví dụ: group.com.yourdomain.appgroupname). Mã nhận dạng này do nhà phát triển tạo và đăng ký trong Apple Developer Console, đồng thời phải khớp với Nhóm ứng dụng được định cấu hình trong các chức năng mục tiêu trong Xcode. SDK Google Home sử dụng giá trị nhận dạng này trong cả hai mục tiêu để tự động đồng bộ hoá trạng thái uỷ quyền, thông tin xác thực cấu trúc và danh sách phòng bằng vùng chứa UserDefaults dùng chung.

Chia sẻ chuỗi khoá (không bắt buộc)

Nếu tiện ích ứng dụng của bạn cần truy xuất thông tin xác thực hoặc mã truy cập do ứng dụng chính lưu trữ bằng UserInfo.authorizationToken(), thì bạn phải định cấu hình một nhóm truy cập chuỗi khoá dùng chung cho cả ứng dụng chính và mục tiêu tiện ích ứng dụng trong plist quyền của các ứng dụng đó:

<key>keychain-access-groups</key>
<array>
    <string>$(AppIdentifierPrefix)your.shared.keychain.group</string>
</array>

Thuộc tính Info.plist

Thêm các khoá mô tả sau vào tệp Info.plist của mục tiêu ứng dụng chính:

• Nội dung mô tả về việc sử dụng thông tin vị trí:

  <key>NSLocationWhenInUseUsageDescription</key>
  <string>Your custom message explaining why location access is needed to read the current Wi-Fi SSID</string>
  

• Dịch vụ Bonjour: Trong NSBonjourServices, hãy thêm các dịch vụ cần thiết cho tính năng khám phá Matter và Thread cục bộ:

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

• Nội dung mô tả về mức sử dụng mạng cục bộ: Thêm khoá NSLocalNetworkUsageDescription kèm theo thông báo giải thích quyền khám phá mạng cục bộ.

Uỷ quyền thiết bị

Cách uỷ quyền thiết bị Matter:

1. Thông báo cho Home APIs iOS SDK để chuẩn bị cho các yêu cầu uỷ quyền Matter bằng structure.prepareForMatterCommissioning(). Lệnh này sẽ thực hiện những việc sau:

   • Xác minh rằng quyền đã được cấp.
   • Đảm bảo trung tâm đang kết nối mạng và có thể truy cập được.
   • Đảm bảo không có phiên uỷ quyền nào khác đang hoạt động.

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

2. Tạo yêu cầu bằng MatterAddDeviceRequest() để bắt đầu quy trình hỗ trợ Matter của Apple.

   let topology = MatterAddDeviceRequest.Topology(
     ecosystemName: "Google Home",
     homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
   )
   
   let request = MatterAddDeviceRequest(topology: topology)
   

3. Thực hiện yêu cầu bằng perform(). Nếu xảy ra lỗi, hãy huỷ yêu cầu uỷ quyền bằng 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. Tạo một App Group ID trong Apple Developer Console để cho phép ứng dụng giao tiếp với tiện ích MatterAddDevice khi uỷ quyền thiết bị.

   Bạn cũng cần cập nhật mã nhận dạng gói ứng dụng và hồ sơ cấp phép để sử dụng mã nhóm này.

5. Khi khởi chạy, hãy định cấu hình thực thể Home để sử dụng giá trị nhận dạng nhóm.

   func application(_ application: UIApplication, didFinishLaunchingWithOptions
   launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
     Home.configure {
       $0.sharedAppGroup = "group.com.sample.app.commissioning"
     }
   
     return true
   }
   

6. Triển khai Tiện ích ứng dụng Matter của iOS của Apple.

   Mã mẫu cho thấy một ví dụ về cách triển khai lớp con của MatterAddDeviceExtensionRequestHandler API của Apple.

   Tối thiểu, hãy thêm GoogleHomeMatterCommissionerSDK Framework vào mục tiêu của tiện ích và ghi đè 3 phương thức để gọi API Google Home platform (GHP)HomeMatterCommissioner.

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