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

เข้าถึง Device API ได้ผ่าน Home API นําเข้าแพ็กเกจเหล่านี้ลงในแอป

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

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

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

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

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

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

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

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

การโทรตัวอย่าง

ดูรายการอุปกรณ์

เมื่อโครงสร้างพร้อมใช้งาน การเรียก devices() จะแสดงผลลัพธ์เป็นโฟลว์ของอุปกรณ์ที่เข้าถึงได้จากโครงสร้างนั้น

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับฟังก์ชันการไหลของ Kotlin ได้ที่ distinctUntilChanged

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

อินเทอร์เฟซ 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 primaryType = types.first { it.metadata.isPrimaryType }

ตรวจสอบว่าลักษณะนิสัยออนไลน์อยู่หรือไม่

ใช้เมธอด connectivityState() เพื่อตรวจสอบการเชื่อมต่อของแทร็ก

val onOffConnectivity = onOffTrait?.metadata?.sourceConnectivity?.connectivityState

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

ตรวจสอบการเชื่อมต่อของอุปกรณ์

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

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

คุณอาจเห็นสถานะ PARTIALLY_ONLINE ในกรณีของอุปกรณ์ประเภทต่างๆ ที่ผสมกันเมื่อไม่มีการเชื่อมต่ออินเทอร์เน็ต ลักษณะของมาตรฐาน Matter อาจยังออนไลน์อยู่เนื่องจากการกำหนดเส้นทางภายใน แต่ลักษณะที่อิงตามระบบคลาวด์จะออฟไลน์

ตรวจสอบการกำหนดเส้นทางเครือข่ายของแทร็ก

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

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

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

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

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

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

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

รายการ API

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

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