ควบคุมอุปกรณ์

ตรวจสอบว่าแอตทริบิวต์รองรับคําสั่งหรือไม่

นอกจากนี้ คุณยังตรวจสอบการสนับสนุนสำหรับคำสั่งลักษณะได้ด้วย นอกจากนี้ ให้ใช้ฟังก์ชันระดับลักษณะ supports เพื่อตรวจสอบว่าอุปกรณ์หนึ่งๆ รองรับคําสั่งหรือไม่

เช่น หากต้องการตรวจสอบว่าอุปกรณ์รองรับคําสั่ง 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")
}

ส่งคำสั่งไปยังอุปกรณ์

การส่งคําสั่งคล้ายกับการอ่านแอตทริบิวต์สถานะจากลักษณะ หากต้องการเปิดหรือปิดอุปกรณ์ ให้ใช้คำสั่งเปิด/ปิดของลักษณะ OnOff ซึ่งกำหนดไว้ในรูปแบบข้อมูลของระบบนิเวศ Google Home เป็น toggle() วิธีนี้จะเปลี่ยน onOff เป็น false หากเป็น true หรือเป็น true หากเป็น false

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

คำสั่งลักษณะทั้งหมดเป็นฟังก์ชัน suspend และจะเสร็จสมบูรณ์ก็ต่อเมื่อ API ส่งการตอบกลับ (เช่น ยืนยันว่าสถานะของอุปกรณ์มีการเปลี่ยนแปลง) คำสั่งอาจแสดงข้อยกเว้นหากตรวจพบปัญหาเกี่ยวกับขั้นตอนการดำเนินการ ในฐานะนักพัฒนาแอป คุณควรใช้บล็อก try-catch เพื่อจัดการข้อยกเว้นเหล่านี้อย่างเหมาะสม และแสดงข้อมูลโดยละเอียดต่อผู้ใช้ในกรณีที่สามารถดำเนินการกับข้อผิดพลาดได้ ข้อยกเว้นที่ไม่ได้รับการจัดการจะหยุดรันไทม์ของแอปและอาจส่งผลให้แอปขัดข้อง

หรือจะใช้คําสั่ง off() หรือ on() เพื่อตั้งค่าสถานะอย่างชัดแจ้งก็ได้

onOffTrait.off()
onOffTrait.on()

หลังจากส่งคําสั่งเพื่อเปลี่ยนสถานะแล้ว เมื่อดำเนินการเสร็จแล้ว คุณจะอ่านสถานะได้ตามที่อธิบายไว้ในอ่านสถานะอุปกรณ์เพื่อจัดการในแอป หรือจะใช้โฟลว์ตามที่อธิบายไว้ในสังเกตสถานะ ซึ่งเป็นวิธีที่แนะนำก็ได้

ส่งคําสั่งพร้อมพารามิเตอร์

คำสั่งบางรายการอาจใช้พารามิเตอร์ เช่น คำสั่งในลักษณะของ OnOff หรือ 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(),
)

คำสั่งบางรายการมีอาร์กิวเมนต์ที่ไม่บังคับ ซึ่งอยู่หลังอาร์กิวเมนต์ที่ต้องระบุ

เช่น คําสั่ง step สําหรับ FanControl trait มีพารามิเตอร์ที่ไม่บังคับ 2 รายการ ได้แก่

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 }

ตรวจสอบว่าลักษณะรองรับแอตทริบิวต์หรือไม่

อุปกรณ์บางรุ่นอาจรองรับลักษณะ Matter แต่ไม่ใช่แอตทริบิวต์ที่เฉพาะเจาะจง เช่น อุปกรณ์ Cloud-to-cloud ที่แมปกับ Matter อาจไม่รองรับแอตทริบิวต์ Matter บางรายการ หากต้องการจัดการกับกรณีเช่นนี้ ให้ใช้ฟังก์ชัน supports ระดับลักษณะและ Attribute enum ของลักษณะเพื่อตรวจสอบว่าอุปกรณ์หนึ่งๆ รองรับแอตทริบิวต์หรือไม่

เช่น หากต้องการตรวจสอบว่าอุปกรณ์รองรับแอตทริบิวต์ 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!")
}

แอตทริบิวต์บางรายการเป็นค่า Null ได้ในสเปค Matter หรือสคีมา Cloud-to-cloud smart home สําหรับแอตทริบิวต์เหล่านี้ คุณสามารถระบุว่าค่า null ที่แอตทริบิวต์แสดงผลนั้นเกิดจากอุปกรณ์ไม่ได้รายงานค่านั้น หรือค่าของแอตทริบิวต์คือ null จริงหรือไม่ โดยใช้ isNullable เพิ่มเติมจาก 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!")
}

อัปเดตแอตทริบิวต์ลักษณะ

หากต้องการเปลี่ยนค่าของแอตทริบิวต์หนึ่งๆ และไม่มีคำสั่งใดของแอตทริบิวต์นั้นที่เปลี่ยนค่าได้ แอตทริบิวต์นั้นอาจรองรับการตั้งค่าค่าอย่างชัดเจน

ความสามารถในการเปลี่ยนแปลงค่าของแอตทริบิวต์ขึ้นอยู่กับปัจจัย 2 อย่างต่อไปนี้

• แอตทริบิวต์เขียนได้ไหม
• ค่าของแอตทริบิวต์จะเปลี่ยนแปลงเป็นผลข้างเคียงของการส่งคําสั่งลักษณะได้ไหม

เอกสารอ้างอิงสำหรับลักษณะและแอตทริบิวต์ของลักษณะมีข้อมูลนี้

ดังนั้น ชุดค่าผสมของพร็อพเพอร์ตี้ที่กำหนดวิธีเปลี่ยนแปลงค่าของแอตทริบิวต์มีดังนี้

• เป็นแบบอ่านอย่างเดียวและไม่ได้รับผลกระทบจากคําสั่งอื่นๆ ซึ่งหมายความว่าค่าของแอตทริบิวต์จะไม่เปลี่ยนแปลง เช่น แอตทริบิวต์ currentPosition ของลักษณะ Switch

• เป็นแบบอ่านอย่างเดียวและได้รับผลกระทบจากคําสั่งอื่นๆ ซึ่งหมายความว่าค่าของแอตทริบิวต์จะเปลี่ยนแปลงได้ก็ต่อเมื่อมีการส่งคําสั่งเท่านั้น เช่น แอตทริบิวต์ currentLevel ของลักษณะ LevelControl Matter เป็นแบบอ่านอย่างเดียว แต่ค่าของแอตทริบิวต์จะเปลี่ยนได้โดยใช้คำสั่ง เช่น moveToLevel

• เขียนได้และไม่ได้รับผลกระทบจากคําสั่งอื่นๆ ซึ่งหมายความว่าคุณสามารถเปลี่ยนแปลงค่าของแอตทริบิวต์ได้โดยตรงโดยใช้ฟังก์ชัน update ของลักษณะ แต่จะไม่มีคำสั่งที่จะส่งผลต่อค่าของแอตทริบิวต์ เช่น แอตทริบิวต์ WrongCodeEntryLimit ของลักษณะ DoorLock

• เขียนได้และได้รับผลกระทบจากคําสั่งอื่นๆ ซึ่งหมายความว่าคุณสามารถเปลี่ยนค่าของแอตทริบิวต์ได้โดยตรงโดยใช้ฟังก์ชัน update ของแอตทริบิวต์ และค่าของแอตทริบิวต์จะเปลี่ยนแปลงตามผลลัพธ์ของการส่งคําสั่ง ตัวอย่างเช่น คุณสามารถเขียนข้อมูลลงในแอตทริบิวต์ occupiedCoolingSetpoint ของลักษณะ Thermostat ได้ และยังอัปเดตด้วยคําสั่ง setpointRaiseLower ได้ด้วย

ตัวอย่างการใช้ฟังก์ชันอัปเดตเพื่อเปลี่ยนค่าของแอตทริบิวต์

ตัวอย่างนี้แสดงวิธีตั้งค่าค่าของแอตทริบิวต์ DoorLockTrait.WrongCodeEntryLimit อย่างชัดเจน

หากต้องการตั้งค่าแอตทริบิวต์ ให้เรียกฟังก์ชัน update ของลักษณะ แล้วส่งผ่านฟังก์ชันตัวแปลงค่าที่จะตั้งค่าใหม่ คุณควรตรวจสอบว่าลักษณะรองรับแอตทริบิวต์ก่อน

เช่น

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