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 dalam 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 mem-build perangkat Matter virtual yang berjalan di komputer Anda
- Cara memesan dan mengontrol perangkat Matter virtual dengan Google Home
Yang Anda butuhkan
- Hub, yaitu perangkat Google Nest apa pun yang mendukung Matter, seperti Nest Hub (generasi ke-2). Anda dapat membeli hub di Google Store atau di retailer pilihan Anda.
- Mesin Linux yang menjalankan sistem windowing X11.
- Docker.
- Pengetahuan dasar tentang Linux.
2. Menyiapkan lingkungan Anda
Kita akan menggunakan container Docker yang telah dikonfigurasi sebelumnya pada mesin host Linux. Container ini menyertakan semua dependensi yang diperlukan untuk mem-build dan menjalankan perangkat virtual Matter.
Periksa hardware
Komputer Windows dan MacOS saat ini tidak didukung oleh penginstalan Docker ini. Anda dapat menginstal dan mem-build Matter secara manual di MacOS atau Windows.
Selain itu, petunjuk ini mengasumsikan bahwa komputer Linux Anda menjalankan sistem windowing X11. Jika komputer Linux Anda menjalankan Wayland, pastikan X.Org juga terinstal.
Menyiapkan Docker
- Instal Docker Engine (jangan gunakan Docker Desktop).
- Tarik 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 beberapa menit untuk diselesaikan. - Mulai container Docker yang berjalan:
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 yang 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 ke perintah tersebut:
xhost local:1000
memungkinkan Sistem Jendela X menerima koneksi dari host lokal pada port 1000, sehingga memungkinkan penggunaan antarmuka pengguna grafis (GUI).docker run … image
menjalankan gambar yang diberikan, mengambilnya dari registry Docker jika perlu.--ipc=host
memungkinkan Docker untuk 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 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.
Secara opsional, Anda dapat menjalankan instance sesi terminal kedua:
user@host> docker exec -it matter-container /bin/bash $
Menghentikan dan memulai container Matter Docker
Setiap kali menjalankan perintah docker run
, Anda akan membuat container baru dengan image yang ditentukan. Saat melakukannya, data lama Anda, yang disimpan di instance container sebelumnya, akan hilang. Terkadang inilah yang Anda inginkan, karena memungkinkan Anda memulai dengan penginstalan baru. Namun, ada kalanya Anda lebih memilih untuk menyimpan konfigurasi pekerjaan dan lingkungan antar-sesi.
Oleh karena itu, setelah membuat container, Anda dapat menghentikan container untuk mencegah hilangnya pekerjaan.
user@host> docker stop matter-container
Jika sudah siap untuk menjalankan lagi, mulai penampung 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
Saat dibuka, terminal Anda akan berada di repositori Matter yang di-clone di ~/connectedhomeip
. Tidak diperlukan langkah penyiapan Matter tambahan.
Berbagi file antara host dan penampung
Untuk mengakses file di mesin host dari dalam container, Anda dapat menggunakan mount binding. Anda juga dapat menulis file ke direktori yang telah 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 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 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 berulang untuk file di direktori yang terpasang ke grup pengguna penampung.
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 terpasang.
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 Google Home Developer
Google Home Developer Console adalah aplikasi web tempat Anda mengelola integrasi Matter dengan Google Home.
Setiap perangkat Matter yang telah lulus sertifikasi CSA Matter dapat berfungsi di ekosistem Google Home. Perangkat dalam pengembangan yang belum disertifikasi dapat diminta dalam ekosistem Google Home dalam kondisi tertentu - lihat Pembatasan penyambungan untuk informasi selengkapnya.
Membuat project developer
Mulai dengan membuka Konsol Google Home:
- Di halaman Kelola project, klik Buat project.
- Di halaman Get started, klik Create project.
- Masukkan nama project unik lalu klik Buat project baru.
- Klik + Add integration, yang akan mengarahkan Anda ke layar 'Matter resources', tempat Anda dapat melihat dokumentasi Pengembangan Matter dan membaca tentang beberapa alat.
- Saat Anda siap melanjutkan, klik Berikutnya: Kembangkan, yang menampilkan halaman Checklist Matter.
- Klik Berikutnya: Penyiapan
- Di halaman Penyiapan, masukkan Nama produk.
- Klik Pilih jenis perangkat, lalu pilih jenis perangkat dari menu dropdown (dalam hal ini,
Light
). - Di ID Vendor (VID), pilih Test VID, dan pilih 0xFFF1 dari menu dropdown Test VID. Di ID Produk (PID), masukkan 0x8000, klik Simpan & lanjutkan, lalu klik Simpan di halaman berikutnya.
- Sekarang Anda akan melihat satu perangkat Matter di bawah integrasi Matter.
- Mulai ulang hub Anda untuk memastikan bahwa hub menerima konfigurasi project integrasi Matter terbaru. Jika nanti Anda harus mengubah VID atau PID, Anda juga perlu memulai ulang setelah menyimpan project agar perubahan diterapkan.
4. Membuat perangkat
Semua contoh dalam Matter dapat ditemukan di folder examples
di repositori GitHub. Ada beberapa contoh yang tersedia, tetapi fokus kita pada codelab ini adalah di Chef.
Chef adalah:
- Aplikasi contoh yang menyediakan antarmuka terminal, yang menggabungkan fitur yang juga ditemukan di aplikasi
examples/shell
. - Skrip yang menggunakan prinsip konvensi melalui konfigurasi untuk mengenkapsulasi beberapa tugas umum yang diperlukan untuk mengembangkan perangkat yang mengaktifkan Matter.
Buka folder contoh Chef dan buat build Matter pertama Anda:
$ cd examples/chef $ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux
Koki 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 level.-z
: memanggil alat ZAP untuk membuat file sumber yang menerapkan jenis perangkat. Artinya, berdasarkan pilihan pencahayaan, ZAP akan otomatis membuat kode untuk digabungkan ke dalam build yang menentukan cahaya (Model Data) dan cara interaksinya 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 menyetel dan mengambil Atribut Model Data.-t linux
: platform target. Platform dukungan adalahlinux
,nrfconnect
, danesp32
. 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 TCP/UDP port 5540, jadi jika ada firewall yang berjalan di komputer, matikan, atau izinkan koneksi TCP/UDP masuk pada port 5540.
Jalankan perangkat virtual di penampung 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 mengalihkan perhatian ke Aplikasi Google Home sehingga kita dapat menetapkan perangkat Anda ke Google Home.
Hentikan perangkat
Anda dapat keluar dari program dengan CTRL+C. Jika aplikasi tidak keluar, Anda mungkin perlu menggunakan CTRL+\ juga.
Kredensial untuk perangkat virtual Anda disimpan di direktori /tmp/
, dalam file yang dimulai dengan awalan chip
.
Jika ingin mengulangi seluruh proses komisi 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 menyediakan representasi visual perangkat virtual Anda.
Anda dapat berinteraksi dengan perangkat virtual melalui antarmuka pengguna grafis (GUI) Pengontrol Perangkat Virtual. Perubahan Anda di GUI memengaruhi model data pokok. Saat ini, Pengontrol Perangkat Virtual mendukung jenis perangkat Dimmable Light.
Menginstal Pengontrol Perangkat Virtual
Pengontrol Perangkat Virtual telah diinstal sebelumnya di 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, pengontrol tersebut akan ditetapkan secara default ke opsi soket jaringan menggunakan port localhost 33000. Setelah dapat terhubung ke perangkat virtual, Pengontrol akan menampilkan layar yang menunjukkan status perangkat Anda:
Aplikasi mengirimkan permintaan ke server RPC perangkat saat Anda membuat perubahan pada aplikasi Pengontrol Virtual, dan melakukan polling pada server RPC sekali per detik untuk mengambil status.
Aplikasi Pengontrol Perangkat Virtual juga dapat digunakan untuk mengambil kode QR sebagai bagian dari alur komisi perangkat Anda. Klik ikon kode QR di samping gambar perangkat untuk menampilkan kode QR untuk perangkat ini:
Anda dapat menggunakan kode QR ini untuk memesan perangkat.
6. Membuat komisi perangkat
Catatan: Langkah ini hanya akan berhasil jika Anda sudah menyiapkan project di Konsol Google Home.
Nest Hub
Hub diperlukan untuk menugaskan perangkat Anda pada kain Matter. Ini adalah perangkat Google Nest, seperti Nest Hub (generasi ke-2), yang mendukung Matter dan yang akan berfungsi sebagai Border Router untuk perangkat yang mengaktifkan Thread dan sebagai jalur fulfillment lokal untuk mengarahkan intent Smart Home.
Lihat daftar ini untuk melihat hub mana yang mendukung Matter.
Sebelum memulai proses komisi, periksa untuk memastikan bahwa:
- Hub Anda disambungkan dengan akun Google yang sama dengan yang digunakan 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 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 komisi memerlukan informasi aktivasi Matter yang diberikan melalui kode QR. Anda bisa mendapatkan kode QR untuk perangkat virtual dari Pengontrol Perangkat Virtual.
Menjalankan operasi komisi
- Buka aplikasi Google Home.
- Ketuk + di sudut kiri atas.
- Ketuk Siapkan perangkat.
- Ketuk Perangkat baru.
- Pilih rumah Anda, lalu ketuk Berikutnya.
- Aplikasi Google Home memindai perangkat Anda. Jika muncul pesan "Perangkat Matter ditemukan...", ketuk 'Ya'. Jika tidak, ketuk Siapkan perangkat lain, lalu pilih Perangkat Matter dari daftar perangkat.
- Arahkan kamera ke kode QR perangkat atau kode QR yang dibuat situs.
- 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.
Pemecahan masalah
Komisi gagal dengan pesan error "Masalah konektivitas" atau "Tidak dapat menghubungi Google"
- 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.
Komisi gagal setelah "Memindai perangkat Anda" untuk jangka waktu yang lama
- Konfirmasikan bahwa firewall komputer Anda nonaktif dan bahwa Anda menjalankan perangkat virtual.
- Putuskan antarmuka jaringan fisik (Ethernet) untuk memastikan komputer Anda menggunakan Wi-Fi secara eksklusif.
7. Mengontrol perangkat
Setelah perangkat yang mengaktifkan Matter berhasil digunakan 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 mengubah 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 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, 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 telah dikemas sebelumnya.
- Mem-build dan menjalankan perangkat virtual Matter.
- Komisi dan kontrol perangkat virtual Anda dari Google Home.
Untuk mempelajari Matter lebih lanjut, baca referensi berikut:
- Matter Primer di Google Home Developer Center, tempat Anda akan mempelajari dasar-dasar konsep Matter.
- Spesifikasi Matter, Library Perangkat Matter, dan Library Cluster Aplikasi Matter, yang dipublikasikan oleh Connectivity Standards Alliance.
- Repositori GitHub Materi.