ควบคุมอุปกรณ์ใน Android

ตรวจสอบว่าลักษณะรองรับคำสั่งหรือไม่

นอกจากนี้ยังตรวจสอบการรองรับคำสั่งลักษณะได้ด้วย นอกจากนี้ ให้ใช้ฟังก์ชันระดับลักษณะ 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

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

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

ตัวอย่างเช่น คำสั่ง 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!")
}

แอตทริบิวต์บางรายการอาจเป็นค่าว่างในข้อกำหนด 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 ของลักษณะ และค่าของแอตทริบิวต์อาจเปลี่ยนแปลงได้อันเป็นผลมาจากการ ส่งคำสั่ง เช่น คุณสามารถเขียนแอตทริบิวต์ speedSetting ของ FanControlTrait ได้โดยตรง แต่ก็ยังแก้ไขได้โดยใช้คำสั่ง step

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

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

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

เช่น

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

ส่งคำสั่งหลายรายการพร้อมกัน

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

คำสั่งในกลุ่มเดียวสามารถกำหนดเป้าหมายลักษณะหลายอย่างในอุปกรณ์หลายเครื่อง ในหลายห้อง ในหลายโครงสร้าง

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

ใช้ Batching API

ขั้นตอนพื้นฐาน 3 ขั้นตอนที่เกี่ยวข้องกับการเรียกใช้คำสั่งผ่าน Batching API มีดังนี้

  1. เรียกใช้เมธอด Home.sendBatchedCommands()
  2. ภายในเนื้อหาของบล็อก sendBatchedCommands() ให้ระบุคำสั่งที่จะรวมไว้ในกลุ่ม
  3. ตรวจสอบผลลัพธ์ของคำสั่งที่ส่งเพื่อดูว่าสำเร็จหรือ ล้มเหลว

เรียกใช้เมธอด sendBatchedCommands()

เรียกใช้เมธอด Home.sendBatchedCommands() เบื้องหลังแล้ว วิธีนี้จะตั้งค่านิพจน์ Lambda ในบริบทของกลุ่มพิเศษ 

home.sendBatchedCommands() {

ระบุคำสั่งแบบกลุ่ม

ในส่วนเนื้อหาของsendBatchedCommands()บล็อก ให้ป้อนbatchable commands คำสั่งที่จัดกลุ่มได้คือคำสั่ง Device API ที่มีอยู่ซึ่งเป็นเวอร์ชัน "เงา" ที่ใช้ในบริบทของกลุ่มได้ และมีชื่อที่เพิ่ม คำต่อท้าย Batchable เช่น คำสั่ง LevelControl ลักษณะ moveToLevel() มีคำสั่งที่คล้ายกันชื่อ moveToLevelBatchable()

ตัวอย่าง

  val response1 = add(command1)

  val response2 = add(command2)

ระบบจะส่งชุดคำสั่งโดยอัตโนมัติเมื่อเพิ่มคำสั่งทั้งหมดลงใน บริบทของชุดคำสั่งและดำเนินการออกจากบริบทแล้ว

โดยคำตอบจะบันทึกไว้ในออบเจ็กต์ DeferredResponse<T>

คุณสามารถรวบรวมอินสแตนซ์ DeferredResponse<T> ไว้ในออบเจ็กต์ประเภทใดก็ได้ เช่น Collection หรือคลาสข้อมูลที่คุณกำหนด ไม่ว่าคุณจะเลือกประกอบคำตอบด้วยออบเจ็กต์ประเภทใด sendBatchedCommands() จะส่งคืนออบเจ็กต์ประเภทนั้น ตัวอย่างเช่น บริบทของกลุ่มสามารถแสดงผลอินสแตนซ์ DeferredResponse 2 รายการใน Pair ได้ดังนี้

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

หรือบริบทกลุ่มสามารถแสดงผลอินสแตนซ์ DeferredResponse ในคลาสข้อมูลที่กำหนดเองได้

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

ตรวจสอบคำตอบแต่ละรายการ

นอกบล็อก sendBatchedCommands() ให้ตรวจสอบการตอบกลับเพื่อดูว่าคำสั่งที่เกี่ยวข้องสำเร็จหรือไม่ โดยทำได้ด้วยการเรียก DeferredResponse.getOrThrow() ซึ่งจะทำอย่างใดอย่างหนึ่งต่อไปนี้ - แสดงผลลัพธ์ของคำสั่งที่ดำเนินการ - หรือหากขอบเขตของกลุ่มยังไม่เสร็จสมบูรณ์หรือคำสั่งไม่สำเร็จ ระบบจะแสดงข้อผิดพลาด

คุณควรตรวจสอบผลลัพธ์นอกsendBatchedCommands()ขอบเขตของ Lambda เท่านั้น

ตัวอย่าง

สมมติว่าคุณต้องการสร้างแอปที่ใช้ Batching API เพื่อตั้งค่าฉาก "ราตรีสวัสดิ์" ที่กำหนดค่าอุปกรณ์ทั้งหมดในบ้านสำหรับช่วงกลางคืนเมื่อทุกคนหลับ แอปนี้ควรปิดไฟและล็อกประตูหน้า และประตูหลัง

วิธีหนึ่งในการทำงานนี้มีดังนี้

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