Perhatian! Program Pratinjau Developer yang baru akan segera diluncurkan. Daftar di sini dan jadilah salah satu developer pertama yang mencoba alat baru serta berikan masukan.

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

  1. Instal Docker Engine (jangan gunakan Docker Desktop).
  2. 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.
  3. 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:

  1. Di halaman Kelola project, klik Buat project.
    Pusat Developer Google Home
  2. Di halaman Get started, klik Create project.

  1. Masukkan nama project unik lalu klik Buat project baru. Dialog Buat project baru
  2. Klik + Add integration, yang akan mengarahkan Anda ke layar 'Matter resources', tempat Anda dapat melihat dokumentasi Pengembangan Matter dan membaca tentang beberapa alat.
  3. Saat Anda siap melanjutkan, klik Berikutnya: Kembangkan, yang menampilkan halaman Checklist Matter.
  4. Klik Berikutnya: Penyiapan
  5. Di halaman Penyiapan, masukkan Nama produk.
  6. Klik Pilih jenis perangkat, lalu pilih jenis perangkat dari menu dropdown (dalam hal ini, Light).
  7. 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.
    Menyiapkan project
  8. Sekarang Anda akan melihat satu perangkat Matter di bawah integrasi Matter. Integrasi Matter
  9. 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 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 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:

Antarmuka pengguna grafis Perangkat Virtual

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:

Kode QR

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

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

Bola lampu yang disambungkan 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

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: