Mem-build perangkat virtual Matter

1. Pengantar

Matter adalah protokol konektivitas yang menghadirkan peluang menarik untuk pengembangan perangkat smart. Dalam codelab ini, Anda akan membuat perangkat Matter pertama Anda menggunakan resource dari Matter SDK.

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 melakukan commissioning dan mengontrol perangkat Matter virtual dengan Google Home

Yang Anda butuhkan

  • Hub, yang merupakan perangkat Google Nest yang mendukung Matter, seperti Nest Hub (generasi ke-2).
  • Mesin Linux yang menjalankan sistem windowing X11.
  • di Docker versi baru.
  • Git.
  • Pengetahuan dasar tentang Linux.
    • Perhatikan bahwa shell yang diasumsikan untuk semua perintah dalam codelab ini adalah BASH.

2. Menyiapkan lingkungan Anda

Periksa hardware Anda

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

Selain itu, petunjuk ini mengasumsikan bahwa komputer Linux Anda menjalankan sistem windowing X11. Jika mesin Linux Anda menjalankan Wayland, pastikan X.Org juga telah diinstal.

Menyiapkan lingkungan pengembangan

  1. Instal Docker Engine (jangan gunakan Desktop Docker).
  2. Clone Matter SDK, perhatikan commit yang kami gunakan dalam hal berikut.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Jalankan container build menggunakan image CI publik SDK, dan jalankan perangkat virtual yang baru dibuat dari dalam container ini. Cari gambar yang akan digunakan untuk mencocokkan versi SDK kami seperti ini:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Jika menggunakan commit yang sama, Anda akan melihat ghcr.io/project-chip/chip-build:66Pertama, teruskan port xhost agar nanti kita dapat menggunakan aplikasi UI:
    xhost local:1000
    Selanjutnya, mulai penampung dengan resource yang sesuai yang diteruskan dari host (resource checkout, jaringan, dan tampilan/komunikasi SDK kami).
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

Mari kita pahami perintah docker dan opsi yang telah kita teruskan:

  • xhost local:1000 memungkinkan Sistem Jendela X untuk menerima koneksi dari host lokal pada port 1000, sehingga memungkinkan penggunaan antarmuka pengguna grafis.
  • docker run … image menjalankan image yang diberikan, mengambilnya dari registry Docker jika perlu.
  • --ipc=host memungkinkan Docker membagikan namespace komunikasi antarproses dengan mesin host Anda.
  • --net=host memungkinkan Docker menggunakan stack jaringan host di dalam penampung, 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.
  • --mount memasang SDK yang sebelumnya kita lihat ke dalam container.
  • --workdir menetapkan direktori kerja saat peluncuran ke direktori SDK yang terpasang.

Secara opsional, 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. Jika Anda melakukannya, data lama, yang disimpan pada instance container sebelumnya, akan hilang. Terkadang hal ini yang Anda inginkan terjadi, karena memungkinkan Anda memulai dengan penginstalan baru. Namun, ada kalanya Anda lebih suka menyimpan konfigurasi lingkungan dan kerja di antara sesi.

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

user@host> docker stop matter-container

Jika Anda sudah siap menjalankan container 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 awal Matter

Menginisialisasi SDK

Lakukan inisialisasi Matter SDK. Operasi ini akan memerlukan waktu beberapa menit hingga selesai.

source scripts/bootstrap.sh
python3 scripts/checkout_submodules.py --shallow --platform linux

Matter SDK Anda kini telah diinisialisasi. Untuk menginisialisasi ulang lingkungan dengan cepat di masa mendatang, jalankan:

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

Berbagi file antara host dan penampung

Sebelumnya, kita mengakses file di mesin host Anda dari dalam container menggunakan bind mount. Anda juga dapat menulis file ke direktori yang terpasang dari dalam container untuk diakses dari host.

Secara umum, gunakan bind mount dengan menjalankan 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 penampung pada direktori yang terpasang 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 pada host container dan tetapkan direktori kerja ke direktori yang dipasang oleh container.

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

user@host> sudo chgrp -R 1000 .

Berikan izin yang diinginkan dalam direktori ke grup. Contoh ini memberikan izin baca, tulis, dan eksekusi pada grup pengguna container pada semua file dalam direktori yang terpasang.

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

Perhatikan bahwa perintah ini tidak memengaruhi izin file baru yang dibuat oleh pengguna host. Ingatlah untuk memperbarui izin file baru yang dibuat di {i>host<i} 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 Google Home adalah aplikasi web tempat Anda mengelola integrasi Matter dengan Google Home.

Setiap 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 proyek.
  2. Masukkan nama project yang unik, lalu klik Create project. Dialog buat project baru
  3. Klik + Tambahkan integrasi, yang akan mengarahkan Anda ke layar Resource Matter, tempat Anda dapat melihat dokumentasi pengembangan Matter dan membaca beberapa alat.
  4. Jika sudah siap untuk melanjutkan, klik Berikutnya: Kembangkan, yang menampilkan halaman Checklist Matter.
  5. Klik Berikutnya: Penyiapan
  6. Di halaman Setup, masukkan Product name.
  7. Klik Pilih jenis perangkat dan 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 Simpan & lanjutkan, lalu klik Simpan di halaman berikutnya. Gunakan nilai VID/PID persis ini, 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 tersebut menerima konfigurasi project integrasi Matter terbaru. Jika harus mengubah VID atau PID nanti, Anda juga harus memulai ulang setelah menyimpan project agar perubahan dapat diterapkan. Lihat Memulai ulang perangkat Google Nest atau Google Wifi untuk mengetahui petunjuk langkah demi langkah memulai ulang perangkat.

4. Membuat perangkat

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

Koki adalah:

  • Aplikasi contoh yang menyediakan antarmuka terminal, yang menggabungkan fitur juga ditemukan di aplikasi examples/shell.
  • Skrip yang mencakup prinsip konvensi-over-konfigurasi untuk merangkum beberapa tugas umum yang diperlukan dalam 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 kita gunakan di sini adalah:

  • -d: menentukan jenis perangkat yang akan digunakan. Dalam hal ini, kita akan membuat aplikasi pencahayaan dengan kontrol aktif/nonaktif dan level.
  • -z: memanggil alat ZAP untuk membuat file sumber yang mengimplementasikan jenis perangkat. Artinya, berdasarkan pilihan pencahayaan Anda, ZAP akan otomatis membuat kode yang akan dimasukkan ke dalam build yang menentukan cahaya (Model Data) dan caranya berinteraksi dengan perangkat lain (Model Interaksi).
  • -b: build.
  • -r: [opsional] mengaktifkan server RPC di 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 dalam 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 Anda berjalan. Sekarang kita akan mengalihkan perhatian ke Aplikasi Google Home sehingga kami dapat menugaskan perangkat Anda ke Google Home.

Hentikan perangkat

Jika Anda perlu menghentikan perangkat, Anda dapat keluar dari program dengan menekan 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. Komisi perangkat

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

Nest Hub

Perlu hub untuk melakukan commissioning pada perangkat Anda pada kain Matter. Perangkat ini adalah perangkat Google Nest, seperti Nest Hub (generasi ke-2), yang mendukung Matter dan akan berfungsi sebagai Router Batas untuk perangkat yang mendukung Thread dan sebagai jalur fulfillment lokal untuk mengarahkan intent Smart Home.

Lihat daftar ini untuk melihat 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 Anda gunakan untuk menjalankan Perangkat Virtual Matter.
  • Hub Anda berada dalam struktur yang sama dengan yang Anda gunakan di Aplikasi Google Home. ("Rumah" di Grafik Google Home mewakili struktur Anda).

Dapatkan Kode QR

Proses commissioning memerlukan informasi aktivasi Matter yang diberikan melalui kode QR. Periksa output konsol aplikasi Matter yang akan berisi link untuk kode QR yang relevan dengan commissioning.

Melakukan operasi komisi

  1. Buka aplikasi Google Home.
  2. Ketuk + di sudut 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 diminta dengan pesan "Perangkat Matter ditemukan...", ketuk 'Ya'. Atau, ketuk Siapkan perangkat lain, lalu pilih Perangkat Matter dari daftar perangkat.
  7. Arahkan kamera Anda ke kode QR perangkat atau kode QR yang dibuat situs Anda.
  8. Lanjutkan proses penyambungan seperti yang ditunjukkan dalam alur aplikasi Google Home.

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

Bohlam yang disambungkan di Aplikasi Google Home

Pemecahan masalah

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

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

Commissioning gagal setelah "Memindai perangkat Anda" untuk jangka waktu yang lama

6. Mengontrol perangkat

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

  • Menggunakan Asisten Google.
  • Menggunakan aplikasi Google Home.

Asisten Google

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

Lihat bagian Mengontrol perangkat smart home dengan perintah suara di Mengontrol perangkat smart home yang ditambahkan ke aplikasi Google Home untuk mengetahui 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 dalam Mengontrol perangkat smart home yang ditambahkan ke aplikasi Google Home untuk mengetahui informasi selengkapnya.

7. Selamat!

Anda telah berhasil membuat perangkat Matter pertama Anda. Keren!

Dalam codelab ini, Anda telah mempelajari cara:

  • Menginstal lingkungan pengembangan Matter.
  • Membuat dan menjalankan perangkat virtual Matter.
  • Lakukan komisi dan kontrol perangkat virtual Anda dari Google Home.

Untuk mempelajari Matter lebih lanjut, pelajari referensi berikut: