將新的 Matter 裝置新增至住家

iOS 適用的 Home API 會使用 Matter 中樞，將裝置委託至 Fabric。在委任期間，應用程式會將指令傳送至 SDK，然後傳送至中樞。

Xcode 專案設定

   在 iOS 範例應用程式中導入   

實作 Commissioning API 之前，請務必在 Xcode 目標中新增必要的功能、授權和 Info.plist 屬性：

授權

在主要應用程式目標和擴充功能的 .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)。 這個 ID 是由開發人員在 Apple Developer Console 中建立及註冊，且必須與 Xcode 目標功能中設定的應用程式群組相符。Google Home SDK 會在兩個目標中使用這個 ID，透過共用的 UserDefaults 容器，自動同步處理調試狀態、Fabric 憑證和房間清單。

鑰匙圈共用 (選用)

如果應用程式擴充功能需要使用 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，準備使用structure.prepareForMatterCommissioning()處理Matter委託要求。這段指令會執行下列動作：

    • 確認已授予權限。
    • 確認中樞已連上網路且可連線。
    • 確認沒有其他進行中的委任工作階段。
    do {
  try await structure.prepareForMatterCommissioning()
} catch {
  // Failed to prepare for Matter Commissioning
  return
}

  2. 使用 MatterAddDeviceRequest() 建立要求，啟動 Apple 的 Matter 支援流程。

    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. 在 Apple Developer Console 中建立 App Group ID，允許應用程式在委託裝置時與 MatterAddDevice 擴充功能通訊。

    您也需要更新應用程式軟體包 ID 和佈建設定檔，才能使用這個群組 ID。

  5. 初始化時，請將 Home 例項設為使用群組 ID。

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

  return true
}

  6. 導入 Apple 的 iOS Matter 應用程式擴充功能。

    程式碼範例顯示如何實作 Apple MatterAddDeviceExtensionRequestHandler API 的子類別。

    至少要將 GoogleHomeMatterCommissionerSDK 架構新增至擴充功能目標，並覆寫三種方法來呼叫 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
    }
  }
}