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

bookmark_border จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

คู่มือนี้ต่อจากหัวข้อเข้าถึงอุปกรณ์และข้อมูลเมตาของอุปกรณ์ใน iOS และจะแสดงตัวอย่างเพิ่มเติมของการควบคุมและการเข้าถึงอุปกรณ์

หากต้องการใช้ประเภทหรือลักษณะของอุปกรณ์ที่เฉพาะเจาะจง เช่น Matter OnOffTrait ที่ใช้ในตัวอย่างที่แสดงที่นี่ คุณต้องนําเข้าดังนี้

import GoogleHomeSDK
import GoogleHomeTypes

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

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

เช่น หากต้องการตรวจสอบว่าอุปกรณ์รองรับคําสั่ง toggle ของลักษณะเปิด/ปิดหรือไม่ ให้ทำดังนี้

// Check if the OnOff trait supports the toggle command.
if onOffTraitTest.supportsToggleCommand {
  print("onOffTrait supports toggle command")
} else {
  print("onOffTrait does not support stateful toggle command")
}

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

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

// Calling a command on a trait.
do {
  try await onOffTraitTest.toggle()
} catch let error as HomeError {
  // Code for handling the exception
}

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

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

do {
  try await onOffTraitTest.off()
  try await onOffTraitTest.on()
} catch let error as HomeError {
  // Code for handling the exception
}

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

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

คำสั่งบางรายการอาจใช้พารามิเตอร์ เช่น คำสั่งใน OnOffTrait หรือ LevelControlTrait

// Turn off the light using the DyingLight effect.
do {
  try await onOffTraitTest.offWithEffect(
    effectIdentifier: Matter.OnOffTrait.EffectIdentifierEnum.dyingLight,
    effectVariant: 0
  )
} catch let error as HomeError {
  // Code for handling the exception
}

// Change the brightness of the light to 50%
do {
  try await levelControlTraitTest.moveToLevel(
    level: UInt8(127),
    transitionTime: 0,
    optionsMask: Matter.LevelControlTrait.OptionsBitmap(),
    optionsOverride: Matter.LevelControlTrait.OptionsBitmap()
  )
} catch let error as HomeError {
  // Code for handling the exception
}

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

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

เช่น หากต้องการตรวจสอบว่าอุปกรณ์รองรับแอตทริบิวต์ onOff ของลักษณะเปิด/ปิดหรือไม่ ให้ทำดังนี้

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

แอตทริบิวต์บางรายการเป็นค่า Null ได้ในสเปค Matter หรือสคีมา Cloud-to-cloud smart home สําหรับแอตทริบิวต์เหล่านี้ คุณสามารถระบุว่า nil ที่แสดงผลโดยแอตทริบิวต์นั้นเกิดจากอุปกรณ์ไม่ได้รายงานค่านั้น หรือค่าของแอตทริบิวต์คือ nil จริงหรือไม่ โดยใช้ isNullable เพิ่มเติมจาก isSupported

// Check if a nullable attribute is set or is not supported.
if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
  if let onOffTrait = deviceType.traits[Matter.OnOffTrait.self] {
    if onOffTrait.attributes.startUpOnOff == nil {
      if onOffTrait.attributes.$startUpOnOff.isSupported {
        print(
          "onOffTrait supports startUpOnOff and it is nil. Check the spec for the contextual meaning."
        )
      } else {
        print("onOffTrait does not support startUpOnOff!")
      }
    } else {
      print(
        "onOffTrait supports startUpOnOff and it is set to \(onOffTrait.attributes.startUpOnOff)"
      )
    }
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

เช่น

if doorLockTraitTest.attributes.$wrongCodeEntryLimit.isSupported {
  let _ = try await doorLockTraitTest.update {
    $0.setWrongCodeEntryLimit(3)
  }
}