一部の Matter デバイスは、同じデバイス タイプの複数のエンドポイントで構成されています。他の Matter デバイスは階層構造になっており、エンドポイントが他のエンドポイント内にネストされています。Home API では、両方の種類のデバイスをマルチパート デバイスと呼びます。
フラットな表現
Home API のリリース 1.8 より前は、マルチパート デバイスは Home API によって、別々の関連性のないデバイスのセットとして表されていました。これはフラット表現と呼ばれます。
たとえば、4 つのスイッチを備えた 1 つの壁パネル デバイスは、Google Home API では 4 つの個別の関連性のないデバイスとして表示されます。冷蔵庫などの階層型 Matter デバイスは、Home API でデバイスのセットとして表されることがあります。各デバイスはエンドポイントの 1 つに対応します。
4 スイッチの壁パネルの平面図。
冷蔵庫のフラットな表現
マルチパート表現
Home API のリリース 1.8 以降では、マルチパート デバイスを API で 1 つのデバイスとして表すことができます。この動作を有効にするには、Structure、Room、または HomeManager で devices() メソッドを呼び出し、enableMultipartDevices パラメータを true に設定します。
var multipartDevice = structure.devices(enableMultipartDevices = multipartEnabled) var multipartDevice = multipartDevices.list().filter{ device -> device.has(PowerStrip)}
次の図は、enableMultipartDevices オプションが Home API でのマルチパート デバイスの表現にどのように影響するかを示しています。
壁パネルのマルチパート表現。
冷蔵庫のマルチパート表現。
enableMultipartDevices パラメータを省略するか、false に設定することで、常にフラットな表現を取得できます。
マルチパート デバイスを操作する
マルチパート デバイスでは、デバイスタイプの各コンポーネント インスタンスはパートと呼ばれます。
パーツには、デバイスタイプまたは Matter セマンティック タグを使用して、親デバイスまたはパーツで直接アクセスすることも、階層的にアクセスすることもできます。セマンティック タグは、DescriptorTrait.SemanticTagStruct を使用して Home API に実装されます。
DeviceType 抽象クラスは HasParts インターフェースを実装し、デベロッパーが parts プロパティと part() メソッドを介してデバイスツリーをナビゲートできるようにします。各パーツ インスタンスは HasParts インターフェースも実装しているため、パーツで parts() を呼び出すと、ゼロ以上のサブパーツのリストが生成されます。
次の例は、マルチスイッチ デバイスのパーツにアクセスする方法を示しています。
val device = homeManager .devices(enableMultipartDevices = true) .itemFlow(Id(MULTI_SWITCH_DEVICE)) .first() // Here at top-level, we are using the homeDevice.parts() API to access flow of // all the switches. Then we get the part ids. val partIds = device .parts() .map { parts -> parts.filter { it.has(Switch) }.mapNotNull { it.metadata.partId } } .first() .toSet()
次の例は、冷蔵庫デバイスのパーツにアクセスする方法を示しています。
val rootDevice = homeManager.devices(true).itemFlow(Id("device@uuid1")) // On the top level, HomeDevice provides both plural (parts) // and singular (part) APIs. // The parts() API returns all the parts accessible from the top level, // including Endpoint 0 and its children. val childParts = rootDevice.parts().first() // childParts contain (EP0 as RootNode, EP1 as Refrigerator) // The singular part() API accepts DeviceType and tags (optional). val refrigerator = rootDevice.part(Refrigerator).first() // Get the refrigerator device which in this case is just device@uuid1 val refrigeratorDevice = homeManager.devices(false).itemFlow(refrigerator.metadata.partId.deviceId) // DeviceType uses a synchronous API for providing access to parts val cabinets = refrigerator.parts // [EP2, EP3] // Get the HomeDevice for these cabinets (device@uuid2 and device@uuid3) val cabinetDeviceIds = cabinets.map { it.metadata.partId } // Now use the devices API with enableMultipartDevices = false. val cabinetDevices = homeManager.devices(false) .map { devices -> devices.filter { it.id in cabinetDeviceIds } }.first()