Perangkat multi-bagian di Android

Beberapa perangkat Matter terdiri dari beberapa endpoint dengan jenis perangkat yang sama. Perangkat Matter Matter lainnya bersifat hierarkis, dengan endpoint yang berada di dalam endpoint lainnya. Di Home API, kedua jenis perangkat ini disebut sebagai perangkat multi-bagian.

Representasi datar

Sebelum rilis 1.8 Home API, perangkat multi-bagian direpresentasikan oleh Home API sebagai kumpulan perangkat terpisah yang tidak terkait. Hal ini disebut sebagai representasi datar.

Misalnya, satu perangkat panel dinding dengan empat sakelar muncul di Home API sebagai empat perangkat berbeda yang tidak terkait. Dan perangkat Matter hierarkis Matter seperti kulkas dapat direpresentasikan di Home API sebagai kumpulan perangkat, yang masing-masing sesuai dengan salah satu endpoint.

Representasi multi-bagian

Mulai dari rilis 1.8 Home API, perangkat multi-bagian dapat direpresentasikan di API sebagai satu perangkat. Untuk mengaktifkan perilaku ini, panggil metode devices() di Structure, Room, atau HomeManager, dan tetapkan parameter enableMultipartDevices ke true:

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)

Diagram berikut mengilustrasikan pengaruh opsi enableMultipartDevices terhadap representasi perangkat multi-bagian di Home API:

Anda selalu memiliki opsi untuk mendapatkan representasi datar dengan menghapus parameter enableMultipartDevices, atau dengan menetapkannya ke false.

Menavigasi perangkat multi-bagian

Dalam perangkat multi-bagian, setiap instance komponen dari jenis perangkat disebut bagian.

Bagian dapat diakses langsung di perangkat induk atau bagian secara hierarkis, menggunakan jenis perangkat atau Matter tag semantik. Tag semantik diimplementasikan di Home API dengan DescriptorTrait.SemanticTagStruct.

Class abstrak DeviceType mengimplementasikan antarmuka HasParts, yang memungkinkan developer menavigasi pohon perangkat melalui properti parts dan metode part(). Setiap instance bagian juga mengimplementasikan antarmuka HasParts, sehingga memanggil parts() pada bagian akan menghasilkan daftar nol atau beberapa sub-bagian.

Contoh berikut menunjukkan cara mengakses bagian perangkat multi-sakelar:

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

Contoh berikutnya menunjukkan cara mengakses bagian perangkat kulkas:

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