Mem-build perangkat virtual Matter

1. Pengantar

Matter adalah protokol konektivitas yang menghadirkan peluang menarik untuk pengembangan perangkat smart. Dalam codelab ini, Anda akan mem-build perangkat Matter pertama Anda menggunakan SDK dan dependensi yang disediakan untuk Anda di image Docker yang telah dikonfigurasi sebelumnya.

Untuk mempelajari Matter, buka Pusat Developer Google Home atau situs Connectivity Standards Alliance.

Yang akan Anda pelajari

  • Cara menyiapkan lingkungan build Matter
  • Cara membuat perangkat Matter virtual yang berjalan di komputer Anda
  • Cara memesan dan mengontrol perangkat Matter virtual dengan Google Home

Yang akan Anda butuhkan

2. Menyiapkan lingkungan Anda

Kita akan menggunakan container Docker yang telah dikonfigurasi sebelumnya pada mesin host Linux. Penampung ini mencakup semua dependensi yang diperlukan untuk membuat dan menjalankan perangkat virtual Matter.

Periksa hardware Anda

Komputer Windows dan macOS tidak didukung oleh penginstalan Docker ini. Anda dapat menginstal dan mem-build Matter secara manual di macOS.

Selain itu, petunjuk ini mengasumsikan bahwa komputer Linux Anda menjalankan sistem {i>windowing<i} X11. Jika mesin Linux Anda menjalankan Wayland, pastikan X.Org juga terinstal.

Menyiapkan Docker

  1. Instal Docker Engine (jangan gunakan Docker Desktop).
  2. Ambil image Docker dari Docker Hub. Di jendela terminal, jalankan:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    
    Operasi ini mungkin memerlukan waktu beberapa menit hingga selesai.
  3. Mulai container Docker dengan menjalankan:
    user@host> xhost local:1000
    user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    

Setelah memulai penampung, Anda akan melihat beberapa output diagnostik diikuti dengan pesan yang menegaskan bahwa konfigurasi penampung Anda sudah benar, dan terakhir, perintah shell container:

Environment looks good, you are ready to go!
$

Mari kita pahami perintah Docker dan opsi yang kita teruskan:

  • xhost local:1000 memungkinkan Sistem Jendela X menerima koneksi dari host lokal pada port 1000, sehingga memungkinkan penggunaan antarmuka pengguna grafis.
  • docker run … image menjalankan image yang ditentukan, dan mengambilnya dari registry Docker jika perlu.
  • --ipc=host memungkinkan Docker berbagi namespace komunikasi antarproses dengan mesin host Anda.
  • --net=host memungkinkan Docker menggunakan stack jaringan host di dalam container, yang diperlukan agar dapat meneruskan traffic mDNS dari host ke container, dan untuk membagikan tampilan X11 host.
  • -e DISPLAY mengekspor $DISPLAY ke host, yang memberikan akses ke antarmuka grafis sistem Anda. Tindakan ini diperlukan untuk menjalankan alat ZAP saat mengedit cluster Matter.
  • -it menjalankan Docker dengan terminal interaktif (tty), bukan sebagai proses latar belakang.

Jika ingin, Anda dapat menjalankan instance sesi terminal kedua:

user@host> docker exec -it matter-container /bin/bash
$

Menghentikan dan memulai container Docker Matter

Setiap kali menjalankan perintah docker run, Anda akan membuat container baru dengan image yang ditentukan. Saat Anda melakukan ini, data lama, yang disimpan di instance penampung sebelumnya, akan hilang. Terkadang inilah yang Anda inginkan, karena memungkinkan Anda memulai dengan instalasi baru. Namun ada kalanya Anda lebih memilih untuk menyimpan konfigurasi kerja dan lingkungan di antara sesi.

Oleh karena itu, setelah membuat penampung, Anda dapat menghentikan penampung agar pekerjaan tidak hilang.

user@host> docker stop matter-container

Jika Anda sudah siap untuk menjalankan lagi, mulai container dan buka jendela terminal:

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

Anda dapat membuka sesi terminal tambahan ke penampung dengan:

user@host> docker exec -it matter-container /bin/bash

Atau mulai sesi root menggunakan:

user@host> docker exec -u 0 -it matter-container /bin/bash

Penyiapan Matter awal

Saat terbuka, terminal akan sudah berada di repositori yang di-clone Matter di ~/connectedhomeip. Tidak diperlukan langkah penyiapan Matter tambahan.

Berbagi file antara host dan penampung

Untuk mengakses file pada mesin host Anda dari dalam container, Anda dapat menggunakan pemasangan bind. Anda juga dapat menulis file ke direktori yang dipasang dari dalam container untuk memudahkan akses dari host.

Jalankan container dengan argumen tambahan --mount source=$(pwd),target=/workspace,type=bind untuk memasang direktori kerja saat ini ke dalam container di /workspace.

user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

Izin pengguna container di direktori yang dipasang harus dikelola di host.

Dapatkan ID grup pengguna penampung dari dalam penampung.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

Buka sesi terminal lain di host container dan tetapkan direktori kerja ke direktori yang dipasang oleh container.

Tetapkan grup secara rekursif untuk file dalam direktori yang dipasang ke grup pengguna container.

user@host> sudo chgrp -R 1000 .

Berikan izin yang Anda inginkan dalam direktori ke grup. Contoh ini memberi grup pengguna container izin baca, tulis, dan eksekusi pada semua file di direktori yang dipasang.

user@host> sudo chmod -R g+rwx .

Perlu diketahui bahwa perintah ini tidak memengaruhi izin file baru yang dibuat oleh pengguna host. Ingatlah untuk memperbarui izin file baru yang dibuat di host sesuai kebutuhan.

Anda dapat menambahkan pengguna host ke grup pengguna penampung untuk mewarisi izin pada file yang dibuat oleh pengguna penampung.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

3. Konsol Developer Google Home

Konsol Developer Google Home adalah aplikasi web tempat Anda mengelola integrasi Matter dengan Google Home.

Semua perangkat Matter yang telah lulus sertifikasi Matter Connectivity Standards Alliance (Alliance) berfungsi di ekosistem Google Home. Perangkat dalam pengembangan yang belum disertifikasi dapat dipesan di ekosistem Google Home dalam kondisi tertentu - lihat Batasan penyambungan untuk mengetahui informasi selengkapnya.

Membuat project developer

Mulailah dengan membuka Konsol Developer Google Home:

  1. Klik Buat project.
  2. Masukkan nama project yang unik, lalu klik Buat project. Dialog untuk membuat project baru
  3. Klik + Add integration, yang akan mengarahkan Anda ke layar Matter resources, tempat Anda dapat melihat dokumentasi pengembangan Matter dan membaca beberapa alat.
  4. Jika Anda siap untuk melanjutkan, klik Next: Develop, yang menampilkan halaman Checklist Matter.
  5. Klik Berikutnya: Penyiapan
  6. Di halaman Penyiapan, masukkan Nama produk.
  7. Klik Pilih jenis perangkat, lalu pilih jenis perangkat dari menu drop-down (dalam hal ini, Light).
  8. Di ID Vendor (VID), pilih Test VID, lalu pilih 0xFFF1 dari menu drop-down Test VID. Di ID Produk (PID), masukkan 0x8000, lalu klik Save & continue, lalu klik Save di halaman berikut. Gunakan nilai VID/PID persis ini, dan langkah-langkah codelab berikutnya akan bergantung pada nilai tersebut.
    Menyiapkan project
  9. Sekarang Anda akan melihat integrasi di bagian Integrasi Matter.
  10. Mulai ulang hub Anda untuk memastikan hub menerima konfigurasi project integrasi Matter terbaru. Jika nanti Anda harus mengubah VID atau PID, Anda juga harus memulai ulang setelah menyimpan project agar perubahan dapat diterapkan. Lihat Memulai ulang perangkat Google Nest atau Google Wifi untuk mendapatkan petunjuk langkah demi langkah memulai ulang.

4. Membuat perangkat

Semua contoh di Matter dapat ditemukan di folder examples di repositori GitHub. Ada beberapa contoh yang tersedia, tetapi fokus kita pada codelab ini adalah Chef.

Chef adalah:

  • Aplikasi contoh yang menyediakan antarmuka terminal, fitur penggabungan juga ditemukan di aplikasi examples/shell.
  • Skrip yang menerapkan prinsip konvensi konfigurasi untuk mengenkapsulasi beberapa tugas umum yang diperlukan untuk mengembangkan perangkat yang kompatibel dengan Matter.

Buka folder contoh Chef dan buat build Matter pertama Anda:

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

Chef memiliki beberapa opsi yang dapat dilihat dengan menjalankan chef.py -h. Opsi yang kami gunakan di sini adalah:

  • -d: menentukan jenis perangkat yang akan digunakan. Dalam hal ini, kita membuat aplikasi pencahayaan dengan kontrol aktif/nonaktif dan tingkat.
  • -z: memanggil alat ZAP untuk membuat file sumber yang menerapkan jenis perangkat. Artinya, berdasarkan pilihan pencahayaan Anda, ZAP akan secara otomatis membuat kode untuk dimasukkan ke dalam build yang menentukan cahaya (Model Data) dan cara ia berinteraksi dengan perangkat lain (Model Interaksi).
  • -b: build.
  • -r: [opsional] mengaktifkan server RPC pada perangkat Matter virtual sehingga komponen lain (seperti GUI) dapat berkomunikasi dengan perangkat untuk menetapkan dan mengambil Atribut Model Data.
  • -t linux: platform target. Platform dukungan adalah linux, nrfconnect, dan esp32. Anda dapat menjalankan ./chef.py -h untuk melihat semua perintah yang tersedia dan platform target yang didukung. linux digunakan untuk perangkat Matter virtual.

Menjalankan perangkat

Matter menggunakan port TCP/UDP 5540. Jadi, jika Anda menjalankan firewall di komputer, nonaktifkan atau izinkan koneksi TCP/UDP yang masuk di port 5540.

Jalankan perangkat virtual di container dengan:

$ ./linux/out/rootnode_dimmablelight_bCwGYSDpoe
   [1648589956496] [14264:16538181] CHIP: [DL] _Init]
...
[1648562026.946882][433632:433632] CHIP:SVR: SetupQRCode: [MT:Y3.13Y2N00KA0648G00]
[1648562026.946893][433632:433632] CHIP:SVR: Copy/paste the below URL in a browser to see the QR Code:
[1648562026.946901][433632:433632] CHIP:SVR: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

Biarkan perangkat tetap berjalan. Sekarang kita akan mengalihkan perhatian ke Aplikasi Google Home sehingga dapat menugaskan perangkat Anda ke Google Home.

Hentikan perangkat

Jika Anda perlu menghentikan perangkat, Anda dapat keluar dari program dengan CTRL+C. Jika aplikasi tidak keluar, Anda mungkin juga perlu menggunakan CTRL+\.

Kredensial untuk perangkat virtual Anda disimpan di direktori /tmp/, dalam file yang dimulai dengan awalan chip.

Jika ingin mengulangi seluruh proses commissioning dari awal, Anda harus menghapus file tersebut dengan menjalankan perintah berikut:

$ rm /tmp/chip*

5. Pengontrol Perangkat Virtual

Pengontrol Perangkat Virtual adalah aplikasi mandiri yang menyediakan antarmuka pengguna grafis untuk mengontrol dan menampilkan status perangkat Matter virtual Anda. Layanan ini menggunakan klien RPC untuk berkomunikasi dengan perangkat Matter yang terhubung ke lingkungan pengembangan Anda.

Pengontrol Perangkat Virtual

Pengontrol Perangkat Virtual memberikan representasi visual dari perangkat virtual Anda.

Anda bisa berinteraksi dengan perangkat virtual melalui antarmuka pengguna grafis (GUI) Pengontrol Perangkat Virtual. Perubahan Anda pada GUI memengaruhi model data pokok. Buka Perangkat yang Didukung untuk mengetahui daftar lengkap jenis Perangkat Virtual Matter yang didukung.

Menginstal Pengontrol Perangkat Virtual

Virtual Device Controller sudah diinstal sebelumnya pada container Docker Ubuntu LTS 20.04.

Menjalankan Pengontrol Perangkat Virtual

Buat instance sesi terminal kedua:

user@host> docker exec -it matter-container /bin/bash
$

Mulai Pengontrol Perangkat Virtual dengan menyediakan soket jaringan yang akan digunakan untuk berkomunikasi dengan perangkat virtual:

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

Jika Anda memulai Pengontrol tanpa memberikan argumen apa pun, Pengontrol akan ditetapkan secara default ke opsi soket jaringan menggunakan port localhost 33000. Setelah Pengontrol dapat terhubung ke perangkat virtual, Pengontrol akan menampilkan layar yang menunjukkan status perangkat Anda:

Antarmuka pengguna grafis Perangkat Virtual

Aplikasi mengirimkan permintaan ke server RPC perangkat saat Anda membuat perubahan pada aplikasi Pengontrol Virtual, dan melakukan polling server RPC sekali per detik untuk mengambil status.

Aplikasi Pengontrol Perangkat Virtual juga dapat digunakan untuk mengambil kode QR sebagai bagian dari alur commissioning perangkat Anda. Klik ikon kode QR di samping image perangkat guna menampilkan kode QR untuk perangkat ini. Gunakan kode QR ini untuk melakukan commissioning pada perangkat Anda.

6. Tetapkan perangkat

Catatan: Langkah ini hanya akan berhasil jika Anda sudah menyiapkan project di Konsol Google Home.

Nest Hub

Hub diperlukan untuk melakukan commissioning pada perangkat Anda di kain Matter. Ini adalah perangkat Google Nest, seperti Nest Hub (generasi ke-2), yang mendukung Matter dan akan berfungsi sebagai Router Pembatas untuk perangkat yang mendukung Thread dan sebagai jalur fulfillment lokal untuk merutekan intent Smart Home.

Lihat daftar ini untuk mengetahui hub mana yang mendukung Matter.

Sebelum memulai proses commissioning, pastikan bahwa:

  • Hub Anda disambungkan dengan Akun Google yang sama dengan yang Anda gunakan untuk login di Konsol Google Home.
  • Hub Anda berada di jaringan Wi-Fi yang sama dengan komputer yang digunakan untuk menjalankan Virtual Matter Device Anda.
  • Hub Anda berada dalam struktur yang sama dengan yang Anda gunakan di Aplikasi Google Home. ("Rumah" di Google Home Graph mewakili struktur Anda).

Dapatkan Kode QR

Proses commissioning memerlukan informasi aktivasi Matter yang disediakan melalui kode QR. Anda bisa mendapatkan kode QR untuk perangkat virtual dari Pengontrol Perangkat Virtual.

Melakukan operasi komisi

  1. Buka aplikasi Google Home.
  2. Ketuk + di pojok kiri atas.
  3. Ketuk Siapkan perangkat.
  4. Ketuk Perangkat baru.
  5. Pilih rumah Anda, lalu ketuk Berikutnya.
  6. Aplikasi Google Home akan memindai perangkat Anda. Jika muncul pesan "Perangkat Matter ditemukan...", ketuk 'Ya'. Jika tidak, ketuk Siapkan perangkat lain, lalu pilih Perangkat Matter dari daftar perangkat.
  7. Arahkan kamera ke kode QR perangkat atau kode QR yang dibuat situs.
  8. Lanjutkan proses penyambungan seperti yang ditunjukkan dalam alur aplikasi Google Home.

Setelah Anda menyelesaikan langkah-langkah ini, perangkat virtual Matter akan berhasil dipesan, dan akan muncul sebagai ikon baru di Aplikasi Google Home Anda.

Bohlam yang tersambung di Aplikasi Google Home

Pemecahan masalah

Commissioning gagal dengan pesan error "Masalah konektivitas" atau "Tidak dapat menghubungi Google"

  • Pastikan Anda telah membuat project dengan kombinasi VID/PID yang benar di Konsol Google Home, dan Anda tidak memiliki project lain yang menggunakan kombinasi VID/PID yang sama.

Commissioning gagal setelah "Memindai perangkat Anda" dalam waktu yang lama

  • Pastikan firewall komputer nonaktif dan Anda menjalankan perangkat virtual.
  • Putuskan sambungan antarmuka jaringan fisik (Ethernet) untuk memastikan bahwa komputer Anda menggunakan Wi-Fi secara eksklusif.

7. Mengontrol perangkat

Setelah perangkat yang kompatibel dengan Matter berhasil dipesan dan muncul di aplikasi Google Home sebagai bohlam, Anda dapat menguji kontrol perangkat dengan metode yang berbeda:

  • Menggunakan Asisten Google.
  • Menggunakan aplikasi Google Home.
  • Menggunakan GUI Perangkat Virtual.

Asisten Google

Gunakan Asisten Google di ponsel atau hub Anda untuk beralih status perangkat dari perintah suara, seperti mengucapkan "Ok Google, alihkan lampu saya".

Lihat bagian Mengontrol perangkat smart home dengan perintah suara dari Mengontrol perangkat smart home yang ditambahkan ke aplikasi Google Home untuk contoh perintah lainnya.

Aplikasi Google Home

Anda dapat mengetuk label Aktif dan Nonaktif di samping ikon bohlam yang ditampilkan di Aplikasi Google Home.

Lihat bagian Mengontrol perangkat dengan aplikasi Google Home di Mengontrol perangkat smart home yang ditambahkan ke aplikasi Google Home untuk informasi selengkapnya.

GUI Perangkat Virtual

Anda dapat berinteraksi dengan GUI Perangkat Virtual untuk mengubah status perangkat. Baik Anda mengontrol perangkat virtual dengan Pengontrol Perangkat Virtual, Aplikasi Google Home di ponsel, atau dengan hub Anda, semua antarmuka ini akan mencerminkan status perangkat virtual saat ini.

8. Selamat!

Anda berhasil membuat perangkat Matter pertama Anda. Keren!

Dalam codelab ini, Anda telah mempelajari cara:

  • Menginstal lingkungan pengembangan Matter menggunakan image Docker yang sudah dikemas sebelumnya.
  • Membuat dan menjalankan perangkat virtual Matter.
  • Komisi dan kontrol perangkat virtual Anda dari Google Home.

Untuk mempelajari Matter lebih lanjut, pelajari referensi berikut: