الأجهزة المتعددة الأجزاء على Android

تتكوّن بعض أجهزة Matter من نقاط نهاية متعدّدة لها نوع الجهاز نفسه. وتكون أجهزة Matter الأخرى هرمية، حيث تكون نقاط النهاية مضمّنة في نقاط نهاية أخرى. في واجهات برمجة التطبيقات لمنزل Google، يُشار إلى كلا النوعين من الأجهزة باسم الأجهزة المتعدّدة الأجزاء.

التمثيل المسطّح

قبل الإصدار 1.8 من واجهات برمجة التطبيقات لمنزل Google، يتم تمثيل الأجهزة المتعدّدة الأجزاء في واجهات برمجة التطبيقات لمنزل Google على أنّها مجموعة من الأجهزة المنفصلة وغير المرتبطة. ويُشار إلى ذلك باسم التمثيل المسطّح.

على سبيل المثال، يظهر جهاز لوحة حائط واحدة مزوّدة بأربعة مفاتيح في واجهات برمجة التطبيقات لمنزل Google على أنّه أربعة أجهزة منفصلة وغير مرتبطة. ويمكن تمثيل جهاز Matter هرمي Matter، مثل الثلاجة، في واجهات برمجة التطبيقات لمنزل Google على أنّه مجموعة من الأجهزة، يتوافق كل منها مع إحدى نقاط النهاية.

التمثيل المتعدّد الأجزاء

بدءًا من الإصدار 1.8 من واجهات برمجة التطبيقات لمنزل Google، يمكن تمثيل جهاز متعدّد الأجزاء في واجهة برمجة التطبيقات على أنّه جهاز واحد. لتفعيل هذا السلوك، استخدِم طريقة devices() في Structure أو Room أو HomeManager واضبط المعلمة enableMultipartDevices على 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)

توضّح المخططات التالية كيف يؤثر الخيار enableMultipartDevices في تمثيل جهاز متعدّد الأجزاء في واجهات برمجة التطبيقات لمنزل Google:

يمكنك دائمًا الحصول على التمثيل المسطّح إما من خلال حذف المعلمة enableMultipartDevices أو ضبطها على false.

الوصول إلى جهاز متعدّد الأجزاء

داخل جهاز متعدّد الأجزاء، يُطلق على كل نموذج مكوّن من نوع جهاز اسم جزء.

يمكن الوصول إلى الأجزاء مباشرةً على الجهاز الرئيسي أو جزء بطريقة هرمية، باستخدام أنواع الأجهزة أو العلامات الدلالية لـ Matter Matter. يتم تنفيذ العلامات الدلالية في واجهات برمجة التطبيقات لمنزل Google باستخدام DescriptorTrait.SemanticTagStruct.

تنفّذ الفئة المجردة 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()