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

1. מבוא

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

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

מה תלמדו

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

מה הדרישות כדי להצטרף לתוכנית?

2. הגדרת הסביבה שלך

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

בודקים את החומרה

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

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

הגדרת Docker

  1. מתקינים את Docker Engine (בלי להשתמש ב-Docker Desktop).
  2. מוציאים את התמונה של Docker מ-Docker Hub. בחלון טרמינל, מריצים את הפקודה:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    
    השלמת הפעולה עשויה להימשך כמה דקות.
  3. מפעילים את הקונטיינר של Docker:
    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
    

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

Environment looks good, you are ready to go!
$

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

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

אפשר להפעיל מכונה נוספת של סשן טרמינל:

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

כשהמסוף שלך ייפתח, הוא כבר יופיע במאגר המשוכפל של Matter בכתובת ~/connectedhomeip. אין צורך בפעולות נוספות להגדרה של Matter.

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

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

מריצים את המאגר עם הארגומנט הנוסף --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

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

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

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

כדי להתחיל, נכנסים אל Google Home Developer Console:

  1. לוחצים על Create Project.
  2. נותנים שם לפרויקט ייחודי ולוחצים על Create Project. תיבת דו-שיח ליצירת פרויקט חדש
  3. לוחצים על + Add integration (הוספת שילוב) כדי לעבור למסך Matter resources (מקורות מידע של Matter), שבו אפשר לעיין במסמכי התיעוד בנושא פיתוח בתקן Matter ולקרוא על כלים מסוימים.
  4. כשמוכנים להמשיך, לוחצים על הבא: פיתוח. בדף הזה מוצג הדף רשימת המשימות של החומר.
  5. לוחצים על הבא: הגדרה
  6. בדף הגדרה, מזינים את שם המוצר.
  7. לוחצים על בחירת סוג מכשיר ובוחרים את סוג המכשיר מהתפריט הנפתח (במקרה הזה, Light).
  8. בקטע 'מזהה ספק' (VID), בוחרים באפשרות בדיקת VID, ובוחרים באפשרות 0xFFF1 בתפריט הנפתח של בדיקת VID. בקטע 'מזהה מוצר' (PID), מזינים 0x8, 000 ולוחצים על שמירה והמשך. לאחר מכן לוחצים על שמירה בדף הבא. משתמשים בערכי ה-VID/PID המדויקים האלה. השלבים מאוחרים יותר ב-Codelab תלויים בהם.
    הגדרת פרויקט
  9. השילוב יופיע עכשיו בקטע Matter integration (שילובים של Matter).
  10. צריך להפעיל מחדש את המרכז כדי לוודא שמתקבלת ההגדרה האחרונה של פרויקט השילוב בתקן Matter. אם יש צורך לשנות את ה-VID או ה-PID בשלב מאוחר יותר, יש להפעיל מחדש גם לאחר שמירת הפרויקט כדי שהשינוי ייכנס לתוקף. במאמר הפעלה מחדש של מכשירי Google Nest או Google Wifi ניתן למצוא הוראות מפורטות להפעלה מחדש.

4. פיתוח מכשיר

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

שף הוא:

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

עוברים לתיקייה לדוגמה 'שף' ויוצרים את גרסת ה-build הראשונה בתקן Matter:

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

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

  • -d: מגדיר את סוג המכשיר שבו ייעשה שימוש. במקרה הזה, אנחנו יוצרים אפליקציית תאורה עם פקדים להפעלה/כיבוי ולשליטה.
  • -z: מפעיל את הכלי ZAP כדי ליצור את קובצי המקור שמטמיעים את סוג המכשיר. כלומר, על סמך בחירת התאורה שלכם, מערכת ZAP תיצור באופן אוטומטי קוד שישולב ב-build שמגדיר את האור (מודל הנתונים) ואת האינטראקציה שלו עם מכשירים אחרים (מודל האינטראקציה).
  • -b: גרסאות build.
  • -r: [אופציונלי] מפעיל את שרת ה-RPC במכשיר הווירטואלי בתקן Matter כדי שרכיבים אחרים (כמו GUI) יוכלו לתקשר עם המכשיר כדי להגדיר ולאחזר מאפיינים של מודל נתונים.
  • -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. בקר המכשיר הווירטואלי

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

בקר המכשיר הווירטואלי

בקר המכשיר הווירטואלי מספק ייצוג חזותי של המכשיר הווירטואלי.

ניתן לקיים אינטראקציה עם המכשיר הווירטואלי באמצעות ממשק המשתמש הגרפי של פקד המכשיר הווירטואלי (GUI). השינויים שתבצעו בחשבונית ה-GUI משפיעים על מודל הנתונים הבסיסי. הרשימה המלאה של סוגי המכשירים הווירטואליים הנתמכים בתקן Matter זמינה בדף מכשירים נתמכים.

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

בקר המכשיר הווירטואלי מותקן מראש בקונטיינר Ubuntu LTS 20.04 Docker.

הפעלת בקר המכשיר הווירטואלי

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

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

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

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

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

ממשק משתמש לגרפיקה של מכשיר וירטואלי

האפליקציה שולחת בקשות לשרת ה-RPC של המכשיר בזמן שמבצעים שינויים באפליקציית Virtual Controller, ומבצעת סקר של שרת ה-RPC פעם בשנייה כדי לאחזר את המצב.

אפשר להשתמש באפליקציה Virtual Device Controller גם כדי לאחזר את קוד ה-QR כחלק מתהליך הזמנת המכשיר. לוחצים על סמל קוד ה-QR שלצד תמונת המכשיר כדי להציג את קוד ה-QR של המכשיר הזה. אפשר להשתמש בקוד ה-QR הזה כדי להזמין את המכשיר.

6. עמלה של המכשיר

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

Nest Hub

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

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

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

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

קבלת קוד QR

לתהליך ההזמנה יש לספק את פרטי ההצטרפות של Matter באמצעות קוד QR. אתם יכולים לקבל את קוד ה-QR של המכשיר הווירטואלי מ-Virtual Device Controller.

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

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

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

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

פתרון בעיות

ההזמנה נכשלת ומוצגת הודעות שגיאה מסוג 'בעיית קישוריות' או 'לא ניתן ליצור קשר עם Google'

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

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

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

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

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

Google Assistant

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

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

אפליקציית Google Home

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

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

ממשק GUI של מכשיר וירטואלי

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

8. כל הכבוד!

יצרת בהצלחה את המכשיר הראשון בתקן Matter. נפלא!

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

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

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

  • Matter Primer במרכז למפתחים של Google Home, שבו אפשר ללמוד את העקרונות הבסיסיים של Matter.
  • מפרט Matter, ספריית מכשירים בתקן Matter וספריית אשכול האפליקציות בתקן Matter, פורסם על ידי Connectivity Standards Alliance.
  • מאגר ה-Matter GitHub