監控 Android 裝置的狀態

在 Android 版 Home API 中，您可以透過 Kotlin 的流程觀察住家狀態的變化。如要觀察 Home API 中住家、房間、裝置中繼資料和裝置狀態的變化，可以使用任何繼承 HomeObjectsFlow 介面的 API。方法是從流程中收集。

新增、刪除或修改集合中的任何項目時，系統會傳回集合的最新快照。

開發人員必須比較這個快照與舊副本，才能推斷出具體變更。Home API 中每個父項物件類型提供的 id 欄位，可用於這項用途。

如何使用流程

以下是從 Home API 流程收集資料的基本範例。在下列範例中，必須先建立 Home 的例項，才能存取住家中的集合：

val context = LocalContext.current
val homeManager = Home.getClient(context)

追蹤住家結構變更

住家結構發生下列變更時，系統會收集這項資訊：

homeManager.structures().map { it.firstOrNull() }.collect {
  println("Structure ${it.id} updated to ${it}")
}

val structure =  homeManager.structures().list().firstOrNull()!!

追蹤特定裝置的變更

對裝置進行下列變更時，系統會收集這項資訊：

structure
  .devices()
  .map { devices -> device.filter { it.name == "Bedroom Lamp" }.single() }
  .collect {
    println("The bedroom lamp has changed!")
  }

val device = structure.devices().list().firstOrNull { it.name == "Bedroom Lamp" }!!

追蹤裝置上特定特性的變更

使用裝置和 Home API 支援的任何特徵。如需完整清單，請參閱 Trait。

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

    trait?.collect {
      if (it != null) {
        println("Got new state update! ${it.onOff}")
      }
    }

追蹤裝置上特定類型的變更

對裝置類型進行下列變更，會觸發這項收集作業：

使用 Home API 支援的任何 Matter 裝置類型。如需完整清單，請參閱 DeviceType。

device.type(DimmableLightDevice).collect { type ->
    println("Got new state update! ${type.trait(LevelControl)?.currentLevel}")
}

追蹤住家結構體中房間的變更

對聊天室進行下列變更會觸發這個集合：

如要追蹤裝置何時新增至房間或從房間移除，請使用 devices() 流程。

structure.rooms().collect {
  println("Got a new updated set of rooms!")

  for (room in it) {
    println("Got room $room")
  }
}

訂閱事件

在 Home API 中，事件用於偵測裝置狀態的變化。

如要訂閱特定裝置上的事件，請呼叫三個 HomeDevice 的其中一個。events 函式，每個函式都會傳回 Flow<Event>：

  1. events(event: EventFactory<T>) 會傳回特定類型事件的流程：

    val eventFlow = homeDevice.type(DoorLockDevice).first().events(DoorLock.DoorLockAlarmEvent)

  2. events(trait: TraitFactory<T>) 會傳回特徵傳送的所有事件串流：

    val eventflow = homeDevice.type(DoorLockDevice).first().events(DoorLock)

  3. events() 會傳回物件可用的事件串流：

    val eventflow = homeDevice.type(DoorLockDevice).first().events()

如要使用流程中的事件，請使用 flow.collect() 函式：

eventflow.collect { event ->
  if (event != null) {
    logger.atInfo().log("Received event %s", event)
    // do something
  }
}

訂閱實體關係事件

每當新增、移除或更新實體 (例如住家結構體、房間、裝置或自動化動作) 時，您都可以監聽系統發出的事件。這些事件是 HomeObjectChangeEvent 的例項，並會攜帶已變更實體的 ID。

如要取得產生所需事件的串流，請在對應 Flow 方法產生的 HomeObjectsFlow<T> 上呼叫 stream() 方法：

表格：事件串流
實體 介面 流量法
Structure HasStructures structures()
Room HasRooms rooms()
HomeDevice HasHomeDevices devices()
Automation HasAutomations automations()

舉例來說，您可以按照下列方式處理裝置變更：

val devicesStream = home.devices().stream()

// Collect and react to device changes.
devicesStream.collect { deviceEvent ->
  when (deviceEvent) {
    is HomeObjectAddedEvent ->
      println("New device now available with id: ${deviceEvent.id}")
    is HomeObjectUpdatedEvent -> println("Device ${deviceEvent.id} has been updated")
    is HomeObjectRemovedEvent -> println("Device is removed from your account")
    else -> {}
  }
}