Multipart-Geräte auf Android-Geräten

Einige Matter-Geräte bestehen aus mehreren Endpunkten mit demselben Gerätetyp. Andere Matter-Geräte sind hierarchisch aufgebaut, wobei Endpunkte in anderen Endpunkten verschachtelt sind. In den Home APIs werden beide Arten von Geräten als Multipart-Geräte bezeichnet.

Einfache Darstellung

Vor der Version 1.8 der Home APIs wurden Geräte mit mehreren Teilen in den Home APIs als eine Reihe separater, unabhängiger Geräte dargestellt. Dies wird als flache Darstellung bezeichnet.

Ein einzelnes Wandpaneel mit vier Schaltern wird in den Home APIs beispielsweise als vier separate und unabhängige Geräte angezeigt. Ein hierarchisches Matter-Gerät wie ein Kühlschrank kann in den Home-APIs als eine Reihe von Geräten dargestellt werden, die jeweils einem der Endpunkte entsprechen.

Mehrteilige Darstellung

Ab Version 1.8 der Home APIs kann ein mehrteiliges Gerät in der API als einzelnes Gerät dargestellt werden. Rufen Sie zum Aktivieren dieses Verhaltens die Methode devices() für Structure, Room oder HomeManager auf und legen Sie den Parameter enableMultipartDevices auf true fest:

let devices = try await self.home.devices(enableMultipartDevices: true).list()
    let device = try XCTUnwrap(devices.first { $0.id == powerstripID })
    let outlets = try await device.types.getAll(of: OnOffPluginUnitDeviceType.self)

Die folgenden Diagramme veranschaulichen, wie sich die Option enableMultipartDevices auf die Darstellung eines mehrteiligen Geräts in den Home APIs auswirkt:

Sie haben immer die Möglichkeit, die flache Darstellung zu erhalten, indem Sie den Parameter enableMultipartDevices weglassen oder auf false setzen.

Mehrteiliges Gerät bedienen

In einem mehrteiligen Gerät wird jede Komponenteninstanz eines Gerätetyps als Teil bezeichnet.

Auf Teile kann entweder direkt auf dem übergeordneten Gerät oder hierarchisch über Gerätetypen oder semantische Matter-Tags zugegriffen werden. Semantische Tags werden in den Home-APIs mit DescriptorTrait.SemanticTagStruct implementiert.

Die abstrakte Klasse DeviceType implementiert die Schnittstelle HasParts. So können Entwickler über die Property parts und die Methode part() im Gerätebaum navigieren. Jede Teilinstanz implementiert auch die HasParts-Schnittstelle, sodass beim Aufrufen von parts() für einen Teil eine Liste mit null oder mehr untergeordneten Teilen zurückgegeben wird.

Das folgende Beispiel zeigt, wie auf die Teile des Geräts mit mehreren Schaltern zugegriffen wird:

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()

Im nächsten Beispiel wird gezeigt, wie auf die Teile eines Kühlschranks zugegriffen wird:

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()