存取 Android 裝置和裝置中繼資料

裝置 API 可透過 Android 版 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

詳情請參閱「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 版中，您可以將 devices() 方法的 enableMultipartDevices 參數設為 true，讓 API 將每個多部分裝置視為單一裝置。詳情請參閱「Android 上的多部分裝置」。

讀取裝置狀態

請參閱範例，瞭解如何從裝置的開/關特徵檢查 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 Flow 函式。

使特徵訂閱中的狀態失效

TraitStateInvalidation 介面可讓您在狀態回報不正確時，透過訂閱項目使從目標裝置擷取的狀態失效。如果使用「C」品質的 Matter 特徵屬性，或是裝置實作方式導致問題，系統可能無法正確回報狀態。

這個 API 會強制讀取目前的特徵狀態，並透過現有的特徵流程傳回結果。

取得特徵，然後在特徵上執行 forceRead：

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

取得裝置類型特徵清單

裝置類型應做為讀取特徵的進入點，因為這類類型會將裝置分解為功能片段 (例如 Matter 中的端點)。

如果裝置有兩種裝置類型，且兩者可能具有相同特徵，系統也會將特徵衝突納入考量。舉例來說，如果裝置同時是音箱和可調暗燈光，就會有兩個「開/關」和兩個「等級控制」特徵。

如要取得 Dimmable Light 裝置類型可用的特徵清單，請按照下列步驟操作：

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

如果裝置有兩個名稱相同的特徵，也可能發生特徵衝突。舉例來說，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)

取得具有特定特徵的裝置清單

Kotlin 中的 filter 函式可用於進一步調整 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 中有多種裝置類型，可代表核心裝置類型。舉例來說，沒有「燈」裝置類型。而是有四種不同的裝置類型可以代表燈具，如上例所示。因此，如要全面瞭解住家中的高階裝置類型，篩選後的流程必須包含多種裝置類型。

如需 Home API 支援的裝置類型完整清單，請參閱 DeviceType 介面。

取得裝置的供應商 ID 或產品 ID

BasicInformation 特徵包含裝置的供應商 ID、產品 ID、產品名稱和序號等資訊：

// 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 裝置，為了透過 BasicInformation 特徵識別 Cloud-to-cloud 裝置，可以在 SYNC 回應中加入下列字串欄位：

  • Connectivity Standards Alliance (Alliance)核發的供應商 ID： "matterOriginalVendorId": "0xfff1",

  • 可專屬識別供應商產品的產品 ID： "matterOriginalProductId": "0x1234",

  • 裝置的專屬 ID，建構方式因製造商而異： "matterUniqueId": "matter-device-id",

輸入這些字串欄位時，請使用Matter 供應商和產品 ID (如有)。如果你不是Alliance成員，且未獲派這些 ID，可以將 matterOriginalVendorId 和 matterOriginalProductId 欄位留空，並提供 matterUniqueId 做為 ID。

以下範例 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 說明文件。

裝置和特徵中繼資料

Google Home API 中的裝置和特徵會與中繼資料建立關聯，有助於管理應用程式中的使用者體驗。

Google 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 位址，請使用 GeneralDiagnostics 特徵的 networkInterfaces 屬性。位址會以位元組陣列的形式傳回，您可以將其格式化為標準 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

在類似 PARTIALLY_ONLINE 連線狀態的情況下，可能會出現 MIXED 狀態：部分特徵以雲端為基礎，其他特徵則為本機。

變更裝置名稱

呼叫 setName() 方法來變更裝置名稱：

mixerDevice.setName("Grendel")

如果名稱超過 60 個 Unicode 碼點 (字元) 的限制，系統會截斷名稱，但不會擲回任何錯誤。開發人員有責任處理長名稱，例如決定是否要通知使用者名稱會遭到截斷。

檢查裝置的群組成員資格

實體裝置可屬於一或多個裝置群組。如要查看裝置所屬的群組，請檢查裝置上的 GroupMembership 特徵：

val groupIds = device.trait(GroupMembershipTrait)?.groupObjectIds.orEmpty()
for (groupId in groupIds) {
  println("HomeAPI", "Device belongs to group: $groupId")
}

反之，您可以在 DeviceGroup 上呼叫 devices() 流程，觀察屬於 DeviceGroup 的所有成員裝置：

group.devices(enableMultipartDevices = true).collect { members ->
  println("HomeAPI", "Group contains ${members.size} devices")
}