Aggiungere nuovi dispositivi Matter a una casa

Le API Home per iOS utilizzano un hub Matter per mettere in servizio un dispositivo in un'infrastruttura. Durante la messa in servizio, l'app invia un comando all'SDK e poi all'hub.

Per eseguire la messa in servizio di un dispositivo Matter:

  1. Comunica a Home APIs iOS SDK di prepararsi alle richieste di messa in servizio di Matter con structure.prepareForMatterCommissioning(). Questo comando eseguirà le seguenti operazioni:

    • Verifica che l'autorizzazione sia stata concessa.
    • Assicurati che l'hub sia online e raggiungibile.
    • Assicurati che non sia in corso un'altra sessione di messa in servizio.
    do {
  try await structure.prepareForMatterCommissioning()
} catch {
  Logger.error("Failed to prepare for Matter Commissioning: \(error).")
  return
}

  2. Crea una richiesta con MatterAddDeviceRequest() per avviare il flusso di assistenza Matter di Apple.

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

let request = MatterAddDeviceRequest(topology: topology)

  3. Esegui la richiesta con perform(). Se si verifica un errore, annulla la richiesta di messa in servizio con 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. Crea un App Group ID in Apple Developer Console per consentire all'app di comunicare con l'estensione MatterAddDevice durante la messa in servizio del dispositivo.

    Dovrai anche aggiornare l'identificatore del bundle dell'applicazione e i profili di provisioning per utilizzare questo ID gruppo.

  5. Durante l'inizializzazione, configura l'istanza Home in modo che utilizzi l'identificatore del gruppo.

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

  return true
}

  6. Implementa l'estensione per app Matter per iOS di Apple.

    Il codice di esempio mostra un esempio di implementazione di una sottoclasse dell'API MatterAddDeviceExtensionRequestHandler di Apple.

    Aggiungi almeno il framework GoogleHomeMatterCommissionerSDK al target dell'estensione e sostituisci tre metodi per chiamare le API Google Home platformHomeMatterCommissioner.

    • 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).")
    }
  }
}