Android의 기기 및 기기 메타데이터에 액세스

기기 API는 Android용 Home API를 통해 액세스할 수 있습니다. 다음 패키지를 앱으로 가져옵니다.

import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id

기기 API에서 특정 기기 유형 또는 특성을 사용하려면 개별적으로 가져와야 합니다.

예를 들어 Matter On/Off 특성 및 On/Off 플러그인 단위 기기 유형을 사용하려면 다음 패키지를 애플리케이션으로 가져옵니다.

import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice

자세한 내용은 Android의 데이터 모델을 참고하세요.

오류 처리

Home API의 모든 메서드는 HomeException을 발생시킬 수 있으므로 모든 호출에서 HomeException을 포착하려면 try-catch 블록을 사용하는 것이 좋습니다.

HomeException을 처리할 때 error.code 및 error.message 필드를 확인하여 무엇이 잘못되었는지 알아봅니다. 하위 오류 코드도 있을 수 있으므로 `getSubErrorCodes()` getSubErrorCodes() 메서드를 호출하고 결과를 확인합니다.

처리되지 않은 예외가 있으면 앱이 비정상 종료됩니다.

자세한 내용은 오류 처리를 참고하세요.

예는 기기에 명령어 전송을 참고하세요.

샘플 호출

기기 목록 가져오기

Structure 인스턴스를 참조하면 devices() 호출이 해당 구조에서 액세스할 수 있는 기기의 Flow를 반환합니다.

// Get a flow of all devices accessible to the user
val allDevicesFlow: HomeObjectsFlow<HomeDevice> = home.devices()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allDevices: Set<HomeDevice> = allDevicesFlow.list()

여기에서 각 기기의 상태에 액세스하고 기기에 명령어를 전송할 수 있습니다.

Home API 버전 1.8에서는 devices() 메서드의 enableMultipartDevices 매개변수를 true로 설정하여 API가 각 멀티파트 기기를 단일 기기로 나타내도록 할 수 있습니다. 자세한 내용은 Android의 멀티파트 기기를 참고하세요.

기기 상태 읽기

기기의 On/Off 특성에서 OnOff 속성을 확인하는 예를 살펴보세요. 이 특성이 OnOff로 식별되는 Home API 특성 데이터 모델을 사용하면 기기 유형의 standardTraits 클래스를 통해 특성 데이터를 검색할 수 있습니다.

// Assuming we have a device.
val deviceFlow = home.devices().itemFlow(myDeviceId)

val device = deviceFlow.first()

// Get a flow of a standard trait on the type. distinctUntilChanged() is needed to only trigger
// on the specific trait changes and not the whole type.
val onOffTraitFlow: Flow<OnOff?> =
  device.type(DimmableLightDevice).map { it.standardTraits.onOff }.distinctUntilChanged()

val onOffTrait: OnOff = onOffTraitFlow.first()!!

Kotlin 흐름 함수에 관한 자세한 내용은 distinctUntilChanged 를 참고하세요.

특성 구독에서 상태 무효화

TraitStateInvalidation 인터페이스 는 상태가 올바르게 보고되지 않는 경우 타겟 기기 구독을 통해 검색된 상태를 무효화하는 기능을 제공합니다. 상태가 올바르게 보고되지 않을 수 있는 예로는 'C' 품질의 Matter 특성에서 속성을 사용하거나 문제를 예기치 않게 일으키는 기기 구현이 있습니다.

이 API는 현재 특성 상태의 강제 읽기를 실행하고 기존 특성 흐름을 통해 결과를 반환합니다.

특성을 가져온 다음 특성에서 forceRead를 실행합니다.

val onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.forceRead()

기기 유형 특성 목록 가져오기

기기 유형은 Matter의 엔드포인트와 같이 기기를 기능적 부분으로 분해하므로 특성을 읽기 위한 진입점으로 사용해야 합니다.Matter

또한 기기에 동일한 특성을 가질 수 있는 두 가지 기기 유형이 있는 경우 특성 충돌을 고려합니다. 예를 들어 기기가 스피커와 조광 가능한 조명인 경우 On/Off 특성이 2개, 수준 제어 특성이 2개 있습니다.

조광 가능한 조명 기기 유형에 사용 가능한 특성 목록을 가져오려면 다음을 실행합니다.

// Get all types available on this device. Requires the types to be part of the registry during
// SDK initialization.
val typesFlow: Flow<Set<DeviceType>> = device.types()

// Get a snapshot of all types.
val types: Set<DeviceType> = typesFlow.first()

// Get the DimmableLightDevice instance from the set of types.
val dimmableLightDevice = types.filterIsInstance<DimmableLightDevice>().firstOrNull()

// Get all traits in the type + traits registered
val allTraits: Set<Trait> = dimmableLightDevice!!.traits()

기기에 이름이 같은 특성이 두 개 있는 경우 다른 종류의 특성 충돌이 발생할 수 있습니다. 예를 들어 onOff는 표준 OnOff 특성의 인스턴스를 참조하거나 제조업체에서 정의한 OnOff 특성의 인스턴스를 참조할 수 있습니다. 어떤 특성이 의도되었는지에 관한 잠재적 모호성을 없애려면 기기를 통해 참조되는 Trait 인스턴스 앞에 한정 네임스페이스가 있어야 합니다. 표준 특성, 즉 Matter 표준 클러스터와 유사한 특성의 경우 standardTraits를 사용합니다. Google 특성의 경우 googleTraits를 사용합니다.

// Accessing standard traits on the type.
val onOffTrait: OnOff? = dimmableLightDevice.standardTraits.onOff
val levelControlTrait: LevelControl? = dimmableLightDevice.standardTraits.levelControl

제조업체별 특성에 액세스하려면 직접 참조합니다.

// Accessing a custom trait on the type.
val customTrait = dimmableLightDevice.trait(MyCustomTrait)

특정 특성이 있는 기기 목록 가져오기

Kotlin의 filter 함수를 사용하여 API 호출을 추가로 세분화할 수 있습니다. 예를 들어 집에 있는 모든 기기의 On/Off 특성 목록을 가져오려면 다음을 실행합니다.

// Get all devices that support OnOff
val onOffDevices: Flow<List<HomeDevice>> =
  home.devices().map { devices -> devices.filter { it.has(OnOff) } }

Home API에서 사용할 수 있는 특성의 전체 목록은 Trait 인터페이스를 참고하세요.

유사한 기기 유형이 있는 기기 목록 가져오기

집에 있는 모든 조명을 나타내는 기기 목록을 가져오려면 다음을 실행합니다.

// Get a list of devices with similar device types (lights)
val lightDevices =
  home.devices().map { devices ->
    devices.filter {
      it.has(DimmableLightDevice) ||
        it.has(OnOffLightDevice) ||
        it.has(ColorTemperatureLightDevice) ||
        it.has(ExtendedColorLightDevice)
    }
  }

Home API에는 핵심 기기 유형을 나타낼 수 있는 여러 기기 유형이 있습니다. 예를 들어 '조명' 기기 유형은 없습니다. 대신 앞의 예와 같이 조명을 나타낼 수 있는 4가지 기기 유형이 있습니다. 따라서 집에서 상위 수준의 기기 유형을 포괄적으로 보려면 필터링된 흐름에 여러 기기 유형을 포함해야 합니다.

Home API에서 사용할 수 있는 기기 유형의 전체 목록은 DeviceType 인터페이스 를 참고하세요.

기기의 공급업체 ID 또는 제품 ID 가져오기

BasicInformation 특성에는 공급업체 ID, 제품 ID, 제품 이름, 기기의 일련번호와 같은 정보가 포함되어 있습니다.

// Get device basic information. All general information traits are on the RootNodeDevice type.
val basicInformation = device.type(RootNodeDevice).first().standardTraits.basicInformation!!
println("vendorName ${basicInformation.vendorName}")
println("vendorId ${basicInformation.vendorId}")
println("productId ${basicInformation.productId}")

기기 제조업체를 위한 클라우드 간 기기 식별

기기 제조업체이고 Cloud-to-cloud 기기를 빌드하는 경우 Cloud-to-cloud 기기를 BasicInformation 특성을 통해 식별하려면 SYNC 응답에 다음 문자열 필드를 포함하면 됩니다.

Connectivity Standards Alliance (Alliance)에서 발급한 공급업체 ID: "matterOriginalVendorId": "0xfff1",
공급업체의 제품을 고유하게 식별하는 제품 식별자: "matterOriginalProductId": "0x1234",
제조업체별 방식으로 구성되는 기기의 고유 식별자: "matterUniqueId": "matter-device-id",

이러한 문자열 필드를 입력할 때는 Matter 공급업체 및 제품 ID가 있는 경우 이를 사용합니다. Alliance 회원이 아니고 이러한 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를 통해 여러 기기 유형을 표시할 수 있습니다. 사용자에게 기기에 적합한 옵션 (예: 기기 제어 및 추천 자동화)이 앱에 표시되도록 하려면 기기의 기본 기기 유형을 확인하는 것이 좋습니다.

먼저 type()을 사용하여 기기의 유형을 가져온 다음 기본 유형을 결정합니다.

val types = device.types().first()
val primaryTypes = types.filter { it.metadata.isPrimaryType }

특성이 온라인 상태인지 확인

connectivityState() 메서드를 사용하여 특성의 연결을 확인합니다.

val onOffConnectivity = onOffTrait?.metadata?.sourceConnectivity?.connectivityState

일부 특성(일반적으로 Google smart home 특성)은 기기에 인터넷 연결이 없는 경우 오프라인으로 표시될 수 있습니다. 이는 이러한 특성이 클라우드 기반이며 로컬 라우팅이 없기 때문입니다.

기기의 연결 확인

일부 기기는 여러 기기 유형을 지원하므로 기기의 연결은 실제로 기기 유형 수준에서 확인됩니다. 반환되는 상태는 해당 기기의 모든 특성에 대한 연결 상태의 조합입니다.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

인터넷 연결이 없는 경우 혼합 기기 유형의 경우 PARTIALLY_ONLINE 상태가 관찰될 수 있습니다. Matter 표준 특성은 로컬 라우팅으로 인해 계속 온라인 상태일 수 있지만 클라우드 기반 특성은 오프라인 상태가 됩니다.

특성의 네트워크 라우팅 확인

특성의 위치는 Home API에서도 사용할 수 있습니다. dataSourceLocality는 특성이 원격으로 (클라우드를 통해), 로컬로 (로컬 허브를 통해) 또는 피어 투 피어 (기기 간 직접, 허브 없음)로 라우팅되는지 나타냅니다.

알 수 없는 위치 값 UNSPECIFIED는 예를 들어 앱이 부팅 중이고 아직 기기 연결을 위한 허브 또는 서버에 도달하지 않은 경우에 가능합니다. 이러한 기기는 연결할 수 없으며 명령어 또는 이벤트의 상호작용 요청이 실패합니다. 이러한 기기를 처리하는 방법은 클라이언트가 결정합니다.

val onOffLocality = onOffTrait?.metadata?.sourceConnectivity?.dataSourceLocality

기기의 네트워크 라우팅 확인

연결과 마찬가지로 위치는 기기 유형 수준에서 확인됩니다. 반환되는 상태는 해당 기기의 모든 특성에 대한 위치의 조합입니다.

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

PARTIALLY_ONLINE 연결과 유사한 시나리오에서 MIXED 상태가 관찰될 수 있습니다. 일부 특성은 클라우드 기반이고 다른 특성은 로컬입니다.

기기 이름 변경

setName() 메서드를 호출하여 기기의 이름을 변경합니다.

mixerDevice.setName("Grendel")

이름이 유니코드 코드 포인트(문자) 제한인 60을 초과하면 잘리고 오류가 발생하지 않습니다. 개발자는 긴 이름을 처리할 책임이 있으며, 예를 들어 사용자에게 이름이 잘린다는 것을 알릴지 결정할 수 있습니다.