기기 API는 iOS용 Home API를 통해 액세스할 수 있습니다. 다음 패키지를 앱으로 가져옵니다.
import GoogleHomeSDK
import GoogleHomeTypes
자세한 내용은 iOS의 데이터 모델을 참고하세요.
오류 처리
Home API의 일부 메서드는 HomeError
를 발생시키므로 do-catch
블록을 사용하여 이러한 호출에서 HomeError
를 포착하는 것이 좋습니다.
HomeError
를 처리할 때는 code
및 message
필드를 확인하여 무엇이 잘못되었는지 알아봅니다.
처리되지 않은 오류가 있으면 앱이 비정상 종료됩니다.
자세한 내용은 오류 처리를 참고하세요.
예시는 기기에 명령어 전송을 참고하세요.
샘플 호출
기기 목록 가져오기
Home
객체에 대한 참조를 사용하여 devices()
를 호출하여 액세스 가능한 기기의 Query
를 가져옵니다.
모든 기기 메타데이터 변경사항과 함께 홈의 현재 상태를 반영하는 Set을 내보내는 Query
의 batched()
메서드를 호출합니다. 또는 Query.list()
을 호출하여 사용 가능한 기기의 스냅샷을 가져옵니다. batched()
스트림을 구독하고 처음 방출된 값을 반환하는 편의 메서드입니다.
Query.stream()
는 이름, 방, 구조와 같은 기기 메타데이터 변경사항에 따라 새 값을 방출하는 스트림을 생성합니다. 내부적으로는 batched()
를 사용하며 변경된 속성만 내보냅니다.
// Get a list of all devices accessible to the user let homeDevices = try await self.home.devices().list()
여기에서 각 기기의 상태에 액세스할 수 있으며 지원되는 명령어를 기기로 전송할 수 있습니다.
기기의 유형 가져오기
기기와 연결된 기기 유형을 가져오려면 DeviceTypeController
를 반환하는 기기의 types
속성을 읽습니다.
DeviceTypeController.subscribe(_:)
를 호출하여 특정 기기 유형의 업데이트를 구독합니다.
let devices = try await self.home.devices().list() if let device = devices.first(where: { $0.id == myDeviceId }) { var receivedUpdate1 = false var receivedUpdate2 = false device.types.subscribe(OnOffLightDeviceType.self) .assertNoFailure() .sink { device in if !receivedUpdate1 { receivedUpdate1 = true Task { try await device.matterTraits.onOffTrait?.on() } return } if !receivedUpdate2 { receivedUpdate2 = true return } fatalError("Received unexpected update") } }
기기가 지정된 기기 유형을 지원하지 않으면 즉시 완료되는 Empty
Publisher
를 반환합니다.
기기가 특정 기기 유형을 지원하는 경우 get()
를 호출하여 해당 유형의 핸들을 가져올 수 있습니다.
if let device = devices.first(where: { $0.id == myDeviceId }) { let deviceType = await device.types.get(OnOffLightDeviceType.self) }
기기가 지정된 유형을 지원하지 않으면 nil
를 반환합니다.
DeviceTypeController.subscribeAll()
를 호출하여 DeviceTypeCollection
의 Publisher
를 가져옵니다.
이 클래스를 사용하면 기기에 특정 기기 유형이 있는지 확인할 수 있습니다.
if let device = devices.first(where: { $0.id == myDeviceId }) { device.types.subscribeAll() .assertNoFailure() .sink { types in let lightDeviceType = types[OnOffLightDeviceType.self] let fanDeviceType = types[FanDeviceType.self] } }
기기 유형 특성 가져오기
기기 유형은 특성을 읽기 위한 진입점입니다. 기기를 기능적 부분 (예: Matter의 엔드포인트)으로 분해하기 때문입니다.
또한 기기에 두 가지 기기 유형이 있고 두 유형 모두 동일한 특성을 가질 수 있는 경우 특성 충돌도 고려합니다. 예를 들어 기기가 스피커와 조광 가능한 조명인 경우 두 개의 On/Off 특성과 두 개의 Level Control 특성이 있습니다.
기기에 이름이 동일한 특성이 두 개 있는 경우 다른 종류의 특성 충돌이 발생할 수 있습니다. 예를 들어 onOff
는 표준 OnOff
특성의 인스턴스를 참조할 수도 있고 제조업체 정의 OnOff
특성의 인스턴스를 참조할 수도 있습니다. 어떤 특성이 의도되었는지에 관한 잠재적 모호성을 없애려면 각 기기 유형에서 두 특성 컬렉션 중 하나를 통해 특성을 참조하세요.
표준 특성(Matter 표준 클러스터와 유사한 특성)의 경우 matterTraits
을 사용합니다. 예를 들어 Dimmable Light 기기 유형의 특정 특성을 가져오려면 다음을 실행합니다.
if let dimmableLightDeviceType = await device.types.get(DimmableLightDeviceType.self) { // Accessing standard trait on the type. let levelControlTrait = dimmableLightDeviceType.matterTraits.levelControlTrait.self }
Google 특성의 경우 googleTraits
를 사용하세요.
if let doorbellDeviceType = await device.types.get(GoogleDoorbellDeviceType.self) { // Accessing Google trait on the type. let doorbellPressTrait = doorbellDeviceType.googleTraits.doorbellPressTrait.self }
제조업체별 특성에 액세스하려면 traits
속성을 통해 참조하되 제조업체의 패키지 이름으로 시작하세요.
let deviceType = await device1?.types.get(OnOffLightDeviceType.self) // Accessing custom trait on the type. if let spinnerTrait = deviceType?.traits[ExampleOrganization.SpinnerTrait.self] { let rpmVal = spinnerTrait.attributes.rpm }
기기 상태 읽기
기기의 On/Off 특성에서 OnOff
속성을 확인하는 다음 예를 참고하세요.
let lightDevices = devices.filter { $0.types.contains(OnOffLightDeviceType.self) } let light1 = lightDevices.first let lightDeviceTypeOptional = await light1?.types.get(OnOffLightDeviceType.self) if let onOffTrait = lightDeviceTypeOptional?.matterTraits.onOffTrait { let onOffVal = onOffTrait.attributes.onOff }
특정 특성이 있는 기기 목록 가져오기
특정 특성이 있는 기기 목록을 가져오려면 기기, 각 기기의 기기 유형, 각 기기 유형의 특성을 반복해야 합니다. 예를 들어 모두 On/Off 특성이 있는 홈의 기기 목록을 가져오려면 다음을 실행합니다.
// Get all light devices that support levelControl var levelControlDevices: [HomeDevice] = [] var allDevices = try await home.devices().list() for device in allDevices { if let deviceType = await device.types.get(OnOffLightDeviceType.self) { if deviceType.traits.contains(Matter.LevelControlTrait.self) { levelControlDevices.append(device) } } }
홈 API에서 사용할 수 있는 특성의 전체 목록은 iOS의 특성 색인을 참고하세요.
유사한 기기 유형의 기기 목록 가져오기
홈의 모든 조명을 나타내는 기기 목록을 가져오려면 다음을 실행하세요.
// Get a list of devices with similar device types (lights) let lightDevices = try await self.home.devices().list().compactMap { $0.types.contains(DimmableLightDeviceType.self) || $0.types.contains(OnOffLightDeviceType.self) || $0.types.contains(ColorTemperatureLightDeviceType.self) || $0.types.contains(ExtendedColorLightDeviceType.self) }
Home API에는 핵심 기기 유형을 나타낼 수 있는 여러 기기 유형이 있습니다. 예를 들어 '조명' 기기 유형은 없습니다. 대신 앞의 예와 같이 조명을 나타낼 수 있는 네 가지 다른 기기 유형이 있습니다. 따라서 홈에서 상위 수준 기기 유형을 포괄적으로 확인하려면 여러 기기 유형이 포함되어야 합니다.
홈 API에서 사용할 수 있는 기기 유형과 특성의 전체 목록은 iOS에서 지원되는 기기 유형을 참고하세요.
기기의 공급업체 이름, 공급업체 ID 또는 제품 ID 가져오기
BasicInformationTrait
특성에는 공급업체 ID, 제품 ID, 제품 이름, 기기의 일련번호와 같은 정보가 포함됩니다.
guard let vendorName = basicInfoTrait.attributes.vendorName else { fatalError("Failed to get vendorName") } guard let vendorID = basicInfoTrait.attributes.vendorID else { fatalError("Failed to get vendorID") } guard let productID = basicInfoTrait.attributes.productID else { fatalError("Failed to get productID") }
기기 제조업체를 위한 클라우드 간 기기 식별
기기 제조업체이고 Cloud-to-cloud 기기를 빌드하는 경우 BasicInformation
특성을 통해 Cloud-to-cloud 기기를 식별하기 위해 SYNC
응답에 다음 문자열 필드를 포함할 수 있습니다.
Connectivity Standards Alliance (CSA)에서 발급한 공급업체 ID:
"matterOriginalVendorId": "0xfff1",
공급업체의 제품을 고유하게 식별하는 제품 식별자입니다.
"matterOriginalProductId": "0x1234",
제조업체별 방식으로 구성된 기기의 고유 식별자입니다.
"matterUniqueId": "matter-device-id",
이러한 문자열 필드를 입력할 때 Matter 공급업체 및 제품 ID가 있는 경우 이를 사용하세요. CSA 회원이 아니고 이러한 ID가 할당되지 않은 경우 matterOriginalVendorId
및 matterOriginalProductId
필드를 비워 두고 matterUniqueId
를 식별자로 제공하면 됩니다.
다음은 이러한 필드를 사용하는 SYNC 응답의 예입니다.
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"agentUserId": "1836.15267389",
"devices": [
{
"id": "456",
"type": "action.devices.types.LIGHT",
"traits": [
"action.devices.traits.OnOff",
"action.devices.traits.Brightness",
"action.devices.traits.ColorSetting",
],
"willReportState": true,
"deviceInfo": { ... },
"matterOriginalVendorId": "0xfff1",
"matterOriginalProductId": "0x1234",
"matterUniqueId": "matter-device-id",
"otherDeviceIds": [
{
"deviceId": "local-device-id",
}
]
}
]
}
}
자세한 내용은 Cloud-to-cloud SYNC
문서를 참고하세요.
기기 및 특성 메타데이터
Home API의 기기와 특성에는 메타데이터가 연결되어 있어 앱에서 사용자 환경을 관리하는 데 도움이 됩니다.
Home API의 각 특성에는 특성의 온라인 상태 및 위치(로컬 또는 원격 라우팅)에 관한 정보가 있는 sourceConnectivity
속성이 포함됩니다.
기기의 기본 유형 가져오기
일부 기기는 Home API를 통해 여러 기기 유형을 표시할 수 있습니다. 사용자에게 기기에 적합한 옵션 (예: 기기 제어 및 추천 자동화)이 앱에 표시되도록 하려면 기기 유형이 기기의 기본 유형인지 확인하는 것이 좋습니다.
if let deviceType = await device?.types.get(HumiditySensorDeviceType.self) { if deviceType.metadata.isPrimaryType { print("Humidity Sensor is the primary type on this device.") } else { print("Humidity Sensor isn't the primary type on this device.") } }
특성이 온라인인지 확인
connectivityState
속성을 읽어 특성의 연결을 확인합니다.
let levelControlConnectivity = levelControlTrait.metadata.sourceConnectivity .connectivityState
일부 특성(일반적으로 Google smart home 특성)은 기기가 인터넷에 연결되어 있지 않으면 오프라인으로 표시될 수 있습니다. 이러한 특성은 클라우드 기반이며 로컬 라우팅이 없기 때문입니다.
기기의 연결 확인
일부 기기는 여러 기기 유형을 지원하므로 기기의 연결은 실제로 기기 유형 수준에서 확인됩니다. 반환된 상태는 해당 기기의 모든 특성의 연결 상태를 조합한 것입니다.
let lightConnectivity = dimmableLightDeviceType.metadata.sourceConnectivity .connectivityState
인터넷 연결이 없는 경우 혼합 기기 유형에서 partiallyOnline
상태가 관찰될 수 있습니다. Matter 표준 특성은 로컬 라우팅으로 인해 온라인 상태일 수 있지만 클라우드 기반 특성은 오프라인 상태가 됩니다.
특성의 네트워크 라우팅 확인
특성의 지역은 Home API에서도 사용할 수 있습니다. dataSourceLocality
는 특성이 원격으로 라우팅되는지 (클라우드를 통해), 로컬로 라우팅되는지 (로컬 허브를 통해), 아니면 피어 투 피어로 라우팅되는지 (기기 간 직접, 허브 없음)를 나타냅니다.
앱이 부팅 중이고 아직 기기 연결을 위한 허브나 서버에 도달하지 않은 동안에는 알 수 없는 지역 값 unspecified
이 가능합니다. 이러한 기기는 연결할 수 없으며 명령어 또는 이벤트의 상호작용 요청이 실패합니다. 이러한 기기를 처리하는 방법은 클라이언트가 결정합니다.
let levelControlLocality = levelControlTrait.metadata.sourceConnectivity .dataSourceLocality
기기의 네트워크 라우팅 확인
연결과 마찬가지로 지역성은 기기 유형 수준에서 확인됩니다. 반환된 상태는 해당 기기의 모든 특성의 지역성의 조합입니다.
let lightLocality = dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality
mixed
상태는 partiallyOnline
연결과 유사한 시나리오에서 관찰될 수 있습니다. 일부 특성은 클라우드 기반이고 다른 특성은 로컬입니다.
기기 이름 변경
setName(_:)
메서드를 호출하여 기기 이름을 변경합니다.
let updatedDevice = try await theDevice.setName("new device name")
기기 이름을 변경할 때 원래 HomeDevice
구조체는 동일하게 유지되고 변경사항은 반환된 업데이트된 HomeDevice
객체에 반영됩니다.
API 목록
Home
인스턴스가 생성되면 다음 기기 API를 통해 액세스할 수 있습니다.
API | 설명 |
---|---|
device(id:) |
변경될 때마다 기기 상태를 내보내는 지정된 기기의 Publisher 를 반환합니다. |
devices() |
Google 계정의 모든 구조에 있는 모든 기기를 가져옵니다. 추가 검색 및 필터링 옵션을 제공하는 Query<HomeDevice> 를 반환합니다. |
HomeDevice
이 있으면 다음 API에 액세스할 수 있습니다.
API | 설명 |
---|---|
id |
기기의 고유 시스템 ID입니다. |
name |
사용자가 제공한 기기 이름입니다. |
structureID |
기기가 할당된 구조의 ID입니다. String? 를 반환합니다. |
roomID |
기기가 할당된 방의 ID입니다. String? 를 반환합니다. |
types |
기기에서 특정 유형 또는 사용 가능한 모든 유형을 가져옵니다. |
isMatterDevice |
기기가 Matter로 지원되는 경우 |
sourceConnectivity |
기기의 소스 연결로, 기기 특성의 집계된 연결 상태와 네트워크 지역성을 나타냅니다. |