สร้างแอป Android สําหรับกรณี

1. ยินดีต้อนรับ

Matter สร้างขึ้นโดยมีเป้าหมายเพื่อรวมมาตรฐาน IoT เข้าด้วยกัน จึงเชื่อมต่ออุปกรณ์สมาร์ทโฮมในระบบนิเวศต่างๆ เช่น Google Home, Zigbee, Bluetooth Mesh, Z-Wave และอื่นๆ

อุปกรณ์เคลื่อนที่เป็นจุดโต้ตอบหลักกับอุปกรณ์สมาร์ทโฮม หากต้องการสร้างแอป Android ของคุณเองเพื่อรองรับอุปกรณ์ Matter เราช่วยให้คุณเริ่มต้นใช้งานได้อย่างรวดเร็ว

แอปตัวอย่าง Google Home สำหรับ Matter (GHSA สำหรับ Matter) แสดง Home Mobile SDK API ซึ่งช่วยให้ผู้ใช้สามารถจัดสรรและแชร์อุปกรณ์ได้ นอกจากนี้ คุณยังใช้แอปตัวอย่างเป็นเครื่องมือการเรียนรู้เพื่อทำความเข้าใจแนวคิดหลักของ Matter ได้ดียิ่งขึ้น รวมถึงเป็นเครื่องมือในการแก้ไขข้อบกพร่องและแก้ปัญหาการโต้ตอบกับอุปกรณ์ Matter ได้ด้วย

สิ่งที่คุณต้องดำเนินการ

ใน Codelab นี้ คุณจะได้ดาวน์โหลดซอร์สโค้ดของแอปตัวอย่างและเรียนรู้วิธีใช้ Home Mobile SDK เพื่อจัดสรรและแชร์อุปกรณ์ นอกจากนี้ คุณยังจะได้เรียนรู้วิธีใช้ไลบรารีการจัดสรรและคลัสเตอร์จากที่เก็บ Matter (connectedhomeip) ด้วย

หลังจากดาวน์โหลดแอปตัวอย่างแล้ว เราจะตรวจสอบซอร์สโค้ดใน Android Studio และติดตั้งใช้งาน Home Mobile SDK API ต่อไปนี้

นอกจากนี้ คุณยังจะได้ทราบข้อมูลเพิ่มเติมเกี่ยวกับแนวคิดการคอมมิชชัน, Fabric ของ Matter และวิธีควบคุมอุปกรณ์ Matter

สิ่งที่คุณต้องมี

ก่อนเริ่มต้น โปรดทำตามขั้นตอนต่อไปนี้

คุณไม่จำเป็นต้องมีฮับ เช่น Google Nest Hub (รุ่นที่ 2) เพื่อเตรียมใช้งานและควบคุมอุปกรณ์ด้วยแอปตัวอย่าง

2. ตั้งค่า

แอปเริ่มต้นของ Codelab อยู่ในกิ่ง codelab หากต้องการเริ่มทำงานกับซอร์สโค้ดของ Codelab คุณสามารถดาวน์โหลดไฟล์ ZIP ได้

คุณจะใช้codelabไฟล์ ZIP นี้เพื่อสร้างตัวอย่างที่ใช้งานได้

เวอร์ชัน Codelab

สาขา codelab มีแท็กเป็นรุ่น 2.0.0 ของแอปตัวอย่าง คุณสามารถดาวน์โหลดซอร์สโค้ดที่เสร็จสมบูรณ์สำหรับรุ่นนี้เพื่อเปรียบเทียบการอัปเดตขณะทำตามแต่ละขั้นตอน

หากต้องการโคลนที่เก็บ GitHub ให้ทำตามวิธีการใน README ของแอปตัวอย่าง

แท็กเริ่มการทำงาน

เราจะแนะนำคุณเกี่ยวกับซอร์สโค้ดที่จำเป็นในการแชร์และจัดสรรอุปกรณ์ แต่คุณอาจต้องทราบการอ้างอิงต่อไปนี้ก่อนที่จะเริ่มต้น โปรดทราบว่ามีการประกาศทรัพยากร Dependency เหล่านี้ในไฟล์ libs.versions.toml และมีการระบุการใช้งานในไฟล์ build.gradle.kts

ซอร์สโค้ด

เราได้สร้างอินเทอร์เฟซผู้ใช้และฟังก์ชันการทำงานส่วนใหญ่ไว้ให้คุณแล้ว

สำหรับ Codelab นี้ เราจะเพิ่มฟังก์ชันการทำงานของ Matter ลงในไฟล์ต่อไปนี้

  • java/com/google/homesampleapp/commissioning/AppCommissioningService: ช่วยให้คุณจัดสรรอุปกรณ์ให้กับ Fabric สำหรับการพัฒนาได้
  • java/com/google/homesampleapp/screens/home/HomeScreen และ java/com/google/homesampleapp/screens/home/HomeViewModel.kt: มีฟังก์ชันการเปิดใช้ Home Mobile SDK
  • java/com/google/homesampleapp/screens/device/DeviceScreen และ java/com/google/homesampleapp/screens/device/DeviceViewModel: มีการเรียก API สำหรับแชร์อุปกรณ์

แต่ละไฟล์จะมีโค้ดบล็อกที่คุณจะแก้ไข เช่น

// CODELAB: add commissioningFunction()

ซึ่งจะช่วยให้คุณค้นหาส่วนที่เกี่ยวข้องใน Codelab ได้อย่างรวดเร็ว

3. ค่าคอมมิชชันที่ Google ได้รับ

ก่อนที่จะควบคุมอุปกรณ์และอนุญาตให้อุปกรณ์สื่อสารกันภายใน Fabric เดียวกันได้ คุณต้องมอบหมายให้ผู้มอบหมาย ซึ่งในกรณีนี้คือแอปพลิเคชันตัวอย่างนี้ ซึ่งก็คือแอปตัวอย่าง Google Home สำหรับ Matter

คุณควรทำความเข้าใจแนวคิดต่อไปนี้เกี่ยวกับการจัดสรร Matter

  • Fabric ช่วยให้อุปกรณ์สื่อสารกันได้
  • Fabric จะใช้ชุดข้อมูลเข้าสู่ระบบที่ไม่ซ้ำกันร่วมกัน
  • ระบบนิเวศมีหน้าที่ออกใบรับรองรูทที่เชื่อถือได้ กำหนดรหัส Fabric และกำหนดรหัสโหนดที่ไม่ซ้ำกัน ระบบนิเวศคือบริการแบ็กเอนด์ของผู้รับค่าคอมมิชชัน เช่น กราฟบ้านสำหรับระบบนิเวศ Google Home
  • อุปกรณ์สามารถเชื่อมต่อกับ Fabric ได้มากกว่า 1 รายการ (ฟีเจอร์ผู้ดูแลระบบหลายคน)

หากต้องการจัดสรรอุปกรณ์ คุณจะต้องใช้ CommissioningClient API การเรียกใช้ .commissionDevice() จะแสดง IntentSender ซึ่งจะเปิดใช้กิจกรรมที่เหมาะสมในบริการ Google Play

interface CommissioningClient {
  Task<IntentSender> commissionDevice(CommissioningRequest request);
}

ในส่วนถัดไป เราจะพูดถึงโค้ดขั้นต่ำที่จำเป็นในการจัดสรรอุปกรณ์ให้กับโครงสร้างพื้นฐานของ Google

ขั้นตอนที่ 1: ตัวเรียกใช้กิจกรรม

หากต้องการจัดการ IntentSender จาก CommissioningClient คุณสามารถใช้ ActivityResultLauncher ได้โดยทำดังนี้

val commissioningLauncher = registerForActivityResult(
    StartIntentSenderForResult()
) { result: ActivityResult ->
    if (result.resultCode == RESULT_OK) {
        Timber.d(TAG, "Commissioning succeeded.")
    } else {
        Timber.d(TAG, "Commissioning failed. " + result.resultCode)
    }
}

ขั้นตอนที่ 2: ฟังก์ชันการทดสอบ

นี่คือตัวอย่างพื้นฐานที่ใช้ CommissioningClient API เพื่อจัดสรรอุปกรณ์ให้กับโครงสร้างพื้นฐานของ Google

  1. กระบวนการจัดสรรเริ่มต้นด้วยฟังก์ชัน commissionDevice() ก่อนอื่น ให้กำหนดCommissioningRequest การกำหนดค่าเริ่มต้นนี้จะทำให้มีการจัดสรรอุปกรณ์ให้กับโครงสร้าง Android ในพื้นที่เท่านั้น
  2. Matter คือจุดแรกเข้าสำหรับ Home Mobile SDK ในการเรียกใช้ครั้งถัดไป .getCommissioningClient จะได้รับ CommissioningClient โดย this (กิจกรรม)
  3. .commissionDevice() ยอมรับCommissioningRequest
  4. และสุดท้ายจะมีการเรียกใช้ .addOnSuccessListener เพื่อประมวลผล CommissioningResult และเปิดใช้กิจกรรมอุปกรณ์ที่เตรียมใช้งานของบริการ Google Play (GPS)
private fun commissionDevice() {
    val request: CommissioningRequest = CommissioningRequest.builder().build()
    Matter.getCommissioningClient(this)
        .commissionDevice(request)
        .addOnSuccessListener { result ->
            commissioningLauncher.launch(IntentSenderRequest.Builder(result).build())
        }
}

คุณใช้ประโยชน์จาก Android Fabric ในเครื่องได้ผ่านการตั้งค่า Android เพื่อลดความซับซ้อนของกระบวนการจัดสรรอุปกรณ์ไปยัง Fabric อื่นๆ

จากนั้น คุณจะได้ดูวิธีจัดสรรอุปกรณ์ให้กับ Fabric สำหรับการพัฒนา

ดูภาพรวมของอินเทอร์เฟซผู้ใช้ในระหว่างกระบวนการจัดสรรได้ที่คู่มือแอปตัวอย่าง Google Home สำหรับ Matter

4. ค่าคอมมิชชันสำหรับโครงสร้างพื้นฐานด้านการพัฒนา

คุณสามารถจัดสรรอุปกรณ์ไปยัง Fabric ได้มากกว่า 1 รายการ หากต้องการจัดการการจับคู่ที่เชื่อถือได้ อุปกรณ์จะจัดเก็บFabricTableที่มีFabricInfoสมาชิกต่างๆ เช่น

  • การระบุเนื้อผ้า
  • รหัสโหนดที่ Fabric กำหนดให้กับอุปกรณ์
  • รหัสผู้ให้บริการ
  • รหัส Fabric
  • ข้อมูลเข้าสู่ระบบการปฏิบัติงานของอุปกรณ์

ผู้จัดการโดเมนการดูแลระบบ (ADM) จะกำหนดข้อมูลเข้าสู่ระบบของ Fabric ในสถานการณ์ก่อนหน้านี้ บริการ Google Play คือระบบนิเวศที่ทำหน้าที่เป็นผู้ออกใบรับรองรูท (CA) ที่เชื่อถือได้ เมื่อคุณจัดสรรอุปกรณ์ให้กับ Fabric Android ในพื้นที่ อุปกรณ์ทุกเครื่องจะมีชุดข้อมูลเข้าสู่ระบบ Fabric เดียวกันและชุด CA เดียวกัน

บริการคอมมิชชันที่กำหนดเอง

เราใช้พารามิเตอร์เริ่มต้นเพื่อสร้าง CommissioningRequest ใน CommissioningClient API เพื่อจัดสรรให้กับ Fabric ของ Android ในพื้นที่

val request: CommissioningRequest = CommissioningRequest.builder().build()

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

คุณสามารถแจ้ง Home Mobile SDK ว่าต้องการจัดสรรอุปกรณ์ให้กับ Fabric ของคุณเองได้โดยส่งบริการที่กำหนดเองไปยัง CommissioningRequest ดังนี้

class CommissioningRequest {
  static CommissioningRequest.Builder builder();

  class Builder {
    Builder setCommissioningService(@Nullable ComponentName commissioningService);

    CommissioningRequest build();
  }
}

ในขั้นตอนถัดไป เราจะแก้ไขฟังก์ชัน commissionDevice() เพื่อใช้บริการที่กำหนดเอง นอกจากนี้ เราจะเพิ่ม Activity Launcher ลงใน Home Fragment และใช้ออบเจ็กต์ LiveData เพื่อจัดการโฟลว์ API

ขั้นตอนที่ 1: สร้างตัวเรียกใช้กิจกรรม GPS

ก่อนอื่น มาสร้าง Activity Launcher เพื่อจัดการ IntentSender จาก CommissioningClient API กัน

  1. เปิด HomeScreen ในโฟลเดอร์ java/com/google/homesampleapp/screens/home/
  2. แทนที่ความคิดเห็น // CODELAB: commissionDeviceLauncher definition ด้วยโค้ดต่อไปนี้เพื่อลงทะเบียนและจัดการผลลัพธ์ของกิจกรรมการจัดสรร
    val commissionDeviceLauncher =
  rememberLauncherForActivityResult(
    contract = ActivityResultContracts.StartIntentSenderForResult()
  ) { result ->
    // Commission Device Step 5.
    // The Commission Device activity in GPS (step 4) has completed.
    val resultCode = result.resultCode
    if (resultCode == Activity.RESULT_OK) {
      Timber.d("CommissionDevice: Success")
      // We let the ViewModel know that GPS commissioning has completed successfully.
      // The ViewModel knows that we still need to capture the device name and will\
      // update UI state to trigger the NewDeviceAlertDialog.
      homeViewModel.gpsCommissioningDeviceSucceeded(result)
    } else {
      homeViewModel.commissionDeviceFailed(resultCode)
    }
  }

ขั้นตอนที่ 2: เรียกใช้การดำเนินการอุปกรณ์ที่เตรียมใช้งาน

ในขั้นตอนนี้ ผู้ใช้จะทริกเกอร์การดำเนินการ "จัดสรรอุปกรณ์" โดยคลิกปุ่ม "+" ที่ด้านขวาล่างของหน้าจอหลัก จากนั้นจะมีการโทรหา commissionDevice()

val onCommissionDevice = {
  ...
  commissionDevice(activity!!.applicationContext, commissionDeviceLauncher)
}

ขั้นตอนที่ 3: เรียกใช้ API

  1. ยังอยู่ใน HomeScreen.kt ในโฟลเดอร์ java/com/google/homesampleapp/screens/home
  2. แทนที่// CODELAB: commissionDeviceความคิดเห็นด้วยcommissionDeviceRequestต่อไปนี้ setCommissioningService จะเชื่อมโยง AppCommissioningService กับอินสแตนซ์ CommissioningService ซึ่งแสดงผลในฟังก์ชัน Callback เมื่อส่งบริการที่กำหนดเอง Home Mobile SDK จะจัดสรรอุปกรณ์ไปยัง Fabric ในพื้นที่ของ Android ก่อน จากนั้นจะส่งเพย์โหลดการเริ่มต้นใช้งานกลับไปยัง AppCommissioningService
    val commissionDeviceRequest =
    CommissioningRequest.builder()
        .setCommissioningService(ComponentName(
            context, AppCommissioningService::class.java))
        .build()
  3. โทร .getCommissioningClient() แล้วโทร .commissionDevice()
Matter.getCommissioningClient(context)
    .commissionDevice(commissionDeviceRequest)

หากต้องการทำให้ฟังก์ชัน commissionDevice เสร็จสมบูรณ์ ให้เพิ่ม addOnSuccessListener และ addOnFailureListener ดังนี้

    .addOnSuccessListener { result ->
      commissionDeviceLauncher.launch(IntentSenderRequest.Builder(result).build())
    }
    .addOnFailureListener { error ->
      Timber.e(error)
    }

5. สร้างบริการการว่าจ้าง

ในฟังก์ชัน commissionDevice() เราได้ขอรับ CommissioningService จาก CommissioningClient API ในขั้นตอนการทำงานนี้ API ของ CommissioningClient จะจัดสรรอุปกรณ์ไปยัง Fabric ของ Android ในพื้นที่ก่อน จากนั้นจะแสดงผล Callback ที่มีออบเจ็กต์ CommissioningRequestMetadata

public interface CommissioningService {
interface Callback {
    void onCommissioningRequested(CommissioningRequestMetadata metadata);
  }
}

ตอนนี้เราต้องรับช่วง CommissioningService.Callback และจัดหาฟังก์ชันการทำงานที่จำเป็นในการจัดสรรอุปกรณ์ให้กับแอปตัวอย่างของเรา ต่อไปนี้เป็นตัวอย่างการติดตั้งใช้งาน CommissioningService ขั้นพื้นฐาน

class MatterCommissioningService : Service(), CommissioningService.Callback {
   private val commissioningServiceDelegate =
     CommissioningService.Builder(this)
       .setCallback(this)
       .build()

   override fun onBind(intent: Intent) = commissioningServiceDelegate.asBinder()

   override fun onCommissioningRequested(metadata: CommissioningRequestMetadata) {
     // perform commissioning

     commissioningServiceDelegate
       .sendCommissioningComplete(CommissioningCompleteMetadata.builder().build())
   }
 }

ขั้นตอนที่ 1: สำรวจ AppCommissioningService ที่กำหนดเอง

เราได้กำหนดโครงสร้างคลาสพื้นฐานสำหรับ CommissioningService ที่กำหนดเองไว้แล้วเพื่อช่วยคุณเริ่มต้นใช้งาน ภาพรวมโดยสรุปของฟังก์ชันการทำงานของบริการมีดังนี้ หากต้องการทำตาม ให้เปิด AppCommissioningService ใน java/commissioning

เราได้เพิ่มการนำเข้าต่อไปนี้สำหรับ API ของ Home Mobile SDK

import com.google.android.gms.home.matter.commissioning.CommissioningCompleteMetadata
import com.google.android.gms.home.matter.commissioning.CommissioningRequestMetadata
import com.google.android.gms.home.matter.commissioning.CommissioningService

AppCommissioningService ยังมีไลบรารีจาก Matter repo (connectedhomeip) ด้วย

import com.google.homesampleapp.chip.ChipClient

สุดท้ายนี้ บริการนี้ยังมีการนำเข้าเพื่อรองรับ Hilt และ Kotlin Coroutines ด้วย

จากนั้นเราจะสร้างตัวสร้างและตั้งค่าบางอย่าง รวมถึง commissioningServiceDelegate ซึ่งเราจะใช้เพื่อแจ้งให้ Google Play Services ทราบเมื่อการจัดสรรเสร็จสมบูรณ์

private lateinit var commissioningServiceDelegate: CommissioningService
...
commissioningServiceDelegate = CommissioningService.Builder(this).setCallback(this).build()

ตอนนี้ถึงเวลาเพิ่มฟังก์ชันการจัดสรรแล้ว

ขั้นตอนที่ 2: ลบล้าง onCommissioningRequested

หากต้องการจัดสรรอุปกรณ์ให้กับโครงสร้างการพัฒนาของแอป ให้ทำตามขั้นตอนต่อไปนี้

  1. เปิด AppCommissioningService ใน java/commissioning
  2. ค้นหาฟังก์ชัน onCommissioningRequested() เราได้ระบุข้อความบันทึกที่พิมพ์ CommissioningRequestMetadata แทนที่ความคิดเห็น // CODELAB: onCommissioningRequested() เพื่อเริ่มโครูทีน serviceScope และรับ deviceId
    // Perform commissioning on custom fabric for the sample app.
serviceScope.launch {
  val deviceId = devicesRepository.incrementAndReturnLastDeviceId()
  3. ดำเนินการคอมมิชชัน สำหรับขั้นตอนนี้ เราจะส่งข้อมูลอุปกรณ์ที่แสดงในออบเจ็กต์ CommissioningRequestMetadata ChipClient ใช้ข้อมูลเมตานี้เพื่อสร้างช่องทางที่ปลอดภัยระหว่างแอป GHSA สำหรับ Matter กับอุปกรณ์ของคุณ
    try {
  Timber.d(
      "Commissioning: App fabric -> ChipClient.establishPaseConnection(): deviceId [${deviceId}]")
  chipClient.awaitEstablishPaseConnection(
      deviceId,
      metadata.networkLocation.ipAddress.hostAddress!!,
      metadata.networkLocation.port,
      metadata.passcode)
  Timber.d(
      "Commissioning: App fabric -> ChipClient.commissionDevice(): deviceId [${deviceId}]")
  chipClient.awaitCommissionDevice(deviceId, null)
} catch (e: Exception) {
  Timber.e(e, "onCommissioningRequested() failed")
  // No way to determine whether this was ATTESTATION_FAILED or DEVICE_UNREACHABLE.
  commissioningServiceDelegate
      .sendCommissioningError(CommissioningError.OTHER)
      .addOnSuccessListener {
        Timber.d(
            "Commissioning: commissioningServiceDelegate.sendCommissioningError() succeeded")
      }
      .addOnFailureListener { e2 ->
        Timber.e(e2, "Commissioning: commissioningServiceDelegate.sendCommissioningError() failed")
      }
  return@launch
}
  4. ใช้ commissioningServiceDelegate เพื่อแจ้งให้บริการ Google Play ทราบว่าการจัดสรรเสร็จสมบูรณ์แล้ว ใน .sendCommissioningComplete() ให้ส่ง CommissioningCompleteMetadata
    commissioningServiceDelegate
    .sendCommissioningComplete(
        CommissioningCompleteMetadata.builder().setToken(deviceId.toString()).build())
    .addOnSuccessListener {
      Timber.d("Commissioning: commissioningServiceDelegate.sendCommissioningComplete() succeeded")
    }
    .addOnFailureListener { e ->
      Timber.e(e, "Commissioning: commissioningServiceDelegate.sendCommissioningComplete() failed")
    }
}

เรียกใช้แอป

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

เมื่อการจัดสรรเสร็จสมบูรณ์แล้ว อุปกรณ์จะเข้าร่วม 2 Fabric ได้แก่ Local Android Fabric และ Fabric การพัฒนาในพื้นที่ แต่ละ Fabric จะมีชุดข้อมูลเข้าสู่ระบบของตัวเองและมีรหัส Fabric แบบ 64 บิตที่ไม่ซ้ำกัน

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

การจัดสรรไปยัง Fabric สำหรับการพัฒนาช่วยให้คุณใช้ไลบรารีจาก ที่เก็บ Matter (connectedhomeip) เพื่อควบคุมอุปกรณ์จากแอปตัวอย่างได้

เราได้สร้างคลาสตัวช่วยเพื่อให้เข้าถึงคลัสเตอร์อุปกรณ์และส่งคำสั่งได้ง่ายขึ้น ดูข้อมูลเพิ่มเติมได้โดยเปิด ClustersHelper ใน java/clusters โปรแกรมช่วย Singleton นี้จะนำเข้าไลบรารีต่อไปนี้เพื่อเข้าถึงข้อมูลอุปกรณ์

import chip.devicecontroller.ChipClusters
import chip.devicecontroller.ChipStructs

เราสามารถใช้คลาสนี้เพื่อรับคลัสเตอร์เปิด/ปิดสำหรับอุปกรณ์ แล้วเรียกใช้ .toggle ได้

suspend fun toggleDeviceStateOnOffCluster(deviceId: Long, endpoint: Int) {
  Timber.d("toggleDeviceStateOnOffCluster())")
  val connectedDevicePtr =
      try {
        chipClient.getConnectedDevicePointer(deviceId)
      } catch (e: IllegalStateException) {
        Timber.e("Can't get connectedDevicePointer.")
        return
      }
  return suspendCoroutine { continuation ->
    getOnOffClusterForDevice(connectedDevicePtr, endpoint)
        .toggle(
            object : ChipClusters.DefaultClusterCallback {
              override fun onSuccess() {
                continuation.resume(Unit)
              }
              override fun onError(ex: Exception) {
                Timber.e("readOnOffAttribute command failure: $ex")
                continuation.resumeWithException(ex)
              }
            })
  }
}

สลับอุปกรณ์

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

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

ในอุปกรณ์ ระบบจะตรวจสอบความถูกต้อง ถอดรหัส แล้วส่งแพ็กเก็ตพร้อมการเรียกกลับ ฟังก์ชันเรียกกลับประกอบด้วย EndpointId, ClusterId และ AttributeId ซึ่งเข้าถึงได้จาก attributePath ตัวอย่างเช่น โค้ดนี้สามารถติดตั้งใช้งานในอุปกรณ์ Matter ได้

void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, uint8_t mask, uint8_t type,
                                       uint16_t size, uint8_t * value)
{
    // handle callback
    ClusterId clusterId     = attributePath.mClusterId;
    AttributeId attributeId = attributePath.mAttributeId;
}

ในขั้นตอนถัดไป คุณจะใช้ Matter SDK และ ClustersHelper เพื่อเปิด/ปิดอุปกรณ์

  1. ไปที่ DeviceViewModel ใน java/screens/device
  2. ค้นหาฟังก์ชัน updateDeviceStateOn
  3. แทนที่ความคิดเห็น // CODELAB: toggle ด้วยโค้ดเพื่อเรียกใช้ clustersHelper จากนั้นอัปเดตที่เก็บอุปกรณ์
    Timber.d("Handling real device")
    try {
      clustersHelper.setOnOffDeviceStateOnOffCluster(deviceUiModel.device.deviceId, isOn, 1)
      devicesStateRepository.updateDeviceState(deviceUiModel.device.deviceId, true, isOn)
    } catch (e: Throwable) {
      Timber.e("Failed setting on/off state")
    }

ฟังก์ชันนี้เรียกใช้จาก DeviceScreen ดังนี้

// On/Off Switch click.
val onOnOffClick: (value: Boolean) -> Unit = { value ->
  deviceViewModel.updateDeviceStateOn(deviceUiModel!!, value)
}

เรียกใช้แอป

เรียกใช้แอปเพื่อโหลดการอัปเดตซ้ำ จากหน้าจอหลัก ให้เปิดและปิดอุปกรณ์

7. แชร์อุปกรณ์กับระบบนิเวศอื่นๆ

การแชร์อุปกรณ์เรียกว่าโฟลว์ผู้ดูแลระบบหลายคนในข้อกำหนดของ Matter

ในขั้นตอนก่อนหน้า เราได้ทราบว่า Home Mobile SDK ช่วยให้สามารถจัดสรรอุปกรณ์ไปยัง Local Android Fabric และ Fabric สำหรับการพัฒนาแอปตัวอย่างได้ ซึ่งเป็นตัวอย่างของโฟลว์แบบผู้ดูแลระบบหลายคน ซึ่งอุปกรณ์สามารถจัดสรรไปยัง Fabric มากกว่า 1 รายการได้

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

Home Mobile SDK มีฟังก์ชันนี้ใน ShareDeviceRequest API ซึ่งช่วยให้คุณทำสิ่งต่อไปนี้ได้

  1. เปิดหน้าต่างการจัดสรรชั่วคราวสำหรับอุปกรณ์
  2. เปลี่ยนสถานะของอุปกรณ์เพื่อให้สามารถมอบหมายไปยัง Fabric อื่นได้
  3. ควบคุมอุปกรณ์จากแอปและระบบนิเวศอื่นๆ

ในขั้นตอนถัดไป คุณจะใช้ Home Mobile SDK เพื่อแชร์อุปกรณ์

ขั้นตอนที่ 1: สร้างตัวเรียกใช้กิจกรรม GPS

เราได้สร้างตัวเรียกใช้กิจกรรมของอุปกรณ์ที่แชร์เพื่อจัดการ IntentSender จาก CommissioningClient API เช่นเดียวกับตัวเรียกใช้กิจกรรมการจัดสรรที่เราสร้างขึ้นเมื่อจัดสรรให้กับโครงสร้างพื้นฐานการพัฒนา

  1. เปิด DeviceScreen ในโฟลเดอร์ java/com/google/homesampleapp/screens/device/
  2. แทนที่ความคิดเห็น // CODELAB: shareDeviceLauncher definition ด้วยโค้ดต่อไปนี้เพื่อลงทะเบียนและจัดการผลลัพธ์ของกิจกรรม .shareDevice()
    val shareDeviceLauncher = rememberLauncherForActivityResult(
  contract = ActivityResultContracts.StartIntentSenderForResult()
) { result ->
  // Commission Device Step 5.
  // The Share Device activity in GPS (step 4) has completed.
  val resultCode = result.resultCode
  if (resultCode == Activity.RESULT_OK) {
    deviceViewModel.shareDeviceSucceeded()
  } else {
    deviceViewModel.shareDeviceFailed(resultCode)
  }
}

ขั้นตอนที่ 2: เรียกใช้การดำเนินการแชร์อุปกรณ์

ในขั้นตอนนี้ ผู้ใช้จะทริกเกอร์การดำเนินการ "แชร์อุปกรณ์" โดยคลิกปุ่ม "แชร์" บนหน้าจออุปกรณ์ จากนั้นจะมีการโทรไปยัง deviceViewModel เพื่อเปิดหน้าต่างการจับคู่สำหรับการแชร์อุปกรณ์

// Share Device button click.
val onShareDevice: () -> Unit = remember {
 {
   deviceViewModel.openPairingWindow(deviceUiModel!!.device.deviceId)
 }
}

หลังจากเปิดหน้าต่างการจับคู่ได้สำเร็จ deviceViewModel จะสื่อสารข้อเท็จจริงดังกล่าวกับ UI การสื่อสารระหว่าง ViewModel กับ UI จะดำเนินการผ่านออบเจ็กต์ StateFlow

// Communicate to the UI that the pairing window is open.
// UI can then launch the GPS activity for device sharing.
_pairingWindowOpenForDeviceSharing.value = true

เมื่อเห็นการเปลี่ยนแปลงออบเจ็กต์ StateFlow แล้ว DeviceScreen จะทำการเรียกต่อไปนี้

shareDevice(activity!!.applicationContext, shareDeviceLauncher, deviceViewModel)

ขั้นตอนที่ 3: เรียกใช้ API

ตอนนี้ถึงเวลาเริ่มงานแชร์อุปกรณ์แล้ว

  1. เปิด DeviceScreen.kt ในโฟลเดอร์ java/com/google/homesampleapp/screens/device/
  2. ค้นหาฟังก์ชัน shareDevice() แทนที่ความคิดเห็น // CODELAB: shareDevice ด้วย ShareDeviceRequest DeviceDescriptor ให้ข้อมูลที่เฉพาะเจาะจงเกี่ยวกับอุปกรณ์ เช่น รหัสผู้ให้บริการ รหัสผลิตภัณฑ์ และประเภทอุปกรณ์ ในตัวอย่างนี้ เราจะฮาร์ดโค้ดค่า
    val shareDeviceRequest =
  ShareDeviceRequest.builder()
    .setDeviceDescriptor(DeviceDescriptor.builder().build())
    .setDeviceName("GHSAFM temp device name")
  3. ตั้งค่า CommissioningWindow และพารามิเตอร์
        .setCommissioningWindow(
        CommissioningWindow.builder()
            .setDiscriminator(Discriminator.forLongValue(DISCRIMINATOR))
            .setPasscode(SETUP_PIN_CODE)
            .setWindowOpenMillis(SystemClock.elapsedRealtime())
            .setDurationSeconds(OPEN_COMMISSIONING_WINDOW_DURATION_SECONDS.toLong())
            .build())
    .build()
  4. โทรหา .getCommissioningClient() แต่คราวนี้ให้ใช้ .shareDevice() API
    Matter.getCommissioningClient(context)
    .shareDevice(shareDeviceRequest)

การเรียกกลับที่สำเร็จของ commissioningClient.shareDevice() API จะให้ IntentSender ที่จะใช้เพื่อเปิดใช้กิจกรรมในอุปกรณ์ที่แชร์ในบริการ Google Play

  1. หากต้องการทำให้ฟังก์ชัน shareDevice เสร็จสมบูรณ์ ให้เพิ่ม addOnSuccessListener และ addOnFailureListener เมื่อสำเร็จ ระบบจะเรียกใช้ launch ใน shareDeviceLauncher เพื่อเปิดใช้งาน GPS สำหรับการแชร์อุปกรณ์
        .addOnSuccessListener { result ->
      Timber.d("ShareDevice: Success getting the IntentSender: result [${result}]")
      shareDeviceLauncher.launch(IntentSenderRequest.Builder(result).build())
    }
    .addOnFailureListener { error ->
      Timber.e(error)
      deviceViewModel.showMsgDialog("Share device failed", error.toString())
    }

เรียกใช้แอป

หากต้องการแชร์อุปกรณ์ Matter กับระบบนิเวศอื่นๆ คุณจะต้องติดตั้งแพลตฟอร์มอื่นในอุปกรณ์ Android เราได้สร้างอินสแตนซ์อื่นของแอปตัวอย่างที่คุณใช้เป็นผู้ดูแลระบบเป้าหมายได้

เมื่อติดตั้งคอมมิชชันเนอร์เป้าหมายในอุปกรณ์ Android แล้ว ให้ตรวจสอบว่าคุณแชร์อุปกรณ์ Matter ได้ แอปผู้รับมอบสิทธิ์เป้าหมายจะมีป้ายกำกับ GHSAFM-TC

ตอนนี้อุปกรณ์ของคุณสามารถเข้าร่วมใน 3 เครือข่ายต่อไปนี้ได้แล้ว

  1. เนื้อหา Android ในเครื่อง
  2. โครงสร้างพื้นฐานการพัฒนาของคุณ (แอปนี้)
  3. ซึ่งเป็นบ้านที่ 3 ที่คุณเพิ่งแชร์อุปกรณ์ด้วย

8. ขั้นตอนถัดไป

ขอแสดงความยินดี

ยินดีด้วย คุณทำ Codelab นี้เสร็จสมบูรณ์แล้ว และได้เรียนรู้วิธีจัดสรรและแชร์อุปกรณ์โดยใช้ Home Mobile SDK

หากพบปัญหาเกี่ยวกับแอปตัวอย่าง ให้ลองทำตามขั้นตอนเพื่อยืนยันสภาพแวดล้อม

หากมีคำถามเกี่ยวกับการใช้แอปตัวอย่างหรือพบข้อบกพร่องของโค้ด คุณสามารถส่งปัญหาไปยังเครื่องมือติดตามปัญหาในที่เก็บ GitHub ได้โดยทำดังนี้

หากต้องการรับคำแนะนำอย่างเป็นทางการจาก Google เกี่ยวกับคำถามทางเทคนิค ให้ใช้ฟอรัมนักพัฒนาสมาร์ทโฮม

หากต้องการรับการสนับสนุนทางเทคนิคจากชุมชน ให้ใช้แท็ก google-smart-home ใน Stack Overflow