1. 簡介
Matter 是連線通訊協定,可為智慧型裝置帶來絕佳機會。在這個程式碼研究室中,您將使用預先設定的 Docker 映像檔中提供的 SDK 和依附元件,建構第一個 Matter 裝置。
如要進一步瞭解 Matter,請造訪 Google Home 開發人員中心或連線標準聯盟網站。
課程內容
- 如何設定 Matter 建構環境
- 如何打造可在電腦上執行的虛擬 Matter 裝置
- 如何使用 Google Home 調試及控制虛擬 Matter 裝置
軟硬體需求
- 中樞裝置,是指支援 Matter 的 Google Nest 裝置,例如 Nest Hub (第 2 代)。
- 執行 X11 視窗系統的 Linux 機器。
- 。
- 對 Linux 有基本瞭解。
2. 設定環境
您將在 Linux 主機機器上使用先前設定的 Docker 容器。這個容器包含建構和執行 Matter 虛擬裝置的所有必要依附元件。
檢查硬體
這個 Docker 安裝項目不支援 Windows 和 macOS 電腦。你可以在 macOS 上手動安裝及建構 Matter。
此外,這些指示假設 Linux 機器正在執行 X11 視窗系統。如果 Linux 機器執行的是 Wayland,請確認已安裝 X.Org。
設定 Docker
- 安裝 Docker Engine (不要使用 Docker Desktop)。
- 從 Docker Hub 提取 Docker 映像檔。在終端機視窗中執行:
user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
這項作業可能需要幾分鐘才能完成。 - 啟動執行中的 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 Registry 中提取映像檔。--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 設定
終端機開啟後,就會顯示在 Matter 複製存放區 (~/connectedhomeip
) 中。無須採取其他 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 的整合作業。
凡是通過連線標準聯盟 (Alliance) Matter 認證的 Matter 裝置,都能在 Google Home 生態系統中運作。處於開發階段的裝置如未經過認證,可於特定條件下在 Google Home 生態系統中委託開發。詳情請參閱配對限制。
建立開發人員專案
首先請前往 Google Home 開發人員控制台:
- 按一下 [Create Project]。
- 輸入不重複的專案名稱,然後按一下「Create project」(建立專案)。
- 按一下「+ 新增整合」,前往「Matter 資源」畫面,即可查看 Matter 開發說明文件及查看部分工具。
- 準備好繼續進行時,請按一下「Next:開發」,系統隨即會顯示「Matter 檢查清單」頁面。
- 點選「下一步:設定」。
- 在「設定」頁面中輸入您的「產品名稱」。
- 按一下「選取裝置類型」,然後從下拉式選單中選取裝置類型 (本例中為
Light
)。 - 在「供應商 ID (VID)」中選取「Test VID」,然後從「測試 VID」下拉式選單中選取「0xFFF1」。在產品 ID (PID) 中輸入 0x8000,然後按一下「儲存並繼續」,接著在下一頁點選「儲存」。請使用這些正確的 VID/PID 值,後續的程式碼研究室步驟取決於這些值。
- 接著,「Matter 整合」下方會顯示整合項目。
- 請重新啟動中樞,確保裝置能接收最新的 Matter 整合專案設定。如果之後要變更 VID 或 PID,您也必須在儲存專案後重新啟動,變更才會生效。如需重新啟動的逐步操作說明,請參閱「重新啟動 Google Nest 或 Google Wifi 裝置」一文。
4. 打造裝置
您可以在 GitHub 存放區的 examples
資料夾中找到 Matter 中的所有範例。有幾個範例可供使用,但本程式碼研究室著重於主廚,
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
:目標平台。支援平台包括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. 虛擬裝置控制器
虛擬裝置控制器是獨立的應用程式,提供圖形使用者介面,方便您控制及顯示虛擬 Matter 裝置的狀態。這項服務使用 RPC 用戶端與連線至開發環境的 Matter 裝置進行通訊。
虛擬裝置控制器
虛擬裝置控制器能以視覺化方式呈現虛擬裝置。
您可以透過虛擬裝置控制器圖像使用者介面 (GUI) 與虛擬裝置互動。您在 GUI 中所做的變更會影響基礎資料模型。如需支援 Matter 虛擬裝置類型的完整清單,請參閱「支援的裝置」。
安裝虛擬裝置控制器
虛擬裝置控制器已預先安裝在 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
如果您在啟動 Controller 時沒有提供任何引數,則會使用使用 localhost 通訊埠 33000 的網路通訊端選項。控制器可以連線至虛擬裝置後,畫面上會顯示顯示裝置狀態的畫面:
在 Virtual Controller 應用程式的變更時,應用程式會將要求傳送至裝置的 RPC 伺服器,並每秒輪詢 RPC 伺服器一次以擷取狀態。
此外,虛擬裝置控制器應用程式也能用來擷取 QR code,藉此進行裝置調適流程。按一下裝置圖片旁邊的 QR code 圖示,即可顯示這部裝置的 QR code。請使用這個 QR code 調試裝置。
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 code
調試程序需要透過 QR code 提供的 Matter 新手上路資訊。您可以透過虛擬裝置控制器取得虛擬裝置的 QR code。
執行佣金作業
- 開啟 Google Home 應用程式。
- 輕觸左上角的「+」。
- 輕觸「設定裝置」。
- 輕觸「新裝置」。
- 選取住家,然後輕觸「下一步」。
- Google Home 應用程式會掃描你的裝置。如果出現「找到 Matter 裝置...」訊息,請輕觸「是」。如果是其他裝置,請輕觸「設定其他裝置」,然後從裝置清單中選取「Matter 裝置」。
- 將相機對準裝置的 QR code 或網站產生的 QR code。
- 按照 Google Home 應用程式流程的說明繼續配對程序。
完成上述步驟後,Matter 虛擬裝置應能順利啟動,而且 Google Home 應用程式中會顯示為新圖示。
疑難排解
調解失敗,出現「連線問題」或「無法聯絡 Google」錯誤訊息
- 確認已在 Google Home 控制台中用正確的 VID/PID 組合 建立專案,且沒有任何其他專案使用相同的 VID/PID 組合。
長時間「掃描你的裝置」後無法執行調試
- 確認電腦的防火牆已關閉,且您正在執行虛擬裝置。
- 中斷任何實體網路介面 (乙太網路) 的連線,確保電腦僅使用 Wi-Fi 網路。
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,請參閱下列參考資料:
- Matter Primer:探索 Google Home 開發人員中心的基本概念,瞭解 Matter 的基本概念。
- Matter 規格、Matter 裝置程式庫和 Matter 應用程式叢集程式庫,由連線標準聯盟發布。
- Matter GitHub 存放區。