Membangun 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 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 mem-build perangkat Matter virtual yang berjalan di komputer Anda
  • Cara mengaktifkan dan mengontrol perangkat Matter virtual dengan Google Home

Yang akan Anda butuhkan

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

2. Menyiapkan lingkungan Anda

Memeriksa 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 mesin Linux Anda menjalankan sistem jendela 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, perhatikan commit yang kita gunakan di bagian 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 di-build dari dalam container ini. Temukan image yang akan digunakan yang cocok dengan versi SDK kita 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:66Pertama, teruskan port xhost agar kita dapat menggunakan aplikasi UI nanti:
    xhost local:1000
    Selanjutnya, mulai container dengan resource yang sesuai yang diteruskan dari host (checkout SDK, jaringan, dan resource tampilan/komunikasi kita).
    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 ke perintah tersebut:

  • 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 mengambilnya dari registry Docker jika diperlukan.
  • --ipc=host memungkinkan Docker berbagi namespace komunikasi antar-proses (IPC) 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 checkout ke dalam container.
  • --workdir menetapkan direktori kerja saat peluncuran ke direktori SDK yang dipasang.

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 container sebelumnya, akan hilang. Terkadang, hal ini yang Anda inginkan, karena memungkinkan Anda memulai dengan penginstalan baru. Namun, ada kalanya Anda lebih suka menyimpan konfigurasi pekerjaan dan lingkungan antar-sesi.

Karena alasan ini, setelah membuat container, Anda dapat menghentikan container untuk mencegah kehilangan pekerjaan.

user@host> docker stop matter-container

Saat Anda 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

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

Membagikan file antara host dan container

Sebelumnya, kita mengakses file di mesin host Anda dari dalam container menggunakan pemasangan bind. Anda juga dapat menulis file ke direktori yang dipasang 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 container pada direktori yang dipasang harus dikelola di host.

Dapatkan ID grup pengguna container dari dalam container.

$ 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 di direktori yang dipasang ke grup pengguna container.

user@host> sudo chgrp -R 1000 .

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

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 host sesuai kebutuhan.

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

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.

Perangkat Matter yang telah lulus sertifikasi Matter Connectivity Standards Alliance (Alliance) berfungsi di ekosistem Google Home. Perangkat yang sedang dikembangkan dan belum disertifikasi dapat diaktifkan di ekosistem Google Home dengan 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 buat project baru
  3. Klik + Tambahkan integrasi, yang akan mengarahkan Anda ke layar Resource Matter, tempat Anda dapat melihat dokumentasi pengembangan Matter dan membaca tentang beberapa alat.
  4. Jika sudah siap untuk melanjutkan, klik Berikutnya: Kembangkan, yang akan menampilkan halaman Checklist Matter.
  5. Klik Berikutnya: Penyiapan
  6. Di halaman Penyiapan, masukkan Nama produk Anda.
  7. Klik Pilih jenis perangkat dan pilih jenis perangkat dari menu drop-down (dalam hal ini, Light).
  8. Di Vendor ID (VID), pilih Test VID, dan pilih 0xFFF1 dari menu drop-down Test VID. Di Product ID (PID), masukkan 0x8000 dan klik Simpan &lanjutkan, lalu klik Simpan di halaman berikutnya. Gunakan nilai VID/PID yang sama persis ini, karena langkah-langkah codelab berikutnya bergantung pada nilai ini.
    Menyiapkan project
  9. Sekarang Anda akan melihat integrasi Anda di bagian Integrasi Matter.
  10. Mulai ulang hub Anda 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 tersebut diterapkan. Lihat Memulai ulang perangkat Google Nest atau Google Wifi untuk mengetahui petunjuk memulai ulang langkah demi langkah.

4. Mem-build perangkat

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

Chef adalah:

  • Aplikasi contoh yang menyediakan antarmuka terminal, yang menggabungkan fitur yang juga ditemukan di aplikasi examples/shell.
  • Skrip yang menerapkan prinsip konvensi-atas-konfigurasi 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 menerapkan jenis perangkat. Artinya, berdasarkan pilihan pencahayaan Anda, ZAP akan otomatis membuat kode yang akan dimasukkan ke dalam build yang menentukan lampu (Model Data) dan cara interaksinya 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 memiliki firewall yang berjalan di komputer, nonaktifkan, 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 berjalan. Sekarang kita akan membahas Aplikasi Google Home agar kita dapat mengaktifkan perangkat Anda ke Google Home.

Menghentikan perangkat

Jika 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 diawali dengan awalan chip.

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

$ rm /tmp/chip*

5. Mengaktifkan 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 akan berfungsi sebagai router pembatas untuk perangkat yang kompatibel dengan Thread dan sebagai jalur pemenuhan lokal untuk merutekan intent Smart Home.

Lihat daftar ini untuk melihat hub mana yang mendukung Matter.

Sebelum memulai proses pengaktifan, pastikan:

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

Mendapatkan Kode QR

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

Menjalankan operasi pengaktifan

  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'. Jika tidak, ketuk Siapkan perangkat lain, lalu pilih Perangkat Matter dari daftar perangkat.
  7. Arahkan kamera ke kode QR perangkat Anda atau kode QR yang dibuat situs.
  8. Lanjutkan proses penyambungan seperti yang ditunjukkan dalam alur aplikasi Google Home.

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

Bohlam yang disambungkan di Aplikasi Google Home

Pemecahan masalah

Pengaktifan gagal dengan pesan error "Connectivity problem" atau "Could not contact 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.

Pengaktifan gagal setelah "Scanning your device" dalam waktu yang lama

6. Mengontrol perangkat

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

  • 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 On dan Off di samping ikon lampu 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:

  • Menginstal lingkungan pengembangan Matter.
  • Mem-build dan menjalankan perangkat virtual Matter.
  • Mengaktifkan dan mengontrol perangkat virtual Anda dari Google Home.

Untuk mempelajari Matter lebih lanjut, lihat referensi berikut: