Mem-build perangkat virtual Matter

1. Pengantar

Matter adalah protokol konektivitas yang menghadirkan peluang menarik untuk pengembangan perangkat smart. Dalam codelab ini, Anda akan membangun perangkat Matter pertama 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, yaitu perangkat Google Nest yang mendukung Matter, seperti Nest Hub (generasi ke-2).
  • Komputer Linux yang menjalankan sistem window X11.
  • Docker.
  • 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 mesin Linux Anda menjalankan sistem window X11. Jika mesin Linux Anda menjalankan Wayland, pastikan X.Org juga diinstal.

Menyiapkan lingkungan pengembangan

  1. Instal Docker Engine (jangan gunakan Docker Desktop).
  2. Clone Matter SDK, catat commit yang kita gunakan di langkah berikutnya.
    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. Temukan gambar yang akan digunakan yang cocok dengan versi SDK kami seperti ini:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Jika Anda menggunakan commit yang sama, Anda akan melihat ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    Selanjutnya, mulai penampung dengan meneruskan resource yang sesuai dari host (resource checkout, jaringan, dan tampilan/komunikasi SDK).
    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 kita teruskan:

  • xhost local:1000 memungkinkan X Window System menerima koneksi dari host lokal di port 1000, sehingga memungkinkan penggunaan antarmuka pengguna grafis.
  • docker run … image menjalankan image yang diberikan, dan menariknya dari registry Docker jika perlu.
  • --ipc=host memungkinkan Docker berbagi namespace komunikasi antar-proses 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 berbagi tampilan X11 host.
  • -e DISPLAY mengekspor $DISPLAY ke host, sehingga memberikan akses ke antarmuka grafis sistem Anda. Hal 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 periksa ke dalam container.
  • --workdir menetapkan direktori kerja saat peluncuran ke direktori SDK yang di-mount.

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 Anda, yang disimpan di instance penampung sebelumnya, akan hilang. Terkadang, inilah yang ingin Anda lakukan, karena memungkinkan Anda memulai dengan penginstalan baru. Namun, ada saatnya Anda lebih memilih untuk menyimpan pekerjaan dan konfigurasi lingkungan di antara sesi.

Oleh karena itu, setelah membuat penampung, Anda dapat menghentikan penampung untuk mencegah hilangnya pekerjaan Anda.

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 container 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

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 pada masa mendatang, jalankan:

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

Membagikan file antara host dan penampung

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

Secara umum, gunakan pemasangan bind dengan menjalankan container Anda dengan argumen tambahan --mount source=$(pwd),target=/workspace,type=bind untuk memasang direktori kerja Anda 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 di direktori yang di-mount 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 di-mount oleh container.

Tetapkan grup secara rekursif untuk file di direktori yang di-mount ke grup pengguna penampung.

user@host> sudo chgrp -R 1000 .

Beri grup izin yang Anda inginkan di direktori. Contoh ini memberikan izin baca, tulis, dan eksekusi grup pengguna penampung pada semua file di direktori yang di-mount.

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

Perhatikan bahwa perintah ini tidak memengaruhi izin file baru yang dibuat oleh pengguna host. Jangan lupa 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 dari Connectivity Standards Alliance (Alliance) dapat berfungsi di ekosistem Google Home. Perangkat dalam pengembangan yang belum disertifikasi dapat diaktifkan di ekosistem Google Home dalam kondisi tertentu - lihat Batasan penyambungan untuk mengetahui informasi selengkapnya.

Membuat project developer

Mulai dengan membuka Konsol Developer Google Home:

  1. Klik Buat proyek.
  2. Masukkan nama project yang unik, lalu klik Buat project. Dialog buat project baru
  3. Klik + Tambahkan integrasi, yang akan mengarahkan Anda ke layar Sumber daya Matter, tempat Anda dapat melihat dokumentasi pengembangan Matter dan membaca tentang beberapa alat.
  4. Jika Anda sudah siap melanjutkan, klik Berikutnya: Kembangkan, yang akan menampilkan halaman Daftar checklist Matter.
  5. Klik Berikutnya: Penyiapan
  6. Di halaman Penyiapan, masukkan Nama produk Anda.
  7. Klik Pilih jenis perangkat, lalu pilih jenis perangkat dari menu drop-down (dalam hal ini, Light).
  8. Di Vendor ID (VID), pilih Test VID, lalu pilih 0xFFF1 dari menu drop-down Test VID. Di Product ID (PID), masukkan 0x8000, lalu klik Save & continue, lalu klik Save di halaman berikutnya. Gunakan nilai VID/PID yang tepat ini, karena langkah-langkah codelab selanjutnya bergantung padanya.
    Menyiapkan project
  9. Sekarang Anda akan melihat integrasi di bagian Integrasi Matter.
  10. Mulai ulang hub untuk memastikan hub menerima konfigurasi project integrasi Matter terbaru. Jika Anda harus mengubah VID atau PID nanti, Anda juga harus memulai ulang setelah menyimpan project agar perubahan diterapkan. Lihat Memulai ulang perangkat Google Nest atau Google Wifi untuk mengetahui petunjuk langkah demi langkah cara memulai ulang.

4. Membangun perangkat

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

Chef adalah:

  • Aplikasi contoh yang menyediakan antarmuka terminal, yang juga mencakup fitur yang ditemukan di aplikasi examples/shell.
  • Skrip yang menerapkan prinsip convention-over-configuration untuk merangkum 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 kita gunakan di sini adalah:

  • -d: menentukan jenis perangkat yang akan digunakan. Dalam hal ini, kita membuat aplikasi pencahayaan dengan kontrol on/off dan level.
  • -z: memanggil alat ZAP untuk membuat file sumber yang mengimplementasikan jenis perangkat. Artinya, berdasarkan pilihan pencahayaan Anda, ZAP akan otomatis membuat kode untuk dimasukkan ke dalam build yang menentukan cahaya (Model Data) dan cara berinteraksi dengan perangkat lain (Model Interaksi).
  • -b: build.
  • -r: [opsional] mengaktifkan server RPC di perangkat virtual Matter sehingga komponen lain (seperti GUI) dapat berkomunikasi dengan perangkat untuk menyetel dan mengambil Atribut Model Data.
  • -t linux: platform target. Platform yang didukung 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 firewall tersebut, atau izinkan koneksi TCP/UDP 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 Anda tetap berjalan. Sekarang kita akan beralih ke Aplikasi Google Home agar dapat mengaktifkan perangkat Anda di Google Home.

Hentikan perangkat

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

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

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

$ rm /tmp/chip*

5. Aktifkan perangkat

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

Nest Hub

Hub diperlukan untuk mengaktifkan perangkat Anda di fabric Matter. Ini adalah perangkat Google Nest, seperti Nest Hub (generasi ke-2), yang mendukung Matter dan yang akan berfungsi sebagai Router Pembatas untuk perangkat yang kompatibel dengan Thread dan sebagai jalur pemenuhan lokal untuk merutekan maksud Smart Home.

Lihat daftar ini untuk mengetahui hub mana yang mendukung Matter.

Sebelum memulai proses aktivasi, periksa untuk memastikan bahwa:

  • Hub Anda dipasangkan 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 Matter Virtual.
  • Hub Anda berada di struktur yang sama dengan yang Anda gunakan di Aplikasi Google Home. ("Rumah" di Google Home Graph mewakili struktur Anda).

Mendapatkan Kode QR

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

Menjalankan 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 Anda diminta dengan pesan "Perangkat Matter ditemukan...", ketuk 'Ya'. Jika tidak, ketuk Siapkan perangkat lain, lalu pilih Perangkat Matter dari daftar perangkat.
  7. Arahkan kamera Anda ke kode QR perangkat Anda 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 di-commissioning, dan akan muncul sebagai ikon baru di Aplikasi Google Home Anda.

Bohlam yang disambungkan di Aplikasi Google Home

Pemecahan masalah

Proses penyiapan 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.

Proses aktivasi gagal setelah "Memindai perangkat Anda" dalam jangka waktu yang lama

6. Mengontrol perangkat

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

  • Menggunakan Asisten Google.
  • Menggunakan aplikasi Google Home.

Asisten Google

Gunakan Asisten Google di ponsel atau hub untuk mengubah status perangkat dari perintah suara, seperti mengucapkan "Ok Google, ubah status 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 di 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:

  • Instal lingkungan pengembangan Matter.
  • Bangun dan jalankan perangkat virtual Matter.
  • Lakukan commissioning dan kontrol perangkat virtual Anda dari Google Home.

Untuk mempelajari Matter lebih lanjut, pelajari referensi berikut: