איך יוצרים מכשיר וירטואלי בתקן Matter

1. מבוא

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

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

מה תלמדו

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

הדרישות

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

4. יצירת מכשיר

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

‫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

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

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

7. מעולה!

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

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

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

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