1. 소개
Home API란 무엇인가요?
Google Home API는 개발자가 Google Home 생태계를 활용할 수 있는 라이브러리 세트를 제공합니다. 개발자는 Home API를 사용하여 스마트 홈 기기를 원활하게 커미셔닝하고 제어하는 앱을 빌드할 수 있습니다.
이 동영상에서는 빌드할 모바일 앱을 간략하게 둘러보므로 Codelab을 진행하면서 동영상을 따라하세요.
Home API 구성요소
Home API는 다음으로 구성됩니다.
- 기기 및 구조 API: 사용자의 홈과 상호작용합니다. 앱은 이러한 API를 사용하여 기기, 방, 구조에 관한 정보를 읽고 (예: 현재 온도 조절기 온도 확인) 기기를 제어할 수 있습니다 (예: 온도 조절기 설정값 변경).
- 커미셔닝 API: 최소한의 노력으로 새 Matter 기기를 패브릭에 커미셔닝 (설정)합니다.
- 자동화 API: 사용자의 홈에서 실행되는 자동화를 생성, 삭제, 쿼리합니다.
기본 요건
- Xcode의 최신 안정화 버전
- 홈에 구조가 하나 이상 있는 Google 계정
- 테스트 계정으로 설정된 iOS 16.4 이상을 실행하는 iOS 기기
- 프로비저닝 프로필을 생성하기 위해 Apple Developer Program에 등록된 Apple ID
- Home API를 지원하는 Google 허브
학습할 내용
- 권장사항을 사용하여 Home API로 iOS 앱을 빌드하는 방법
- 기기 및 구조 API를 사용하여 스마트 홈을 표현하고 제어하는 방법
- 커미셔닝 API를 사용하여 기기를 Google Home 생태계에 추가하는 방법
- Automation API를 사용하여 기본 자동화를 만드는 방법
2. 홈 설정
기기 준비
Google Home Playground는 다양한 사전 빌드된 에뮬레이션 스마트 홈 기기를 제공하며, 특히 집에 기기가 제한적으로 있는 경우 Home API의 잠재력을 최대한 활용하는 데 권장됩니다.
안내에 따라 Google Home Playground에 로그인하고 Google Home 앱에서 계정 연결을 완료합니다. 완료되면 Google Home 앱의 '기기' 탭에 기기가 표시됩니다.
3. 설정
샘플 앱 코드 가져오기
먼저 GitHub에서 소스 코드를 클론합니다.
git clone https://github.com/google-home/google-home-api-sample-app-ios.git
샘플 디렉터리에는 이 Codelab의 두 브랜치 start와 finished가 포함되어 있습니다.
start: 이 프로젝트의 시작 코드로, 이 코드를 변경하여 Codelab을 완료합니다.finished: 이 Codelab의 완료 코드입니다. 작업 확인에 사용됩니다.
'시작' 코드 살펴보기
클론된 저장소의 start 브랜치로 전환하여 이 Codelab을 시작합니다.
git checkout start
이 브랜치에는 프로젝트의 시작 코드가 포함되어 있습니다. Codelab을 진행하면서 이 코드를 수정하여 전체 기능을 구현합니다. Codelab 샘플 앱은 Home APIs iOS SDK와 상호작용하기 위해 Swift로 빌드된 기본 구조를 제공합니다. 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: UI에서 제어 가능한 기기를 나타내는 기본 클래스입니다.- 특정 하위 클래스 (
LightControl.swift,FanControl.swift,OnOffPlugInUnitControl.swift등): 특성을 기반으로 다양한 기기 유형의 UI 로직, 기기 제어, 상태 매핑을 구현합니다. DeviceControlFactory.swift: 지정된HomeDevice에 적합한DeviceControl서브클래스를 만듭니다.
Commissioning (Commissioning/):CommissioningManager.swift: Matter 기기 커미셔닝 흐름을 관리하는 로직이 포함되어 있습니다.
Utilities & UX (Utils/, UX/, Storage/): UI 요소 (색상, 크기), 오류 처리, 데이터 저장소 (SelectedStructureStorage.swift), 기타 유틸리티의 도우미 코드를 포함합니다.
이 Codelab 전반에 걸쳐 TODO와 같은 주석이나 주석 처리된 코드 블록, start 프로젝트 내 알림이 표시됩니다. 이러한 주석은 제공된 단계에 따라 필요한 기능을 구현하기 위해 코드를 추가하거나 주석 해제할 섹션을 표시합니다.
Apple 배포 구성 파일 만들기
App Attest를 구성하려면 Apple 배포 구성 파일 만들기에 관한 안내를 따르세요. 설정 후에는 시뮬레이터가 아닌 실제 기기에만 앱을 배포할 수 있습니다.
인증 설정
OAuth 클라이언트 ID를 가져오고 Home API를 사용 설정하려면 먼저 Google Cloud에 로그인하고 새 프로젝트를 만들거나 기존 프로젝트를 선택합니다. 그런 다음 제공된 단계에 따라 OAuth 클라이언트 ID를 생성하고 Home API를 사용 설정한 후 계정을 허용 목록에 추가합니다.
SDK 설정
SDK 설정에 제공된 설정 안내를 참고하여 Home APIs iOS SDK를 획득하고 구성합니다. HOME_API_TODO_ADD_APP_GROUP을 자체 앱 그룹으로 바꿔야 합니다.
프로젝트 빌드 및 실행
start 브랜치로 프로젝트를 빌드하고 실행하면 TODO 대화상자와 '로그인 필요'가 표시된 화면이 표시됩니다. Home API 상호작용은 다음 섹션에서 구현됩니다.
참고: 대화상자에 표시된 텍스트로 프로젝트를 검색하여 수정해야 하는 코드를 찾습니다. 예를 들어 'TODO: initialize Home'을 검색합니다.
4. 초기화
Home 초기화
iOS용 Home API를 사용하기 전에 앱에서 Home를 초기화해야 합니다. Home는 SDK의 최상위 항목이며 사용자 구조의 모든 항목에 대한 액세스를 제공합니다. 특정 유형의 모든 항목을 요청하면 API는 결과를 수신하는 방법을 선택할 수 있는 Query 객체를 반환합니다. GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift에서 connect()의 주석과 알림을 삭제하여 홈 초기화를 구현합니다.
/// 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).")
}
}
}
Home API 사용 권한
앱을 실행하면 동의 화면이 표시됩니다. Google Home 구조를 선택하고 Google Cloud 프로젝트의 허용 목록에 있는 계정을 선택합니다.
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() 함수는 먼저 기기가 동일한 방에 있는지 확인한 후 DeviceControl 및 DeviceControlFactory을 사용하여 기기가 HomeDevices으로 상호작용하도록 합니다.
참고: 기기가 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)
}
}
}
OnOffPlugInUnitControl 클래스 내에 있는 primaryAction() 함수는 스마트 플러그 또는 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()로 새 회의실을 만들려면 왼쪽 상단으로 이동하여 '+' 아이콘 > 회의실 추가를 선택합니다. 새 채팅방 이름을 입력하고 '채팅방 만들기'를 클릭합니다. 새 방은 몇 초 후에 표시됩니다.
기기를 다른 방으로 이동하기
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()가 있는 기기를 재배치하려면 기기를 길게 누르고 '다른 방으로 이동'을 선택한 후 새 방을 선택합니다.
빈 회의실 삭제
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()이 있는 빈 채팅방을 삭제하려면 채팅방 이름 오른쪽에 있는 휴지통 아이콘을 클릭하고 작업을 확인합니다. 비어 있는 회의실만 삭제할 수 있습니다.
참고: 기기를 다시 이동하여 빈 방을 만듭니다.
6. 커미셔닝
참고: 이 섹션에는 Google 허브와 Matter 기기가 필요합니다. 구조의 Google 허브가 온라인 상태이고 연결할 수 있는지 확인합니다. Matter 기기가 없는 경우 Matter 가상 기기 앱을 대신 사용해 보세요.
Matter 기기 추가
커미셔닝 API를 사용하면 앱에서 사용자의 홈 및 Google 계정에 새로운 Matter 기기를 추가할 수 있습니다. 이를 통해 앱 내에서 바로 원활한 설정 환경을 제공할 수 있습니다.
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 패브릭에 기기 추가를 선택합니다. MatterAddDeviceRequest을 사용하여 Matter 기기를 방에 추가합니다. 방과 기기 이름을 선택하면 '기기' 화면에 기기가 표시됩니다.
7. 자동화
구조의 모든 자동화 보기
하단 탐색 메뉴에서 자동화를 탭합니다. structure.listAutomations()를 사용하면 구조의 모든 자동화가 나열됩니다.
참고: 홈 자동화를 설정하지 않은 경우 '자동화를 추가하여 시작하세요'라는 메시지가 표시됩니다.
자동화 만들기
이제 기기 및 구조 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초 후에 조명을 끄는 자동화를 만들려면 자동화 뷰로 이동하여 '+ 추가' 버튼을 클릭합니다. 그런 다음 '5초 후에 조명 끄기'를 선택합니다. starter, condition, action를 비롯한 자동화 세부정보가 표시됩니다. '저장'을 클릭하여 structure.createAutomation()로 자동화를 만듭니다.
참고: 사용할 수 있는 자동화는 홈에 있는 기기에 따라 다릅니다. 사용 가능한 자동화가 표시되지 않으면 조명 기기의 이름을 'light2'로 변경해 보세요.
'기기' 탭으로 돌아가서 'light2'라는 조명을 켭니다. 5초 후에 자동으로 꺼집니다.
자동화의 구성요소는 다음과 같습니다.
- 시작 조건: 자동화를 시작하는 이벤트입니다. 이 예에서는
OnOffTrait에 변경사항이 있으면 자동화가 시작됩니다. - 조건: 시작 기기가 특정 요구사항을 충족하는지 확인합니다. 이 경우 조명이 켜져 있으면 자동화가 실행됩니다.
- 작업: 시작 조건이 요구사항을 충족하는 경우에만 실행할 자동화입니다. 조건이 충족되면 조명이 꺼집니다.
추가 예시는 자동화 예시 페이지를 참고하세요.
자동화 삭제
structure.deleteAutomation() 메서드는 기존 자동화를 왼쪽으로 스와이프하고 휴지통 아이콘을 탭하여 구조에서 삭제할 때 호출됩니다.
8. 축하합니다
축하합니다. iOS용 Home API를 사용하여 기본 스마트 홈 앱을 성공적으로 빌드했습니다.
달성한 내용:
- 초기화:
Home.connect()를 사용하여 앱을 Google Home 생태계에 연결했습니다. - 권한: 홈 데이터 액세스를 위한 사용자 인증 및 승인을 처리했습니다.
- 기기 및 구조:
home.rooms()및home.devices()를 사용하여 방과 기기를 가져와 표시했습니다. - 기기 제어: 특성에서 명령어를 호출하여
OnOffPluginUnitDeviceType의 상태를 전환하는 등 기기 상호작용을 구현했습니다. - 구조 관리: 새 방 만들기 (
structure.createRoom()), 방 간 기기 이동 (structure.move()), 빈 방 삭제 (structure.deleteRoom()) 기능이 추가되었습니다. - 커미셔닝: SDK의 커미셔닝 흐름을 통합하여 새로운 Matter 기기 (
MatterAddDeviceRequest)를 추가했습니다. - 자동화: 구조 내에서 자동화를 나열하고, 만들고 (
structure.createAutomation()), 삭제 (structure.deleteAutomation())하는 방법을 살펴봤습니다.
이제 Home API를 활용하여 iOS에서 풍부한 스마트 홈 제어 환경을 빌드하는 방법을 기본적인 수준에서 이해했습니다.
다음 단계:
- 샘플 앱에 제공된 다른 기기 유형 (조명, 선풍기, 블라인드 등)을 제어해 보세요.
- 다양한 기기에서 사용할 수 있는 다양한 특성과 명령어를 자세히 알아보세요.
- 다양한 시작 조건, 조건, 작업을 사용하여 더 복잡한 자동화를 만들어 보세요.
- 고급 기능 및 세부정보는 Home API 문서를 참고하세요.
잘하셨습니다.