Создайте мобильное приложение с использованием Home API на iOS

1. Введение

f154e30306882c74.png

Что представляют собой API для домашней страницы?

API Google Home предоставляют разработчикам набор библиотек для работы с экосистемой Google Home. С помощью API Home разработчики могут создавать приложения, которые позволяют беспрепятственно вводить в эксплуатацию и управлять устройствами умного дома.

3e11583c779a2cec.png

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

Компоненты API главной страницы

API Home состоят из:

  • API для устройств и строений : Взаимодействие с домом пользователя. Приложения могут использовать эти API для чтения информации об устройствах, комнатах и ​​строениях (например, для просмотра текущей температуры термостата) и управления устройствами (например, для изменения заданной температуры термостата).
  • API для ввода в эксплуатацию : Вводите (настраивайте) новые устройства Matter в сеть с минимальными усилиями.
  • API автоматизации : Создание, удаление и запрос автоматизаций, запущенных в домашней директории пользователя.

Предварительные требования

  • Последняя стабильная версия Xcode .
  • Аккаунт Google, к которому подключено хотя бы одно строение в домашней сети.
  • Устройство iOS с операционной системой iOS 16.4+, настроенное с использованием тестовой учетной записи.
  • Для создания профиля подготовки требуется Apple ID, зарегистрированный в программе Apple Developer Program .
  • Центр Google, поддерживающий API Home .

Что вы узнаете

  • Как создать iOS-приложение с использованием API Home, следуя лучшим практикам.
  • Как использовать API-интерфейсы Device и Structure для представления и управления умным домом.
  • Как использовать API ввода в эксплуатацию для добавления устройств в экосистему Google Home.
  • Как использовать API автоматизации для создания базовой автоматизации.

2. Обустройте свой дом

Подготовьте устройства

Google Home Playground предлагает множество предварительно настроенных эмулированных устройств умного дома и рекомендуется для изучения всего потенциала API Home, особенно если у вас ограниченное количество устройств в доме.

Следуйте инструкциям, чтобы войти в Google Home Playground и завершить привязку учетной записи в приложении Google Home . После этого вы сможете увидеть устройства на вкладке «Устройства» в приложении Google Home.

c892afce113abe8f.png

3. Настройка

Получите код примера приложения

Для начала клонируйте исходный код с GitHub:

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

В директории sample находятся две ветки, start и finished , для данного практического занятия.

  • start : Начальный код для этого проекта, в который вы будете вносить изменения для завершения выполнения практического задания.
  • finished : Завершенный код для этого практического занятия, используемый для проверки вашей работы.

Изучите начальный код.

Для начала выполнения этого практического задания переключитесь на start ветку клонированного репозитория:

git checkout start

Эта ветка содержит стартовый код проекта. Вы будете изменять этот код на протяжении всего курса, чтобы реализовать весь функционал. Пример приложения для курса предоставляет базовую структуру, созданную на Swift, для взаимодействия с iOS SDK Home API. Давайте кратко рассмотрим ключевые компоненты start проекта:

  • Main Entry (GoogleHomeAPISampleIOSApp) : Расположен в GoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift . Это основная точка входа в приложение. Она настраивает и инициализирует SDK и формирует основной пользовательский интерфейс.
  • Core Views (View/) :
    • MainView.swift : Корневой элемент представления после запуска, содержащий основной NavigationView . Он обрабатывает выбор активной структуры Google Home и отображает соответствующий StructureView .
    • StructureView.swift : Отображает содержимое выбранной структуры, используя вкладки для переключения между сеткой устройств и списком автоматизаций . Также предоставляет меню для добавления комнат или устройств.
    • DeviceView.swift : Представляет интерактивный элемент для отдельного устройства в сетке StructureView .
    • AutomationsView.swift : Отображает список существующих автоматизаций для данной структуры и предоставляет навигацию для создания или просмотра сведений об автоматизации.
  • ViewModels (ViewModel/) : Эти классы управляют состоянием и логикой представлений.
    • AccountViewModel.swift : Обрабатывает подключение к объекту Home и управляет состоянием аутентификации.
    • MainViewModel.swift : Управляет списком доступных объектов Structure и отслеживает выбранную структуру.
    • StructureViewModel.swift : Управляет отображением комнат и объектов DeviceControl в выбранной структуре.
    • AutomationList.swift , AutomationViewModel.swift и другие: обрабатывают получение, отображение, создание и управление автоматизациями.
  • Device Controls (ViewModel/Device/) :
    • DeviceControl.swift : Базовый класс для представления управляемых устройств в пользовательском интерфейсе.
    • Конкретные подклассы ( LightControl.swift , FanControl.swift , OnOffPlugInUnitControl.swift и т. д.): Реализуйте логику пользовательского интерфейса, управление устройствами и сопоставление состояний для различных типов устройств в зависимости от их характеристик.
    • DeviceControlFactory.swift : Отвечает за создание соответствующего подкласса DeviceControl для заданного HomeDevice .
  • Commissioning (Commissioning/) :
    • CommissioningManager.swift : Содержит логику управления процессом ввода в эксплуатацию устройств Matter.
  • Utilities & UX (Utils/, UX/, Storage/) : содержит вспомогательный код для элементов пользовательского интерфейса (цвета, размеры), обработки ошибок, хранения данных ( SelectedStructureStorage.swift ) и других вспомогательных функций.

В ходе этого практического занятия вы найдете комментарии, такие как TODO , закомментированные блоки кода и оповещения в start проекте. Они отмечают разделы, где вы будете добавлять или раскомментировать код для реализации необходимой функциональности, следуя предоставленным инструкциям.

Создайте файлы конфигурации развертывания Apple.

Для настройки App Attest следуйте инструкциям по созданию файлов конфигурации развертывания Apple . Обратите внимание, что после настройки приложение можно будет развернуть только на реальном устройстве, а не в симуляторе.

Настройка аутентификации

Чтобы получить идентификатор клиента OAuth и включить API Home, сначала войдите в Google Cloud и создайте новый проект или выберите существующий. Затем выполните указанные шаги для генерации идентификатора клиента OAuth, включения API Home и добавления вашей учетной записи в список разрешенных.

Настройте SDK.

Получите iOS SDK Home APIs и настройте его, следуя инструкциям по настройке, приведенным в разделе «Настройка SDK» . Не забудьте заменить HOME_API_TODO_ADD_APP_GROUP на вашу собственную группу приложений.

Соберите и запустите проект.

После сборки и запуска проекта с использованием start ветки должно появиться диалоговое окно TODO и экран с сообщением «Требуется вход в систему». Взаимодействие с API главной страницы будет реализовано в следующих разделах.

bd56b7080037e38a.png9c0f08a3f4197a77.png

Примечание : Найдите код, который необходимо изменить, выполнив поиск в проекте по тексту, отображаемому в диалоговом окне. Например, найдите "TODO: initialize Home".

4. Инициализация

Инициализация главной страницы

Перед использованием любого из API Home для iOS необходимо инициализировать Home в вашем приложении. Home — это главный интерфейс SDK, предоставляющий доступ ко всем сущностям в структуре пользователя. При запросе всех сущностей определенного типа API возвращает объект Query , который позволяет выбрать способ получения результатов. В файле GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift удалите комментарий и всплывающее окно в connect() чтобы реализовать инициализацию Home.

  /// TODO: initialize Home
  /// Remove comments to initialize Home and handling permission.
  private func connect() {
    Task {
      do {
        self.home = try await Home.connect()
      } catch {
        Logger().error("Auth error: \(error).")
      }
    }
  }

Разрешение на использование API Home

При запуске приложения появится экран подтверждения согласия. Выберите структуру Google Home и укажите учетную запись, которая находится в списке разрешенных для вашего проекта Google Cloud.

47310f458c0094d9.png4a571dbd9979a88c.pnge29c75891a3a67af.png

5. Устройства и конструкции

Получите комнаты и устройства

В файле GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift удалите комментарий и всплывающее окно в методе getRoomsAndDevices() чтобы получить комнаты и устройства в выбранной структуре с помощью home.rooms() и home.devices() соответственно.

  /// TODO: get rooms and devices
  /// Remove comments to get the rooms and devices from home entry
  private func getRoomsAndDevices(){
    self.home.rooms().batched()
      .combineLatest(self.home.devices().batched())
      .receive(on: DispatchQueue.main)
      .catch { error in
        Logger().error("Failed to load rooms and devices: \(error)")
        return Just((Set<Room>(), Set<HomeDevice>()))
      }
      .map { [weak self] rooms, devices in
        guard let self = self else { return [] }
        self.hasLoaded = true
        return self.process(rooms: rooms, devices: devices)
      }
      /// receive from .map and .assign() to publisher entries
      .assign(to: &self.$entries)
  }

Функция process() сначала убеждается, что устройства находятся в одной комнате, прежде чем заставить их взаимодействовать как HomeDevices используя DeviceControl и DeviceControlFactory .

4c677c4c294e67ca.png

Примечание : Если ваше устройство отсутствует в списке DeviceControlFactory , оно будет отображаться как «Неподдерживаемое». Чтобы узнать больше о поддерживаемых устройствах, см. страницу «Поддерживаемые типы устройств в iOS ».

Взаимодействие с устройством

При касании или перемещении по устройствам розетка outlet1 изначально неактивна. Чтобы включить взаимодействие с ней, найдите файл GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift и удалите комментарий и всплывающее окно в функции primaryAction() .

  /// TODO: primary action of OnOffPlug
  /// Toggles the plug; usually provided as the `action` callback on a Button.
  public override func primaryAction() {
    self.updateTileInfo(isBusy: true)
    Task { @MainActor [weak self] in
      guard
        let self = self,
        let onOffPluginUnitDeviceType = self.onOffPluginUnitDeviceType,
        let onOffTrait = onOffPluginUnitDeviceType.matterTraits.onOffTrait
      else { return }

      do {
        try await onOffTrait.toggle()
      } catch {
        Logger().error("Failed to to toggle OnOffPluginUnit on/off trait: \(error)")
        self.updateTileInfo(isBusy: false)
      }
    }
  }

Функция primaryAction() , расположенная в классе OnOffPlugInUnitControl , переключает состояние включения/выключения умной розетки или любого устройства, представленного типом OnOffPluginUnitDeviceType .

Дополнительные примеры управления устройством доступны в GoogleHomeAPISampleIOS/ViewModel/Device .

Создать новую комнату

API структуры позволяет создавать и удалять комнаты, а также перемещать устройства между комнатами.

В файле GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift удалите комментарий и всплывающее окно в addRoom() .

  /// TODO: add room
  /// Add a new room in a given structure.
  func addRoom(name: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.createRoom(name: name)
      } catch {
        Logger().error("Failed to create room: \(error)")
      }
    }
  }

Чтобы создать новую комнату с помощью structure.createRoom() , перейдите в верхний левый угол и выберите значок "+" > Добавить комнату . Введите название новой комнаты и нажмите "Создать комнату". Новая комната появится через несколько секунд.

b122ae6642b7da1c.pnga45f785e1d51938e.png7753b56cbdcff8d6.png

Переместите устройство в другую комнату.

В файле GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift удалите комментарий и всплывающее окно в moveDevice() .

  /// TODO: move device
  /// Move a device into a different room.
  func moveDevice(device deviceID: String, to roomID: String, structure: Structure) {
    Task {
      do {
        _ = try await structure.move(device: deviceID, to: roomID)
      } catch {
        Logger().error("Failed to move to room: \(error)")
      }
    }
  }

Чтобы переместить устройство с помощью structure.move() , нажмите и удерживайте его, выберите «Переместить в другую комнату» и выберите новую комнату.

f9627592af44163d.pngfd126fabb454f2bf.png813e1e23e50cd9f6.png

Удалить пустую комнату

В файле GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift удалите комментарий и всплывающее окно в removeRoom() .

  /// TODO: delete room
  /// Delete an empty room in a given structure.
  func removeRoom(id: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.deleteRoom(id: id)
      } catch {
        Logger().error("Failed to remove room: \(error)")
      }
    }
  }

Чтобы удалить пустую комнату с помощью structure.deleteRoom() , щелкните значок корзины справа от названия комнаты и подтвердите действие. Обратите внимание, что удалять можно только пустые комнаты.

4f129262ad67f564.png

Примечание : Чтобы создать пустое помещение, переместите устройство назад.

6. Ввод в эксплуатацию

Примечание : Для этого раздела необходимы Google Hub и устройство Matter. Убедитесь, что Google Hub в вашем здании подключен к сети и доступен. Если у вас нет устройства Matter, попробуйте использовать приложение Matter Virtual Device .

Добавить устройство Matter

API для ввода устройств в эксплуатацию позволяет вашему приложению добавлять новые устройства Matter в домашнюю папку пользователя и его учетную запись Google. Это обеспечивает удобную настройку непосредственно в вашем приложении.

В файле GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift удалите комментарий и всплывающее окно в addMatterDevice() .

  /// TODO: add Matter Device
  /// Starts the Matter device commissioning flow to add the device to the user's home.
  /// - Parameters:
  ///   - structure: The structure to add the device to.
  ///   - add3PFabricFirst: Whether to add the device to a third party fabric first.
  public func addMatterDevice(to structure: Structure, add3PFabricFirst: Bool) {
    self.isCommissioning = true

    /// pass if it's 1p or 3p commissioning
    let userDefaults = UserDefaults(
      suiteName: CommissioningManager.appGroup)
    userDefaults?.set(
    add3PFabricFirst, forKey: CommissioningUserDefaultsKeys.shouldPerform3PFabricCommissioning)

    Task {
      do {
        try await structure.prepareForMatterCommissioning()
      } catch {
        Logger().error("Failed to prepare for Matter Commissioning: \(error).")
        self.isCommissioning = false
        return
      }

      // Prepare the Matter request by providing the ecosystem name and home to be added to.
      let topology = MatterAddDeviceRequest.Topology(
        ecosystemName: "Google Home",
        homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
      )
      let request = MatterAddDeviceRequest(topology: topology)

      do {
        Logger().info("Starting MatterAddDeviceRequest.")
        try await request.perform()
        Logger().info("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).")
      }

      self.isCommissioning = false
    }
  }

Чтобы создать новую комнату с помощью structure.prepareForMatterCommissioning() , перейдите в верхний левый угол и выберите значок "+" > Добавить устройство в Google Fabric . Для добавления устройства Matter в вашу комнату используется MatterAddDeviceRequest . После выбора комнаты и имени устройства оно отобразится на экране "Устройства".

adf6cbb531787aaf.pngf002bd6320bc480d.png

7. Автоматизация

Просмотреть все автоматизации в структуре

Нажмите на «Автоматизация» в нижней панели навигации. Отобразится список всех автоматизаций в вашей структуре с помощью structure.listAutomations() .

cc6d50f72f812c24.png

Примечание : Если у вас не настроены никакие системы домашней автоматизации, вы увидите сообщение «Добавьте автоматизацию, чтобы начать».

Создайте автоматизацию

Теперь, когда вы знакомы с API устройств и структур, а также с добавлением нового устройства, пришло время создать новую автоматизацию с помощью API автоматизации .

В GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift удалите комментарий, всплывающее окно и пустую автоматизацию в lightAutomation() . 

  /// TODO: create automation
  /// - Parameter devices: devices in current selected structure
  /// - Returns: the automation object to be created
  /// This automation will turn off the light after 5 seconds.
  public func lightAutomation(devices: Set<HomeDevice>) async throws -> any DraftAutomation {
    let light = devices.first { $0.name == "light2" }
    
    guard let light else {
      Logger().error("Unable to find light device with name light2")
      throw HomeError.notFound("No devices support OnOffLightDeviceType")
    }
    
    return automation(
      name: "Turn off light after 5 seconds",
      description:
        """
        Turns off light2 after it has been on for 5 seconds.
        """
    ) {
      let onOffStarter = starter(light, OnOffLightDeviceType.self, OnOffTrait.self)
      onOffStarter
      condition {
        onOffStarter.onOff.equals(true)
      }
      delay(for: Duration.seconds(5))
      action(light, OnOffLightDeviceType.self) {
        OnOffTrait.off()
      }
    }
  }

Чтобы создать автоматизацию, которая будет выключать свет через пять секунд после включения, перейдите в представление автоматизации и нажмите кнопку « + Добавить ». Затем выберите « Выключать свет через 5 секунд ». Отобразятся сведения об автоматизации, включая starter , condition и action . Нажмите « Сохранить », чтобы создать автоматизацию с помощью structure.createAutomation() .

21c1f8ea2a29134b.png4bd36f6ed9c5f6e9.png

Примечание : Доступные сценарии автоматизации зависят от устройств в вашем доме. Если вы не видите доступных сценариев автоматизации, попробуйте переименовать устройство управления освещением в "light2".

Вернитесь на вкладку «Устройства» и включите индикатор с названием «light2». Он автоматически выключится через пять секунд.

Компонентами автоматизации являются:

  • Стартер: Это событие, которое запускает автоматизацию. В этом примере автоматизация запустится при изменении параметра OnOffTrait .
  • Условие: Эта проверка проверяет, соответствует ли пусковое устройство определенным требованиям. В этом случае автоматизация будет выполнена, если свет горит.
  • Действие: Это автоматическое действие, которое вы хотите выполнить, но только если пусковое устройство соответствует требованиям. Если условия выполнены, свет будет выключен.

Дополнительные примеры можно найти на странице «Примеры автоматизации» .

Удалить автоматизацию

Метод structure.deleteAutomation() вызывается, когда вы проводите пальцем влево по существующей автоматизации и нажимаете на значок корзины, чтобы удалить ее из структуры.

dc678cd9e16f89a5.png

8. Поздравляем!

Поздравляем! Вы успешно создали простое приложение для умного дома, используя API Home для iOS.

Ваши достижения :

  • Инициализация : Ваше приложение подключено к экосистеме Google Home с помощью Home.connect() .
  • Права доступа : Обеспечена аутентификация и авторизация пользователей для доступа к данным домашней страницы.
  • Устройства и структуры : Получение и отображение комнат и устройств с помощью home.rooms() и home.devices() .
  • Управление устройством : Реализовано взаимодействие с устройством, например, переключение состояния OnOffPluginUnitDeviceType путем вызова команд для его характеристик.
  • Управление структурой : Добавлена ​​функциональность для создания новых комнат ( structure.createRoom() ), перемещения устройств между комнатами ( structure.move() ) и удаления пустых комнат ( structure.deleteRoom() ).
  • Ввод в эксплуатацию : Интегрирован процесс ввода в эксплуатацию SDK для добавления новых устройств Matter ( MatterAddDeviceRequest ).
  • Автоматизация : Рассмотрены способы перечисления, создания ( structure.createAutomation() ) и удаления ( structure.deleteAutomation() ) автоматизаций внутри структуры.

Теперь у вас есть базовое понимание того, как использовать API Home для создания многофункциональных интерфейсов управления умным домом на iOS.

Следующие шаги :

  • Изучите возможности управления другими типами устройств, представленными в демонстрационном приложении (освещение, вентиляторы, жалюзи и т. д.).
  • Подробнее изучите различные характеристики и команды, доступные для разных устройств.
  • Поэкспериментируйте с созданием более сложных автоматизаций, используя различные заставки, условия и действия.
  • Для получения более подробной информации о расширенных функциях и возможностях обратитесь к документации по API Home .

Отличная работа!