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

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.
  • גית.
  • ידע בסיסי ב-Linux.
    • שימו לב שהמעטפת של כל הפקודות ב-Codelab הזה היא BASH.

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

בדיקת החומרה

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

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

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

  1. מתקינים את Docker Engine (לא משתמשים ב-Docker Desktop).
  2. משכפלים את ה-SDK של Matter. שימו לב שאתם שומרים את ערך ההתחייבות שבו אנחנו משתמשים בקטעים הבאים.
    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
    אם משתמשים באותה שמירה, אמורה להופיע ghcr.io/project-chip/chip-build:66קודם כל יציאות מסוג xhost כדי שנוכל להשתמש באפליקציות בממשק המשתמש מאוחר יותר:
    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 לקבל חיבורים מהמארח המקומי ביציאה 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

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

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

באופן כללי, צריך להשתמש בטעינות של קישורי חיבור על ידי הרצת הקונטיינר עם הארגומנט הנוסף --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 שעבר אישור של Connectivity Standards Alliance (Alliance) פועל בסביבה העסקית של Google Home. בסביבה העסקית של Google Home אפשר להזמין מכשירים שנמצאים בפיתוח שלא אושרו בתנאים מסוימים. מידע נוסף זמין במאמר בנושא הגבלות התאמה.

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

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

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

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

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

שף הוא שניהם:

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

עוברים לתיקייה לדוגמה של Chef ויוצרים את גרסת ה-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. הזמנת המכשיר

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

Nest Hub

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

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

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

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

קבלת קוד QR

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

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

  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.

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

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

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

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

Google Assistant

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

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

אפליקציית Google Home

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

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

7. מעולה!

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

ב-Codelab הזה למדנו איך:

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

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

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