Điều khiển thiết bị

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

Bạn cũng có thể kiểm tra tính năng hỗ trợ cho một lệnh thuộc tính. 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 thiết bị có hỗ trợ lệnh toggle của thuộc tính Bật/Tắt hay không:

// 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 tương tự như việc đọc 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 Bật/tắt của thuộc tính OnOff. 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 thay đổi onOff thành false nếu là true hoặc thành true nếu là false:

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

Tất cả lệnh thuộc tính đề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 trường hợp ngoại lệ này và hiển thị thông tin chi tiết cho người dùng trong trường hợp có thể xử lý 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.

Ngoài ra, hãy sử dụng các 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, khi lệnh này hoàn tất, bạn có thể đọc trạng thái như mô tả trong phần Đọ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 phần Quan sát trạng thái. Đây là 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ác đặc điểm OnOff hoặc LevelControl:

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

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

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

Ví dụ: lệnh step cho đặc điểm FanControl có hai đố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 đặc điểm Matter, nhưng không hỗ trợ một thuộc tính cụ thể. Ví dụ: thiết bị Cloud-to-cloud được ánh xạ đến Matter có thể không hỗ trợ mọi thuộc tính Matter. Để 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 thiết bị có hỗ trợ thuộc tính onOff của thuộc tính Bật/Tắt hay không:

// 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ể nhận 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ề có phải là do thiết bị không báo cáo giá trị đó hay không, hoặc giá trị của thuộc tính thực sự là null hay không, 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 thuộc tính đặ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 thuộc tính 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.

Liệu có thể thay đổi giá trị của một thuộc tính hay không phụ thuộc vào hai 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 các đặc điểm đó cung cấp thông tin này.

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

• Chỉ có thể đọ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ó thể đọ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 lệnh. Ví dụ: thuộc tính currentLevel của đặc điểm Matter LevelControl chỉ có thể đọc, nhưng giá trị của thuộc tính này có thể được thay đổi bằng 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 thuộc tính, nhưng không có lệnh nào sẽ ả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.

• 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 thuộc tính và giá trị của thuộc tính có thể thay đổi do việc gửi lệnh. Ví dụ: bạn có thể ghi vào nhưng cũng có thể cập nhật thuộc tính occupiedCoolingSetpoint của đặc điểm Thermostat bằng lệnh setpointRaiseLower.

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 biết cách đặt giá trị của thuộc tính DoorLockTrait.WrongCodeEntryLimit một cách rõ ràng.

Để đặt giá trị thuộc tính, hãy gọi hàm update của đặc điểm và truyền vào hàm đó một hàm sửa đổi để đặt giá trị mới. Trước tiên, bạn nên xác minh rằng đặc điểm này hỗ trợ một thuộc tính.

Ví dụ:

    var 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) }
    }