建構 Matter 虛擬裝置

1. 簡介

Matter 是一種連線通訊協定，可為智慧型裝置的開發帶來絕佳機會。在本程式碼研究室中，您將使用 Matter SDK 中的資源建構第一個 Matter 裝置。

如要進一步瞭解 Matter，請造訪 Google Home 開發人員中心或連線標準聯盟網站。

課程內容

  • 如何設定 Matter 建構環境
  • 如何建構在電腦上運作的虛擬 Matter 裝置
  • 如何透過 Google Home 調控及控制虛擬 Matter 裝置

軟硬體需求

  • 中樞，包括所有支援 Matter 的 Google Nest 裝置，例如 Nest Hub (第 2 代)。
  • 執行 X11 窗型系統的 Linux 電腦。
  • Docker。
  • Git。
  • 具備 Linux 的基本知識。
    • 請注意，本程式碼研究室中所有指令的假設殼層為 BASH。

2. 設定環境

檢查硬體

這項 Docker 安裝作業不支援 Windows 和 macOS 電腦。你可以在 macOS 上手動安裝及建構 Matter。

這些指示假設 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. 使用 SDK 的公開 CI 映像檔執行建構容器，並從這個容器中執行新建立的虛擬裝置。找出要使用的 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 通訊埠，以便之後使用 UI 應用程式：
    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 Registry 中提取。
  • --ipc=host 允許 Docker 與主體共用處理序間通訊命名空間。
  • --net=host 允許 Docker 在容器內使用主機的網路堆疊，這樣才能將主機的 mDNS 流量傳遞至容器，並共用主機 X11 的顯示畫面。
  • -e DISPLAY 會將 $DISPLAY 匯出至主機，以便存取系統圖形介面。編輯 Matter 叢集時，這是執行 ZAP 工具的必要條件。
  • -it 會透過互動式終端機 (Tty) 執行 Docker，而非做為背景程序。
  • --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

Matter SDK 現已初始化。如要在日後快速重新初始化環境，請執行以下指令：

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。

$ 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 的整合作業。

凡是通過 Connectivity Standards Alliance (聯盟) Matter 認證的 Matter 裝置，都能在 Google Home 生態系統中運作。在特定情況下，如果是開發中的裝置未經認證，便可在 Google Home 生態系統中調用裝置。詳情請參閱「配對限制」。

建立開發人員專案

請先前往 Google Home 開發人員控制台：

  1. 按一下 [Create Project]。
  2. 輸入不重複的專案名稱，然後按一下「建立專案」。 建立新專案對話方塊
  3. 按一下「+ 新增整合」，即可前往「Matter 資源」畫面，您可以查看 Matter 開發說明文件，並查看部分工具。
  4. 準備好進行後續步驟時，請點選「下一步：開發」，開啟 Matter 檢查清單頁面。
  5. 點選「下一步：設定」
  6. 在「設定」頁面中輸入您的 產品名稱。
  7. 按一下「選取裝置類型」，然後從下拉式選單中選取裝置類型 (在本例中為 Light)。
  8. 在供應商 ID (VID) 中，選取「Test VID」，然後在「Test VID」下拉式選單中選取「0xFFF1」。在 Product ID (PID) 中輸入 0x8000，然後按一下「Save &」(儲存並)繼續，然後在下一頁中按一下 [儲存]儲存。請使用這些確切的 VID/PID 值，在後續的程式碼研究室步驟中，必須使用這些值。
    設定專案
  9. 你現在會在「Matter 整合」下方看到整合作業。
  10. 請重新啟動中樞，確保裝置能接收最新的 Matter 整合專案設定。如果之後要變更 VID 或 PID，您需在儲存專案後重新啟動，變更才會生效。如需重新啟動的逐步操作說明，請參閱「重新啟動 Google Nest 或 Google Wifi 裝置」。

4. 打造裝置

您可以在 GitHub 存放區的 examples 資料夾中找到 Matter 的所有範例。我們提供幾個範例，但本程式碼研究室的重點在於 Chef。

Chef 的同時是：

  • 此範例應用程式提供終端機介面，也能使用 examples/shell 應用程式提供的包裝功能。
  • 運用「沿用常規設定」原則的指令碼，封裝支援 Matter 的裝置所需的幾項常見工作。

前往 Chef 範例資料夾，並建立第一個 Matter 版本：

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

執行 chef.py -h 即可檢視 Chef 提供的幾種選項。可用選項如下：

  • -d：定義要使用的裝置類型。在本例中，我們製作的照明應用程式具備開啟/關閉和水平控制項。
  • -z：叫用 ZAP 工具，產生實作裝置類型的來源檔案。換句話說，ZAP 會根據您選定的光線，自動建立程式碼，將程式碼併入定義亮光 (「資料模型」) 以及與其他裝置互動的方式 (「互動模型」) 的版本。
  • -b：版本。
  • -r：[選用] 在虛擬 Matter 裝置上啟用遠端程序呼叫 (RPC) 伺服器，讓其他元件 (例如 GUI) 與裝置通訊，以便設定及擷取資料模型屬性。
  • -t linux：目標平台。支援平台包括 linux、nrfconnect 和 esp32。您可以執行 ./chef.py -h 查看所有可用的指令和支援的目標平台。linux 可用於虛擬 Matter 裝置。

執行裝置

Matter 使用 TCP/UDP 通訊埠 5540，因此如果您的電腦執行防火牆，請將其關閉，或允許通訊埠 5540 傳入 TCP/UDP 連線。

使用以下指令在容器中執行虛擬裝置：

$ ./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 織布上強制使用裝置。這是指支援 Matter 的 Google Nest 裝置 (例如 Nest Hub (第 2 代))。這類裝置會做為支援 Matter 的邊界路由器，也會做為轉送智慧型住宅意圖的本機執行要求路徑。

請參閱這份清單，瞭解哪些中樞支援 Matter。

開始調試程序前，請確認下列事項：

  • 你的 Hub 已經與你透過 Google Home 控制台登入的 Google 帳戶配對。
  • 中樞裝置已連上你用來執行虛擬 Matter 裝置的電腦相同的 Wi-Fi 網路。
  • 中樞裝置與你在 Google Home 應用程式中使用的結構相同。(Google Home 圖譜中的「房屋」代表您的結構)。

取得 QR code

這項程序需要透過 QR code 提供 Matter 新手上路資訊。檢查 Matter 應用程式的主控台輸出內容，其中包含執行啟動相關 QR code 的連結。

執行佣金作業

  1. 開啟 Google Home 應用程式。
  2. 輕觸左上角的「+」圖示。
  3. 輕觸 [設定裝置]。
  4. 輕觸「新裝置」。
  5. 選取住家，然後輕觸「下一步」。
  6. Google Home 應用程式會掃描你的裝置。如果出現「找到 Matter 裝置...」的訊息，請輕觸「是」。否則，請輕觸「設定其他裝置」，然後從裝置清單中選取「Matter 裝置」。
  7. 將相機鏡頭對準裝置的 QR code，或是網站產生的 QR code。
  8. 按照 Google Home 應用程式流程的說明繼續進行配對程序。

完成上述步驟後，Matter 虛擬裝置應該就能順利調用，並在 Google Home 應用程式中顯示為新圖示。

Google Home 應用程式中的配對燈泡

疑難排解

調試失敗，並顯示「連線能力問題」或「無法與 Google 聯絡」錯誤訊息

  • 確認已在 Google Home 控制台中使用正確的 VID/PID 組合 建立專案，而且你也沒有其他專案使用相同的 VID/PID 組合。

無法在「掃描裝置」後執行佣金很長一段時間

6. 控制裝置

成功啟用支援 Matter 的裝置，並在 Google Home 應用程式中顯示為燈泡後，你可以透過下列方式測試裝置的控制方式：

  • 使用 Google 助理。
  • 使用 Google Home 應用程式。

Google 助理

使用手機或 Nest Hub 上的 Google 助理，透過語音指令切換裝置狀態，例如說出「Ok Google，切換燈具」。

如需更多指令範例，請參閱「使用語音指令控制已新增至 Google Home 應用程式的智慧住宅裝置」一文中的「使用語音指令控制智慧住宅裝置」一節。

Google Home 應用程式

你可以在 Google Home 應用程式顯示的燈泡圖示旁邊，輕觸「開啟」和「關閉」標籤。

詳情請參閱「使用 Google Home 應用程式控制已新增至 Google Home 應用程式的智慧住宅裝置」一文中的「使用 Google Home 應用程式控制裝置」一節。

7. 恭喜！

您已成功建立第一個 Matter 裝置。太棒了！

在本程式碼研究室中，您瞭解如何：

  • 安裝 Matter 開發環境。
  • 建構及執行 Matter 虛擬裝置。
  • 透過 Google Home 控制及控制虛擬裝置。

如要進一步瞭解 Matter，請參閱下列參考資料：