Android のデバイスとデバイスのメタデータにアクセスする

デバイス API には、Android 用の Google Home API を介してアクセスできます。次のパッケージをアプリにインポートします。

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

デバイス API で特定のデバイスタイプまたはトレイトを使用するには、個別にインポートする必要があります。

たとえば、Matter オン/オフトレイトとオン/オフプラグインユニットのデバイスタイプを使用するには、次のパッケージをアプリケーションにインポートします。

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

詳細については、Android のデータモデルをご覧ください。

エラー処理

Google Home API のメソッドは HomeException をスローする可能性があるため、すべての呼び出しで try-catch ブロックを使用して HomeException をキャッチすることをおすすめします。

HomeException を処理するときは、 error.code フィールドと error.message フィールドを確認して、何が問題だったかを把握します。サブエラーコードも存在する可能性があるため、 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()

そこから、各デバイスの状態にアクセスして、デバイスにコマンドを送信できます。

Google Home API のリリース 1.8 では、devices() メソッドの enableMultipartDevices パラメータを true に設定することで、各マルチパートデバイスを 1 つのデバイスとして API に表すことができます。詳細については、Android のマルチパートデバイスをご覧ください。

デバイスの状態を読み取る

デバイスのオン/オフトレイトから OnOff 属性を確認する例を見てみましょう。このトレイトが OnOff として識別される Google 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 をご覧ください。

トレイトサブスクリプションの状態を無効にする

The TraitStateInvalidation インターフェースを使用すると、状態が正しく報告されない場合に、対象デバイスへのサブスクリプションを介して取得した状態を無効にできます。状態が正しく報告されない例としては、品質が「C」の Matter トレイトで属性を使用する場合や、デバイスの実装が原因で問題が予期せず発生する場合などがあります。

この API は、現在のトレイトの状態の強制読み取りを発行し、既存のトレイトフローを介して結果を返します。

トレイトを取得し、トレイトに対して forceRead を実行します。

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

デバイスタイプのトレイトのリストを取得する

デバイスタイプは、トレイトを読み取るためのエントリポイントとして使用する必要があります。デバイスを機能的な部分（Matter のエンドポイントなど）に分解するためです。 Matter

また、デバイスに 2 つのデバイスタイプがあり、両方に同じトレイトが含まれている場合に、トレイトの衝突を考慮します。たとえば、デバイスがスピーカーと調光可能な照明の両方である場合、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()

デバイスに同じ名前のトレイトが 2 つある場合、別の種類のトレイトの衝突が発生する可能性があります。たとえば、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 呼び出しをさらに絞り込むことができます。たとえば、オン/オフトレイトを持つ家にあるデバイスのリストを取得するには:

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

Google 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)
    }
  }

Google Home API には、コアデバイスタイプを表すことができるデバイスタイプが複数あります。たとえば、「照明」というデバイスタイプはありません。代わりに、前の例に示すように、照明を表すことができる 4 つの異なるデバイスタイプがあります。そのため、家にある上位レベルのデバイスタイプを包括的に把握するには、フィルタされたフローに複数のデバイスタイプを含める必要があります。

Google 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 と商品 ID がある場合はそれを使用します。Alliance のメンバーではなく、これらの ID が割り当てられていない場合は、 matterOriginalVendorId フィールドと matterOriginalProductId フィールドを空白のままにして、 matterUniqueId を識別子として指定できます。Alliance

次の 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 のドキュメントをご覧ください。

デバイスとトレイトのメタデータ

Google Home API のデバイスとトレイトにはメタデータが関連付けられており、アプリでのユーザーエクスペリエンスの管理に役立ちます。

Google Home API の各トレイトには、トレイトのオンラインステータスとロケール（ローカルルーティングまたはリモートルーティング）に関する情報を含む sourceConnectivity プロパティが含まれています。

デバイスの主なタイプを取得する

一部のデバイスでは、Google Home API を介して複数のデバイスタイプが表示されることがあります。デバイスの適切なオプション（デバイスの制御やおすすめの自動化など）がアプリでユーザーに表示されるようにするには、デバイスの主なデバイスタイプを確認すると便利です。

重要: デバイスには複数の主なタイプを設定できます。

プライマリエンドポイントに属するすべてのタイプは、プライマリタイプと見なされます。
照明などの Matter スーパセットタイプのメンバーが 1 つでもプライマリである場合、デバイスに存在するそのスーパセットタイプの他のメンバーもすべてプライマリになります。たとえば、デバイスが OnOffLightDevice, DimmableLightDevice, ColorTemperatureLightDevice と ExtendedColorLightDevice, をサポートしていて、そのうちの 1 つがプライマリである場合、それらはすべてプライマリになります。スーパセットデバイスタイプの詳細については、 Matter Application Cluster Specificationのセクション 9.2.5「Superset Device Types」をご覧ください。

まず、デバイスのタイプを使用して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 標準トレイトはローカルルーティングによりオンラインのままですが、クラウドベースのトレイトはオフラインになります。

トレイトのネットワークルーティングを確認する

トレイトのロケールは、Google Home API でも使用できます。dataSourceLocality は、トレイトがリモート（クラウド経由）、ローカル（ローカルハブ経由）、ピアツーピア（デバイスからデバイスへ直接、ハブなし）のいずれでルーティングされるかを示します。

不明なロケール値 UNSPECIFIED は、たとえば、アプリの起動中にデバイス接続用のハブまたはサーバーにまだ到達していない場合に発生する可能性があります。これらのデバイスには到達できず、コマンドやイベントからのインタラクションリクエストは失敗します。このようなデバイスの処理方法はクライアントが決定します。

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

デバイスのネットワークルーティングを確認する

接続と同様に、ロケールはデバイスタイプレベルで確認されます。返される状態は、そのデバイスのすべてのトレイトのロケールの組み合わせです。

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

PARTIALLY_ONLINE 接続と同様のシナリオで、MIXED の状態になることがあります。一部のトレイトはクラウドベースで、他のトレイトはローカルです。

デバイスの名前を変更する

setName() メソッドを呼び出して、デバイスの名前を変更します。

mixerDevice.setName("Grendel")

名前が 60 Unicode コードポイント（文字）の制限を超えると切り捨てられますが、エラーはスローされません。デベロッパーは長い名前を処理する責任があります。たとえば、名前が切り捨てられることをユーザーに通知するかどうかを決定できます。