ご案内: 新しいデベロッパー プレビュー プログラムがまもなくリリースされます。こちらからお申し込みのうえ、新しいツールを試してフィードバックをいち早くご利用ください。

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 を設定する

  1. Docker Engine をインストールします（Docker Desktop は使用しないでください）。
  2. Docker Hub から Docker イメージを pull する。ターミナル ウィンドウで以下を実行します。
    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 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 デベロッパー コンソールに移動します。

  1. [プロジェクトの管理] ページで、[プロジェクトを作成] をクリックします。
    Google Home デベロッパー センター
  2. [スタートガイド] ページで、[プロジェクトを作成] をクリックします。

  1. 一意のプロジェクト名を入力し、[Create new project] をクリックします。 [Create new project] ダイアログ
  2. [+ 統合を追加] をクリックします。[Matter リソース] 画面が表示されます。この画面で、Matter の開発ドキュメントを参照したり、いくつかのツールを確認したりできます。
  3. 続行する準備ができたら、[次へ: 開発] をクリックします。Matter チェックリスト ページが表示されます。
  4. [次へ: 設定] をクリックします。
  5. [設定] ページで、プロダクト名を入力します。
  6. [Select device type] をクリックし、プルダウン メニューからデバイスタイプを選択します（この場合は Light）。
  7. ベンダー ID（VID）で、[Test VID] を選択し、[Test VID] プルダウン メニューから [0xFFF1] を選択します。プロダクト ID（PID）に「0x8000」と入力し、[保存して次へ] をクリックしてから次のページで [保存] をクリックします。
    プロジェクトの設定
  8. [Matter との統合] の下に、1 つの Matter デバイスが表示されます。Matter の統合
  9. 最新の 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 対応デバイスのボーダー ルーターとして機能するほか、スマートホーム インテントをルーティングするためのローカル フルフィルメント パスとしても機能します。

Matter 対応のハブについては、こちらのリストをご覧ください。

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

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

QR コードを取得する

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

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

  1. Google Home アプリを開きます。
  2. 左上の [+] をタップします。
  3. [デバイスのセットアップ] をタップします。
  4. [新しいデバイス] をタップします。
  5. 家を選択して [次へ] をタップします。
  6. Google Home アプリがデバイスをスキャンします。「Matter Device found...」というメッセージが表示されたら、[はい] をタップします。それ以外の場合は、[別のデバイスのセットアップ] をタップし、デバイスのリストから [Matter デバイス] を選択します。
  7. デバイスの QR コードまたはウェブサイトで生成された QR コードにカメラを向けます。
  8. 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 について詳しくは、以下のリファレンスをご覧ください。