Matter sanal cihazı oluşturma

1. Giriş

Matter, akıllı cihazların geliştirilmesi için heyecan verici fırsatlar sunan bir bağlantı protokolüdür. Bu codelab'de, Matter SDK'sindeki kaynakları kullanarak ilk Matter cihazınızı oluşturacaksınız.

Matter hakkında bilgi edinmek için Google Home Geliştirici Merkezi'ni veya Connectivity Standards Alliance web sitesini ziyaret edin.

Neler öğreneceksiniz?

  • Matter derleme ortamı oluşturma
  • Bilgisayarınızda çalışan sanal bir Matter cihazı oluşturma
  • Google Home ile sanal Matter cihazını kullanıma alma ve kontrol etme

İhtiyacınız olanlar

  • Nest Hub (2. nesil) gibi Matter'ı destekleyen herhangi bir Google Nest cihazı olan bir hub.
  • X11 pencere sistemini çalıştıran bir Linux makine.
  • Docker.
  • Git.
  • Linux hakkında temel düzeyde bilgi sahibi olunması.
    • Bu codelab'deki tüm komutlar için varsayılan kabuğun BASH olduğunu unutmayın.

2. Ortamınızı ayarlama

Donanımınızı kontrol edin

Windows ve macOS bilgisayarlar bu Docker yüklemesi tarafından desteklenmez. macOS'e Matter'ı manuel olarak yükleyip oluşturabilirsiniz.

Ayrıca bu talimatlarda, Linux makinenizde X11 pencere sisteminin çalıştığı varsayılır. Linux makineniz Wayland'i çalıştırıyorsa X.Org'un da yüklendiğinden emin olun.

Geliştirme ortamını kurma

  1. Docker Engine'i yükleyin (Docker Desktop'ı kullanmayın).
    .
  2. Matter SDK'sını klonlayın ve aşağıda kullandığımız commit'i not edin.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. SDK'nın herkese açık CI görüntülerini kullanarak bir derleme container'ı çalıştırın ve yeni oluşturulan sanal cihazı bu container'ın içinden yürütün. SDK'mızın sürümüyle eşleşen görüntüyü şu şekilde bulun:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Aynı commit'i kullanıyorsanız ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    Ardından, ana makineden yönlendirilen uygun kaynaklarla (SDK ödeme, ağ oluşturma ve görüntüleme/iletişim kaynaklarımız) kapsayıcıyı başlatın.
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

Docker komutunu ve bu komuta ilettiğimiz seçenekleri inceleyelim:

  • xhost local:1000, X Window System'in 1000 numaralı bağlantı noktasında yerel ana makineden bağlantı almasına olanak tanır. Böylece grafik kullanıcı arayüzü kullanılabilir.
  • docker run … image, gerekli durumlarda Docker kayıt defterinden çekerek belirtilen görüntüyü çalıştırır.
  • --ipc=host, Docker'ın işlemler arası iletişim ad alanını ana makinenizle paylaşmasına olanak tanır.
  • --net=host, Docker'ın ana makinenin ağ yığınını kapsayıcı içinde kullanmasına olanak tanır. Bu, ana makineden kapsayıcıya mDNS trafiğini iletmek ve ana makine X11 ekranını paylaşmak için gereklidir.
  • -e DISPLAY, $DISPLAY öğesini ana makineye aktararak sisteminizin grafik arayüzüne erişim sağlar. Matter kümelerini düzenlerken ZAP aracını çalıştırmak için bu gereklidir.
  • -it, arka plan işlemi olarak değil, etkileşimli bir terminalle (tty) Docker'ı çalıştırır.
  • --mount, daha önce kullanıma sunduğumuz SDK'yı kapsayıcıya monte eder.
  • --workdir, başlatma sırasında çalışma dizinini bağlı SDK dizinimize ayarlar.

İsteğe bağlı olarak ikinci bir terminal oturumu örneği çalıştırabilirsiniz:

user@host> docker exec -it matter-container /bin/bash
$

Matter Docker kapsayıcısını durdurma ve başlatma

docker run komutunu her çalıştırdığınızda, belirtilen görüntüyle yeni bir kapsayıcı oluşturursunuz. Bu işlemi yaptığınızda önceki bir kapsayıcı örneğine kaydedilen eski verileriniz kaybolur. Bazen bu durum, yeni bir yüklemeyle başlamanıza olanak tanıdığı için tercih edilebilir. Ancak bazen çalışmanızı ve ortam yapılandırmanızı oturumlar arasında kaydetmek isteyebilirsiniz.

Bu nedenle, kapsayıcınızı oluşturduktan sonra çalışmanızı kaybetmemek için kapsayıcıyı durdurabilirsiniz.

user@host> docker stop matter-container

Tekrar çalıştırmaya hazır olduğunuzda kapsayıcıyı başlatın ve bir terminal penceresi açın:

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

Aşağıdaki komutla kapsayıcınızda ek terminal oturumları açabilirsiniz:

user@host> docker exec -it matter-container /bin/bash

Dilerseniz aşağıdaki yöntemleri kullanarak bir kök oturumu başlatabilirsiniz:

user@host> docker exec -u 0 -it matter-container /bin/bash

İlk Matter kurulumu

SDK'yı başlatma

Matter SDK'sını başlatın. Bu işlemin tamamlanması birkaç dakika sürer.

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

Matter SDK'nız başlatıldı. Gelecekte ortamı hızlıca yeniden başlatmak için şu komutu çalıştırın:

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

Ana makine ile kapsayıcı arasında dosya paylaşma

Daha önce, bağlama montajı kullanarak kapsayıcı içinden ana makinenizdeki dosyalara erişiyorduk. Ana makineden erişmek için kapsayıcı içinden de bağlı dizine dosya yazabilirsiniz.

Genel olarak, mevcut çalışma dizininizi /workspace konumunda kapsayıcıya bağlamak için kapsayıcınızı ek --mount source=$(pwd),target=/workspace,type=bind bağımsız değişkeniyle çalıştırarak bağlama bağlamalarını kullanın.

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

Bağlı dizinde kapsayıcı kullanıcısının izinleri ana makinede yönetilmelidir.

Kapsayıcı kullanıcısının grup kimliğini kapsayıcı içinden alın.

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

Container ana makinesinde başka bir terminal oturumu açın ve çalışma dizinini container tarafından bağlanan dizin olarak ayarlayın.

Bağlı dizindeki dosyaların grubunu, kapsayıcı kullanıcısının grubu olarak yinelemeli şekilde ayarlar.

user@host> sudo chgrp -R 1000 .

Dizinde istediğiniz izinleri gruba verin. Bu örnek, kapsayıcı kullanıcısının grubuna bağlı dizindeki tüm dosyalar için okuma, yazma ve yürütme izinleri verir.

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

Bu komutların, barındıran kullanıcı tarafından oluşturulan yeni dosyaların iznini etkilemediğini unutmayın. Ana makinede oluşturulan yeni dosyaların izinlerini gerektiği şekilde güncellemeyi unutmayın.

Kapsayıcı kullanıcının oluşturduğu dosyalardaki izinleri devralmak için ana makine kullanıcınızı kapsayıcı kullanıcının grubuna ekleyebilirsiniz.

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

3. Google Home Developer Console

Google Home Developer Console, Google Home ile Matter entegrasyonlarınızı yönettiğiniz web uygulamasıdır.

Connectivity Standards Alliance (Alliance) Matter sertifikasını almış tüm Matter cihazlar Google Home ekosisteminde çalışır. Geliştirme aşamasında olan ve sertifika almamış cihazlar, belirli koşullar altında Google Home ekosisteminde kullanılabilir. Daha fazla bilgi için Eşleme kısıtlamaları başlıklı makaleyi inceleyin.

Geliştirici projesi oluşturma

Google Home Developer Console'a giderek başlayın:

  1. Proje oluştur'u tıklayın.
  2. Benzersiz bir proje adı girin ve Proje oluştur'u tıklayın. Yeni proje oluşturma iletişim kutusu
  3. + Entegrasyon ekle'yi tıkladığınızda Matter kaynakları ekranına yönlendirilirsiniz. Bu ekranda Matter geliştirme belgelerini görüntüleyebilir ve bazı araçlar hakkında bilgi edinebilirsiniz.
  4. Devam etmeye hazır olduğunuzda Sonraki: Geliştir'i tıklayın. Matter yapılacaklar listesi sayfası gösterilir.
  5. Sonraki: Kurulum'u tıklayın.
  6. Kurulum sayfasında Ürün adınızı girin.
  7. Cihaz türünü seçin'i tıklayın ve açılır menüden cihaz türünü seçin (bu örnekte Light).
  8. Tedarikçi kimliği (VID) bölümünde Test VID'yi seçin ve Test VID açılır menüsünden 0xFFF1'i belirleyin. Ürün Kimliği (PID) alanına 0x8000 girin ve Kaydet ve devam et'i, ardından sonraki sayfada Kaydet'i tıklayın. Bu VID/PID değerlerini aynen kullanın. Sonraki codelab adımları bu değerlere bağlıdır.
    Proje oluşturma
  9. Entegrasyonunuzu artık Matter entegrasyonları bölümünde görebilirsiniz.
  10. En son Matter entegrasyonu proje yapılandırmasını aldığından emin olmak için hub'ınızı yeniden başlatın. VID veya PID'yi daha sonra değiştirmeniz gerekirse değişikliğin geçerli olması için projeyi kaydettikten sonra yeniden başlatmanız da gerekir. Adım adım yeniden başlatma talimatları için Google Nest veya Google Wifi cihazlarını yeniden başlatma başlıklı makaleyi inceleyin.

4. Cihaz oluşturma

Matter'daki tüm örnekleri GitHub deposundaki examples klasöründe bulabilirsiniz. Birkaç örnek mevcuttur ancak bu codelab'de Chef'e odaklanacağız.

Chef hem:

  • examples/shell uygulamasında da bulunan özellikleri kapsayan bir terminal arayüzü sağlayan örnek uygulama.
  • Matter özellikli bir cihaz geliştirmek için gerekli olan yaygın görevlerin birçoğunu kapsayan, yapılandırma yerine kural ilkesini benimseyen bir komut dosyası.

Chef örnek klasörüne gidin ve ilk Matter derlemenizi oluşturun:

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

Chef'in, chef.py -h komutu çalıştırılarak görüntülenebilen birkaç seçeneği vardır. Burada kullandığımız seçenekler şunlardır:

  • -d: Kullanılacak cihaz türünü tanımlar. Bu örnekte, açma/kapatma ve seviye kontrolleri olan bir aydınlatma uygulaması oluşturuyoruz.
  • -z: Cihaz türünü uygulayan kaynak dosyaları oluşturmak için ZAP aracını çağırır. Yani, aydınlatma seçiminize göre ZAP, ışığı (Veri Modeli) ve diğer cihazlarla nasıl etkileşime girdiğini (Etkileşim Modeli) tanımlayan, derlemeye dahil edilecek kodu otomatik olarak oluşturur.
  • -b: derlemeler.
  • -r: [isteğe bağlı] Diğer bileşenlerin (ör. GUI) cihazla iletişim kurarak Veri Modeli Özelliklerini ayarlayıp alabilmesi için sanal Matter cihazında RPC sunucusunu etkinleştirir.
  • -t linux: hedef platform. Desteklenen platformlar linux, nrfconnect ve esp32'dir. Kullanılabilir tüm komutları ve desteklenen hedef platformları görmek için ./chef.py -h komutunu çalıştırabilirsiniz. linux, sanal Matter cihazları için kullanılır.

Cihazı çalıştırma

Matter, 5540 numaralı TCP/UDP bağlantı noktasını kullanır. Bu nedenle, bilgisayarınızda çalışan bir güvenlik duvarınız varsa güvenlik duvarını kapatın veya 5540 numaralı bağlantı noktasında gelen TCP/UDP bağlantılarına izin verin.

Sanal cihazı kapsayıcıda şu komutla çalıştırın:

$ ./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]

Cihazınızın çalışmaya devam etmesini sağlayın. Şimdi cihazınızı Google Home'a ekleyebilmek için Google Home uygulamasına geçelim.

Cihazı durdurma

Cihazı durdurmanız gerekirse CTRL+C tuşlarına basarak programdan çıkabilirsiniz. Uygulama çıkmazsa CTRL+\ tuşlarını da kullanmanız gerekebilir.

Sanal cihazınızın kimlik bilgileri, /tmp/ dizininde chip önekiyle başlayan dosyalarda saklanır.

Tüm devreye alma sürecini baştan tekrarlamak istiyorsanız aşağıdaki komutu çalıştırarak bu dosyaları silmeniz gerekir:

$ rm /tmp/chip*

5. Cihazı devreye alma

Not: Bu adım yalnızca projenizi Google Home Developer Console'da daha önce ayarladıysanız başarılı olur.

Nest Hub

Cihazınızı Matter ağında kullanıma almak için hub gereklidir. Bu, Matter'ı destekleyen ve hem Thread özellikli cihazlar için sınır yönlendirici hem de akıllı ev amaçlarını yönlendirmek için yerel bir karşılama yolu olarak hizmet verecek bir Google Nest cihazıdır (ör. Nest Hub [2. nesil]).

Hangi hub'ların Matter'ı desteklediğini görmek için bu listeye bakın.

Devreye alma işlemine başlamadan önce şunlardan emin olun:

  • Merkeziniz, Google Home Console'da oturum açmak için kullandığınız Google Hesabı ile eşlenmiş olmalıdır.
  • Hub'ınız, sanal Matter cihazınızı çalıştırmak için kullandığınız bilgisayarla aynı kablosuz ağda olmalıdır.
  • Hub'ınız, Google Home uygulamanızda kullandığınız yapı ile aynı olmalıdır (Google Home Grafiği'ndeki "ev" yapınızı temsil eder).

QR kodu alma

Hazır hale getirme işlemi için QR kodu aracılığıyla sağlanan Matter onboarding bilgilerine ihtiyaç vardır. Matter uygulamasının konsol çıkışını inceleyin. Bu çıkışta, devreye alma işlemiyle ilgili QR kodunun bağlantısı yer alır.

Komisyon işlemini gerçekleştirme

  1. Google Home uygulamasını açın.
  2. Sol üst köşedeki + simgesine dokunun.
  3. Cihazı kur'a dokunun.
  4. Yeni cihaz'a dokunun.
  5. Evinizi seçip Sonraki'ye dokunun.
  6. Google Home uygulaması cihazınızı tarar. "Matter cihazı bulundu..." mesajı gösterilirse "Evet"e dokunun. Aksi takdirde, Farklı bir cihaz kur'a dokunun ve cihaz listesinden Matter cihaz'ı seçin.
  7. Kameranızı cihazınızın QR koduna veya web sitesi tarafından oluşturulan QR koduna doğru tutun.
  8. Google Home uygulamasındaki akışta belirtildiği şekilde eşleme işlemine devam edin.

Bu adımları tamamladığınızda Matter sanal cihazı başarıyla devreye alınır ve Google Home uygulamanızda yeni bir simge olarak görünür.

Google Home uygulamasında eşlenmiş ampul

Sorun giderme

Hazır hale getirme işlemi "Bağlantı sorunu" veya "Google ile iletişim kurulamadı" hata mesajlarıyla başarısız oluyor

  • Google Home Console'da doğru VID/PID kombinasyonuna sahip bir proje oluşturduğunuzdan ve aynı VID/PID kombinasyonunu kullanan başka projelerinizin olmadığından emin olun.

"Cihazınız taranıyor" mesajı uzun süre gösterildikten sonra hazırlama işlemi başarısız oluyor

6. Cihazı kontrol etme

Matter özellikli cihazınız başarıyla devreye alındıktan ve Google Home uygulamasında ampul olarak göründükten sonra cihazın kontrolünü farklı yöntemlerle test edebilirsiniz:

  • Google Asistan'ı kullanma
  • Google Home uygulamasını kullanma

Google Asistan

"Ok Google, ışıklarımı aç/kapat" gibi sesli komutlar vererek cihaz durumunu değiştirmek için telefonunuzda veya hub'ınızda Google Asistan'ı kullanın.

Komutlarla ilgili daha fazla örnek için Google Home uygulamasına eklenen akıllı ev cihazlarını kontrol etme başlıklı makalenin Akıllı ev cihazlarını sesli komutlarla kontrol etme bölümüne bakın.

Google Home uygulaması

Google Home uygulamasında gösterilen ampul simgesinin yanındaki Açık ve Kapalı etiketlerine dokunabilirsiniz.

Daha fazla bilgi için Google Home uygulamasına eklenen akıllı ev cihazlarını kontrol etme başlıklı makalenin Cihazları Google Home uygulamasıyla kontrol etme bölümüne bakın.

7. Tebrikler!

İlk Matter cihazınızı başarıyla oluşturdunuz. Mükemmel!

Bu codelab'de şunları öğrendiniz:

  • Matter geliştirme ortamı yükleyin.
  • Matter sanal cihazı oluşturup çalıştırma
  • Google Home'dan sanal cihazınızı devreye alın ve kontrol edin.

Matter hakkında daha fazla bilgi edinmek için şu referansları inceleyin: