Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Aggiungere nuovi dispositivi Matter a una casa

Le API Home per iOS utilizzano un Matter hub per configurare un dispositivo su un fabric. Durante la configurazione, l'app invia un comando all'SDK e poi all'hub.

Configurazione del progetto Xcode

Prima di implementare l'API Commissioning, assicurati di aggiungere le funzionalità, i diritti e le proprietà Info.plist richiesti ai target Xcode:

Diritti

Includi le seguenti voci nei file .entitlements del target dell'app principale e dell'estensione:

Gestione delle credenziali di rete Thread:
```
<key>com.apple.developer.networking.manage-thread-network-credentials</key>
<true/>
```
Per utilizzare questo diritto in una build distribuita, devi inviare un modulo di richiesta di diritti ad Apple. Apple richiede di dimostrare l'appartenenza al Thread Group e di verificare che il Thread Border Router (TBR) sia certificato dal Thread Group.

Informazioni sulla rete Wi-Fi:

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

Gruppi di app: aggiungi un gruppo di app condiviso per consentire all'app principale e all' Matter estensione Add Device di comunicare (ad es. group.com.yourdomain.appgroupname). Questo identificatore viene creato e registrato dallo sviluppatore nella sua Apple Developer Console e deve corrispondere al gruppo di app configurato nelle funzionalità di destinazione in Xcode. L'SDK Google Home utilizza questo identificatore in entrambi i target per sincronizzare automaticamente lo stato di configurazione, le credenziali del fabric e gli elenchi di stanze utilizzando un container UserDefaults condiviso.

Condivisione del portachiavi (facoltativa)

Se l'estensione dell'app deve recuperare le credenziali o i token di accesso archiviati dall'app principale utilizzando UserInfo.authorizationToken(), devi configurare un gruppo di accesso al portachiavi condiviso per i target dell'app principale e dell'estensione dell'app nei relativi file plist dei diritti:

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

Proprietà Info.plist

Includi le seguenti chiavi di descrizione nel file Info.plist del target dell'app principale:

Descrizione dell'utilizzo della posizione:

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

Servizi Bonjour: In NSBonjourServices, includi i servizi richiesti per l'individuazione locale di Matter e Thread:

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

Descrizione dell'utilizzo della rete locale: includi la chiave NSLocalNetworkUsageDescription con un messaggio che spiega le autorizzazioni di individuazione della rete locale.

Configurare un dispositivo

Per configurare un dispositivo Matter:

Notifica al Home APIs iOS SDK di prepararsi per le richieste di configurazione Matter con structure.prepareForMatterCommissioning(). Questo comando:
- 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 configurazione attiva.
```
do {
  try await structure.prepareForMatterCommissioning()
} catch {
  // Failed to prepare for Matter Commissioning
  return
}
```

Crea una richiesta con MatterAddDeviceRequest() per avviare il flusso di supporto di Apple's Matter.

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

let request = MatterAddDeviceRequest(topology: topology)

Esegui la richiesta con perform(). Se si verifica un errore, annulla la richiesta di configurazione con 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.
}

Crea un App Group ID nella Apple Developer Console per consentire all'app di comunicare con l'estensione MatterAddDevice durante la configurazione del dispositivo.

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

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
}

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

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

Come minimo, aggiungi il framework GoogleHomeMatterCommissionerSDK al target dell'estensione ed esegui l'override di tre metodi per chiamare le API Google Home platformHomeMatterCommissioner.

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