Добавьте в дом новые устройства Matter

API Home для iOS используют хаб Matter для ввода устройства в эксплуатацию. Во время ввода в эксплуатацию приложение отправляет команду в SDK, а затем в хаб.

конфигурация проекта Xcode

Прежде чем внедрять API ввода в эксплуатацию, убедитесь, что вы добавили необходимые возможности, права доступа и свойства Info.plist в ваши цели Xcode:

Права

Включите следующие записи в файлы .entitlements вашего основного приложения и расширения:

  • Управление сетевыми учетными данными потоков:

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

    Для использования этого разрешения в распределенной сборке необходимо отправить запрос на получение разрешения в Apple. Apple требует подтверждения членства в группе Thread Group и проверки того, что ваш маршрутизатор Thread Border Router сертифицирован этой группой.

  • Информация о Wi-Fi:

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

  • Группы приложений: добавьте общую группу приложений, чтобы ваше основное приложение и расширение Matter Add Device Extension могли взаимодействовать (например, group.com.yourdomain.appgroupname ). Этот идентификатор создается и регистрируется разработчиком в его консоли разработчика Apple и должен совпадать с группой приложений, настроенной в целевых возможностях в Xcode. SDK Google Home использует этот идентификатор в обоих целевых приложениях для автоматической синхронизации состояния ввода в эксплуатацию, учетных данных Fabric и списков комнат с помощью общего контейнера UserDefaults .

Совместное использование связки ключей (необязательно)

Если вашему расширению приложения необходимо получать учетные данные или токены доступа, хранящиеся в основном приложении, с помощью 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 о необходимости подготовки к запросам на ввод в эксплуатацию Matter с помощью structure.prepareForMatterCommissioning() . Эта команда выполнит следующие действия:

    • Убедитесь, что разрешение получено.
    • Убедитесь, что центр управления находится в сети и доступен.
    • Убедитесь, что в данный момент не ведется никаких других активных процедур ввода в эксплуатацию. 
    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. Создайте App Group ID в консоли разработчика Apple , чтобы разрешить приложению взаимодействовать с расширением MatterAddDevice при вводе устройства в эксплуатацию.

    Вам также потребуется обновить идентификатор пакета приложения и профили подготовки, чтобы использовать этот идентификатор группы.

  5. При инициализации настройте экземпляр Home для использования идентификатора группы.

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

  return true
}

  6. Внедрите расширение для iOS-приложения Matter от Apple.

    В приведенном примере кода показана реализация подкласса API MatterAddDeviceExtensionRequestHandler от Apple.

    Как минимум, добавьте фреймворк GoogleHomeMatterCommissionerSDK в целевой объект расширения и переопределите три метода для вызова API Google Home platform 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
    }
  }
}