建構 Matter 虛擬裝置

1. 簡介

Matter 是一種連線通訊協定,可為智慧型裝置開發帶來許多回報。在本程式碼研究室中,您將使用在預先設定的 Docker 映像檔中提供的 SDK 和依附元件,建構第一個 Matter 裝置。

如要進一步瞭解 Matter,請前往 Google Home 開發人員中心Connectivity Standards Alliance 網站

課程內容

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

軟硬體需求

2. 設定環境

我們會在 Linux 主機電腦上使用先前設定的 Docker 容器。這個容器包含建構及執行 Matter 虛擬裝置的所有必要依附元件。

檢查硬體

這個 Docker 安裝項目目前不支援 Windows 和 MacOS 電腦。您可以在 MacOS 或 Windows 上手動安裝及建立 Matter

此外,以下操作說明適用於 Linux 機器執行 X11 視窗系統。如果您的 Linux 機器搭載 Wayland,請確認也已安裝 X.Org

設定 Docker

  1. 安裝 Docker Engine (請勿使用 Docker Desktop)。
  2. 從 Docker Hub 提取 Docker 映像檔。在終端機視窗中執行:
    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 匯出至主機,以便存取系統圖形介面。如要編輯 Matter 叢集,就必須執行 ZAP 工具
  • -it 會使用互動終端機 (tty) 執行 Docker,而非背景程序。

您也可以執行第二個終端機工作階段執行個體:

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 初始設定

開啟終端機後,該終端機便已位於 ~/connectedhomeip 的 Matter 複製存放區中。您不須採取其他 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。

$ 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 開發人員控制台這個網頁應用程式,可管理 Matter 與 Google Home 的整合作業。

凡是通過 Connectivity Standards Alliance (Alliance) Matter 認證的任何 Matter 裝置,都可以在 Google Home 生態系統中運作。如果裝置未經認證,可在特定情況下透過 Google Home 生態系統進行開發,詳情請參閱配對限制一文。

建立開發人員專案

首先,請前往 Google Home 開發人員控制台:

  1. 在「管理專案」頁面中,按一下「建立專案」
    Google Home 開發人員中心
  2. 在「開始使用」頁面中,按一下「建立專案」

  1. 輸入不重複的專案名稱,然後按一下「Create New Project」(建立新專案) 建立新專案對話方塊
  2. 按一下「+ 新增整合」,系統會將您帶往「案件資源」畫面,您可以在此查看 Matter 開發說明文件及瞭解部分工具。
  3. 準備就緒後,請點選「Next: Develop」(下一步:開發),系統會顯示「Matter checklist」頁面。
  4. 點選「下一步:設定」
  5. 在「設定」頁面上輸入產品名稱
  6. 按一下「選取裝置類型」,然後從下拉式選單中選取裝置類型 (本例中為 Light)。
  7. 在供應商 ID (VID) 中選取「Test VID」,然後在「Test VID」下拉式選單中選取「0xFFF1」。在產品 ID (PID) 中輸入 0x8000,然後按一下「儲存並繼續」,然後點選下一頁的「儲存」
    設定專案
  8. 現在你會在 Matter 整合項目下方看到一部 Matter 裝置。Matter 整合
  9. 重新啟動 Hub,確保能收到最新的 Matter 整合專案設定。如果日後需要變更 VID 或 PID,儲存專案後也需要重新啟動,變更才會生效。按照重新啟動 Google Nest 或 Google Wifi 裝置一文中的逐步重新啟動操作說明。

4. 建構裝置

所有 Matter 範例都位於 GitHub 存放區examples 資料夾中。我們提供多個範例,但本程式碼研究室著重於 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 會自動建立程式碼,以整合至建構的光源 (資料模型) 和其與其他裝置 (互動模型) 的互動方式。
  • -b:建構。
  • -r:[選用] 啟用虛擬 Matter 裝置的 RPC 伺服器,讓其他元件 (例如 GUI) 會與裝置通訊,以設定及擷取資料模型屬性。
  • -t linux:目標平台。支援平台為 linuxnrfconnectesp32。您可以執行 ./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 應用程式,方便你將裝置設為使用 Google Home。

停止裝置

您可以透過 CTRL+C 退出該程式。如果應用程式並未結束,您可能也需要使用 CTRL+\。

虛擬裝置的憑證會儲存在 /tmp/ 目錄,位於開頭為 chip 的檔案中。

如要從頭開始執行整個佣金程序,請執行下列指令,刪除這些檔案:

$ rm /tmp/chip*

5. 虛擬裝置控制器

虛擬裝置控制器是一種獨立應用程式,可提供圖形使用者介面來控管及顯示虛擬 Matter 裝置的狀態。其使用 RPC 用戶端與連接至開發環境的 Matter 裝置進行通訊。

虛擬裝置控制器

虛擬裝置控制器會以視覺化方式呈現虛擬裝置。

您可以透過虛擬裝置控制器使用者介面 (GUI) 與虛擬裝置互動。您在 GUI 中所做的變更會影響基準資料模型。虛擬裝置控制器目前支援可調光裝置類型。

安裝虛擬裝置控制器

虛擬裝置控制器已預先安裝在 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 的網路通訊端選項。控制器能夠與虛擬裝置連線後,畫面上會顯示裝置狀態的畫面:

虛擬裝置圖形使用者介面

當您在 Virtual Controller 應用程式中進行變更時,應用程式會將要求傳送至裝置的 RPC 伺服器,並每秒輪詢 RPC 伺服器一次以擷取狀態。

虛擬裝置控制器應用程式也可以用來在裝置佣金流程中擷取 QR 圖碼。按一下裝置圖片旁的 QR 圖碼,即可顯示這部裝置的 QR 圖碼:

QR code

你可以使用這個 QR 圖碼委託裝置。

6. 替換裝置

注意:你必須在 Google Home 開發人員控制台中設定專案,這個步驟才會成功。

Nest Hub

裝置需要支援 Matter 布料,才能使用裝置殼。這些 Google Nest 裝置 (例如 Nest Hub (第 2 代)) 支援 Matter,也是做為支援 Thread 裝置邊界的邊界路由器,也是轉送智慧住宅意圖的本機執行要求路徑。

如要查看支援 Matter 的中樞裝置,請參閱這份清單

開始執行佣金程序前,請確認下列事項:

  • 你的中樞裝置會與用於登入 Google Home 控制台的 Google 帳戶配對。
  • 中樞裝置會與您執行虛擬 Matter 電腦所用的 Wi-Fi 網路相同。
  • 中樞裝置採用與 Google Home 應用程式相同的結構 (Google Home 圖表中的「房屋」)。

取得 QR 圖碼

佣金程序需要透過 QR code 提供 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」錯誤訊息

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

「掃描裝置」頁面長時間執行失敗

7. 控制裝置

如果支援 Matter 的裝置成功充電,並在 Google Home 應用程式中顯示為燈泡,則可透過其他方式測試裝置控制功能:

  • 使用 Google 助理。
  • 使用 Google Home 應用程式。
  • 使用虛擬裝置 GUI。

Google 助理

使用手機或集線器使用 Google 助理,即可直接透過語音指令切換裝置狀態,例如說出「Ok Google,切換燈具」。

如要瞭解其他指令,請參閱使用 Google Home 應用程式控制智慧住宅裝置的「使用語音指令控制智慧住宅裝置」一節。

Google Home 應用程式

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

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

虛擬裝置 GUI

您可以與虛擬裝置 GUI 互動,以變更裝置狀態。無論是透過虛擬裝置控制器、手機上的 Google Home 應用程式或使用中樞裝置控制虛擬裝置,所有介面都會反映虛擬裝置目前的狀態。

8. 恭喜!

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

在本程式碼研究室中,您瞭解如何:

  • 使用預先封裝的 Docker 映像檔安裝 Matter 開發環境。
  • 建構並執行 Matter 虛擬裝置。
  • 透過 Google Home 設定及控制虛擬裝置。

如要進一步瞭解 Matter,請參考下列參考資料: