このページは Cloud Translation API によって翻訳されました。

Matter 仮想デバイスを作成する

1. はじめに

Matter は、スマートデバイスの開発に魅力的な機会をもたらす接続プロトコルです。この Codelab では、事前構成済みの Docker イメージで提供されている SDK と依存関係を使用して、最初の Matter デバイスを構築します。

Matter について詳しくは、Google Home デベロッパーセンターまたは Connectivity Standards Alliance のウェブサイトをご覧ください。

ラボの内容

Matter ビルド環境を設定する方法
パソコンで動作する仮想 Matter デバイスを構築する方法
Google Home で仮想 Matter デバイスをコミッションして操作する方法

必要なもの

ハブ（Google Nest Hub（第 2 世代）など、Matter をサポートする Google Nest デバイス）。ハブは Google ストアまたはご希望の販売店でご購入いただけます。
X11 ウィンドウシステムを実行する Linux マシン。
Docker。
Linux に関する基本的な知識。

2. 環境を設定する

先ほど構成した Docker コンテナを Linux ホストマシン上で使用します。このコンテナには、Matter 仮想デバイスの作成と実行に必要なすべての依存関係が含まれています。

ハードウェアを確認する

現在、この Docker のインストールでは Windows パソコンと MacOS パソコンはサポートされていません。MacOS または Windows に Matter を手動でインストールしてビルドできます。

また、以下の手順は Linux マシンが X11 ウィンドウシステムを実行していることを前提としています。Linux マシンで Wayland を実行している場合は、X.Org もインストールされていることを確認します。

Docker を設定する

Docker Engine をインストールします（Docker Desktop は使用しないでください）。
Docker Hub から Docker イメージを pull する。ターミナルウィンドウで以下を実行します。
```
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 Window System はポート 1000 でローカルホストから接続を受信できます。これにより、グラフィックユーザーインターフェースを使用できます。
docker run … image は指定されたイメージを実行し、必要に応じて Docker レジストリから pull します。
--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 の統合を管理するウェブアプリケーションです。

CSA Matter 認定試験に合格した Matter デバイスは、Google Home エコシステムで動作します。

デベロッパープロジェクトを作成する

まず、Google Home デベロッパーコンソールに移動します。Google Home デベロッパーコンソールに移動します。

[プロジェクトの管理] 画面で [プロジェクトを作成] をクリックします。
[使ってみる] 画面で [プロジェクトを作成] をクリックします。

一意のプロジェクト名を入力し、[Create new project] をクリックします。
重要: プロジェクト名は、意味のある独特なものにすることをおすすめします。会社名のほか、導入するデバイスの種類やアクションを明記することを検討してください。たとえば、「encom-smartlight-switch」はこれらの要素の両方を使用します。
[+ Matter の統合を追加] をクリックします。[Matter リソース] 画面が表示されます。この画面で、Matter の開発ドキュメントを参照し、いくつかのツールを確認できます。
続行する準備ができたら、[次へ: 開発] をクリックします。これにより、[Matter チェックリスト] 画面が表示されます。
[次へ: 設定] をクリックします。
[設定] 画面でプロダクト名を入力します。
[Select device type] をクリックし、プルダウンメニューからデバイスタイプを選択します（この場合は Light）。
ベンダー ID（VID）で、[Test VID] を選択し、[Test VID] プルダウンメニューから [0xFFF1] を選択します。プロダクト ID（PID）に「0x8000」と入力し、[保存して次へ] をクリックしてから次のページで [保存] をクリックします。
注: VID 0xFFF1、0xFFF2、0xFFF3、0xFFF4 はテスト用に予約されています。サービスをリリースする前に、Connected Standards Alliance で VID を申請する必要があります。また、PID 0x8000 ～ 0x801F には、テスト（デバイス認証証明書）DAC を使用できます。独自の DAC を設定する場合を除き、この範囲内の PID を使用してください。
[Matter との統合] の下に、1 つの Matter デバイスが表示されます。
最新の Matter 統合プロジェクト構成を受け取るように、ハブを再起動します。後で VID または PID を変更する必要がある場合は、プロジェクトを保存した後に再起動して変更を反映する必要があります。

4. デバイスをビルドする

Matter のすべての例は、GitHub リポジトリの examples フォルダにあります。いくつかのサンプルがありますが、この Codelab は Chef に焦点を当てます。

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+\ も使用する必要があります。

仮想デバイスの認証情報は、chip プレフィックスで始まるファイルの /tmp/ ディレクトリに保存されます。

コミッションプロセス全体を最初からやり直す場合は、次のコマンドを実行してこれらのファイルを削除する必要があります。

$ rm /tmp/chip*

5. 仮想デバイスコントローラ

仮想デバイスコントローラは、仮想 Matter デバイスの状態を制御、表示するグラフィカルユーザーインターフェースを提供するスタンドアロンアプリです。RPC クライアントを使用して、開発環境に接続している Matter デバイスと通信します。

仮想デバイスコントローラ

仮想デバイスコントローラは、仮想デバイスを視覚的に表したものです。

仮想デバイスコントローラのグラフィックユーザーインターフェース（GUI）を使用して、仮想デバイスを操作できます。GUI に加えた変更は、基盤となるデータモデルに影響します。現在、仮想デバイスコントローラは調光可能デバイスタイプをサポートしています。

仮想デバイスコントローラをインストールする

仮想デバイスコントローラは、Ubuntu LTS 20.04 Docker コンテナにプリインストールされています。

仮想デバイスコントローラを実行する

2 つ目のターミナルセッションインスタンスを作成します。

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 を使用するネットワークソケットオプションが使用されます。コントローラが仮想デバイスに接続できるようになると、デバイスの状態を示す画面が表示されます。

仮想デバイスのグラフィックユーザーインターフェース

仮想コントローラアプリに変更を加えると、アプリはデバイスの RPC サーバーにリクエストを送信し、1 秒に 1 回 RPC サーバーにポーリングして状態を取得します。

仮想デバイスコントローラアプリを使用して、デバイスのコミッションフローの一環として QR コードを取得することもできます。デバイス画像の横にある QR コードアイコンをクリックして、このデバイスの QR コードを表示します。

QR コード

この QR コードを使用してデバイスを試用できます。

6. デバイスのコミッション

注: この手順は、Google Home デベロッパーコンソールでプロジェクトをすでに設定している場合にのみ完了します。

Google Nest Hub

Matter ファブリックでデバイスをコミッションするには、ハブが必要です。これは、Google Nest デバイス（Google Nest Hub（第 2 世代）など）で、Matter に対応しており、Thread 対応デバイスのボーダールーターとして機能するほか、スマートホームインテントをルーティングするためのローカルフルフィルメントパスとしても機能します。

コミッションプロセスを開始する前に、以下のことを確認してください。

ハブは、Google Home Console へのログインに使用したのと同じ Google アカウントとペア設定されています。
ハブは、Virtual Matter デバイスの実行に使用しているパソコンと同じ Wi-Fi ネットワークに接続されています。
ハブは、Google Home アプリで使用しているのと同じストラクチャ内にあります（Google Home グラフの「家」はストラクチャを表します）。

QR コードを取得する

コミッションプロセスには、QR コードを通じて提供される案件のオンボーディング情報が必要です。仮想デバイスの QR コードは、仮想デバイスコントローラから取得できます。

コミッションオペレーションを実行する

Google Home アプリを開きます。
左上の [+] をタップします。
[デバイスのセットアップ] をタップします。
[新しいデバイス] をタップします。
家を選択して [次へ] をタップします。
Google Home アプリがデバイスをスキャンします。「Matter Device found...」というメッセージが表示されたら、[はい] をタップします。それ以外の場合は、[別のデバイスのセットアップ] をタップし、デバイスのリストから [Matter デバイス] を選択します。
デバイスの QR コードまたはウェブサイトで生成された QR コードにカメラを向けます。
Google Home アプリのフローの手順に沿ってペア設定の手続きを進めます。

これらの手順を完了すると、Matter 仮想デバイスが正常にコミッションされ、Google Home アプリに新しいアイコンとして表示されるはずです。

Google Home アプリでペア設定した電球

トラブルシューティング

接続エラー「接続エラー」または「Google に接続できませんでした」というエラーメッセージが表示される

Google Home Console で正しい 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 デバイスが正常に作成されました。うまくできました。

この Codelab では、以下について学びました。

事前にパッケージ化された Docker イメージを使用して Matter 開発環境をインストールする。
Matter 仮想デバイスをビルドして実行します。
Google Home から仮想デバイスをコミッションして操作できます。

Matter について詳しくは、以下のリファレンスをご覧ください。

Google Home デベロッパーセンターの Matter 入門ガイドでは、Matter のコンセプトの基本を学ぶことができます。
Matter の仕様、Matter デバイスライブラリ、Matter アプリケーションクラスタライブラリ（Connectivity Standards Alliance で公開）
Matter GitHub リポジトリ。