Einem Zuhause neue Matter-Geräte hinzufügen

Die Home APIs für iOS verwenden einen Matter-Hub, um ein Gerät in einer Fabric in Betrieb zu nehmen. Während der Inbetriebnahme sendet die App einen Befehl an das SDK und dann an den Hub.

So nehmen Sie ein Matter-Gerät in Betrieb:

  1. Informieren Sie den Home APIs iOS SDK, dass er sich auf Matter-Inbetriebnahmeanfragen bei structure.prepareForMatterCommissioning() vorbereiten soll. Mit diesem Befehl wird Folgendes ausgeführt:

    • Prüfen Sie, ob die Berechtigung erteilt wurde.
    • Prüfen Sie, ob der Hub online und erreichbar ist.
    • Es darf keine andere aktive Einrichtungssitzung laufen.
    do {
  try await structure.prepareForMatterCommissioning()
} catch {
  Logger.error("Failed to prepare for Matter Commissioning: \(error).")
  return
}

  2. Erstelle eine Anfrage mit MatterAddDeviceRequest(), um den Matter-Supportablauf von Apple zu starten.

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

let request = MatterAddDeviceRequest(topology: topology)

  3. Führen Sie die Anfrage mit perform() aus. Wenn ein Fehler auftritt, storniere die Inbetriebnahmeanfrage mit structure.cancelMatterCommissioning().

    do {
  Logger.info("Starting MatterAddDeviceRequest.")
  try await request.perform()
  Logger.info("Successfully completed MatterAddDeviceRequest.")
  let commissionedDeviceIDs = try structure.completeMatterCommissioning()
  Logger.info("Commissioned device IDs: \(commissionedDeviceIDs).")
} catch let error {
  structure.cancelMatterCommissioning()
  Logger.error("Failed to complete MatterAddDeviceRequest: \(error).")
}

  4. Erstellen Sie in der Apple Developer Console eine App Group ID, damit die App bei der Inbetriebnahme des Geräts mit der MatterAddDevice-Erweiterung kommunizieren kann.

    Außerdem müssen Sie die Kennung des Anwendungspakets und die Bereitstellungsprofile aktualisieren, um diese Gruppen-ID zu verwenden.

  5. Konfigurieren Sie die Home-Instanz bei der Initialisierung so, dass die Gruppen-ID verwendet wird.

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

  return true
}

  6. Implementiere die iOS-Matter-App-Erweiterung von Apple.

    Der Beispielcode zeigt die Implementierung einer Unterklasse der MatterAddDeviceExtensionRequestHandler API von Apple.

    Fügen Sie dem Erweiterungsziel mindestens das GoogleHomeMatterCommissionerSDK-Framework hinzu und überschreiben Sie drei Methoden, um die Google Home platformHomeMatterCommissioner APIs aufzurufen.

    • commissionDevice
    • rooms
    • configureDevice
    import MatterSupport
import GoogleHomeMatterCommissionerSDK
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 {
    Logger.info("Commission Matter device with payload: '\(onboardingPayload)'.")

    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()
      Logger.info("Returning \(fetchedRooms.count) fetched rooms.")
      return fetchedRooms
    } catch {
      Logger.info("Failed to fetch rooms with error: \(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 {
    Logger.info("Configure Device name: '\(name)', room: \(room?.displayName ?? "").")
    do {
      let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
      await homeMatterCommissioner.configureMatterDevice(
        deviceName: name, roomName: room?.displayName)
    } catch {
      Logger.info("Configure Device failed with error: \(error).")
    }
  }
}