Kiểm soát thiết bị trên Android

Kiểm tra xem một đặc điểm có hỗ trợ một lệnh hay không

Bạn cũng có thể kiểm tra xem một lệnh đặc điểm có được hỗ trợ hay không. Ngoài ra, hãy sử dụng hàm supports ở cấp đặc điểm để kiểm tra xem một lệnh có được hỗ trợ cho một thiết bị cụ thể hay không.

Ví dụ: để kiểm tra xem một thiết bị có hỗ trợ lệnh của đặc điểm Bật/Tắt hay không, hãy làm như sau: toggle

// Check if the OnOff trait supports the toggle command.
if (onOffTrait.supports(OnOff.Command.Toggle)) {
  println("onOffTrait supports toggle command")
} else {
  println("onOffTrait does not support stateful toggle command")
}

Gửi lệnh đến một thiết bị

Việc gửi lệnh cũng tương tự như việc đọc một thuộc tính trạng thái từ một đặc điểm. Để bật hoặc tắt thiết bị, hãy sử dụng lệnh Toggle của OnOff đặc điểm. Lệnh này được xác định trong mô hình dữ liệu hệ sinh thái Google Home là toggle(). Phương thức này sẽ thay đổi onOff thành false nếu giá trị là true hoặc thành true nếu giá trị là false:

// Calling a command on a trait.
try {
  onOffTrait.toggle()
} catch (e: HomeException) {
  // Code for handling the exception
}

Tất cả các lệnh đặc điểm đều là hàm suspend và chỉ hoàn tất khi API trả về một phản hồi (chẳng hạn như xác nhận trạng thái thiết bị đã thay đổi). Các lệnh có thể trả về một ngoại lệ nếu phát hiện thấy vấn đề với quy trình thực thi. Là nhà phát triển, bạn nên sử dụng khối try-catch để xử lý đúng cách các ngoại lệ này và hiển thị thông tin chi tiết cho người dùng về những trường hợp có thể khắc phục lỗi. Các ngoại lệ chưa được xử lý sẽ dừng thời gian chạy ứng dụng và có thể dẫn đến sự cố trong ứng dụng của bạn.

Ngoài ra, hãy sử dụng lệnh off() hoặc on() để đặt trạng thái một cách rõ ràng:

onOffTrait.off()
onOffTrait.on()

Sau khi gửi lệnh để thay đổi trạng thái, bạn có thể đọc trạng thái như mô tả trong bài viết Đọc trạng thái thiết bị để xử lý trạng thái đó trong ứng dụng. Ngoài ra, hãy sử dụng các luồng như mô tả trong bài viết Quan sát trạng thái (phương thức ưu tiên).

Gửi lệnh có tham số

Một số lệnh có thể sử dụng các tham số, chẳng hạn như các tham số trên đặc điểm OnOff hoặc LevelControl:

offWithEffect

// Turn off the light using the DyingLight effect.
onOffTrait.offWithEffect(
  effectIdentifier = OnOffTrait.EffectIdentifierEnum.DyingLight,
  effectVariant = 0u,
)

moveToLevel

// Change the brightness of the light to 50%
levelControlTrait.moveToLevel(
  level = 127u.toUByte(),
  transitionTime = null,
  optionsMask = LevelControlTrait.OptionsBitmap(),
  optionsOverride = LevelControlTrait.OptionsBitmap(),
)

Lưu ý: Theo Matter Thông số kỹ thuậtcurrentLevel, thuộc tính có phạm vi từ 0 (hoặc 1) đến 254. Do đó, để đặt mức độ sáng thành khoảng 50%, hãy sử dụng giá trị 127.

Một số lệnh có đối số không bắt buộc, xuất hiện sau các đối số bắt buộc.

Ví dụ: lệnh step cho đặc điểm FanControl trait có 2 đối số không bắt buộc:

val fanControlTraitFlow: Flow<FanControl?> =
  device.type(FanDevice).map { it.standardTraits.fanControl }.distinctUntilChanged()

val fanControl = fanControlTraitFlow.firstOrNull()

// Calling a command with optional parameters not set.
fanControl?.step(direction = FanControlTrait.StepDirectionEnum.Increase)

// Calling a command with optional parameters.
fanControl?.step(direction = FanControlTrait.StepDirectionEnum.Increase) { wrap = true }

Kiểm tra xem một đặc điểm có hỗ trợ một thuộc tính hay không

Một số thiết bị có thể hỗ trợ một Matter đặc điểm, nhưng không hỗ trợ một thuộc tính cụ thể. Ví dụ: một thiết0/} bị đã được ánh xạ tới Matter có thể không hỗ trợ mọi Matter thuộc tính.Cloud-to-cloud Để xử lý các trường hợp như vậy, hãy sử dụng hàm supports ở cấp đặc điểm và enum Attribute của đặc điểm để kiểm tra xem thuộc tính có được hỗ trợ cho một thiết bị cụ thể hay không.

Ví dụ: để kiểm tra xem một thiết bị có hỗ trợ thuộc tính của đặc điểm Bật/Tắt hay không, hãy làm như sau:onOff

// Check if the OnOff trait supports the onOff attribute.
if (onOffTrait.supports(OnOff.Attribute.onOff)) {
  println("onOffTrait supports onOff state")
} else {
  println("onOffTrait is for a command only device!")
}

Một số thuộc tính có thể có giá trị rỗng trong thông số kỹ thuật Matter hoặc giản đồ Cloud-to-cloud smart home. Đối với các thuộc tính này, bạn có thể xác định xem giá trị null do thuộc tính trả về là do thiết bị không báo cáo giá trị đó hay giá trị của thuộc tính thực sự là null, bằng cách sử dụng isNullable ngoài supports:

// Check if a nullable attribute is set or is not supported.
if (onOffTrait.supports(OnOff.Attribute.startUpOnOff)) {
  // The device supports startupOnOff, it is safe to expect this value in the trait.
  if (OnOff.Attribute.startUpOnOff.isNullable && onOffTrait.startUpOnOff == null) {
    // This value is nullable and set to null. Check the specification as to
    // what null in this case means
    println("onOffTrait supports startUpOnOff and it is null")
  } else {
    // This value is nullable and set to a value.
    println("onOffTrait supports startUpOnOff and it is set to ${onOffTrait.startUpOnOff}")
  }
} else {
  println("onOffTrait does not support startUpOnOff!")
}

Cập nhật các thuộc tính của đặc điểm

Nếu bạn muốn thay đổi giá trị của một thuộc tính nhất định và không có lệnh nào của đặc điểm thực hiện việc này, thì thuộc tính đó có thể hỗ trợ việc đặt giá trị một cách rõ ràng.

Việc có thể thay đổi giá trị của một thuộc tính hay không phụ thuộc vào 2 yếu tố:

Thuộc tính có thể ghi được không?
Giá trị của thuộc tính có thể thay đổi do tác dụng phụ của việc gửi lệnh đặc điểm không?

Tài liệu tham khảo về các đặc điểm và thuộc tính của chúng cung cấp thông tin này.

Do đó, các tổ hợp thuộc tính quyết định cách thay đổi giá trị của một thuộc tính là:

Chỉ đọc và không bị ảnh hưởng bởi các lệnh khác. Điều này có nghĩa là giá trị của thuộc tính không thay đổi. Ví dụ: thuộc tính currentPosition của đặc điểm Switch.
Chỉ đọc và bị ảnh hưởng bởi các lệnh khác. Điều này có nghĩa là cách duy nhất để giá trị của thuộc tính có thể thay đổi là do kết quả của việc gửi một lệnh. Ví dụ: thuộc tính currentLevel của đặc điểm LevelControl Matter là chỉ đọc, nhưng giá trị của thuộc tính này có thể bị thay đổi bởi các lệnh như moveToLevel.
Có thể ghi và không bị ảnh hưởng bởi các lệnh khác. Điều này có nghĩa là bạn có thể trực tiếp thay đổi giá trị của thuộc tính bằng cách sử dụng hàm update của đặc điểm, nhưng không có lệnh nào ảnh hưởng đến giá trị của thuộc tính. Ví dụ: thuộc tính WrongCodeEntryLimit của đặc điểm DoorLock trait.
Có thể ghi và bị ảnh hưởng bởi các lệnh khác. Điều này có nghĩa là bạn có thể trực tiếp thay đổi giá trị của thuộc tính bằng cách sử dụng hàm update của đặc điểm và giá trị của thuộc tính có thể thay đổi do kết quả của việc gửi một lệnh. Ví dụ: bạn có thể ghi trực tiếp vào thuộc tính speedSetting của FanControlTrait , nhưng cũng có thể thay đổi thuộc tính này bằng lệnh step.

Ví dụ về cách sử dụng hàm cập nhật để thay đổi giá trị của một thuộc tính

Ví dụ này cho thấy cách đặt giá trị của thuộc tính một cách rõ ràng DoorLockTrait.WrongCodeEntryLimit.

Để đặt giá trị thuộc tính, hãy gọi hàm update của đặc điểm và truyền cho hàm này một hàm mutator đặt giá trị mới. Bạn nên xác minh trước rằng đặc điểm hỗ trợ một thuộc tính.

Ví dụ:

    val doorLockDevice = home.devices().list().first { device -> device.has(DoorLock) }

    val traitFlow: Flow<DoorLock?> =
      doorLockDevice.type(DoorLockDevice).map { it.standardTraits.doorLock }.distinctUntilChanged()

    val doorLockTrait: DoorLock = traitFlow.first()!!

    if (doorLockTrait.supports(DoorLock.Attribute.wrongCodeEntryLimit)) {
      val unused = doorLockTrait.update { setWrongCodeEntryLimit(3u) }
    }

Gửi nhiều lệnh cùng lúc

API Nhóm cho phép một ứng dụng gửi nhiều lệnh thiết bị Home API trong một tải trọng. Các lệnh được nhóm thành một tải trọng và thực thi song song, tương tự như cách một người có thể tạo một quy trình tự động hoá Home API automation bằng nút song song, chẳng hạn như ví dụ Mở rèm trước khi mặt trời mọc. Tuy nhiên, API Nhóm cho phép các hành vi phức tạp và tinh vi hơn so với API Tự động hoá, chẳng hạn như khả năng chọn thiết bị một cách linh hoạt trong thời gian chạy theo bất kỳ tiêu chí nào.

Các lệnh trong một nhóm có thể nhắm đến nhiều đặc điểm trên nhiều thiết bị, trong nhiều phòng, trong nhiều cấu trúc.

Việc gửi các lệnh trong một nhóm cho phép các thiết bị thực hiện hành động đồng thời. Điều này không thực sự có thể khi các lệnh được gửi tuần tự trong các yêu cầu riêng biệt. Hành vi đạt được bằng cách sử dụng các lệnh được nhóm cho phép nhà phát triển đặt trạng thái của một nhóm thiết bị để khớp với trạng thái tổng hợp được xác định trước.

Sử dụng API Nhóm

Có 3 bước cơ bản liên quan đến việc gọi lệnh thông qua API Nhóm:

Gọi Home.sendBatchedCommands() phương thức.
Trong phần nội dung của khối sendBatchedCommands(), hãy chỉ định các lệnh sẽ được đưa vào nhóm.
Kiểm tra kết quả của các lệnh đã gửi để xem lệnh có thành công hay không.

Gọi phương thức sendBatchedCommands()

Gọi Home.sendBatchedCommands() phương thức. Trên thực tế, phương thức này thiết lập một biểu thức lambda trong một ngữ cảnh nhóm đặc biệt.

home.sendBatchedCommands() {

Chỉ định các lệnh nhóm

Trong phần nội dung của khối sendBatchedCommands(), hãy điền các lệnh có thể nhóm. Các lệnh có thể nhóm là phiên bản "bóng" của các lệnh Device API hiện có có thể được sử dụng trong ngữ cảnh nhóm và được đặt tên bằng hậu tố Batchable được thêm vào. Ví dụ: lệnh của đặc điểm có một lệnh đối ứng có tên là moveToLevelBatchable().LevelControlmoveToLevel()

Ví dụ:

  val response1 = add(command1)

  val response2 = add(command2)

Nhóm sẽ tự động được gửi sau khi tất cả các lệnh đã được thêm vào ngữ cảnh nhóm và quá trình thực thi đã thoát khỏi ngữ cảnh.

Các phản hồi được ghi lại trong DeferredResponse<T> các đối tượng.

Bạn có thể thu thập các thực thể DeferredResponse<T> thành một đối tượng thuộc bất kỳ loại nào, chẳng hạn như Collection, hoặc một lớp dữ liệu mà bạn xác định. Bất kể loại đối tượng nào bạn chọn để tập hợp các phản hồi đều là đối tượng được sendBatchedCommands() trả về. Ví dụ: ngữ cảnh nhóm có thể trả về 2 DeferredResponse thực thể trong một Pair:

  val (response1, response2) = homeClient.sendBatchedComamnds {
    val response1 = add(someCommandBatched(...))
    val response2 = add(someOtherCommandBatched(...))
    Pair(response1, response2)
  }

Ngoài ra, ngữ cảnh nhóm có thể trả về các thực thể DeferredResponse trong một lớp dữ liệu tuỳ chỉnh:

  // Custom data class
  data class SpecialResponseHolder(
    val response1: DeferredResponse<String>,
    val response2: DeferredResponse<Int>,
    val other: OtherResponses
  )
  data class OtherResponses(...)

Kiểm tra từng phản hồi

Bên ngoài khối sendBatchedCommands(), hãy kiểm tra các phản hồi để xác định xem lệnh tương ứng có thành công hay không. Bạn có thể thực hiện việc này bằng cách gọi DeferredResponse.getOrThrow(). Phương thức này sẽ: - trả về kết quả của lệnh đã thực thi, - hoặc, nếu phạm vi nhóm chưa hoàn tất hoặc lệnh không thành công, thì sẽ gửi một lỗi.

Bạn chỉ nên kiểm tra kết quả bên ngoài phạm vi lambda sendBatchedCommands().

Ví dụ:

Giả sử bạn muốn xây dựng một ứng dụng sử dụng API Nhóm để thiết lập một cảnh "chúc ngủ ngon" định cấu hình tất cả các thiết bị trong nhà cho ban đêm, khi mọi người đều ngủ. Ứng dụng này sẽ tắt đèn và khoá cửa trước và cửa sau.

Sau đây là một cách tiếp cận nhiệm vụ này:

val lightDevices: List<OnOffLightDevice>
val doorlockDevices: List<DoorLockDevice>

// Send all the commands
val responses: List<DeferredResponse<Unit>> = home.sendBatchedCommands {
  // For each light device, send a Batchable command to turn it on
  val lightResponses: List<DeferredResponse<Unit>> = lightDevices.map { lightDevice ->
    add(lightDevice.standardTraits.onOff.onBatchable())
  }

  // For each doorlock device, send a Batchable command to lock it
  val doorLockResponse: List<DeferredResponse<Unit>> = doorlockDevices.map { doorlockDevice ->
    add(doorlockDevice.standardTraits.doorLock.lockDoorBatchable())
  }

  lightResponses + doorLockResponses
}

// Check that all responses were successful
for (response in responses) {
  response.getOrThrow()
}

Kiểm soát thiết bị trên Android Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Kiểm tra xem một đặc điểm có hỗ trợ một lệnh hay không

Gửi lệnh đến một thiết bị

Gửi lệnh có tham số

offWithEffect

moveToLevel

Kiểm tra xem một đặc điểm có hỗ trợ một thuộc tính hay không

Cập nhật các thuộc tính của đặc điểm

Ví dụ về cách sử dụng hàm cập nhật để thay đổi giá trị của một thuộc tính

Gửi nhiều lệnh cùng lúc

Sử dụng API Nhóm

Gọi phương thức sendBatchedCommands()

Chỉ định các lệnh nhóm

Kiểm tra từng phản hồi

Ví dụ:

Kiểm soát thiết bị trên Android