เข้าถึงอุปกรณ์และข้อมูลเมตาของอุปกรณ์สำหรับ 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 ให้ตรวจสอบฟิลด์ error.code และ error.message เพื่อดูว่าเกิดข้อผิดพลาดใด นอกจากนี้ อาจมีรหัสข้อผิดพลาดย่อย ด้วย ดังนั้นให้เรียกใช้เมธอด getSubErrorCodes() แล้วตรวจสอบผลลัพธ์

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

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

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

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

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

เมื่อมีข้อมูลอ้างอิงถึงอินสแตนซ์ Structure แล้ว การเรียกใช้ 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 APIs ซึ่งระบุลักษณะนี้เป็น 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 onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.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 (Alliance)รหัสผู้ให้บริการที่ออกให้ "matterOriginalVendorId": "0xfff1",

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

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

เมื่อป้อนฟิลด์สตริงเหล่านี้ ให้ใช้Matter รหัสผู้ให้บริการและผลิตภัณฑ์หากมี หากคุณไม่ได้เป็นAllianceสมาชิกและไม่ได้รับรหัสเหล่านี้ คุณสามารถ ปล่อยช่อง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 (อักขระ) และจะไม่มีข้อผิดพลาด นักพัฒนาแอปมีหน้าที่จัดการชื่อที่ยาว และสามารถตัดสินใจได้ว่าจะแจ้งให้ผู้ใช้ทราบว่าระบบจะตัดชื่อให้สั้นลงหรือไม่