เข้าถึงอุปกรณ์และข้อมูลเมตาของอุปกรณ์สำหรับ 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 รายการและลักษณะเฉพาะการควบคุมระดับ 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สำหรับรายการทั้งหมด

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

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

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

ดูที่อยู่ 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 ตัว และจะไม่แสดงข้อผิดพลาด นักพัฒนาแอปมีหน้าที่รับผิดชอบในการจัดการชื่อที่ยาว และสามารถตัดสินใจได้ว่าจะแจ้งให้ผู้ใช้ทราบว่าระบบจะตัดชื่อให้สั้นลงหรือไม่