เข้าถึงอุปกรณ์และข้อมูลเมตาของอุปกรณ์สำหรับ Android

คุณเข้าถึง Device API ได้ผ่าน Home API สำหรับ Android นำเข้าแพ็กเกจต่อไปนี้ลงในแอป

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

หากต้องการใช้อุปกรณ์หรือลักษณะเฉพาะบางอย่างกับ Device API คุณต้องนำเข้าอุปกรณ์หรือลักษณะเฉพาะเหล่านั้นทีละรายการ

ตัวอย่างเช่น หากต้องการใช้Matterลักษณะเปิด/ปิดและประเภทอุปกรณ์ปลั๊กอินเปิด/ปิด ให้นำเข้าแพ็กเกจต่อไปนี้ลงในแอปพลิเคชัน

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

ดูข้อมูลเพิ่มเติมได้ที่โมเดลข้อมูลใน Android

การจัดการข้อผิดพลาด

เมธอดใดก็ตามใน Home API สามารถส่ง HomeException ได้ ดังนั้นเราขอแนะนำให้คุณใช้บล็อก try-catch เพื่อตรวจหา HomeException ในการเรียกใช้ทั้งหมด

เมื่อจัดการ HomeException ให้ตรวจสอบฟิลด์ code และ message เพื่อดูว่าเกิดข้อผิดพลาดใด

ข้อยกเว้นที่ไม่ได้จัดการจะทำให้แอปขัดข้อง

ดูข้อมูลเพิ่มเติมได้ที่ การจัดการข้อผิดพลาด

ดูตัวอย่างได้ที่ส่งคำสั่งไปยังอุปกรณ์

ตัวอย่างการเรียก

รับรายการอุปกรณ์

เมื่อมีโครงสร้าง 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()

จากนั้นคุณจะเข้าถึงสถานะของอุปกรณ์แต่ละเครื่องและส่งคำสั่งที่รองรับไปยังอุปกรณ์ได้

อ่านสถานะอุปกรณ์

มาดูตัวอย่างการตรวจสอบแอตทริบิวต์ OnOff จากลักษณะเปิด/ปิดของอุปกรณ์กัน เมื่อใช้โมเดลข้อมูลลักษณะของ Home API ซึ่งระบุลักษณะนี้เป็น OnOff คุณจะเรียกข้อมูลลักษณะผ่านคลาส 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()!!

ดู distinctUntilChanged เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับฟังก์ชันโฟลว์ของ Kotlin

ทำให้สถานะในการติดตามลักษณะไม่ถูกต้อง

TraitStateInvalidationอินเทอร์เฟซ ช่วยให้คุณยกเลิกสถานะที่ดึงข้อมูลผ่านการสมัครใช้บริการ ไปยังอุปกรณ์เป้าหมายได้ในกรณีที่ระบบรายงานสถานะไม่ถูกต้อง ตัวอย่างกรณีที่อาจมีการรายงานสถานะไม่ถูกต้อง ได้แก่ การใช้แอตทริบิวต์ในMatterลักษณะที่มีคุณภาพ "C" หรือเนื่องจากการติดตั้งใช้งานอุปกรณ์ที่ทำให้เกิดปัญหาโดยไม่คาดคิด

API นี้จะออกคำสั่งให้อ่านสถานะลักษณะปัจจุบันและแสดงผลลัพธ์ ผ่านขั้นตอนลักษณะที่มีอยู่

รับลักษณะ จากนั้นเรียกใช้ forceRead ในลักษณะ

val generalDiagnosticsTrait = device.trait(GeneralDiagnostics).first()
generalDiagnosticsTrait.forceRead()

ดูรายการลักษณะของประเภทอุปกรณ์

ควรใช้ประเภทอุปกรณ์เป็นจุดเริ่มต้นในการอ่านลักษณะ เนื่องจากประเภทอุปกรณ์จะ แยกอุปกรณ์ออกเป็นชิ้นส่วนที่ใช้งานได้ (เช่น ปลายทางใน Matter)

นอกจากนี้ยังพิจารณาถึงการชนกันของลักษณะในกรณีที่อุปกรณ์มีอุปกรณ์ 2 ประเภท ซึ่งทั้ง 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)

ดูรายการอุปกรณ์ที่มีลักษณะเฉพาะ

คุณใช้ฟังก์ชัน filter ใน Kotlin เพื่อปรับแต่งการเรียก API เพิ่มเติมได้ ตัวอย่างเช่น หากต้องการดูรายการอุปกรณ์ในบ้านที่มีลักษณะเปิด/ปิดทั้งหมด ให้ทำดังนี้

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

ดูรายการลักษณะทั้งหมดที่มีใน 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)
    }
  }

มีอุปกรณ์หลายประเภทใน Home API ที่อาจแสดงถึงประเภทอุปกรณ์หลัก เช่น ไม่มีประเภทอุปกรณ์ "หลอดไฟ" แต่จะมีอุปกรณ์ 4 ประเภทที่แตกต่างกันซึ่งอาจแสดงถึงหลอดไฟ ดังที่แสดงใน ตัวอย่างก่อนหน้า ดังนั้น หากต้องการดูภาพรวมที่ครอบคลุมของอุปกรณ์ประเภทระดับสูงในบ้าน คุณต้องรวมอุปกรณ์หลายประเภทไว้ในโฟลว์ที่กรองแล้ว

ดูรายการประเภทอุปกรณ์ทั้งหมดที่พร้อมใช้งานใน Home API ได้ที่DeviceTypeอินเทอร์เฟซ

ดูรหัสผู้ให้บริการหรือรหัสผลิตภัณฑ์สำหรับอุปกรณ์

ลักษณะBasicInformation ประกอบด้วยข้อมูล เช่น รหัสผู้ให้บริการ รหัสผลิตภัณฑ์ ชื่อผลิตภัณฑ์ และ หมายเลขซีเรียลของอุปกรณ์

// 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 (CSA) ออกรหัสผู้ให้บริการ: "matterOriginalVendorId": "0xfff1",

• ตัวระบุผลิตภัณฑ์ที่ระบุผลิตภัณฑ์ของผู้ขายได้อย่างไม่ซ้ำกัน "matterOriginalProductId": "0x1234",

• ตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์ ซึ่งสร้างขึ้นในลักษณะเฉพาะของผู้ผลิต "matterUniqueId": "matter-device-id",

เมื่อป้อนฟิลด์สตริงเหล่านี้ ให้ใช้Matter รหัสผู้ให้บริการและรหัสผลิตภัณฑ์หากมี หากคุณไม่ได้เป็นสมาชิก CSA และไม่ได้รับมอบหมายรหัสเหล่านี้ คุณสามารถเว้นช่อง matterOriginalVendorId และ matterOriginalProductId ว่างไว้ แล้วระบุ matterUniqueId เป็นตัวระบุได้

ตัวอย่างการตอบกลับ 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

ข้อมูลเมตาของอุปกรณ์และลักษณะ

อุปกรณ์และลักษณะใน Home API มีข้อมูลเมตาที่เชื่อมโยงอยู่ ซึ่งจะช่วยในการจัดการประสบการณ์ของผู้ใช้ในแอปได้

ลักษณะแต่ละอย่างใน Home API มีพร็อพเพอร์ตี้ sourceConnectivity ซึ่งมีข้อมูลเกี่ยวกับสถานะออนไลน์และสถานที่ตั้งของลักษณะ (การกำหนดเส้นทางในพื้นที่หรือระยะไกล)

รับประเภทหลักของอุปกรณ์

อุปกรณ์บางเครื่องอาจแสดงอุปกรณ์หลายประเภทผ่าน Home API หากต้องการให้ผู้ใช้เห็นตัวเลือกที่เหมาะสมใน แอป (เช่น การควบคุมอุปกรณ์และการทำงานอัตโนมัติที่แนะนำ) สำหรับอุปกรณ์ของตน คุณควรตรวจสอบประเภทอุปกรณ์หลักของอุปกรณ์

ก่อนอื่น ให้รับประเภทของอุปกรณ์โดยใช้ 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 ลักษณะมาตรฐานอาจยังออนไลน์อยู่เนื่องจากการกำหนดเส้นทางในพื้นที่ แต่ลักษณะที่อิงตามระบบคลาวด์จะออฟไลน์

ตรวจสอบการกำหนดเส้นทางเครือข่ายของลักษณะ

นอกจากนี้ คุณยังดูสถานที่ตั้งของลักษณะได้ใน Home API dataSourceLocality จะระบุว่ามีการกำหนดเส้นทางลักษณะจากระยะไกล (ผ่านระบบคลาวด์) ในเครื่อง (ผ่านฮับในเครื่อง) หรือแบบเพียร์ทูเพียร์ (จากอุปกรณ์ไปยังอุปกรณ์โดยตรง ไม่ต้องใช้ฮับ)

ค่าสถานที่ที่ไม่รู้จัก UNSPECIFIED อาจเกิดขึ้นได้ เช่น ขณะที่แอป กำลังบูตและยังไม่ได้เชื่อมต่อกับฮับหรือเซิร์ฟเวอร์เพื่อเชื่อมต่ออุปกรณ์ อุปกรณ์เหล่านี้ไม่สามารถเข้าถึงได้และจะทำให้คำขอโต้ตอบจากคำสั่งหรือเหตุการณ์ล้มเหลว ทั้งนี้ขึ้นอยู่กับไคลเอ็นต์ที่จะกำหนดวิธีจัดการอุปกรณ์ดังกล่าว

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

ตรวจสอบการกำหนดเส้นทางเครือข่ายสำหรับอุปกรณ์

เช่นเดียวกับการเชื่อมต่อ ระบบจะตรวจสอบสถานที่ที่ระดับประเภทอุปกรณ์ สถานะ ที่ส่งคืนคือการรวมกันของสถานที่ตั้งสำหรับลักษณะทั้งหมดในอุปกรณ์นั้น

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

สถานะของ MIXED อาจสังเกตได้ในสถานการณ์ที่คล้ายกัน กับการเชื่อมต่อ PARTIALLY_ONLINE โดยลักษณะบางอย่างจะอยู่ในระบบคลาวด์ ขณะที่ลักษณะอื่นๆ จะอยู่ในเครื่อง

เปลี่ยนชื่ออุปกรณ์

เรียกใช้เมธอด setName() เพื่อเปลี่ยนชื่ออุปกรณ์

mixerDevice.setName("Grendel")

ระบบจะตัดชื่อหากเกินขีดจำกัด 60 Code Point ของ Unicode (อักขระ) และจะไม่มีข้อผิดพลาด นักพัฒนาแอปมีหน้าที่จัดการชื่อที่ยาว และสามารถตัดสินใจได้ว่าจะแจ้งให้ผู้ใช้ทราบว่าระบบจะตัดชื่อให้สั้นลงหรือไม่

รายการ API

เมื่อสร้างอินสแตนซ์ของ Home แล้ว คุณจะเข้าถึง Device API ต่อไปนี้ผ่านอินสแตนซ์ได้

เมื่อมี HomeDevice แล้ว คุณจะเข้าถึง API ต่อไปนี้ได้