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

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

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

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

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

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

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

ใน Home API เวอร์ชัน 1.8 คุณมีตัวเลือกให้ API แสดงอุปกรณ์แบบหลายส่วนเป็นอุปกรณ์เดียวโดยตั้งค่าพารามิเตอร์ enableMultipartDevices ของเมธอด devices() เป็น true ดูข้อมูลเพิ่มเติมได้ที่ อุปกรณ์แบบหลายส่วนใน Android

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

ดูตัวอย่างการตรวจสอบแอตทริบิวต์ OnOff จากลักษณะเฉพาะ On/Off ของอุปกรณ์ เมื่อใช้โมเดลข้อมูลลักษณะเฉพาะของ 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()!!

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

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

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

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

รับลักษณะเฉพาะ แล้วเรียกใช้ forceRead ในลักษณะเฉพาะ

val onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.forceRead()

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

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

นอกจากนี้ ประเภทอุปกรณ์ยังคำนึงถึงการชนกันของลักษณะเฉพาะในกรณีที่อุปกรณ์มีประเภทอุปกรณ์ 2 ประเภท ซึ่งทั้ง 2 ประเภทอาจมีลักษณะเฉพาะเดียวกัน ตัวอย่างเช่น หากอุปกรณ์เป็นทั้งลำโพงและหลอดไฟแบบหรี่แสงได้ อุปกรณ์จะมีลักษณะเฉพาะ On/Off 2 รายการและลักษณะเฉพาะ Level Control 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 เพิ่มเติมได้ ตัวอย่างเช่น หากต้องการดูรายการอุปกรณ์ในบ้านที่มีลักษณะเฉพาะ On/Off ทั้งหมด ให้ทำดังนี้

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

ดูรายการลักษณะเฉพาะทั้งหมดที่พร้อมใช้งานใน Home API ได้ที่อินเทอร์เฟซ Traitสำหรับรายการลักษณะเฉพาะทั้งหมดที่พร้อมใช้งานใน Home API

ดูรายการอุปกรณ์ที่มีประเภทอุปกรณ์คล้ายกัน

หากต้องการดูรายการอุปกรณ์ที่แสดงหลอดไฟทั้งหมดในบ้าน ให้ทำดังนี้

// 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 มีประเภทอุปกรณ์หลายประเภทที่แสดงประเภทอุปกรณ์หลักได้ ตัวอย่างเช่น ไม่มีประเภทอุปกรณ์ "Light" แต่มีประเภทอุปกรณ์ 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 คุณสามารถรวมฟิลด์สตริงต่อไปนี้ไว้ในการตอบกลับ SYNC เพื่อระบุอุปกรณ์แบบ Cloud-to-cloud ผ่านลักษณะเฉพาะ BasicInformation

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

ดูที่อยู่ IP ของอุปกรณ์

หากต้องการดูที่อยู่ IP ของอุปกรณ์ ให้ใช้แอตทริบิวต์ networkInterfaces ของ ลักษณะเฉพาะ GeneralDiagnostics ระบบจะแสดงที่อยู่เป็นอาร์เรย์ไบต์ ซึ่งคุณสามารถจัดรูปแบบเป็นสตริง IPv4 หรือ IPv6 มาตรฐานได้

val ipAddresses =
  trait.networkInterfaces?.flatMap { networkInterface ->
    (networkInterface.ipv4Addresses + networkInterface.ipv6Addresses).mapNotNull { bytes ->
      try {
        java.net.InetAddress.getByAddress(bytes).hostAddress
      } catch (e: java.net.UnknownHostException) {
        null
      }
    }
  } ?: emptyList()

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

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

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

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

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

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

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

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

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

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

mixerDevice.setName("Grendel")

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