בניית מכשיר וירטואלי

1. מבוא

‫Matter הוא פרוטוקול קישוריות שמציע הזדמנויות מעניינות לפיתוח מכשירים חכמים. ב-codelab הזה תבנו את מכשיר Matter הראשון שלכם באמצעות משאבים מ-Matter SDK.

מידע נוסף על Matter זמין במרכז הפיתוח של Google Home או באתר של Connectivity Standards Alliance.

מה תלמדו

  • איך מגדירים סביבת build של תקן Matter
  • איך יוצרים מכשיר וירטואלי של Matter שפועל במחשב
  • איך מפעילים את המכשיר הווירטואלי בתקן Matter ושולטים בו באמצעות Google Home

הדרישות

  • רכזת, שהיא כל מכשיר Google Nest שתומך ב-Matter, כמו Nest Hub (דור שני).
  • מחשב Linux שמופעלת בו מערכת החלונות X11.
  • Docker.
  • ‫Git.
  • ידע בסיסי ב-Linux.
    • הערה: מעטפת הפקודות שמוצגת ב-codelab הזה היא BASH.

2. הגדרת הסביבה

בדיקת החומרה

התקנת Docker הזו לא תומכת במחשבים עם Windows ו-macOS. אפשר להתקין ולבנות את Matter באופן ידני ב-macOS.

בנוסף, ההנחיות האלה מניחות שבמחשב Linux שלכם פועלת מערכת החלונות X11. אם מכונת Linux שלכם מריצה Wayland, צריך לוודא שגם X.Org מותקן.

הגדרת סביבת פיתוח

  1. מתקינים את Docker Engine (לא משתמשים ב-Docker Desktop).
  2. משכפלים את Matter SDK ורושמים את הקומיט שבו משתמשים בהמשך.
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. מריצים קונטיינר של build באמצעות תמונות CI ציבוריות של ה-SDK, ומריצים את המכשיר הווירטואלי החדש שנבנה מתוך הקונטיינר הזה. מאתרים את התמונה שרוצים להשתמש בה בהתאם לגרסת ה-SDK שלכם, כך:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    אם משתמשים באותה פעולת commit, אמורה להופיע ההודעה ghcr.io/project-chip/chip-build:66First, forward xhost ports so we can later use UI applications:
    xhost local:1000
    לאחר מכן, מפעילים את מאגר התגים עם משאבים מתאימים שהועברו מהמארח (התשלום ב-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

כדאי להבין את פקודת Docker ואת האפשרויות שהעברנו אליה:

  • ‫xhost local:1000 מאפשרת ל-X Window System לקבל חיבורים מהמארח המקומי ביציאה 1000, וכך מאפשרת שימוש בממשק משתמש גרפי.
  • ‫docker run … image מריץ את התמונה שצוינה, ומושך אותה ממאגר Docker אם צריך.
  • ‫--ipc=host מאפשר ל-Docker לשתף את מרחב השמות של תקשורת בין תהליכים עם המחשב המארח.
  • ‫--net=host מאפשר ל-Docker להשתמש במערך פרוטוקולי הרשת של המארח בתוך הקונטיינר. זה נדרש כדי להעביר תנועת mDNS מהמארח לקונטיינר ולשתף את התצוגה X11 של המארח.
  • ‫-e DISPLAY מייצא את $DISPLAY למארח, וכך מספק גישה לממשק הגרפי של המערכת. הדרישה הזו נדרשת כדי להריץ את כלי ZAP כשעורכים קלאסטרים של Matter.
  • ‫-it מריץ את Docker עם מסוף אינטראקטיבי (tty), במקום כתהליך ברקע.
  • ‫--mount מעלה את ה-SDK שבדקנו קודם למאגר.
  • ‫--workdir מגדיר את ספריית העבודה בהפעלה לספריית ה-SDK המותקנת שלנו.

אפשר להריץ גם מופע שני של סשן טרמינל:

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

עצירה והפעלה של קונטיינר Matter Docker

בכל פעם שמריצים פקודת docker run, נוצר קונטיינר חדש עם התמונה שצוינה. כשעושים את זה, הנתונים הישנים שנשמרו במופע קודם של מאגר תגים יאבדו. לפעמים זה מה שרוצים שיקרה, כי זה מאפשר להתחיל עם התקנה חדשה. אבל לפעמים כדאי לשמור את העבודה ואת הגדרות הסביבה בין הפעלות.

לכן, אחרי שיוצרים את הקונטיינר, אפשר להפסיק אותו כדי למנוע אובדן של העבודה.

user@host> docker stop matter-container

כשמוכנים להפעיל שוב, מפעילים את הקונטיינר ופותחים חלון טרמינל:

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

אפשר לפתוח סשנים נוספים של טרמינל למאגר התגים באמצעות הפקודה:

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

אפשר גם להתחיל סשן בסיסי באמצעות:

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

הגדרה ראשונית של Matter

אתחול ה-SDK

מאתחלים את Matter SDK. הפעולה הזו תימשך כמה דקות.

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

ערכת ה-SDK של Matter מאותחלת עכשיו. כדי לאתחל מחדש את הסביבה במהירות בעתיד, מריצים את הפקודה:

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

שיתוף קבצים בין המארח לבין הקונטיינר

קודם לכן, ניגשנו לקבצים במחשב המארח מתוך הקונטיינר באמצעות bind mount. אפשר גם לכתוב קבצים בספרייה המצורפת מתוך הקונטיינר כדי לגשת אליהם מהמארח.

באופן כללי, כדי להשתמש ב-bind mounts, מריצים את הקונטיינר עם הארגומנט הנוסף --mount source=$(pwd),target=/workspace,type=bind כדי לטעון את ספריית העבודה הנוכחית לקונטיינר בנתיב /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

צריך לנהל את ההרשאות של המשתמש במאגר התגים בספרייה המצורפת במארח.

מקבלים את מזהה הקבוצה של משתמש הקונטיינר מתוך הקונטיינר.

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

פותחים עוד סשן של מסוף במארח של הקונטיינר ומגדירים את ספריית העבודה לספרייה שהקונטיינר טוען.

הגדרה רקורסיבית של הקבוצה לקבצים בספרייה המצורפת לקבוצה של משתמש הקונטיינר.

user@host> sudo chgrp -R 1000 .

נותנים לקבוצה את ההרשאות הרצויות בספרייה. בדוגמה הזו, הקבוצה של משתמש הקונטיינר מקבלת הרשאות קריאה, כתיבה והרצה בכל הקבצים בספרייה המצורפת.

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

שימו לב שהפקודות האלה לא משפיעות על ההרשאות של קבצים חדשים שנוצרו על ידי המשתמש המארח. חשוב לזכור לעדכן את ההרשאות של קבצים חדשים שנוצרו במארח לפי הצורך.

אפשר להוסיף את המשתמש המארח לקבוצת המשתמשים של הקונטיינר כדי לרשת הרשאות בקבצים שנוצרו על ידי משתמש הקונטיינר.

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

3. Google Home Developer Console

Google Home Developer Console היא אפליקציית האינטרנט שבה מנהלים את השילובים של Matter עם Google Home.

כל מכשיר Matter שעבר את אישור Matter של Connectivity Standards Alliance (הארגון) פועל במערכת האקולוגית של Google Home. אפשר להוסיף מכשירים שנמצאים בפיתוח ולא עברו אישור למערכת האקולוגית של Google Home בתנאים מסוימים. מידע נוסף זמין במאמר בנושא הגבלות על צימוד מכשירים.

יצירת פרויקט למפתחים

כדי להתחיל, עוברים אל Google Home Developer Console:

  1. לוחצים על יצירת פרויקט.
  2. מזינים שם ייחודי לפרויקט ולוחצים על יצירת פרויקט. תיבת דו-שיח ליצירת פרויקט חדש
  3. לוחצים על + הוספת שילוב כדי לעבור למסך משאבי תקן Matter, שבו אפשר לראות את מאמרי העזרה למפתחים של תקן Matter ולקרוא על כמה כלים.
  4. כשמוכנים להמשיך, לוחצים על הבא: פיתוח כדי להציג את הדף רשימת המשימות בנושא.
  5. לוחצים על הבא: הגדרה.
  6. בדף הגדרה, מזינים את שם המוצר.
  7. לוחצים על בחירת סוג מכשיר ובוחרים את סוג המכשיר מהתפריט הנפתח (במקרה הזה, Light).
  8. בקטע Vendor ID (מזהה ספק, VID), בוחרים באפשרות Test VID ואז בוחרים באפשרות 0xFFF1 מהתפריט הנפתח Test VID. בשדה Product ID (מזהה מוצר, PID), מזינים 0x8000 ולוחצים על Save & continue (שמירה והמשך), ואז לוחצים על Save (שמירה) בדף הבא. משתמשים בערכי ה-VID/PID המדויקים האלה, כי השלבים הבאים ב-codelab תלויים בהם.
    הגדרת פרויקט
  9. עכשיו האינטגרציה תופיע בקטע Matter integrations.
  10. מפעילים מחדש את המרכז כדי לוודא שהוא מקבל את ההגדרה העדכנית ביותר של פרויקט השילוב של Matter. אם תצטרכו לשנות את ה-VID או ה-PID בהמשך, תצטרכו גם להפעיל מחדש את המחשב אחרי שתשמרו את הפרויקט כדי שהשינוי ייכנס לתוקף. הוראות מפורטות להפעלה מחדש מופיעות במאמר הפעלה מחדש של מכשירי Google Nest או Google Wifi.

4. איך בונים מכשיר

כל הדוגמאות ב-Matter נמצאות בתיקייה examples במאגר GitHub. יש כמה דוגמאות זמינות, אבל במעבדת התכנות הזו נתמקד ב-Chef.

‫Chef הוא גם:

  • אפליקציה לדוגמה שמספקת ממשק מסוף, עם תכונות שקיימות גם באפליקציית examples/shell.
  • סקריפט שמיישם את העיקרון של הסכמה עדיפה על הגדרה, כדי לתמצת כמה מהמשימות הנפוצות שנדרשות לפיתוח מכשיר תואם לתקן Matter.

עוברים לתיקיית הדוגמה של Chef ויוצרים את הגרסה הראשונה של Matter:

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

ל-Chef יש כמה אפשרויות שאפשר לראות על ידי הפעלת chef.py -h. האפשרויות שבהן אנחנו משתמשים כאן הן:

  • ‫-d: מגדיר את סוג המכשיר שבו יש להשתמש. בדוגמה הזו, אנחנו יוצרים אפליקציה לשליטה בתאורה עם אפשרויות הפעלה/השבתה ושליטה ברמה.
  • ‫-z: מפעיל את כלי ZAP כדי ליצור את קובצי המקור שמיישמים את סוג המכשיר. כלומר, על סמך בחירת התאורה, ZAP ייצור באופן אוטומטי קוד שישולב ב-build, שיגדיר את התאורה (מודל הנתונים) ואת האינטראקציה שלה עם מכשירים אחרים (מודל האינטראקציה).
  • ‫-b: builds.
  • ‫-r: [אופציונלי] מפעיל את שרת ה-RPC במכשיר הווירטואלי של Matter, כדי שרכיבים אחרים (כמו ממשק המשתמש הגרפי) יוכלו לתקשר עם המכשיר כדי להגדיר ולאחזר מאפיינים של מודל הנתונים.
  • ‫-t linux: פלטפורמת היעד. הפלטפורמות הנתמכות הן linux, ‏ nrfconnect ו-esp32. אפשר להריץ את הפקודה ./chef.py -h כדי לראות את כל הפקודות הזמינות ואת פלטפורמות היעד הנתמכות. linux משמש למכשירי Matter וירטואליים.

הפעלת המכשיר

פרוטוקול Matter משתמש ביציאת TCP/UDP מספר 5540, לכן אם מופעלת חומת אש במחשב, צריך להשבית אותה או לאפשר חיבורי TCP/UDP נכנסים ביציאה 5540.

מריצים את המכשיר הווירטואלי במאגר התגים באמצעות הפקודה:

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

משאירים את המכשיר פועל. עכשיו נתמקד באפליקציית Google Home כדי להפעיל את המכשיר ב-Google Home.

הפסקת השימוש במכשיר

אם אתם צריכים להפסיק את המכשיר, אתם יכולים לצאת מהתוכנית באמצעות CTRL+C. אם האפליקציה לא נסגרת, יכול להיות שתצטרכו להשתמש גם ב-CTRL+\.

פרטי הכניסה למכשיר הווירטואלי מאוחסנים בספרייה /tmp/ בקבצים שמתחילים בקידומת chip.

אם רוצים לחזור על כל תהליך ההפעלה מההתחלה, צריך למחוק את הקבצים האלה באמצעות הפעלת הפקודה הבאה:

$ rm /tmp/chip*

5. חיבור המכשיר

הערה: השלב הזה יצליח רק אם כבר הגדרתם את הפרויקט ב-Google Home Developer Console.

Nest Hub

כדי להפעיל את המכשיר ברשת Matter, צריך רכזת. זהו מכשיר Google Nest, כמו Nest Hub (דור שני), שתומך ב-Matter וישמש גם כנתב גבולות למכשירים עם פרוטוקול Thread וגם כנתיב לביצוע מקומי של כוונות לבית חכם.

ברשימה הזו אפשר לראות אילו רכזות תומכות בתקן Matter.

לפני שמתחילים בתהליך ההפעלה, חשוב לוודא את הפרטים הבאים:

  • המרכז שלכם משויך לאותו חשבון Google שבו השתמשתם כדי להיכנס ל-Google Home Console.
  • ההאב מחובר לאותה רשת Wi-Fi שאליה מחובר המחשב שבו אתם מריצים את מכשיר Matter הווירטואלי.
  • המרכז נמצא באותו מבנה שבו אתם משתמשים באפליקציית Google Home. (ה'בית' בגרף Google Home מייצג את המבנה שלכם).

קבלת קוד QR

תהליך ההפעלה דורש פרטי הצטרפות בתקן Matter, שמופיעים בקוד QR. בודקים את פלט המסוף של אפליקציית Matter, שכולל קישור לקוד ה-QR שרלוונטי להפעלה.

ביצוע פעולת העמלה

  1. פותחים את אפליקציית Google Home.
  2. מקישים על + בפינה הימנית העליונה.
  3. מקישים על הגדרת המכשיר.
  4. מקישים על מכשיר חדש.
  5. בוחרים את הבית ומקישים על הבא.
  6. אפליקציית Google Home סורקת את המכשיר. אם מופיעה ההודעה 'נמצא מכשיר Matter...', מקישים על 'כן'. אם לא, מקישים על הגדרת מכשיר אחר ואז בוחרים באפשרות מכשיר Matter מתוך רשימת המכשירים.
  7. מכוונים את המצלמה אל קוד ה-QR של המכשיר או אל קוד ה-QR שנוצר באתר.
  8. ממשיכים בתהליך ההתאמה כמו שמופיע בתהליך העבודה באפליקציית Google Home.

אחרי שתשלימו את השלבים האלה, המכשיר הווירטואלי של Matter יופעל בהצלחה ויופיע כסמל חדש באפליקציית Google Home.

נורה משויכת באפליקציית Google Home

פתרון בעיות

הפעלת המכשיר נכשלת ומוצגות הודעות השגיאה "בעיית קישוריות" או "לא הייתה אפשרות ליצור קשר עם Google"

  • מוודאים שיצרתם פרויקט עם שילוב VID/PID נכון ב-Google Home Console, ואין לכם פרויקטים אחרים שמשתמשים באותו שילוב VID/PID.

ההפעלה נכשלת אחרי שהאפשרות 'סריקת המכשיר' מוצגת למשך זמן ארוך

6. שליטה במכשיר

אחרי שהפעלתם בהצלחה את המכשיר תואם לתקן Matter והוא מופיע באפליקציית Google Home כנורת חשמל, אתם יכולים לבדוק את השליטה במכשיר בשיטות שונות:

  • שימוש ב-Google Assistant.
  • באמצעות אפליקציית Google Home.

Google Assistant

אפשר להשתמש ב-Google Assistant בטלפון או במרכז הבקרה כדי לשנות את מצב המכשיר באמצעות פקודות קוליות, למשל "Ok Google, toggle my lights" (הפעלת האורות).

בקטע שליטה במכשירים לבית חכם באמצעות פקודות קוליות במאמר שליטה במכשירים לבית חכם שנוספו לאפליקציית Google Home יש עוד דוגמאות לפקודות.

אפליקציית Google Home

אפשר להקיש על התוויות פועל וכבוי לצד סמל הנורה שמופיע באפליקציית Google Home.

מידע נוסף זמין בקטע שליטה במכשירים באמצעות אפליקציית Google Home במאמר שליטה במכשירים לבית חכם שנוספו לאפליקציית Google Home.

7. מעולה!

יצרתם בהצלחה את מכשיר Matter הראשון שלכם. מדהים!

ב-codelab הזה למדתם איך:

  • מתקינים סביבת פיתוח של Matter.
  • פיתוח והפעלה של מכשיר וירטואלי בתקן Matter.
  • אפשר להפעיל את המכשיר הווירטואלי ולשלוט בו מ-Google Home.

מידע נוסף על Matter זמין במקורות המידע הבאים: