建構 Matter 虛擬裝置

1. 簡介

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

如要瞭解 Matter，請造訪 Google Home 開發人員中心或 Connectivity Standards Alliance 網站。

課程內容

  • 如何設定 Matter 建構環境
  • 如何建構可在電腦上執行的虛擬 Matter 裝置
  • 如何使用 Google Home 委派及控制虛擬 Matter 裝置

軟硬體需求

  • 中樞裝置，也就是支援 Matter 的 Google Nest 裝置，例如 Nest Hub (第 2 代)。
  • 執行 X11 視窗系統的 Linux 機器。
  • Docker。
  • Git。
  • 具備 Linux 基礎知識。
    • 請注意，本程式碼研究室中所有指令的預設 Shell 都是 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
    如果您使用相同的提交，應該會看到「First, forward xhost ports so we can later use UI applications:」(首先，轉送 xhost 連接埠，以便稍後使用 UI 應用程式)：ghcr.io/project-chip/chip-build:66
    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 匯出至主機，提供系統圖形介面的存取權。編輯 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 開發人員控制台是網頁應用程式，您可以在這裡管理與 Google Home 的 Matter 整合。

只要是通過連線標準聯盟 (聯盟) Matter 認證的裝置，都可以在 Google Home 生態系統中運作。在特定情況下，尚未通過認證的開發中裝置可委託 Google Home 生態系統，詳情請參閱「配對限制」。

建立開發人員專案

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

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

4. 建立裝置

Matter 中的所有範例都位於 Github 存放區的 examples 資料夾中。我們提供多個範例，但本程式碼研究室的重點是 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 開發人員控制台中設定專案，才能成功完成這個步驟。

Nest Hub

你必須使用中樞裝置，才能在 Matter Fabric 上佈建裝置。這是指支援 Matter 的 Google Nest 裝置，例如 Nest Hub (第 2 代)，可做為支援 Thread 裝置的邊界路由器，以及智慧住宅意圖的本機履行路徑。

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

開始委任程序前，請先確認下列事項：

  • 中樞裝置已與你用來登入 Google Home 控制台的 Google 帳戶配對。
  • 中樞裝置與用來執行虛擬 Matter 裝置的電腦連上同一個 Wi-Fi 網路。
  • 中樞裝置與 Google Home 應用程式使用的住家結構相同。(Google Home Graph 中的「住家」代表住家結構)。

取得 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 助理

在手機或中樞裝置上使用 Google 助理，透過語音指令切換裝置狀態，例如說出「Ok Google，切換燈光」。

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

Google Home 應用程式

輕觸 Google Home 應用程式中燈泡圖示旁的「開啟」和「關閉」標籤。

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

7. 恭喜！

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

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

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

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

  • Google Home 開發人員中心的「Matter 基礎知識」一文，瞭解 Matter 概念的基本知識。
  • 連線標準聯盟 (Connectivity Standards Alliance) 發布的 Matter 規格、Matter 裝置程式庫和 Matter 應用程式叢集程式庫。
  • Matter GitHub 存放區。